diff --git a/scripts/architecture-baseline.json b/scripts/architecture-baseline.json index 9348509..7dd0caa 100644 --- a/scripts/architecture-baseline.json +++ b/scripts/architecture-baseline.json @@ -143,8 +143,8 @@ "forbiddenImportCount": 0 }, "src/commands/doctor.ts": { - "countedLines": 250, - "physicalLines": 258, + "countedLines": 243, + "physicalLines": 251, "forbiddenImportCount": 0 }, "src/commands/first.ts": { diff --git a/spec-validator.config.mjs b/spec-validator.config.mjs index 627bc3d..2885a59 100644 --- a/spec-validator.config.mjs +++ b/spec-validator.config.mjs @@ -74,7 +74,7 @@ export default defineConfig(headingRequirements(), { chapters: ["spec/src/architecture.md"], }, { - pattern: "^src/commands/(?:doctor(?:-qmd)?|init)\\.ts$", + pattern: "^src/commands/(?:doctor(?:-(?:qmd|files))?|init)\\.ts$", chapters: ["spec/src/doctor-and-init.md"], }, { diff --git a/spec/src/architecture.md b/spec/src/architecture.md index da76b24..07c08a1 100644 --- a/spec/src/architecture.md +++ b/spec/src/architecture.md @@ -147,3 +147,7 @@ The bounded-document delivery extracts validator defaults, document-role classif Release qualification installs mdBook 0.5.2 before canonical checks and the actual nested-book regression. The failed v0.1.1 package gate exposed an absent CI binary, not a passing substitute; v0.1.2 retains that regression and qualifies the explicit prerequisite. The 0.2.0 gate runs entirely on Node: pnpm installs from the frozen lockfile and the canonical checks, tests, and publint run without a Deno toolchain. The verified release tarball lives under `.release/`; artifact upload explicitly includes hidden files while restricting its path to that one tarball pattern. The v0.1.2 gate passed all tests but artifact upload excluded the hidden directory; v0.1.3 preserves the failed tag and the exact validated artifact boundary. + +Configured doctor discovery is extracted into the bounded `doctor-files` command +module. The original doctor module's counted-line budget decreases; the public +Node CLI/build/runtime contract remains unchanged. diff --git a/spec/src/configuration.md b/spec/src/configuration.md index ce6c9e9..86b9bd2 100644 --- a/spec/src/configuration.md +++ b/spec/src/configuration.md @@ -70,3 +70,7 @@ validator exists yet. The counted-line contract itself is normative in [Architecture](./architecture.md) as SV-ARCH-008 and SV-ARCH-009. The release workflow is mapped to Architecture alongside package metadata so installation and publication changes retain same-change canonical coverage. + +Doctor canonical-file discovery consumes the existing resolved verification +`file`/`files` options without adding schema fields or consumer path defaults. +The spec-first map includes its owned `doctor-files` module under Doctor and init. diff --git a/spec/src/doctor-and-init.md b/spec/src/doctor-and-init.md index 82ccafb..7f7c52e 100644 --- a/spec/src/doctor-and-init.md +++ b/spec/src/doctor-and-init.md @@ -4,11 +4,12 @@ ## Public surface coverage -| Surface | Public boundary | Requirement | -| ----------------- | --------------- | ----------- | -| Init scaffolds | Doctor and init | SV-DOC-001 | -| Doctor report | Doctor and init | SV-DOC-002 | -| Doctor fix safety | Doctor and init | SV-DOC-003 | +| Surface | Public boundary | Requirement | +| ------------------------------ | --------------- | ----------- | +| Init scaffolds | Doctor and init | SV-DOC-001 | +| Doctor report | Doctor and init | SV-DOC-002 | +| Doctor fix safety | Doctor and init | SV-DOC-003 | +| Configured canonical discovery | Doctor and init | SV-DOC-004 | ## SV-DOC-001 — Init scaffolds @@ -42,3 +43,32 @@ - `--fix` MUST report each applied repair. - Canonical Markdown under `spec/src` MUST remain untouched. - A repair that cannot be applied safely MUST stay a finding. + +## SV-DOC-004 — Configured canonical discovery + +**Requirement.** Doctor MUST discover verification matrices from the resolved validator configuration rather than require a fixed consumer layout. + +### Acceptance details + +- Enabled verification MUST use `file` when `files` is empty, otherwise match the configured regular expressions against Markdown chapter paths relative to `specDir`. +- Missing literal files and empty pattern selections MUST fail even when an unselected default matrix exists. +- Every selected matrix MUST receive a discrete presence check; disabled verification MUST impose no matrix requirement. +- A missing `SUMMARY.md` MUST fail independently of verification selection. + +## Qualification evidence + +The public CLI regression records5 failures and1 pass before repair, covering +nested literal/pattern selection, precedence and disabled verification. It also +retains default/missing-file controls, summary failure and strict wrapped-alias +warnings. Terminal's configured `current/verification.md` is the original +consumer reproduction; packed CLI acceptance remains distinct from adoption. + +The repaired source passes6/6 focused CLI tests and the full check: typecheck, +Node runtime audit, lowered architecture budget,5 specification lanes, +6 workspace tests,19 architecture controls,67 Node tests, mdBook and publint. +Formatter and own doctor/QMD checks pass with the intentional wrapped-alias +warning retained. A temporary packed public CLI (SHA256 +77f4ad226c357eab0a00686816eeb33a0c3f9b2fd3e86128dbe3bb3546f6f361) +accepts Terminal's configured matrix with10 passes and one wrapped-alias warning; +Terminal manifest, lock, workflows and WIP are unchanged. No package is published +or consumer dependency adopted by this source qualification. diff --git a/spec/src/verification.md b/spec/src/verification.md index 945f676..e042513 100644 --- a/spec/src/verification.md +++ b/spec/src/verification.md @@ -32,6 +32,7 @@ | SV-DOC-001 | Implemented | `src/commands/init.ts` | | SV-DOC-002 | Implemented | `src/commands/doctor.ts`; `src/commands/doctor-qmd.ts` native-module probe | | SV-DOC-003 | Implemented | `src/commands/doctor.ts` `--fix` | +| SV-DOC-004 | Implemented | `src/commands/doctor-files.ts`; public CLI regression `src/commands/doctor-files.spec.ts` | | SV-QMD-001 | Implemented | `src/commands/search.ts`; `.qmd/index.yml`; `src/commands/search-results.spec.ts` absolute scoped paths | | SV-QMD-002 | Implemented | `src/commands/search.ts` PATH resolution and degraded `rg` fallback; `src/commands/search.spec.ts` exit-status and warning contract | | SV-SKL-001 | Implemented | `src/commands/skill.ts`; `skill/spec-validator/SKILL.md` | diff --git a/src/commands/doctor-files.spec.ts b/src/commands/doctor-files.spec.ts new file mode 100644 index 0000000..ff84b6b --- /dev/null +++ b/src/commands/doctor-files.spec.ts @@ -0,0 +1,123 @@ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { test } from "node:test"; + +const cli = fileURLToPath(new URL("../../dist/cli.js", import.meta.url)); +function doctor(verification: unknown, files: string[], strict = false) { + const root = mkdtempSync(join(tmpdir(), "spec-doctor-files-")); + try { + for (const file of [".gitignore", ...files]) { + const target = join(root, file); + mkdirSync(dirname(target), { recursive: true }); + writeFileSync( + target, + file === ".gitignore" ? "spec/book/\n" : "# Fixture\n", + ); + } + writeFileSync( + join(root, "spec-validator.config.json"), + JSON.stringify({ + name: "fixture", + ruleIds: { internal: "TEST-GOV-001" }, + diagnostics: { "*": "TEST-GOV-001" }, + validators: { verification }, + }), + ); + writeFileSync( + join(root, "package.json"), + JSON.stringify({ + scripts: { "spec:check": "node source-owned-wrapper.mjs" }, + }), + ); + const result = spawnSync( + process.execPath, + [cli, "doctor", "--json", ...(strict ? ["--strict"] : [])], + { cwd: root, encoding: "utf8" }, + ); + assert.ifError(result.error); + assert(result.stdout, result.stderr); + return { status: result.status, report: JSON.parse(result.stdout) }; + } finally { + rmSync(root, { recursive: true, force: true }); + } +} +const summary = "spec/src/SUMMARY.md"; +const matrix = "spec/src/current/verification.md"; + +test("public doctor accepts a configured literal verification path and preserves alias warnings", () => { + const { status, report } = doctor({ file: "current/verification.md" }, [ + summary, + matrix, + ]); + assert.equal(status, 0); + assert.equal( + report.checks.find((check: { name: string }) => check.name === matrix) + ?.status, + "pass", + ); + assert.equal( + report.checks.find((check: { name: string }) => check.name === "scripts") + ?.status, + "warn", + ); + assert.equal( + doctor({ file: "current/verification.md" }, [summary, matrix], true).status, + 1, + ); +}); + +test("public doctor accepts pattern-selected matrices without inventing a default matrix", () => { + const { status, report } = doctor( + { files: ["^current/verification\\.md$", "^other/verification\\.md$"] }, + [summary, matrix, "spec/src/other/verification.md"], + ); + assert.equal(status, 0); + assert.equal( + report.checks.filter((check: { name: string }) => + check.name.endsWith("/verification.md"), + ).length, + 2, + ); +}); + +test("empty configured patterns fail even when the default and ignored literal file exist", () => { + const { status, report } = doctor( + { file: "legacy.md", files: ["^missing/verification\\.md$"] }, + [summary, "spec/src/verification.md", "spec/src/legacy.md"], + ); + assert.equal(status, 1); + assert( + report.checks.some( + (check: { status: string; message: string }) => + check.status === "fail" && + /verification selection is empty/.test(check.message), + ), + ); +}); + +test("missing literal and default matrices remain failures", () => { + assert.equal( + doctor({ file: "current/verification.md" }, [ + summary, + "spec/src/verification.md", + ]).status, + 1, + ); + assert.equal(doctor(true, [summary]).status, 1); + assert.equal(doctor(true, [summary, "spec/src/verification.md"]).status, 0); +}); + +test("missing summary is never hidden by a matching matrix", () => { + assert.equal( + doctor({ files: ["^current/verification\\.md$"] }, [matrix]).status, + 1, + ); +}); + +test("disabled verification does not demand an inactive matrix", () => { + assert.equal(doctor(false, [summary]).status, 0); +}); diff --git a/src/commands/doctor-files.ts b/src/commands/doctor-files.ts new file mode 100644 index 0000000..a81786f --- /dev/null +++ b/src/commands/doctor-files.ts @@ -0,0 +1,48 @@ +import { markdownFiles, toPosix } from "../model.js"; +import { existsSync, path } from "../platform/current.js"; +import type { DoctorCheck, ResolvedConfig } from "../types.js"; + +export function canonicalFileChecks( + repoRoot: string, + config: ResolvedConfig, +): DoctorCheck[] { + const summary = `${config.specDir}/SUMMARY.md`; + const present = existsSync(path.join(repoRoot, summary)); + const checks: DoctorCheck[] = [ + { + name: summary, + status: present ? "pass" : "fail", + message: present ? "present" : "missing canonical chapter", + }, + ]; + const options = config.validators.verification; + if (options === false) return checks; + const directory = path.join(repoRoot, config.specDir); + const selected = markdownFiles(directory) + .map((file) => toPosix(path.relative(directory, file))) + .filter((chapter) => + options.files.length + ? options.files.some((pattern) => new RegExp(pattern).test(chapter)) + : chapter === options.file, + ); + if (!selected.length) { + checks.push({ + name: options.files.length + ? `${config.specDir} (verification)` + : `${config.specDir}/${options.file}`, + status: "fail", + message: options.files.length + ? `verification selection is empty; restore the configured matrices matching ${options.files.join(", ")}` + : "missing canonical chapter", + }); + } else { + checks.push( + ...selected.map((file): DoctorCheck => ({ + name: `${config.specDir}/${file}`, + status: "pass", + message: "present", + })), + ); + } + return checks; +} diff --git a/src/commands/doctor.ts b/src/commands/doctor.ts index 613d217..edccb5a 100644 --- a/src/commands/doctor.ts +++ b/src/commands/doctor.ts @@ -13,6 +13,7 @@ import { import type { Reporter } from "../reporter.js"; import type { DoctorCheck, ResolvedConfig } from "../types.js"; import { qmdBinaryCheck, qmdNativeCheck } from "./doctor-qmd.js"; +import { canonicalFileChecks } from "./doctor-files.js"; import { globalSkillPath, installSkill } from "./skill.js"; function which(command: string): boolean { @@ -76,15 +77,7 @@ async function inspect( ], }; } - for (const file of ["SUMMARY.md", "verification.md"]) { - const relative = `${config.specDir}/${file}`; - const present = existsSync(path.join(repoRoot, relative)); - checks.push({ - name: relative, - status: present ? "pass" : "fail", - message: present ? "present" : "missing canonical chapter", - }); - } + checks.push(...canonicalFileChecks(repoRoot, config)); if (config.validators.book) { const present = existsSync(path.join(repoRoot, "spec/book.toml")); checks.push({