Docs & test-quality debt — tracking

[joekotvas]

Docs & test-quality debt — tracking

Live, untracked documentation inaccuracies, vacuous/flawed tests, and low/nit code smells surfaced in the audit re-triage.

• TESTING.md still claims getScore() returns stale data, contradicting ADR-006

  • docs/TESTING.md:242 ('The getScore() method may return stale data in test environments') and :251 ('Fragile - may return stale data') survive, while docs/adr/006-synchronous-api-engine-access.md documents synchronous mutate-then-read. The audit's reconciliation deliverable (corrections Feature: Configure ESLint for code consistency #16, I/O lens) was never done. No open issue.

• docs(CHANGELOG): alpha.11 claims suites are "mutation-verified" but no mutation tooling exists

  • CONFIRMED PRESENT in current dev (v1.0.0-alpha.16).

CHANGELOG.md:195 (under the ## [1.0.0-alpha.11] header, line 164 — NOT alpha.12 as the candidate stated; the line number is correct, the version label is off by one):
"- Verification scaffolding — fast-check property harness, SVG geometry oracle, SMuFL codepoint registry, MusicXML duration-sum oracle (wired to real output), fast-xml-parser/abcjs/XSD fixtures, and a CI workflow. New suites are oracle-backed and mutation-verified."

No mutation-testing tooling exists anywhere in the repo:

• package.json scripts: build/dev/test(jest)/test:coverage/lint/typecheck/format/demo/visual — no mutation/stryker script.
• package.json dependencies + devDependencies: no @stryker-mutator/* or any mutation package.
• find . -iname "*stryker*" -not -path "*/node_modules/*" → empty (no config: stryker.conf.js/json, no .stryker-tmp).
• ls node_modules | grep -i stryker → none installed.
• .github/workflows/ — only ci.yml (typecheck/lint/test/build) and visual.yml; no mutation job.

The repo's OWN documentation contradicts the CHANGELOG claim:

• .github/workflows/ci.yml:4-5: "Browser-geometry / visual / mutation jobs are deferred to later phases per the verification strategy."
• docs/audit/AUDIT_QA_2026-06.md:402: "[LOW] Mutation testing scope/threshold realism ... StrykerJS remains intentionally deferred (no stryker config present) ... advisory, no code defect."
• docs/audit/PARALLEL_IMPLEMENTATION_PLAN.md:73 and docs/audit/AUDIT_QA_2026-06.md:146 (recommend deferring mutation testing for a one-dev alpha).

So the suites are genuinely oracle-backed (true) but NOT mutation-verified (false claim).

TRACKING: No issue covers the CHANGELOG-accuracy discrepancy. Verified via gh: #235 (OPEN) lists "StrykerJS mutation-testing baseline on engines/layout, exporters, accidentalContext, core" as an outstanding to-do (it establishes mutation testing is future/unbuilt, but tracks BUILDING the verification work, not correcting the docs). #272 (OPEN) is a low/nit deep-QA tracking bucket but lists unrelated items (MIDI overfill, reflow id re-mint, setTimeSignature validation, coverage gaps) — nothing about this claim. gh searches for "mutation"/"stryker"/"CHANGELOG mutation-verified" return no matching issue.

• Audit-doc correction backlog: duplicate-merge, severity re-grade, directional/citation/framing fixes never applied to CORRECTNESS_AUDIT (corrections Bug: Clef symbols in clef selector menu are not sized or positioned correctly #2,Bug: Footer stays in light theme when switching back to dark theme #3,Feature: Marketing demo page with hero, intro, examples, and docs links #6,Feature: Imperative API for external script integration #7,Bug: Left arrow skips newly entered note after committing with Enter #8,Feature: ABC Notation importing #10)

  • CORRECTNESS_AUDIT_2026-06.md still lists the ~7 duplicate findings separately (e.g. both findings, count=2) with original severities; line 261 still 'F#4 -> E#4'; 'src/constants.ts' SMuFL citations uncorrected (lines 197,320); no phase-numbering cross-ref (0 hits); framing at lines 117/403 not softened. Only a top-level disclaimer acknowledges them. No open issue.

• Two still-vacuous flawed tests: grandStaffAlignment:79 Math.max tautology and TimelineService:219 frequency>0 (line 414)

  • grandStaffAlignment.test.ts:79 still asserts toBe(Math.max(trebleWidth,bassWidth)) against a LOCAL reimplementation (calculateSynchronizedMeasureWidths defined at :7) rather than the production sync path. TimelineService.test.ts:219 still 'expect(t1[0].frequency).toBeGreaterThan(0) // G3' while the same file at :277/:280 demonstrates the exact-Hz pattern. (RenderingDetailed now has 15 expects and ChromaticTranspose:107 pins a single spelling — those two are fixed.) Test-quality burndown only loosely tracked under Deep-QA: low/nit findings + coverage gaps (tracking) #272/Improve Test ID Robustness and Naming Conventions #210.

• useChordTrack test mocks getValidChordQuants as Set instead of Map<number, Set>, masking type drift and leaving isValidPosition untestable

  • CONFIRMED PRESENT in current dev (v1.0.0-alpha.16).

1. Mock returns wrong type: src/tests/hooks/chord/useChordTrack.test.ts:36-50 — jest.mock('@/services/ChordService') makes getValidChordQuants return new Set<number>() populated with global quants (baseQuant + beat*24 across measures).

2. Real production type is a Map: src/services/chord/ChordQuants.ts:69 — getValidChordQuants = (score: Score): Map<number, Set<number>> (measure index -> set of measure-LOCAL quants). Re-exported through the mocked path src/services/ChordService.ts (export * from './chord').

3. isValidPosition is broken under the mock: src/hooks/chord/useChordTrack.ts:227-233 calls validPositions.get(position.measure)?.has(position.quant). A Set has no .get method (verified: Set.prototype.get === undefined), so under the mock this is always undefined?.has(...) => false. The hook DOES expose isValidPosition (useChordTrack.ts:135, :359), but it is NEVER tested in this file (grep for isValidPosition in the test returned zero matches) — so the breakage is latent, and the mock is unusable for any future test of that method.

4. Wrong-type assertions: test lines 144 and 897 assert toBeInstanceOf(Set), but production yields a Map. Lines 146-147 (.has(0), .has(24)) pass only because the flat mock Set happens to contain those global values; against a real Map keyed by measure index they would be the wrong call shape.

5. Full suite still green: npx jest .../useChordTrack.test.ts => 34/34 passed, confirming the type drift is masked rather than caught.

Mock and assertions introduced in cdcbef9 (feat: Chord Symbols Feature #29, #205); test file last touched 23b44eb without fixing this. No tracked issue covers it: #223 (chord nav boundary tests — Tab/Shift+Tab in ScoreCanvas, different concern), #71 CLOSED (OutputPanel/pausePlayback stale mocks, unrelated paths), #210 (test ID robustness, unrelated).

• constants.ts file vs constants/ directory sibling-stem smell (line 188)

  • src/constants.ts (16KB file) and src/constants/SMuFL.ts (in a dir of the same stem) still coexist; no constants/index.ts barrel and constants.ts does not re-export SMuFL. '@/constants' currently resolves to the file; adding constants/index.ts later would silently change resolution. No open issue.

• cleanup dead processedIndices Set in calculateTupletBrackets

  • Present in current dev. tuplets.ts:106 declares the Set, line 109 reads .has(i), but grep finds the only .add() in measure.ts:521 (different Set). So the Set is always empty and the guard is dead; dedup is actually done by event.tuplet.position === 0 at line 112. Not in any issue (Deep-QA nits: role=status on errors, dead planInsertion, ChordErrorCode coupling, drift-prone vertical availability #262, Deep-QA: low/nit findings + coverage gaps (tracking) #272, Tuplet bracket angle should match beam angle, ignoring rests #131, Tuplet Button Incorrectly Disabled When There's Sufficient Space #201, Beaming: tuplet-within-beat grouping unhandled (deferred with the xLCM grid, #237) #245, Tuplet-fill entry leaves the new note unselected (selection resolves against stale React score) #268 checked).

---

Source: 2026-06 audit re-triage (2026-06-13); each item is tagged 🔴 LIVE in docs/audit/. Some are single-pass audit/fresh-eyes findings not independently re-verified — confirm against current code before fixing.