Implement the 031-quality-gates-hygiene feature that strengthens automated quality gates by adding pnpm audit to the check script, v8 coverage thresholds with per-directory auto-ratchet (domain 96%, adapters 71%, persistence 87%), Biome cognitive complexity enforcement (max 15), and keyboard accessibility for the combatant row, while cleaning up all blanket biome-ignore comments, refactoring 5 overly complex functions into smaller helpers, and codifying the early-enforcement principle in the constitution and CLAUDE.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lukas
144
specs/031-quality-gates-hygiene/spec.md
Normal file
144
specs/031-quality-gates-hygiene/spec.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Feature Specification: Quality Gates & Code Hygiene
|
||||
|
||||
**Feature Branch**: `031-quality-gates-hygiene`
|
||||
**Created**: 2026-03-10
|
||||
**Status**: Draft
|
||||
**Input**: User description: "Refine constitution early enforcement principle, add Vitest coverage thresholds, Biome cognitive complexity rule, pnpm audit in check script, fix biome-ignore hygiene, review Biome a11y rules"
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### User Story 1 - Constitution codifies early enforcement (Priority: P1)
|
||||
|
||||
A contributor reads the constitution and CLAUDE.md and understands that every automated quality gate MUST run at the earliest feasible enforcement point — currently pre-commit via Lefthook's `pnpm check`. No gate may exist only as a CI step or manual process.
|
||||
|
||||
**Why this priority**: This principle governs all other items in the feature; without it, the remaining gates lack authoritative backing.
|
||||
|
||||
**Independent Test**: Can be verified by reading the updated constitution and CLAUDE.md and confirming the early-enforcement language is present.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the constitution's Development Workflow section, **When** a reader reviews it, **Then** there is an explicit rule stating all automated quality gates MUST run at the earliest feasible enforcement point (currently pre-commit).
|
||||
2. **Given** CLAUDE.md, **When** a reader reviews it, **Then** the early-enforcement principle is reflected operationally in the Commands or Conventions section.
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - Test coverage thresholds prevent regressions (Priority: P1)
|
||||
|
||||
A contributor runs `pnpm check` and coverage is measured automatically. If coverage drops below the configured thresholds (initial: lines 70%, branches 60%), the check fails. Thresholds ratchet upward automatically as coverage improves.
|
||||
|
||||
**Why this priority**: Coverage thresholds are the most impactful new gate — they catch untested code before it reaches the repository.
|
||||
|
||||
**Independent Test**: Can be tested by running `pnpm check` and verifying coverage is reported and thresholds are enforced.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the project with current test suite, **When** a contributor runs `pnpm check`, **Then** test coverage is measured using the v8 provider and reported.
|
||||
2. **Given** coverage thresholds configured at lines: 70, branches: 60, **When** a change drops coverage below either threshold, **Then** `pnpm check` fails.
|
||||
3. **Given** `thresholds.autoUpdate: true`, **When** coverage exceeds the configured thresholds, **Then** the thresholds are automatically ratcheted upward in the config file.
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - Cognitive complexity catches overly complex functions (Priority: P2)
|
||||
|
||||
A contributor writes a function with cognitive complexity exceeding 15. Biome flags it during `pnpm check`, prompting the contributor to refactor.
|
||||
|
||||
**Why this priority**: Directly supports the Deterministic Domain Core principle by keeping pure functions small and understandable, but is less impactful than coverage gates.
|
||||
|
||||
**Independent Test**: Can be tested by writing a function with complexity > 15 and verifying Biome reports an error.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** Biome configured with `noExcessiveCognitiveComplexity` at threshold 15, **When** `pnpm check` runs against a function exceeding that threshold, **Then** Biome reports a lint error.
|
||||
2. **Given** all existing code in the repository, **When** the rule is enabled, **Then** no existing code violates the threshold (or violations are addressed).
|
||||
|
||||
---
|
||||
|
||||
### User Story 4 - Dependency audit catches known CVEs (Priority: P2)
|
||||
|
||||
A contributor runs `pnpm check` and known high-severity dependency vulnerabilities are flagged before commit.
|
||||
|
||||
**Why this priority**: Security hygiene is important but the blast radius is smaller than coverage or complexity — it catches external dependency issues rather than code quality.
|
||||
|
||||
**Independent Test**: Can be tested by running `pnpm check` and verifying audit runs with `--audit-level=high`.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** `pnpm audit --audit-level=high` is wired into `pnpm check`, **When** a contributor runs `pnpm check`, **Then** the audit step executes.
|
||||
2. **Given** no high-severity advisories exist in the current dependency tree, **When** `pnpm check` runs, **Then** the audit step passes.
|
||||
3. **Given** a high-severity advisory exists, **When** `pnpm check` runs, **Then** the check fails and the advisory is reported.
|
||||
|
||||
---
|
||||
|
||||
### User Story 5 - Biome-ignore comments are hygienic (Priority: P2)
|
||||
|
||||
All `biome-ignore` comments in the codebase specify the exact rule being suppressed. Blanket `biome-ignore lint:` comments are eliminated. The number of total ignores is reduced where possible.
|
||||
|
||||
**Why this priority**: Code hygiene — blanket ignores silently suppress future rules and mask technical debt.
|
||||
|
||||
**Independent Test**: Can be tested by searching the codebase for `biome-ignore` comments and verifying none use blanket `lint:` form.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** `packages/domain/src/set-initiative.ts` line 65, **When** the blanket `biome-ignore lint:` is removed, **Then** the code is refactored so no ignore is needed (e.g., inline undefined checks or narrowing).
|
||||
2. **Given** `apps/web/src/components/combatant-row.tsx` with 8 a11y ignores (4 pairs of `useKeyWithClickEvents` + `noStaticElementInteractions`), **When** the clickable wrapper divs are refactored, **Then** the number of biome-ignore comments is reduced (ideally eliminated) by using semantic elements or a shared wrapper component.
|
||||
3. **Given** the full codebase, **When** searched for `biome-ignore lint:` (blanket form without a specific rule), **Then** zero results are found.
|
||||
|
||||
---
|
||||
|
||||
### User Story 6 - Biome a11y rules are comprehensive (Priority: P3)
|
||||
|
||||
The Biome configuration explicitly enables relevant non-recommended a11y rules that benefit this React UI app, beyond what `recommended: true` provides by default.
|
||||
|
||||
**Why this priority**: Incremental improvement — the app already has `recommended: true` covering stable a11y rules. Non-recommended rules add coverage but are lower urgency.
|
||||
|
||||
**Independent Test**: Can be tested by reviewing `biome.json` and verifying a11y nursery rules are explicitly listed.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** Biome 2.0 with `recommended: true`, **When** a developer reviews `biome.json`, **Then** relevant non-recommended a11y rules are explicitly enabled.
|
||||
2. **Given** the newly enabled rules, **When** `pnpm check` runs against the existing codebase, **Then** no new violations are introduced (or all violations are fixed).
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- What happens when `pnpm audit` finds a vulnerability in a dev-only dependency? The `--audit-level=high` flag filters by severity, not dependency type — dev-only high-severity CVEs still fail the check.
|
||||
- What happens when `thresholds.autoUpdate` writes to the config file? The updated thresholds file should be committed by the contributor as part of their change.
|
||||
- What happens if Biome nursery rules produce false positives? Individual false positives can be suppressed with rule-specific `biome-ignore` comments (never blanket ignores).
|
||||
- What happens if `pnpm audit` is slow or unavailable offline? The audit command may fail if the registry is unreachable; contributors working offline may need to skip the check temporarily (acceptable trade-off for pre-commit enforcement).
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: The constitution's Development Workflow section MUST include an explicit early-enforcement principle stating all automated quality gates run at the earliest feasible enforcement point.
|
||||
- **FR-002**: CLAUDE.md MUST reflect the early-enforcement principle operationally.
|
||||
- **FR-003**: Vitest MUST be configured with the v8 coverage provider and initial thresholds of lines: 70, branches: 60.
|
||||
- **FR-004**: Vitest coverage MUST have `thresholds.autoUpdate: true` enabled so thresholds ratchet upward.
|
||||
- **FR-005**: Coverage enforcement MUST be wired into `pnpm check`.
|
||||
- **FR-006**: Biome MUST have `noExcessiveCognitiveComplexity` enabled with the default threshold (15).
|
||||
- **FR-007**: `pnpm audit --audit-level=high` MUST be added to the `pnpm check` script.
|
||||
- **FR-008**: The blanket `biome-ignore lint:` in `set-initiative.ts` MUST be replaced with either a rule-specific ignore or (preferably) a code fix that eliminates the need for any ignore.
|
||||
- **FR-009**: The 8 a11y ignores in `combatant-row.tsx` MUST be reduced by refactoring clickable wrapper divs to use semantic elements or a shared wrapper component.
|
||||
- **FR-010**: No `biome-ignore lint:` (blanket form) may exist anywhere in the codebase after implementation.
|
||||
- **FR-011**: Relevant non-recommended Biome a11y rules MUST be explicitly enabled in `biome.json`.
|
||||
- **FR-012**: All changes MUST pass `pnpm check` after implementation.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The v8 coverage provider is compatible with the existing Vitest setup (Vitest 3.x supports v8 natively).
|
||||
- Initial coverage thresholds (lines: 70, branches: 60) are conservative enough that the current test suite passes without needing to add tests.
|
||||
- Biome 2.0's `noExcessiveCognitiveComplexity` default threshold of 15 is reasonable for existing code — no existing functions exceed it.
|
||||
- The project's current dependencies have no high-severity advisories (pnpm audit passes cleanly).
|
||||
- Non-recommended Biome a11y rules are stable enough for pre-commit enforcement and won't produce excessive false positives.
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: `pnpm check` enforces all six gate types: unused code (knip), formatting/linting (biome), type checking (tsc), tests with coverage (vitest), copy-paste detection (jscpd), and dependency audit (pnpm audit).
|
||||
- **SC-002**: Test coverage thresholds are enforced and automatically ratchet upward — no manual maintenance needed.
|
||||
- **SC-003**: Zero blanket `biome-ignore lint:` comments remain in the codebase.
|
||||
- **SC-004**: The total number of `biome-ignore` comments in `combatant-row.tsx` is reduced from 8 to 4 or fewer.
|
||||
- **SC-005**: The constitution and CLAUDE.md explicitly document the early-enforcement principle.
|
||||
- **SC-006**: All existing code passes `pnpm check` with the new gates enabled — no regressions.
|
||||
Reference in New Issue
Block a user