Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions scripts/architecture-baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -143,8 +143,8 @@
"forbiddenImportCount": 0
},
"src/commands/doctor.ts": {
"countedLines": 250,
"physicalLines": 258,
"countedLines": 243,
"physicalLines": 251,
"forbiddenImportCount": 0
},
"src/commands/first.ts": {
Expand Down
2 changes: 1 addition & 1 deletion spec-validator.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
},
{
Expand Down
4 changes: 4 additions & 0 deletions spec/src/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 4 additions & 0 deletions spec/src/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
40 changes: 35 additions & 5 deletions spec/src/doctor-and-init.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
1 change: 1 addition & 0 deletions spec/src/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
123 changes: 123 additions & 0 deletions src/commands/doctor-files.spec.ts
Original file line number Diff line number Diff line change
@@ -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);
});
48 changes: 48 additions & 0 deletions src/commands/doctor-files.ts
Original file line number Diff line number Diff line change
@@ -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;
}
11 changes: 2 additions & 9 deletions src/commands/doctor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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({
Expand Down
Loading