125 lines
8.6 KiB
Markdown
125 lines
8.6 KiB
Markdown
# Quality and Architecture Remediation Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Make coverage, scenario, CI, and architecture gates measure executable production behavior and fail when their measured universe is empty or incomplete.
|
|
|
|
**Architecture:** One typed gate schema drives both the local runner and generated workflow. Coverage separates repository inventory from instrumented totals. The Babel/resolver graph is the sole architecture authority while TypeScript 7 is unsupported by dependency-cruiser.
|
|
|
|
**Tech Stack:** TypeScript 7, Node.js 24, Babel parser, Vitest 4, Playwright, Gitea Actions.
|
|
|
|
## Global Constraints
|
|
|
|
- A zero-file or zero-module result is failure, never success.
|
|
- High-risk changed modules need explicit coverage ownership or an owned, expiring waiver.
|
|
- Scenario declarations count only when a table-driven test executes all required assertions.
|
|
- Checked-in workflow content is generated deterministically from the same gate model used locally.
|
|
- Every enforcement change begins with a failing fixture.
|
|
|
|
---
|
|
|
|
### Task 1: Repository-aware risk coverage
|
|
|
|
**Files:**
|
|
- Modify: `vitest.config.ts`
|
|
- Modify: `config/testing/risk-coverage.json`
|
|
- Modify: `scripts/check-risk-coverage.ts`
|
|
- Modify: `tests/fixtures/coverage/below-threshold.json`
|
|
- Create: `tests/fixtures/coverage/repository-omission.json`
|
|
- Create: `tests/unit/risk-coverage.test.ts`
|
|
|
|
- [ ] Add tests asserting `selectedTotal`, `repositoryTotal`, uncovered repository modules, and changed high-risk ownership. A summary covering 14 files while production inventory is larger must fail.
|
|
- [ ] Run `corepack pnpm exec vitest run tests/unit/risk-coverage.test.ts` and confirm RED because only selected totals exist.
|
|
- [ ] Enumerate every production `.ts`/`.tsx` module under `src`, exclude declarations/stories/generated files explicitly, and emit both totals. Expand coverage instrumentation to `src/**/*.{ts,tsx}` with documented exclusions.
|
|
- [ ] Seed the critical registry with HTTP V3, bounded request/response readers, boot bounds, Service Worker lifecycle, scope generation, and release loading. Validate waiver owner, reason, and future expiry.
|
|
- [ ] Run focused tests and `corepack pnpm test:coverage`; commit with `git commit -m "fix: measure repository-wide risk coverage"`.
|
|
|
|
### Task 2: Executable HTTP scenario catalog
|
|
|
|
**Files:**
|
|
- Modify: `tests/mocks/scenarios/catalog.ts`
|
|
- Create: `tests/integration/http-scenario-catalog.test.ts`
|
|
- Modify: `tests/mocks/handlers/reference-resources.ts`
|
|
- Modify: `scripts/check-test-evidence.ts`
|
|
- Modify: `config/testing/test-evidence.json`
|
|
|
|
- [ ] Define typed expectations for status/outcome/effect/retry/fetch count/media type/body bound/scope fence for every declared scenario.
|
|
- [ ] Add a table-driven test that executes each operation/scenario pair through `ContractHttpExecutor` and asserts every expectation field. Add a deliberately declared-but-unexecuted fixture and make the evidence checker reject it.
|
|
- [ ] Run `corepack pnpm exec vitest run tests/integration/http-scenario-catalog.test.ts && node scripts/check-test-evidence.ts` and confirm RED because the current gate counts source tokens.
|
|
- [ ] Export execution receipts from the test artifact and make the checker compare exact catalog IDs to exact executed IDs; source-token counts become diagnostics only.
|
|
- [ ] Re-run tests/checker and commit with `git commit -m "test: execute the HTTP scenario catalog"`.
|
|
|
|
### Task 3: Shared CI gate schema and deterministic workflow generation
|
|
|
|
**Files:**
|
|
- Create: `scripts/contracts/ci-gates.ts`
|
|
- Create: `scripts/generate-ci-workflow.ts`
|
|
- Modify: `scripts/run-ci-gate.ts`
|
|
- Modify: `config/ci/gates.json`
|
|
- Modify: `.gitea/workflows/quality-gates.yml`
|
|
- Create: `tests/unit/ci-workflow-generation.test.ts`
|
|
|
|
- [ ] Add invalid gate fixtures for unknown fields, duplicate IDs, missing artifact schemas, unknown dependencies, and cycles. Add a snapshot test for the full generated workflow plus `--check` drift.
|
|
- [ ] Run `corepack pnpm exec vitest run tests/unit/ci-workflow-generation.test.ts` and confirm RED because no shared parser/generator exists.
|
|
- [ ] Parse gates once with strict Zod schemas. Generate every job, dependency, command, environment mapping, timeout, artifact upload/download, and schema validation deterministically.
|
|
- [ ] Replace regex/token workflow checks with `node scripts/generate-ci-workflow.ts --check`; generated YAML must match byte-for-byte.
|
|
- [ ] Re-run tests and check mode; commit with `git commit -m "refactor: generate CI workflow from gate contracts"`.
|
|
|
|
### Task 3b: Semantic validation for every CI evidence format
|
|
|
|
**Files:**
|
|
- Modify: `scripts/contracts/release-artifacts.ts`
|
|
- Modify: producer scripts for the remaining generic JSON evidence
|
|
- Modify: `scripts/lib/ci-artifact-validator.ts`
|
|
- Modify: `config/ci/gates.json`
|
|
- Modify: `tests/unit/ci-artifact-contract.test.ts`
|
|
|
|
- [x] Inventory every artifact still mapped to `generic-json-object` and export/reuse the producer's strict schema, including cross-field status/failure/count invariants. Do not treat a non-empty JSON object as semantic evidence.
|
|
- [x] Replace substring-only JUnit/HTML acceptance with bounded well-formed document validation. Reject DTD/entities, malformed nesting, duplicate/invalid roots, and trailing non-whitespace content.
|
|
- [x] Add invalid-but-pattern-matching fixtures for all structured kinds and a table proving every configured artifact resolves to a semantic validator.
|
|
- [ ] Run focused artifact tests, `corepack pnpm check:ci`, types, lint, and diff checks; commit separately so this evidence-quality closeout is independently reviewable.
|
|
|
|
### Task 4: One authoritative architecture graph
|
|
|
|
**Files:**
|
|
- Modify: `scripts/check-architecture.ts`
|
|
- Modify: `config/architecture/layers.json`
|
|
- Modify: `.dependency-cruiser.json`
|
|
- Create: `tests/fixtures/architecture/forbidden/contracts-import-application.ts`
|
|
- Create: `tests/fixtures/architecture/forbidden/feature-adapter-imports-global-adapter.ts`
|
|
- Create: `tests/unit/architecture-policy.test.ts`
|
|
|
|
- [ ] Add fixtures proving contracts cannot import application/runtime layers, feature adapters cannot import concrete global adapters, unresolved imports fail, cycles fail, and a zero-module root fails.
|
|
- [ ] Run `corepack pnpm exec vitest run tests/unit/architecture-policy.test.ts` and confirm missing rules/zero-module behavior fail.
|
|
- [ ] Make the Babel parser plus Node/TS resolver graph authoritative. Keep dependency-cruiser output informational while it sees zero TS7 modules, and explicitly fail authoritative counts of zero modules or zero dependencies in a non-empty source tree.
|
|
- [ ] Add the two dependency-direction rules to the typed layer policy and ensure aliases/extensions resolve identically to TypeScript.
|
|
- [ ] Run focused tests and `corepack pnpm check:architecture`; commit with `git commit -m "fix: enforce architecture with the TS7 graph"`.
|
|
|
|
### Task 5: Test hygiene and production read/write E2E
|
|
|
|
**Files:**
|
|
- Modify: `vitest.config.ts`
|
|
- Modify: `tests/setup.ts`
|
|
- Modify: `playwright.config.ts`
|
|
- Modify: `playwright.dev.config.ts`
|
|
- Modify: `playwright.storybook.config.ts`
|
|
- Modify: `playwright.visual.config.ts`
|
|
- Create: `tests/e2e/reference-resource-write.spec.ts`
|
|
- Modify: `scripts/check-test-evidence.ts`
|
|
|
|
- [ ] Add a fixture containing `.only` and a leaking fake timer; assert the gate rejects/isolation restores them. Assert every Playwright config resolves `forbidOnly: true`.
|
|
- [ ] Add E2E that loads a real mocked GET response, submits POST, verifies request body/header contract, verifies response-rendered resource, then reloads and verifies read-after-write.
|
|
- [ ] Run focused Vitest and Playwright tests and confirm RED for inherited configs/current shallow E2E.
|
|
- [ ] Enable Vitest sequence hook that rejects `.only`, restore real timers in common `afterEach`, and centralize a Playwright base config with `forbidOnly: true` inherited by all configs.
|
|
- [ ] Make E2E evidence require both observed response and observed mutation receipt.
|
|
- [ ] Re-run supported tests; commit with `git commit -m "test: harden test isolation and read-write E2E"`.
|
|
|
|
### Task 6: Quality verification
|
|
|
|
- [ ] Run `corepack pnpm check:architecture`.
|
|
- [ ] Run `corepack pnpm test:coverage`.
|
|
- [ ] Run `node scripts/check-test-evidence.ts`.
|
|
- [ ] Run `node scripts/generate-ci-workflow.ts --check`.
|
|
- [ ] Run `corepack pnpm test:all`, `corepack pnpm check:types`, `corepack pnpm lint`, and `git diff --check`.
|
|
- [ ] Run browser/E2E gates only when the environment supports them and report exact commands separately.
|