Skip to content

Commit 658208b

Browse files
codeaholicguycodeaholicguy
authored
Add lint command (#19)
* Add lint command planning * feat(lint): add lint command implementation * refactor(lint): split rules and keep service business-only * refactor(lint): centralize levels and labels in constants
1 parent ff2046f commit 658208b

23 files changed

+1359
-2
lines changed

‎docs/ai/design/feature-lint-command.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
phase: design
3+
title: System Design & Architecture
4+
description: Define the technical architecture, components, and data models
5+
---
6+
7+
# System Design & Architecture
8+
9+
## Architecture Overview
10+
**What is the high-level system structure?**
11+
12+
```mermaid
13+
graph TD
14+
User --> CLI[ai-devkit lint command]
15+
CLI --> ArgParser[Feature and output argument parser]
16+
ArgParser --> LintService[Lint validation service]
17+
LintService --> BaseCheck[Base docs checker]
18+
LintService --> FeatureCheck[Feature docs checker]
19+
LintService --> GitCheck[Worktree and branch checker]
20+
BaseCheck --> FS[(File System)]
21+
FeatureCheck --> FS
22+
GitCheck --> Git[(Git metadata)]
23+
CLI --> Reporter[Terminal and JSON reporter]
24+
```
25+
26+
- Key components and responsibilities
27+
- `lint` command handler: parse options and orchestrate checks.
28+
- Name normalizer: convert `--feature` input into canonical `<name>` and `feature-<name>` (accept `foo` and `feature-foo`).
29+
- Base docs checker: validate required phase template files (`docs/ai/*/README.md`).
30+
- Feature docs checker: validate `docs/ai/{phase}/feature-<name>.md` across lifecycle phases.
31+
- Git/worktree checker: evaluate feature branch/worktree convention used by `dev-lifecycle` Phase 1 prerequisite.
32+
- Reporter (command-owned): consistent output rows (`[OK]`, `[MISS]`, `[WARN]`) and final summary with exit code.
33+
- Technology stack choices and rationale
34+
- TypeScript within existing CLI package for shared UX and testability.
35+
- Extract shell script checks into reusable TS utilities to avoid behavior drift.
36+
- Git checks via lightweight git commands (`git worktree list`, branch existence checks) to preserve compatibility.
37+
38+
## Data Models
39+
**What data do we need to manage?**
40+
41+
- Core entities and their relationships
42+
- `LintOptions`: parsed CLI options.
43+
- `LintTarget`: normalized feature identity (`name`, `branchName`, `docSlug`).
44+
- `LintCheckResult`: result of individual check.
45+
- `LintSummary`: aggregate counts and final status.
46+
- Data schemas/structures
47+
- `LintOptions`
48+
- `{ feature?: string, json?: boolean }`
49+
- `LintTarget`
50+
- `{ rawFeature: string, normalizedName: string, branchName: string, docFilePrefix: string }`
51+
- `LintCheckResult`
52+
- `{ id: string, level: 'ok' | 'miss' | 'warn', category: 'base-docs' | 'feature-docs' | 'git-worktree', required: boolean, message: string, fix?: string }`
53+
- `LintSummary`
54+
- `{ checks: LintCheckResult[], hasRequiredFailures: boolean, warningCount: number }`
55+
- Data flow between components
56+
- Parse args -> normalize feature -> run applicable checks -> collect results -> render terminal or JSON output -> return exit code.
57+
58+
## API Design
59+
**How do components communicate?**
60+
61+
- External APIs (if applicable)
62+
- CLI invocations:
63+
- `ai-devkit lint`
64+
- `ai-devkit lint --feature <name>`
65+
- `ai-devkit lint --feature <name> --json`
66+
- Internal interfaces
67+
- `runLintChecks(options, dependencies?): LintReport`
68+
- `renderLintReport(report, options): void` (in `commands/lint`)
69+
- `normalizeFeatureName(input): string`
70+
- `isInsideGitWorkTreeSync(cwd): boolean`
71+
- `localBranchExistsSync(cwd, branchName): boolean`
72+
- `getWorktreePathsForBranchSync(cwd, branchName): string[]`
73+
- Request/response formats
74+
- Input: CLI flags and current working directory.
75+
- Output:
76+
- Default: human-readable checklist and summary.
77+
- `--json`: structured JSON object for CI parsing (checks, counts, normalized feature, pass/fail state).
78+
- Exit code policy:
79+
- `0`: no required failures.
80+
- `1`: one or more required failures.
81+
- Warnings (including missing dedicated worktree) do not change exit code when required checks pass.
82+
- Authentication/authorization approach
83+
- Read-only operations only (filesystem + git metadata queries).
84+
85+
## Component Breakdown
86+
**What are the major building blocks?**
87+
88+
- Frontend components (if applicable)
89+
- Terminal output formatter using existing CLI conventions.
90+
- JSON formatter for machine-readable mode.
91+
- Backend services/modules
92+
- `commands/lint` command entry.
93+
- `services/lint/lint.service.ts` for orchestration and business rules only.
94+
- `services/lint/rules/*` for modular validation rules (base docs, feature docs, feature-name, git worktree).
95+
- `util/git` sync helpers for git/worktree checks.
96+
- `util/terminal-ui` for consistent terminal output formatting.
97+
- Database/storage layer
98+
- None.
99+
- Third-party integrations
100+
- Local git executable.
101+
102+
## Design Decisions
103+
**Why did we choose this approach?**
104+
105+
- Key architectural decisions and trade-offs
106+
- Re-implement shell checks in TypeScript while keeping output semantics:
107+
- Pros: testable, reusable, cross-command integration.
108+
- Cons: initial duplication until script is retired/repointed.
109+
- Classify checks as required vs warning:
110+
- Pros: keeps lifecycle gating strict for missing docs while allowing advisory worktree guidance.
111+
- Cons: users may ignore warnings if not enforced in team policy.
112+
- Normalize feature names automatically:
113+
- Pros: better UX (`foo` and `feature-foo` both accepted).
114+
- Cons: requires clear messaging of normalized value.
115+
- Include `--json` output in v1:
116+
- Pros: CI-friendly parsing and automated reporting.
117+
- Cons: requires stable output schema maintenance.
118+
- Alternatives considered
119+
- Keep shell script only and wrap it from CLI:
120+
- Rejected due to weaker cross-platform consistency and lower unit-test coverage.
121+
- Hard-fail when dedicated worktree is missing:
122+
- Rejected; requirement is warning-only behavior for this condition.
123+
- Patterns and principles applied
124+
- Single-responsibility check modules.
125+
- Deterministic output for CI and humans.
126+
- Collect-all-results reporting to surface all issues in one run.
127+
- Avoid shell interpolation for git operations by using argument-based command execution.
128+
129+
## Non-Functional Requirements
130+
**How should the system perform?**
131+
132+
- Performance targets
133+
- Complete typical checks in under 1 second on standard repositories.
134+
- Scalability considerations
135+
- Check implementation should be extensible for additional lifecycle validations later.
136+
- Security requirements
137+
- No file writes or mutations.
138+
- No network access required.
139+
- Reliability/availability needs
140+
- Command should gracefully handle missing git repo context and provide actionable fixes.

‎docs/ai/implementation/feature-lint-command.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
phase: implementation
3+
title: Implementation Guide
4+
description: Technical implementation notes, patterns, and code guidelines
5+
---
6+
7+
# Implementation Guide
8+
9+
## Development Setup
10+
**How do we get started?**
11+
12+
- `npm install` at repository root.
13+
- CLI package local validation commands:
14+
- `npm run lint` (from `packages/cli`)
15+
- `nx run cli:test -- --runInBand lint.test.ts` (from repo root)
16+
17+
## Code Structure
18+
**How is the code organized?**
19+
20+
- `packages/cli/src/cli.ts`
21+
- Registers new `lint` command and options (`--feature`, `--json`).
22+
- `packages/cli/src/commands/lint.ts`
23+
- Command entrypoint that runs checks, renders output, and sets process exit code.
24+
- `packages/cli/src/services/lint/lint.service.ts`
25+
- Core lint orchestration and business logic only (no terminal rendering).
26+
- `packages/cli/src/services/lint/rules/`
27+
- Rule modules split by concern (`base-docs`, `feature-name`, `feature-docs`, `git-worktree`).
28+
- `packages/cli/src/__tests__/services/lint/lint.test.ts`
29+
- Unit coverage for normalization and check outcomes.
30+
- `packages/cli/src/__tests__/commands/lint.test.ts`
31+
- Command-level coverage for orchestration and exit-code behavior.
32+
33+
## Implementation Notes
34+
**Key technical details to remember:**
35+
36+
### Core Features
37+
- Base readiness checks validate `docs/ai/{requirements,design,planning,implementation,testing}/README.md`.
38+
- Feature mode normalizes `feature-<name>` and `<name>` into a shared `normalizedName`.
39+
- Feature names are validated as kebab-case before running feature-level checks.
40+
- Feature mode validates lifecycle docs:
41+
- `docs/ai/{phase}/feature-<normalizedName>.md`
42+
- Git validation behavior:
43+
- Missing git repository => required failure.
44+
- Missing `feature-<name>` branch => required failure.
45+
- Missing dedicated worktree for branch => warning only.
46+
- Command rendering supports:
47+
- human-readable checklist output
48+
- JSON report output with summary and per-check metadata
49+
50+
### Patterns & Best Practices
51+
- `runLintChecks` accepts injected dependencies (`cwd`, `existsSync`, `execFileSync`) for testability.
52+
- Shared phase-doc rule helper keeps base/feature doc checks consistent while avoiding duplication.
53+
- Check results use a normalized shape (`LintCheckResult`) so rendering and JSON use one source of truth.
54+
- Required failures drive exit code; warnings are advisory only.
55+
56+
## Integration Points
57+
**How do pieces connect?**
58+
59+
- CLI wiring: Commander action in `packages/cli/src/cli.ts` calls `lintCommand`.
60+
- `lintCommand` delegates to `runLintChecks` then `renderLintReport`.
61+
- `lint.service` composes rule modules and uses `util/git` sync helpers to query `git rev-parse`, `git show-ref`, and `git worktree list --porcelain`.
62+
- `commands/lint` owns `renderLintReport` and uses `util/terminal-ui` for consistent user-facing output.
63+
64+
## Error Handling
65+
**How do we handle failures?**
66+
67+
- Git command failures are converted into deterministic lint results (miss or warn), not thrown errors.
68+
- Missing files are reported with explicit path and remediation guidance.
69+
- Output includes suggested fixes (for example `npx ai-devkit init`, `git worktree add ...`).
70+
71+
## Performance Considerations
72+
**How do we keep it fast?**
73+
74+
- Uses direct existence checks and small git commands only.
75+
- No recursive repository scans or network calls.
76+
77+
## Security Notes
78+
**What security measures are in place?**
79+
80+
- Read-only filesystem and git metadata checks only.
81+
- No mutation of repository state.
82+
- Git commands use argument-based process execution (`execFileSync`) to avoid shell interpolation risks from user input.
83+
84+
## Phase 6 Check Implementation
85+
86+
- Design/requirements alignment: aligned for command surface, normalization, check categories, and exit behavior.
87+
- Deviations and gaps:
88+
- Full CLI binary execution via `npm run dev -- lint ...` is currently blocked by unrelated pre-existing TypeScript errors in `src/commands/memory.ts`.
89+
90+
## Phase 8 Code Review
91+
92+
- Blocking issue found and resolved:
93+
- `packages/cli/src/services/lint/lint.service.ts`: replaced shell-command interpolation with argument-based git execution and added feature-name validation.
94+
- Remaining non-blocking gap:
95+
- Full CLI binary execution remains blocked by unrelated pre-existing TypeScript issues outside this feature.

‎docs/ai/planning/feature-lint-command.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
phase: planning
3+
title: Project Planning & Task Breakdown
4+
description: Break down work into actionable tasks and estimate timeline
5+
---
6+
7+
# Project Planning & Task Breakdown
8+
9+
## Milestones
10+
**What are the major checkpoints?**
11+
12+
- [x] Milestone 1: Lint requirements/design approved
13+
- [x] Milestone 2: `ai-devkit lint` base + feature checks implemented
14+
- [x] Milestone 3: Tests, docs, and rollout complete
15+
16+
## Task Breakdown
17+
**What specific work needs to be done?**
18+
19+
### Phase 1: Foundation
20+
- [x] Task 1.1: Audit current CLI command registration and identify insertion point for `lint`
21+
- [x] Task 1.2: Extract/reimplement `check-docs.sh` base and feature doc checks in TypeScript utilities
22+
- [x] Task 1.3: Implement feature-name normalization utility (`foo` and `feature-foo` -> `foo`)
23+
- [x] Task 1.4: Define shared lint result model and formatter (`ok/miss/warn`, remediation hints)
24+
25+
### Phase 2: Core Features
26+
- [x] Task 2.1: Add `ai-devkit lint` command handler with base workspace checks
27+
- [x] Task 2.2: Add `--feature <name>` mode with feature doc checks across all lifecycle phases
28+
- [x] Task 2.3: Add git checks for `feature-<name>` branch/worktree presence and mapping
29+
- [x] Task 2.4: Ensure proper exit codes and summary output for CI compatibility
30+
31+
### Phase 3: Integration & Polish
32+
- [x] Task 3.1: Update help text and README command documentation
33+
- [x] Task 3.2: Decide whether to keep `skills/dev-lifecycle/scripts/check-docs.sh` as wrapper or migrate references to `ai-devkit lint`
34+
- [x] Task 3.3: Add actionable remediation guidance in failures (`npx ai-devkit init`, worktree creation command)
35+
- [x] Task 3.4: Validate behavior against existing lifecycle docs and feature naming conventions
36+
37+
### Phase 4: Validation
38+
- [x] Task 4.1: Unit tests for base docs checks and feature docs checks
39+
- [x] Task 4.2: Unit tests for feature normalization and git/worktree validation logic
40+
- [x] Task 4.3: Integration tests for CLI exit codes and terminal output
41+
- [x] Task 4.4: Manual verification on repositories with and without required docs/worktrees
42+
43+
## Dependencies
44+
**What needs to happen in what order?**
45+
46+
- Task dependencies and blockers
47+
- Command registration and result model must be in place before integration tests.
48+
- Feature-name normalization should be implemented before feature doc and git checks.
49+
- Git check module should be stable before finalizing remediation messages.
50+
- External dependencies (APIs, services, etc.)
51+
- Local git executable availability for feature-level checks.
52+
- Team/resource dependencies
53+
- Maintainer review for lifecycle workflow compatibility and naming conventions.
54+
55+
## Timeline & Estimates
56+
**When will things be done?**
57+
58+
- Estimated effort per task/phase
59+
- Phase 1: 0.5-1 day
60+
- Phase 2: 1-1.5 days
61+
- Phase 3: 0.5 day
62+
- Phase 4: 0.5-1 day
63+
- Target dates for milestones
64+
- Milestone 1: day 1
65+
- Milestone 2: day 2-3
66+
- Milestone 3: day 3-4
67+
- Buffer for unknowns
68+
- +20% for git/worktree edge-case handling and cross-platform output differences
69+
70+
## Risks & Mitigation
71+
**What could go wrong?**
72+
73+
- Technical risks
74+
- Git worktree detection may vary by repo state and user flow.
75+
- Divergence between shell script and new TypeScript checks can cause inconsistent behavior.
76+
- Resource risks
77+
- Limited test coverage for unusual git/worktree layouts.
78+
- Dependency risks
79+
- Existing scripts or docs may still assume `check-docs.sh` behavior/output.
80+
- Mitigation strategies
81+
- Add fixture-based tests for multiple git states.
82+
- Keep output mapping close to existing `check-docs.sh` semantics initially.
83+
- Update docs and scripts in same change to avoid workflow drift.
84+
85+
## Resources Needed
86+
**What do we need to succeed?**
87+
88+
- Team members and roles
89+
- CLI implementer and reviewer
90+
- Tools and services
91+
- Existing TypeScript unit/integration test tooling
92+
- Infrastructure
93+
- Local git repo fixtures for worktree tests
94+
- Documentation/knowledge
95+
- Dev-lifecycle skill conventions and existing `check-docs.sh` behavior

0 commit comments

Comments
 (0)