cyber-sdd 0.4.0 → 0.4.2

package/dist/check-spec-references/scripts/check-spec-references.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/check-spec-references/scripts/check-spec-references.mts
+/** Suppresses every reference on the line it appears on. Matched as a COMPLETE html comment, not
+* as a substring: a marker whose name merely starts with this one's (a typo, a future sibling)
+* must not silently inherit its power to hide a reference. The optional `: reason` is convention,
+* not syntax — the marker is recognized with or without one. */
+const IGNORE_MARKER_RE = /<!--\s*spec-ref-ignore\s*(?::[^>]*)?-->/;
+/** A markdown inline link whose target is explicitly relative — covering the plain form, an
+* angle-bracket-wrapped target, and an optional title in any of markdown's three quotings. Run only
+* over the parts of a line that are NOT inside a code span: inside one, markup is literal text on
+* display, not a link. */
+const LINK_RE = /\]\(\s*(?:<([^>\n]*)>|(\.{1,2}\/[^)\s]*))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g;
+/** A reference-style link definition (`[label]: ../path`) whose target is explicitly relative. It
+* is a link target like any other — the label form changes where the path is written, not what it
+* points at. */
+const LINK_DEF_RE = /^\s{0,3}\[.+\]:\s*(?:<([^>\n]*)>|(\S+))/;
+/** An explicitly-relative path, and nothing else. The trailing class excludes whitespace and
+* backticks so that "the span's WHOLE content is the path" means what it says: a span holding
+* `../a` plus commentary is prose that starts with a path, not a citation. */
+const RELATIVE_RE = /^\.{1,2}\/[^\s`]*$/;
+/** The same, minus the no-whitespace rule — for an ANGLE-BRACKET link target, whose whole reason
+* for existing is to carry a path with a space in it. */
+const RELATIVE_IN_ANGLES_RE = /^\.{1,2}\/[^`]*$/;
+/**
+* The fence a line opens, or `undefined`. CommonMark: three or more backticks or tildes, indented
+* fewer than four spaces.
+*/
+function fenceOpenedBy(line) {
+	const m = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+	if (m === null) return void 0;
+	const run = m[1];
+	return {
+		char: run[0],
+		length: run.length
+	};
+}
+/**
+* Whether `line` CLOSES `fence`: the same character, at least as long, and nothing but whitespace
+* after it.
+*
+* Matching the delimiter rather than toggling a boolean on any fence-shaped line is what keeps the
+* exclusion honest. A bare toggle flips on a `~~~` line inside a backtick fence — so a reference
+* genuinely inside a fence gets extracted, and, worse, a fence-shaped line inside another fence
+* leaves the parity inverted and every genuinely broken reference AFTER the block is silently
+* swallowed. That is this engine's own failure class, reached through the one rule meant to
+* suppress noise.
+*/
+function fenceClosedBy(line, fence) {
+	const m = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line);
+	if (m === null) return false;
+	const run = m[1];
+	return run[0] === fence.char && run.length >= fence.length;
+}
+/**
+* A line that starts a new block: blank, an ATX heading, a blockquote, a list item, or a thematic
+* break. Inline parsing happens WITHIN a block, so a code span cannot reach across one of these —
+* and the boundary matters in the under-reporting direction. An unclosed backtick left by a typo
+* would otherwise pair with the first backtick of the next block, swallowing the span that was
+* about to open and every reference after it in the flow.
+*/
+function startsNewBlock(line) {
+	if (/^[ \t]*$/.test(line)) return true;
+	if (/^ {0,3}#{1,6}(\s|$)/.test(line)) return true;
+	if (/^ {0,3}>/.test(line)) return true;
+	if (/^ {0,3}([-+*]|\d{1,9}[.)])(\s|$)/.test(line)) return true;
+	if (/^ {0,3}((\*[ \t]*){3,}|(-[ \t]*){3,}|(_[ \t]*){3,})$/.test(line)) return true;
+	return false;
+}
+/** Same length, same line breaks, no content — so blanking a region shifts no offset and moves no
+* finding to another line. */
+function blankOut(region) {
+	return region.replace(/[^\n]/g, " ");
+}
+/**
+* The inline-code spans on one line, scanned the way CommonMark delimits them: a run of N backticks
+* opens, the next run of EXACTLY N closes, and one leading + trailing space is stripped when both
+* are present.
+*
+* Scanning properly rather than matching a single-backtick pair is what makes the reference rule —
+* "a code span is a reference when its WHOLE content is the path" — mean one thing everywhere. A
+* doubled span written around another span (`` `x` ``) has content that still carries backticks, so
+* it is not a path and not a reference; a doubled span written around a bare path has the path as
+* its content, so it IS one. Neither is a special case, and neither leaves a broken reference
+* anywhere to hide.
+*/
+function scanCodeSpans(text, blockStarts = []) {
+	const out = [];
+	let i = 0;
+	while (i < text.length) {
+		if (text[i] !== "`") {
+			i++;
+			continue;
+		}
+		const open = i;
+		while (text[i] === "`") i++;
+		const runLength = i - open;
+		const limit = blockStarts.find((b) => b > open) ?? text.length;
+		let j = i;
+		let closeStart = -1;
+		while (j < limit) {
+			if (text[j] !== "`") {
+				j++;
+				continue;
+			}
+			const runStart = j;
+			while (text[j] === "`") j++;
+			if (j - runStart === runLength) {
+				closeStart = runStart;
+				break;
+			}
+		}
+		if (closeStart === -1) {
+			i = open + runLength;
+			continue;
+		}
+		let content = text.slice(open + runLength, closeStart).replace(/\r?\n/g, " ");
+		if (content.length > 1 && content.startsWith(" ") && content.endsWith(" ") && content.trim() !== "") content = content.slice(1, -1);
+		out.push({
+			content,
+			start: open,
+			end: j
+		});
+		i = j;
+	}
+	return out;
+}
+/**
+* Every explicitly-relative reference in `text`, in document order.
+*
+* Skipped: lines inside a fenced code block, and lines carrying the ignore marker. Extraction is
+* line-scoped on purpose — it is what gives each finding a line number, and what lets the marker's
+* scope be exactly the line it appears on rather than the whole file.
+*/
+function extractReferences(text) {
+	const lines = text.split("\n");
+	let fence;
+	const unfenced = lines.map((line) => {
+		if (fence !== void 0) {
+			if (fenceClosedBy(line, fence)) fence = void 0;
+			return blankOut(line);
+		}
+		const opened = fenceOpenedBy(line);
+		if (opened !== void 0) {
+			fence = opened;
+			return blankOut(line);
+		}
+		return line;
+	});
+	const scannable = unfenced.join("\n");
+	const lineStarts = [];
+	let acc = 0;
+	for (const line of lines) {
+		lineStarts.push(acc);
+		acc += line.length + 1;
+	}
+	const blockStarts = lineStarts.filter((_start, i) => i > 0 && startsNewBlock(unfenced[i]));
+	const lineOf = (offset) => {
+		let lo = 0;
+		let hi = lineStarts.length - 1;
+		while (lo < hi) {
+			const mid = lo + hi + 1 >> 1;
+			if (lineStarts[mid] <= offset) lo = mid;
+			else hi = mid - 1;
+		}
+		return lo;
+	};
+	const spans = scanCodeSpans(scannable, blockStarts);
+	let outsideSpans = scannable;
+	for (const span of spans) outsideSpans = outsideSpans.slice(0, span.start) + blankOut(outsideSpans.slice(span.start, span.end)) + outsideSpans.slice(span.end);
+	const outsideLines = outsideSpans.split("\n");
+	const marked = outsideLines.map((line) => IGNORE_MARKER_RE.test(line));
+	const perLine = /* @__PURE__ */ new Map();
+	const add = (line, ref) => {
+		if (marked[line] === true) return;
+		const set = perLine.get(line) ?? /* @__PURE__ */ new Set();
+		set.add(ref);
+		perLine.set(line, set);
+	};
+	for (const span of spans) {
+		const content = span.content.trim();
+		if (RELATIVE_RE.test(content)) add(lineOf(span.start), content);
+	}
+	outsideLines.forEach((line, i) => {
+		const addTarget = (angled, bare) => {
+			if (angled !== void 0) {
+				if (RELATIVE_IN_ANGLES_RE.test(angled)) add(i, angled);
+				return;
+			}
+			if (bare !== void 0 && RELATIVE_RE.test(bare)) add(i, bare);
+		};
+		for (const m of line.matchAll(LINK_RE)) addTarget(m[1], m[2]);
+		const def = LINK_DEF_RE.exec(line);
+		if (def) addTarget(def[1], def[2]);
+	});
+	const out = [];
+	for (const line of [...perLine.keys()].sort((a, b) => a - b)) for (const ref of perLine.get(line)) out.push({
+		line: line + 1,
+		ref
+	});
+	return out;
+}
+/**
+* Where `ref` points, resolved against `fileDir` — the directory of the file that CARRIES it,
+* never the spec root and never the repo root. A trailing `#fragment` is stripped first; a
+* trailing slash is immaterial (`resolve` drops it), so a directory reference resolves either way.
+*/
+function resolveReference(fileDir, ref) {
+	const withoutFragment = ref.replace(/#.*$/, "");
+	return resolve(fileDir, withoutFragment);
+}
+/** Every `.md` file under `dir`, at any depth, absolute and sorted so the report is stable. */
+function listMarkdownFiles(dir) {
+	const out = [];
+	const walk = (d) => {
+		for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+			const p = join(d, e.name);
+			if (e.isDirectory()) walk(p);
+			else if (e.name.endsWith(".md")) out.push(p);
+		}
+	};
+	walk(dir);
+	return out;
+}
+/**
+* Every unresolved reference under `specDir`, ordered by file, then line, then reference — so two
+* runs over an unchanged tree render byte-identically.
+*
+* EVERY finding, never the first: a single off-by-one lands as a whole family of broken
+* references, and reporting one at a time would take as many runs to clear as there are levels
+* wrong.
+*/
+function audit(specDir, options = {}) {
+	const list = options.listMarkdownFiles ?? listMarkdownFiles;
+	const read = options.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const has = options.exists ?? existsSync;
+	const findings = [];
+	for (const file of list(specDir)) {
+		const fileDir = dirname(file);
+		for (const { line, ref } of extractReferences(read(file))) {
+			const resolved = resolveReference(fileDir, ref);
+			if (!has(resolved)) findings.push({
+				file,
+				line,
+				ref,
+				resolved
+			});
+		}
+	}
+	return findings.sort((a, b) => a.file !== b.file ? a.file < b.file ? -1 : 1 : a.line !== b.line ? a.line - b.line : a.ref < b.ref ? -1 : 1);
+}
+/** Renders each finding as `file:line: <ref> -> <resolved>`, both paths relative to `base` so the
+* report reads the same from any checkout. */
+function formatFindings(findings, base) {
+	if (findings.length === 0) return "check-spec-references: every relative reference resolves\n";
+	const lines = findings.map((f) => `  ${relative(base, f.file)}:${f.line}: \`${f.ref}\` -> ${relative(base, f.resolved)} — no file or directory there\n`);
+	lines.push(`check-spec-references: ${findings.length} unresolved reference(s)\n`);
+	return lines.join("");
+}
+function main(argv, cwd = process.cwd()) {
+	const i = argv.indexOf("--spec-dir");
+	const specDir = i === -1 ? "" : argv[i + 1] ?? "";
+	if (specDir === "") {
+		process.stderr.write("check-spec-references: --spec-dir <dir> is required\n");
+		return 1;
+	}
+	const dir = resolve(cwd, specDir);
+	if (!existsSync(dir)) {
+		process.stderr.write(`check-spec-references: no directory at ${relative(cwd, dir)}\n`);
+		return 1;
+	}
+	const findings = audit(dir);
+	const report = formatFindings(findings, cwd);
+	if (findings.length === 0) {
+		process.stdout.write(report);
+		return 0;
+	}
+	process.stderr.write(report);
+	return 1;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { audit, extractReferences, formatFindings, listMarkdownFiles, main, resolveReference, scanCodeSpans, startsNewBlock };

package/dist/check-spec-structure/scripts/check-spec-structure.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/check-spec-structure/scripts/check-spec-structure.mts
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".turbo",
+	".next",
+	"coverage"
+]);
+const DEFAULT_MAX_SCENARIOS = 40;
+const REQUIRED_BEHAVIORAL_SECTIONS = [
+	"What",
+	"Use Cases",
+	"Control Flow",
+	"Scenario map"
+];
+function parseNodeFrontmatter(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text);
+	if (!m) return { concepts: [] };
+	const fm = { concepts: [] };
+	const lines = m[1].split("\n").map((l) => l.replace(/\r$/, ""));
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line.trim() === "" || line.trim().startsWith("#")) continue;
+		if (line.length - line.trimStart().length !== 0) continue;
+		const [key, ...rest] = line.trim().split(":");
+		const value = rest.join(":").trim();
+		if (key === "spec-type") fm.specType = unquote(value);
+		else if (key === "concept") {
+			if (value === "" || value === "|" || value === ">") for (let j = i + 1; j < lines.length; j++) {
+				const item = lines[j];
+				if (item.trim() === "") continue;
+				if (item.length - item.trimStart().length === 0) break;
+				const dash = /^\s*-\s+(.*)$/.exec(item);
+				if (dash) fm.concepts.push(unquote(dash[1].trim()));
+			}
+			else fm.concepts.push(...parseScalarOrFlow(value));
+		}
+	}
+	return fm;
+}
+function parseScalarOrFlow(value) {
+	const v = value.trim();
+	if (v.startsWith("[") && v.endsWith("]")) return v.slice(1, -1).split(",").map((s) => unquote(s.trim())).filter((s) => s.length > 0);
+	const single = unquote(v);
+	return single.length > 0 ? [single] : [];
+}
+function unquote(v) {
+	return v.replace(/^["']|["']$/g, "");
+}
+function parseSectionHeadings(text) {
+	const headings = [];
+	let inFence = false;
+	for (const raw of text.split("\n")) {
+		const line = raw.replace(/\r$/, "");
+		if (/^\s*(```|~~~)/.test(line)) {
+			inFence = !inFence;
+			continue;
+		}
+		if (inFence) continue;
+		const m = /^##\s+(.+?)\s*$/.exec(line);
+		if (m) headings.push(m[1].replace(/`/g, "").trim());
+	}
+	return headings;
+}
+function countScenarios(featureText) {
+	let n = 0;
+	for (const line of featureText.split("\n")) if (/^\s*Scenario:/.test(line)) n++;
+	return n;
+}
+const SECTION_HEADER = /^\s*#\s*(?:──|-{3,})/;
+function profileFeature(featureText) {
+	const lines = featureText.split("\n");
+	let scenarioCount = 0;
+	let taggedCount = 0;
+	let clusterCount = 0;
+	let pendingRubric = false;
+	for (const line of lines) {
+		if (/^\s*Scenario:/.test(line)) {
+			scenarioCount++;
+			if (pendingRubric) taggedCount++;
+			pendingRubric = false;
+			continue;
+		}
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		if (trimmed.startsWith("@")) {
+			if (/(^|\s)@rubric(\s|$)/.test(trimmed)) pendingRubric = true;
+			continue;
+		}
+		if (SECTION_HEADER.test(line)) {
+			clusterCount++;
+			pendingRubric = false;
+			continue;
+		}
+		pendingRubric = false;
+	}
+	return {
+		scenarioCount,
+		plainCount: scenarioCount - taggedCount,
+		taggedCount,
+		clusterCount
+	};
+}
+function displayPath(relPath) {
+	const p = relPath.replace(/\\/g, "/");
+	return p.endsWith("/README.md") ? p.slice(0, -9) : p;
+}
+function scanProjectSpec(specDir) {
+	const records = [];
+	walk(specDir, specDir, records);
+	return records.sort((a, b) => a.display.localeCompare(b.display));
+}
+function walk(dir, specDir, out) {
+	const entries = readdirSync(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, specDir, out);
+		else if (entry.name === "README.md") {
+			const readmeText = readFileSync(full, "utf8");
+			const fm = parseNodeFrontmatter(readmeText);
+			if (fm.specType === void 0 && fm.concepts.length === 0) continue;
+			const sectionHeadings = parseSectionHeadings(readmeText);
+			const features = entries.filter((e) => e.isFile() && e.name.endsWith(".feature"));
+			const hasFeature = features.length > 0;
+			const profile = hasFeature ? profileFeature(readFileSync(join(dir, features[0].name), "utf8")) : {
+				scenarioCount: 0,
+				plainCount: 0,
+				taggedCount: 0,
+				clusterCount: 0
+			};
+			const relPath = full.slice(specDir.length + 1).replace(/\\/g, "/");
+			out.push({
+				relPath,
+				capability: relPath.split("/")[0],
+				display: displayPath(relPath),
+				concepts: fm.concepts,
+				specType: fm.specType,
+				sectionHeadings,
+				hasFeature,
+				scenarioCount: profile.scenarioCount,
+				plainCount: profile.plainCount,
+				taggedCount: profile.taggedCount,
+				clusterCount: profile.clusterCount
+			});
+		}
+	}
+}
+function checkUntagged(records) {
+	return records.filter((r) => r.specType !== void 0 && r.concepts.length === 0).map((r) => ({
+		kind: "untagged-node",
+		severity: "blocking",
+		node: r.display,
+		detail: `spec-type: ${r.specType} but no concept tag — orphaned from the by-concept index`
+	}));
+}
+function checkOversized(records, maxScenarios) {
+	return records.filter((r) => r.scenarioCount > maxScenarios).map((r) => ({
+		kind: "oversized-node",
+		severity: "advisory",
+		node: r.display,
+		detail: `${r.scenarioCount} scenarios > ${maxScenarios} — shape profile: plain ${r.plainCount}, tagged ${r.taggedCount}, clusters ${r.clusterCount} (soft breadth hint); the Warden routes breadth-vs-depth`
+	}));
+}
+function checkGlossary(specDir) {
+	if (existsSync(join(specDir, "glossary.md"))) return [];
+	return [{
+		kind: "missing-glossary",
+		severity: "advisory",
+		node: "glossary.md",
+		detail: "no root glossary.md — the project has no home for its ubiquitous language, so a term can be used without ever being defined; a root file, never a folder"
+	}];
+}
+function checkIncomplete(records) {
+	return records.filter((r) => r.specType === "behavioral" && r.hasFeature).map((r) => {
+		return {
+			record: r,
+			missing: REQUIRED_BEHAVIORAL_SECTIONS.filter((s) => !r.sectionHeadings.includes(s))
+		};
+	}).filter(({ missing }) => missing.length > 0).map(({ record, missing }) => ({
+		kind: "incomplete-node",
+		severity: "advisory",
+		node: record.display,
+		detail: `behavioral leaf spec missing required section(s): ${missing.map((s) => `## ${s}`).join(", ")} — a spec that stops at ## Use Cases never draws its CFG or scenario map (sdd:spec-format-governance)`
+	}));
+}
+function audit(records, maxScenarios, specDir) {
+	return [
+		...checkUntagged(records),
+		...checkOversized(records, maxScenarios),
+		...checkIncomplete(records),
+		...specDir === void 0 ? [] : checkGlossary(specDir)
+	];
+}
+function hasBlocking(findings) {
+	return findings.some((f) => f.severity === "blocking");
+}
+function renderFindings(findings, specDir) {
+	const blocking = findings.filter((f) => f.severity === "blocking");
+	const advisory = findings.filter((f) => f.severity === "advisory");
+	const lines = [`check-spec-structure: spec-dir=${specDir}`];
+	lines.push(`blocking[${blocking.length}]:`);
+	for (const f of blocking) lines.push(`  ${f.node} — ${f.kind}: ${f.detail}`);
+	lines.push(`advisory[${advisory.length}]:`);
+	for (const f of advisory) lines.push(`  ${f.node} — ${f.kind}: ${f.detail}`);
+	lines.push("note: advisory — findings feed the Warden formation pass; the engine writes nothing");
+	return lines.join("\n");
+}
+function main(argv) {
+	let specDir = ".";
+	let mode = "audit";
+	let format = "toon";
+	let maxScenarios = 40;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--spec-dir") specDir = argv[++i] ?? ".";
+		else if (a === "--check") mode = "check";
+		else if (a === "--max-scenarios") maxScenarios = Number(argv[++i] ?? 40);
+		else if (a === "--format") format = argv[++i] ?? "toon";
+	}
+	const findings = audit(scanProjectSpec(specDir), maxScenarios, specDir);
+	if (mode === "check") {
+		if (hasBlocking(findings)) {
+			process.stderr.write(`check-spec-structure: ${findings.filter((f) => f.severity === "blocking").length} blocking finding(s)\n`);
+			return 1;
+		}
+		process.stdout.write("check-spec-structure: no blocking findings\n");
+		return 0;
+	}
+	if (format === "json") process.stdout.write(`${JSON.stringify(findings)}\n`);
+	else process.stdout.write(`${renderFindings(findings, specDir)}\n`);
+	return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { DEFAULT_MAX_SCENARIOS, REQUIRED_BEHAVIORAL_SECTIONS, audit, checkGlossary, checkIncomplete, checkOversized, checkUntagged, countScenarios, hasBlocking, main, parseNodeFrontmatter, parseScalarOrFlow, parseSectionHeadings, profileFeature, renderFindings, scanProjectSpec };