bugfix-workflow

Bugfix Workflow — NestJS Clean Architecture

A structured 5-phase methodology for diagnosing and fixing bugs in this project. Follow these phases in order. Do not skip phases — each one narrows the search space and prevents wasted effort.

For a catalog of common bugs with symptoms, root causes, and TypeScript code fixes, read references/common-bugs.md.

---

Phase 1: REPRODUCE — Understand the Bug

Start every bugfix by establishing what is actually broken.

1. Get the exact error message or description of unexpected behavior from the user. Ask for the full stack trace if available.
2. Identify which endpoint, use case, or layer is involved. Map the symptom to an entry point:
   • API endpoint → controller → use case → repository chain
   • Test failure → specific spec file and test name
   • Build error → TypeScript compilation in a specific file
3. Check if a failing test already exists that demonstrates the bug. Search in test/ for specs related to the affected feature.
4. If no test exists, write one first. Create a test that expects the correct behavior — it should fail (red). This test becomes your verification that the fix works (green). Place it in the correct test/ subdirectory mirroring src/.

Key questions to answer before moving on:

• What is the expected behavior?
• What is the actual behavior?
• Is this a regression (did it work before)?

---

Phase 2: LOCATE — Find Where the Bug Lives

Use the error type and HTTP status code to narrow down the layer, then trace the call chain.

Error-to-Layer Map

Symptom	Likely Layer	Where to Look
HTTP 400 / 422	Adapter	DTO validation decorators in src/adapters/controllers/[feature]/dto/
HTTP 401	Infrastructure	JWT guard, strategy in src/infrastructure/common/strategies/
HTTP 403	Infrastructure	CASL ability factory in src/infrastructure/services/casl/
HTTP 404	Use Case / Infra	Repository query or missing route registration
HTTP 500	Use Case / Domain	Use case logic, domain entity method, or repository implementation
Wrong data returned	Adapter / Infra	Presenter mapping or repository toEntity()
Type error at compile	Any	Check imports, constructor signatures, interface conformance
Cannot resolve dependencies	Module	Missing or wrong Symbol binding in module providers
Test failure	Test	Mock setup, stub data, or assertion mismatch

Tracing the Call Chain

Use Serena tools to trace the data flow through layers:

1. Start from the controller method — use find_symbol to locate the endpoint handler.
2. Follow the use case it calls — use find_referencing_symbols to find where the use case's execute() is invoked.
3. Check the repository method the use case calls — use find_symbol on the repository interface method, then find its implementation.
4. Inspect the TypeORM query in the repository implementation.

Trace the full data transformation chain:

Request → DTO (validation) → Controller → Use Case → Repository Interface
    → Repository Impl → TypeORM Entity → Database
    → TypeORM Entity → toEntity() → Domain Entity → Presenter → Response

Every arrow is a potential failure point. Identify which transformation breaks.

---

Phase 3: UNDERSTAND — Root Cause Analysis

Read the suspected code carefully. Use find_symbol with include_body: true to examine the implementation.

Data Transformation Verification

Walk through each transformation step and verify data integrity:

1. DTO → Controller: Does the DTO class-validator decorator accept the input format the client sends?
2. Controller → Use Case: Does the controller pass all required fields to execute()?
3. Use Case → Repository: Does the use case call the correct repository method with correct parameters?
4. Repository → Database: Does the TypeORM query include correct WHERE clauses, JOINs, and column names?
5. Database → toEntity(): Does toEntity() map every column to the domain entity constructor in the correct order?
6. Domain Entity → Presenter: Does the presenter constructor read all required fields from the entity?

Cross-Reference Checklist

• Compare the domain entity constructor parameter order with the toEntity() call arguments — a mismatch here silently swaps fields.
• Compare the domain entity fields with the presenter fields — a missing field means the API silently drops data.
• Compare the TypeORM entity columns with the database migration — a mismatch means queries fail at runtime.
• Compare the Symbol token in @Inject(IXxxRepository) with the one in the module's provide: — they must be the same Symbol.

---

Phase 4: FIX — Apply the Fix

Fix in the Correct Layer

Apply the fix where the bug originates, not where it manifests:

• If a wrong value reaches the presenter, the bug might be in toEntity(), not in the presenter.
• If a use case gets wrong data, the bug might be in the repository query, not in the use case.
• If validation rejects valid input, fix the DTO decorator, not the controller.

Fix Order for Multi-Layer Bugs

When a fix spans multiple layers, work inside-out:

1. Domain — Fix entity logic, enums, or constructor
2. Use Case — Fix business rules, default values, or repository calls
3. Infrastructure — Fix toEntity(), TypeORM entity, queries
4. Adapter — Fix DTO, presenter, or controller wiring
5. Module — Fix DI bindings
6. Tests — Update stubs, mocks, and assertions

Fix Principles

• Keep the fix minimal and focused — do not refactor unrelated code.
• Follow the dependency rule: domain never imports from infrastructure or adapters.
• If adding a new field to an entity, update all layers: domain entity → TypeORM entity → toEntity() → presenter → DTO (if input) → stubs → tests.
• If fixing a migration issue, generate a new migration — never edit existing migration files.

