diff --git a/AGENTS.md b/AGENTS.md index e7859738..cc721728 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,17 +12,87 @@ ## Code Quality - Keep cyclomatic complexity under 10 per function - Aim for files under 300 lines +- All files must follow single responsibility principle (one clear purpose per module) +- Extract complex logic into reusable utilities/services ## Testing + +### Standard Testing (Ongoing) - Write unit tests for all utility functions - Minimum 80% coverage on new code - Use Vitest for unit tests +### AI-Friendly Refactoring Testing Strategy (v1.10.16+) +**Scope:** Full test coverage before refactoring to prevent UI/functionality regression. + +**Backend Testing (Pytest)** +- Target: 85%+ coverage (unit + integration tests) +- Structure: `backend/tests/` with suites for routers, models, auth, AI pipeline +- Coverage tools: `pytest backend/tests/ --cov=backend --cov-report=html` +- Test types: Unit (functions), Integration (full API workflows), Fixtures (mocked auth, in-memory DB) + +**Frontend Testing (Vitest)** +- Target: 80%+ coverage (components, hooks, snapshots) +- Structure: `frontend/tests/` with component tests, hook tests, integration workflows +- Coverage tools: `npm test -- --coverage` +- Test types: Component rendering, Hook state/side effects, Snapshot tests for UI layouts + +**E2E Testing (Playwright)** +- Target: Critical user workflows automated +- Workflows: Login, Scan → Match → Stock adjustment, New Item (AI), Admin config, Offline sync +- Runtime: ~30 min total +- Command: `npx playwright test` + +**Test-First Approach** +- All tests written and passing BEFORE refactoring any code +- Tests serve as gating condition: no code changes if tests fail +- Functional preservation: Zero behavior changes post-refactor +- Regression prevention: Manual checklist + automated tests catch UI breakage + ## Security - Store all secrets in inventory.env — never hardcode credentials - Never log API keys, tokens or passwords - Validate all user input before processing ## Git Conventions -- Use conventional commits (feat:, fix:, docs:, etc.) +- Use conventional commits (feat:, fix:, docs:, refactor:, test:, etc.) - Keep PRs under 400 lines of diff when possible +- Refactoring commits: `refactor: split {module} into smaller modules` +- Testing commits: `test: add {suite} coverage for {module}` +- All commits must have passing test suite before merge + +## Refactoring Guidelines (AI-Friendly Modularity) + +### Refactoring Principles +- **Target:** Break monolithic files into focused modules (<300 lines each) +- **Priority Order:** Backend routers → Components → Pages +- **No Behavior Changes:** Every refactor must pass 100% of existing tests +- **Gating Rule:** No refactor commit unless all tests pass (pre + post) +- **Regression Prevention:** Manual checklist + automated tests validate UI integrity + +### Refactoring Process +1. Ensure full test coverage exists (backend 85%, frontend 80%) +2. Run complete test suite (all tests PASS) +3. Refactor module: split into smaller files/services +4. Run test suite again (all tests PASS) +5. Manual browser validation: UI unchanged, all buttons/features work +6. Commit with test results in message body +7. Move to next module + +### Module Extraction Patterns +- **Backend Routers:** Split into router (endpoints only) + service (business logic) + validators (input validation) +- **Components:** Split into orchestrator component + sub-components + custom hooks for state/logic +- **Pages:** Extract page logic into custom hooks, move forms into separate components +- **Utilities:** Consolidate repeated logic into `lib/` or `services/` modules + +### Validation Checklist (Post-Refactor) +- [ ] All pytest tests passing (backend coverage 85%+) +- [ ] All vitest tests passing (frontend coverage 80%+) +- [ ] All e2e workflows passing (Playwright) +- [ ] Login works (LDAP + local) +- [ ] Scanner functional (scan → match → stock adjustment) +- [ ] AI extraction working (new item → AI popup → validation) +- [ ] Admin page responsive and functional +- [ ] No console errors in browser +- [ ] Mobile responsive (320px, 768px, 1024px+ viewports) +- [ ] Keyboard navigation works (focus indicators visible)