Codebase audit 2026-04-17: consolidated tech-debt & quality findings

[rucka]

Context

Codebase-wide audit eseguito il 2026-04-17 componendo manualmente le capability skills (verify-quality, verify-adoption, assess-stack, assess-testing, verify-done, assess-debt, assess-code-quality) che normalmente /pair-process-review applicherebbe a una PR — qui applicate all'intera codebase.

Verdict: HEALTHY — TECH-DEBT tracked. Nessun finding critico bloccante. Quality gate + smoke + E2E verdi (1479 test), adoption compliant, architecture OK. Gli item sotto sono cleanup / refactor da schedulare.

Segnali di salute (baseline positiva)

• 0 TODO/FIXME/HACK in codice di produzione
• 0 .skip / xit / it.todo
• 0 @ts-ignore / @ts-expect-error / @ts-nocheck
• 0 eslint-disable (fuori dal detector di hygiene)
• 1 solo residuo :any in tutto src/ (item P2.1)
• Test/source ratio ~59% LoC
• code-hygiene-check.js + docs-staleness-check.js wired in pnpm quality-gate
• Code quality score stimato: ~72/100 (MEDIUM-HIGH)

P0 — high impact, low effort

P0.1 — CI silent-failure masking

.github/workflows/ci.yml (righe ~61-67): gli step ts:check / build / lint terminano con || echo \"No ... script defined\". Mascherano fallimenti reali del job. Rimuovere i suffissi || echo.

P0.2 — Workspace catalog drift in content-ops

packages/content-ops/package.json:

• riga 52: \"@types/adm-zip\": \"^0.5.5\" (catalog ha 0.5.7)
• riga 63: \"adm-zip\": \"^0.5.9\" (catalog ha 0.5.16)

Sostituire con \"catalog:\". Se la divergenza è intenzionale, registrare un ADL in .pair/adoption/decision-log/.

P0.3 — Monster test file: cli.e2e.test.ts

apps/pair-cli/src/cli.e2e.test.ts → 1507 LOC in un solo file. Split per comando (install / update / kb-validate / update-link) → 4-5 file. Benefici: parallelismo CI, failure locality, readability.

P0 — high impact, medium effort

P0.4 — LinkProcessor = namespace statico

packages/content-ops/src/markdown/link-processor.ts:42-411 — class LinkProcessor contiene 13+ metodi statici e zero stato di istanza. Violazione delle naming conventions. Convertire a modulo con named exports (il pattern è già emergente nei re-export alle righe 409-418).

P0.5 — copyPathOps.ts god-module

packages/content-ops/src/ops/copyPathOps.ts → 705 LOC, 19 funzioni. Superato il size threshold 2.3×. Split lungo linee naturali:

• copy-directory.ts
• copy-file.ts
• copy-orchestrator.ts

P1 — medium impact

P1.1 — Silent test failures in knowledge-hub

packages/knowledge-hub/package.json:

• riga 13: \"test\": \"vitest run || pnpm check:links\" — un vitest green può mascherare fallimenti (e viceversa)
• riga 14: test:coverage termina con || true — coverage failures soppressi

Rimuovere i fallback.

P1.2 — Coverage gates mancanti

Solo 3/5 workspace hanno thresholds: { lines/functions/branches/statements: 80 } nei vitest config. Aggiungerli a:

• apps/website/vitest.config.ts
• packages/brand/vitest.config.ts

P1.3 — MoveCtx con non-null assertions

packages/content-ops/src/ops/movePathOps.ts:189 — MoveCtx = Partial<...> forza ctx.source!, ctx.target! nei siti d'uso. Refactor a discriminated union per preservare type safety.

P1.4 — Baseline coverage non persistito

reports/ contiene solo .gitkeep. Wirare pnpm -r test -- --coverage e serializzare coverage-summary.json in reports/ per trend tracking.

P2 — low impact / opportunistico

P2.1 — Ultimo :any residuo

apps/pair-cli/src/commands/kb-verify/metadata.ts — l'unico :any in tutta src/. Tiparlo e chiudere la 'zero any story'.

P2.2 — packages/brand/dev/App.tsx

456 LOC di dev harness con 11 section component inline. Dev-only ma oltre threshold. Estrarre sezioni in dev/sections/*.

P2.3 — in-memory-fs.ts

packages/content-ops/src/test-utils/in-memory-fs.ts → 429 LOC. Split read ops / write ops / seed helpers.

P2.4 — Duplication scanner assente

code-metrics.md:139 raccomanda jscpd. Non wired in quality-gate. Integrarlo per visibility su duplicazione.

Cluster di debito

• packages/content-ops/src/ops/ — 4 dei top-10 file più grandi non-test vivono qui (copyPathOps 705, movePathOps 416, link-batch-processor 292, path-operation-helpers). Candidato per decomposizione bounded-context-style.
• Infra "silent failure" — 4 item (CI || echo, knowledge-hub test fallback, knowledge-hub coverage fallback, content-ops catalog bypass). Non critici singolarmente, insieme erodono la fiducia nei gate.

Suggested execution

• PR singolo per i P0.1 + P0.2 + P1.1 (rimozione silent failures + catalog fix) — 1–2h.
• PR separato per P0.3 (split cli.e2e.test.ts) — 2–3h.
• Issue/story separate per P0.4 e P0.5 (refactor non banali).
• P1.2 + P1.4 in batch piccolo.
• P1.3 opportunistico quando si tocca movePathOps.
• P2.* come story low-priority o good-first-issue.

References

• Report completo del turno: audit eseguito in conversazione Claude Code il 2026-04-17.
• Commit recente correlato: 5da2825 (backfill adoption: dotenv/markdownlint/Playwright/jsdom).