123 lines
5.5 KiB
Markdown
123 lines
5.5 KiB
Markdown
# Tasks: Add Knip Unused Code Detection
|
||
|
||
**Input**: Design documents from `/specs/007-add-knip/`
|
||
**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, quickstart.md
|
||
|
||
**Tests**: No automated test tasks — this is a tooling feature validated by running `pnpm knip` and `pnpm check`.
|
||
|
||
**Organization**: Tasks follow the two user stories (US1: quality gate enforcement, US2: standalone command).
|
||
|
||
## Format: `[ID] [P?] [Story] Description`
|
||
|
||
- **[P]**: Can run in parallel (different files, no dependencies)
|
||
- **[Story]**: Which user story this task belongs to (e.g., US1, US2)
|
||
- Include exact file paths in descriptions
|
||
|
||
## Phase 1: Setup
|
||
|
||
**Purpose**: Install Knip and create configuration
|
||
|
||
- [x] T001 Install Knip v5 as a root devDependency via `pnpm add -Dw knip`
|
||
- [x] T002 Create `knip.json` at the repository root with workspace-aware configuration covering `packages/*` and `apps/*`, including `$schema` for editor support
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (Blocking Prerequisites)
|
||
|
||
**Purpose**: Ensure Knip passes cleanly on the current codebase before integrating into the gate
|
||
|
||
**CRITICAL**: Must resolve all false positives before wiring into the quality gate
|
||
|
||
- [x] T003 Run `pnpm knip` against the current codebase and capture output
|
||
- [x] T004 If false positives are reported, tune `knip.json` with `ignore`, `ignoreDependencies`, `entry`, or plugin-specific overrides until the codebase passes cleanly (FR-006 through FR-009)
|
||
|
||
**Checkpoint**: `pnpm knip` exits with code 0 on the current codebase (SC-002)
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 - Detect Unused Code on Commit (Priority: P1)
|
||
|
||
**Goal**: Integrate Knip into the `pnpm check` quality gate so unused code is caught on every commit via Lefthook.
|
||
|
||
**Independent Test**: Introduce an unused export in any workspace package, run `pnpm check`, and confirm it fails with a clear report. Remove the unused export and confirm `pnpm check` passes.
|
||
|
||
### Implementation for User Story 1
|
||
|
||
- [x] T005 [US1] Update the `check` script in `package.json` to prepend `knip &&` before `biome check .` so unused code is checked as part of the quality gate
|
||
- [x] T006 [US1] Run `pnpm check` end-to-end and verify it passes on the current codebase (SC-001, SC-002)
|
||
- [x] T007 [US1] Manually verify detection: (a) add a temporary unused export to `packages/domain/src/index.ts`, run `pnpm check`, confirm it fails with a report identifying the unused export and its file location (SC-001, SC-004), then remove the temporary change; (b) verify that exports re-exported through barrel files (e.g., `index.ts`) are correctly traced and not falsely flagged
|
||
|
||
**Checkpoint**: Quality gate enforces unused-code detection on every commit. US1 acceptance scenarios 1–5 are satisfied.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 - Run Unused-Code Check Independently (Priority: P2)
|
||
|
||
**Goal**: Provide a standalone `pnpm knip` command developers can run without the full quality gate.
|
||
|
||
**Independent Test**: Run `pnpm knip` from the workspace root and verify it analyzes all three workspace packages and reports results.
|
||
|
||
### Implementation for User Story 2
|
||
|
||
- [x] T008 [US2] Add a `"knip": "knip"` script to `package.json` so developers can run `pnpm knip` independently
|
||
- [x] T009 [US2] Verify `pnpm knip` runs from the workspace root and reports results covering all workspace packages (`packages/domain`, `packages/application`, `apps/web`) (SC-003, SC-004)
|
||
|
||
**Checkpoint**: Developers can run `pnpm knip` standalone. US2 acceptance scenarios 1–2 are satisfied.
|
||
|
||
---
|
||
|
||
## Phase 5: Polish & Cross-Cutting Concerns
|
||
|
||
**Purpose**: Final validation and documentation
|
||
|
||
- [x] T010 Run quickstart.md validation: confirm `pnpm knip` and `pnpm check` both work as documented
|
||
- [x] T011 Update CLAUDE.md commands section if `pnpm knip` should be listed as a project command
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### Phase Dependencies
|
||
|
||
- **Setup (Phase 1)**: No dependencies — start immediately
|
||
- **Foundational (Phase 2)**: Depends on Phase 1 (T001, T002 must complete first)
|
||
- **User Story 1 (Phase 3)**: Depends on Phase 2 (clean Knip pass required before wiring into gate)
|
||
- **User Story 2 (Phase 4)**: Depends on Phase 3 (T008 modifies the same `package.json` as T005, so must follow it)
|
||
- **Polish (Phase 5)**: Depends on Phases 3 and 4
|
||
|
||
### User Story Dependencies
|
||
|
||
- **User Story 1 (P1)**: Depends on Foundational phase — needs clean codebase pass before gate integration
|
||
- **User Story 2 (P2)**: Depends on US1 — T008 modifies the same `package.json` as T005, so must execute after it
|
||
|
||
### Parallel Opportunities
|
||
|
||
- T001 and T002 are sequential (T002 needs Knip installed for schema validation)
|
||
- T008 (US2) modifies `package.json` (same as T005), so execute sequentially after T005
|
||
|
||
---
|
||
|
||
## Implementation Strategy
|
||
|
||
### MVP First (User Story 1 Only)
|
||
|
||
1. Complete Phase 1: Install Knip, create config
|
||
2. Complete Phase 2: Ensure clean pass on current codebase
|
||
3. Complete Phase 3: Wire into quality gate
|
||
4. **STOP and VALIDATE**: `pnpm check` passes clean; intentional unused code is caught
|
||
|
||
### Incremental Delivery
|
||
|
||
1. Phase 1 + Phase 2 → Knip works locally
|
||
2. Add US1 (Phase 3) → Quality gate enforced on every commit (MVP!)
|
||
3. Add US2 (Phase 4) → Standalone `pnpm knip` command available
|
||
4. Phase 5 → Documentation updated
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- All tasks modify root-level files only (no domain/application/adapter changes)
|
||
- The Lefthook pre-commit hook already runs `pnpm check`, so no Lefthook config changes needed
|
||
- If Knip reports false positives in Phase 2, the most common fixes are `ignoreDependencies` for tooling packages and `entry` patterns for non-standard entry points
|