---

Phase 5: VERIFY — Confirm the Fix

Run verification commands in order. Stop at the first failure and fix before continuing.

# 1. Run the specific test that demonstrates the bug (should now pass)
docker exec -it app-api npm run test:watch <test-file>

# 2. Run the full test suite (no regressions)
docker exec -it app-api npm run test

# 3. Build (no compilation errors)
docker exec -it app-api npm run build

# 4. Lint (no style violations)
docker exec -it app-api npm run lint

Verification Checklist

• The test that was red before the fix is now green
• All existing tests still pass
• The build succeeds without TypeScript errors
• Lint passes without new warnings
• If the fix touches a presenter or controller, the API response shape is correct
• If the fix touches a migration, run migration:run to apply it

---

Layer-Specific Debugging Strategies

Domain Layer — src/domain/

• Check entity constructor parameter order — positional arguments are error-prone. Compare with every new XxxEntity(...) call site.
• Check state transition guards — e.g., complete() throws if status is not OnGoing. Verify the entity is in the expected state.
• Check enum value comparisons — ensure you compare enum members, not raw numbers.
• Verify business rule logic in entity methods — pure TypeScript, easy to unit test in isolation.

Use Case Layer — src/use-cases/

• Check @Inject() token — must use the Symbol (e.g., ITaskRepository), not a string literal.
• Check execute() parameter types — must match what the controller passes in.
• Check repository method called with correct parameters — especially userId for ownership filtering.
• Verify default values — e.g., dto.priority ?? TaskPriorityEnum.Medium.
• Check the @Injectable() decorator is present on the class.

Controller / Adapter Layer — src/adapters/controllers/

• Check DTO validation decorators — @IsString(), @IsOptional(), @IsEnum(), etc. A missing @IsOptional() rejects valid partial updates.
• Check @User('id') — extracts id from the JWT payload. Verify the JWT strategy puts id in the right place.
• Check @CheckPolicies({ action, subject }) — the subject string must match what CASL defines in TSubject.
• Verify presenter maps all required fields — compare presenter constructor with domain entity fields.
• Check route decorators — @Get(), @Post(), @Patch(':id') must match the intended HTTP method and path.

Infrastructure Layer — src/infrastructure/

• Check toEntity() maps ALL fields in the correct order — this is the single most common bug in this architecture.
• Check TypeORM entity column types match domain entity types — especially enums, dates, and nullable fields.
• Check query builder conditions — especially for optional filters using .andWhere() with conditional logic.
• Verify @InjectRepository() uses the correct TypeORM entity class (not the domain entity).
• Check column names in @Column() decorators match the database schema.

Module / DI Layer — src/modules/

• Check Symbol token binding: { provide: IXxxRepository, useClass: XxxRepository } — both sides must be correct.
• Check all use cases used by the controller are registered in providers.
• Check the module is imported in app.module.ts.
• Check for circular dependencies — Module A imports Module B which imports Module A. Use forwardRef() if unavoidable.

---

Common Bug Decision Tree

Use this tree to quickly narrow down the root cause:

Error Message / Symptom	Root Cause	Fix Location
Nest can't resolve dependencies of XxxUseCase	Missing Symbol binding in module	Module providers array
Cannot read properties of undefined	Missing field in toEntity() or presenter	Repository toEntity() or presenter constructor
Unexpected token / compile error	Wrong import path or missing type	Check import statements and tsconfig paths
401 Unauthorized	JWT missing, expired, or guard not applied	Auth strategy or @UseGuards(JwtAuthGuard)
403 Forbidden	CASL ability does not allow this action	casl-ability.factory.ts or TSubject type
Entity not found / empty result	Repository query missing WHERE clause	Repository implementation query
Duplicate entry	Missing unique constraint or no upsert logic	Migration or repository save logic
Column "xxx" does not exist	Migration not run or TypeORM entity out of sync	Generate + run migration
mockResolvedValue not working	jest.fn() not configured or wrong method name	Test mock setup in beforeEach
Fields appear swapped	toEntity() argument order mismatch	Repository toEntity() method
New field missing from response	Presenter not updated	Presenter constructor
Valid input rejected with 400	DTO decorator too strict or missing @IsOptional()	DTO class decorators

---

Regression Test Checklist

After every fix, verify these items:

1. Write a test that FAILS before the fix — this proves the bug exists and the test catches it.
2. Apply the fix — make the minimal change in the correct layer.
3. Verify the test PASSES — the fix resolves the specific bug.
4. Run the full test suite — no existing tests broke.
5. Check coverage didn't drop — run npm run test:cov if the fix touches critical paths.
6. Update stubs if needed — if you added a field to an entity, update test/stubs/ factories to include it.

Related Skills

• testing-patterns — exact patterns for writing regression tests after a fix
• exception-handling — if the bug involves incorrect error handling or missing exceptions