Skip to content

feature-lint-command.md

Latest commit

 

History

History
95 lines (75 loc) · 4.15 KB

feature-lint-command.md

File metadata and controls

95 lines (75 loc) · 4.15 KB
phase implementation
title Implementation Guide
description Technical implementation notes, patterns, and code guidelines

Implementation Guide

Development Setup

How do we get started?

  • npm install at repository root.
  • CLI package local validation commands:
    • npm run lint (from packages/cli)
    • nx run cli:test -- --runInBand lint.test.ts (from repo root)

Code Structure

How is the code organized?

  • packages/cli/src/cli.ts
    • Registers new lint command and options (--feature, --json).
  • packages/cli/src/commands/lint.ts
    • Command entrypoint that runs checks, renders output, and sets process exit code.
  • packages/cli/src/services/lint/lint.service.ts
    • Core lint orchestration and business logic only (no terminal rendering).
  • packages/cli/src/services/lint/rules/
    • Rule modules split by concern (base-docs, feature-name, feature-docs, git-worktree).
  • packages/cli/src/__tests__/services/lint/lint.test.ts
    • Unit coverage for normalization and check outcomes.
  • packages/cli/src/__tests__/commands/lint.test.ts
    • Command-level coverage for orchestration and exit-code behavior.

Implementation Notes

Key technical details to remember:

Core Features

  • Base readiness checks validate docs/ai/{requirements,design,planning,implementation,testing}/README.md.
  • Feature mode normalizes feature-<name> and <name> into a shared normalizedName.
  • Feature names are validated as kebab-case before running feature-level checks.
  • Feature mode validates lifecycle docs:
    • docs/ai/{phase}/feature-<normalizedName>.md
  • Git validation behavior:
    • Missing git repository => required failure.
    • Missing feature-<name> branch => required failure.
    • Missing dedicated worktree for branch => warning only.
  • Command rendering supports:
    • human-readable checklist output
    • JSON report output with summary and per-check metadata

Patterns & Best Practices

  • runLintChecks accepts injected dependencies (cwd, existsSync, execFileSync) for testability.
  • Shared phase-doc rule helper keeps base/feature doc checks consistent while avoiding duplication.
  • Check results use a normalized shape (LintCheckResult) so rendering and JSON use one source of truth.
  • Required failures drive exit code; warnings are advisory only.

Integration Points

How do pieces connect?

  • CLI wiring: Commander action in packages/cli/src/cli.ts calls lintCommand.
  • lintCommand delegates to runLintChecks then renderLintReport.
  • lint.service composes rule modules and uses util/git sync helpers to query git rev-parse, git show-ref, and git worktree list --porcelain.
  • commands/lint owns renderLintReport and uses util/terminal-ui for consistent user-facing output.

Error Handling

How do we handle failures?

  • Git command failures are converted into deterministic lint results (miss or warn), not thrown errors.
  • Missing files are reported with explicit path and remediation guidance.
  • Output includes suggested fixes (for example npx ai-devkit init, git worktree add ...).

Performance Considerations

How do we keep it fast?

  • Uses direct existence checks and small git commands only.
  • No recursive repository scans or network calls.

Security Notes

What security measures are in place?

  • Read-only filesystem and git metadata checks only.
  • No mutation of repository state.
  • Git commands use argument-based process execution (execFileSync) to avoid shell interpolation risks from user input.

Phase 6 Check Implementation

  • Design/requirements alignment: aligned for command surface, normalization, check categories, and exit behavior.
  • Deviations and gaps:
    • Full CLI binary execution via npm run dev -- lint ... is currently blocked by unrelated pre-existing TypeScript errors in src/commands/memory.ts.

Phase 8 Code Review

  • Blocking issue found and resolved:
    • packages/cli/src/services/lint/lint.service.ts: replaced shell-command interpolation with argument-based git execution and added feature-name validation.
  • Remaining non-blocking gap:
    • Full CLI binary execution remains blocked by unrelated pre-existing TypeScript issues outside this feature.