cyber-sdd 0.7.0 → 0.7.2

package/skills/check-retired-terms/scripts/check-retired-terms.mts

@@ -1,293 +0,0 @@
-#!/usr/bin/env node
-// check-retired-terms — corpus-wide sweep for survivors of a retired path, directory, or naming
-// convention. A design decision retires a term (a path, a convention) and records the retirement
-// once in the registry (.agents/sdd/retired-terms.toml); this engine reads that registry, scans
-// every git-tracked file in the repo — not only the node someone happened to touch — and reports
-// every literal, case-sensitive occurrence as a violation, with the replacement to use.
-//
-// It is the corpus-wide, declared-data sibling of check:metaphor-free (packages/cyberlegion/src/
-// metaphor-free.ts): same "banned term, allow-list, exclusion list, scope" shape, but the banned
-// list here is registry data appended by any CR (a changelog), not a hardcoded package charter.
-//
-// The registry is parsed with a hand-rolled minimal TOML subset — the same spirit as
-// discover-specs's parseAnchorsToml (plugins/sdd/skills/discover-specs/scripts/discover-specs.mts)
-// — an array of `[[retired]]` tables with string keys (term/since/replacement) and string-array
-// keys (scope/allow). `allow` entries are flat strings, either a bare path (sanctions the whole
-// file) or `path :: substring` (sanctions only lines carrying that substring) — deliberately, so
-// the parser never needs nested inline tables.
-//
-// A malformed registry is NOT a fail-safe empty list (contrast discover-specs's readAnchors, which
-// warns and falls back for an unrelated scan): here the registry IS the check, so a parse failure
-// must be loud and non-zero, never a false-clean.
-//
-// Pure functions are exported for node:test; running the file directly drives the CLI. No
-// dependencies (the repo's node-≥23.6 / no-deps convention).
-
-import { execFileSync } from 'node:child_process'
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-// ── Registry ──
-
-export interface RetiredEntry {
-	/** The literal, case-sensitive text that is retired. */
-	term: string
-	/** The CR that retired it. */
-	since: string
-	/** What to use instead. */
-	replacement: string
-	/** Repo-relative include prefixes. Absent/empty means the whole tracked tree. */
-	scope?: string[]
-	/** Sanctioned occurrences: a bare path (whole file) or "path :: substring" (matching lines only). */
-	allow?: string[]
-}
-
-export class RegistryParseError extends Error {}
-
-const REGISTRY_PATH = '.agents/sdd/retired-terms.toml'
-
-function isBlankOrComment(line: string): boolean {
-	const t = line.trim()
-	return t === '' || t.startsWith('#')
-}
-
-function extractString(block: string, key: string): string {
-	const m = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*"([^"]*)"[^\\n]*`).exec(block)
-	if (!m) throw new RegistryParseError(`[[retired]] entry is missing a string "${key}"`)
-	return m[2]
-}
-
-// A `[key = [...]]` array, tolerant of the array spanning several lines (as the README's worked
-// example does). An opened-but-never-closed array is a parse error, not a silently empty result —
-// silently swallowing it would be exactly the false-green this guard exists to prevent.
-function extractArray(block: string, key: string): string[] {
-	const openRe = new RegExp(`(^|\\n)\\s*${key}\\s*=\\s*\\[`)
-	const openMatch = openRe.exec(block)
-	if (!openMatch) return []
-	const openIdx = openMatch.index + openMatch[0].length - 1 // index of the "["
-	const closeIdx = block.indexOf(']', openIdx)
-	if (closeIdx === -1) throw new RegistryParseError(`"${key}" array is never closed with "]"`)
-	const arrText = block.slice(openIdx, closeIdx)
-	const out: string[] = []
-	for (const q of arrText.matchAll(/"([^"]*)"/g)) out.push(q[1])
-	return out
-}
-
-/** Parses the registry's minimal TOML subset: an array of `[[retired]]` tables carrying string
- * keys (term/since/replacement, all required) and optional string-array keys (scope/allow). Throws
- * `RegistryParseError` on anything that does not fit that shape — an absent registry is handled by
- * the caller (`readRegistry`), not here; an empty/comment-only file parses to `[]`. */
-export function parseRegistryToml(text: string): RetiredEntry[] {
-	const marker = '[[retired]]'
-	const firstIdx = text.indexOf(marker)
-	if (firstIdx === -1) {
-		if (text.split('\n').every(isBlankOrComment)) return []
-		throw new RegistryParseError('no [[retired]] table found and the file is not empty/comment-only')
-	}
-	const preamble = text.slice(0, firstIdx)
-	if (!preamble.split('\n').every(isBlankOrComment)) {
-		throw new RegistryParseError('content found before the first [[retired]] table header')
-	}
-	const blocks = text.slice(firstIdx).split(marker).slice(1)
-	return blocks.map((block) => {
-		const term = extractString(block, 'term')
-		const since = extractString(block, 'since')
-		const replacement = extractString(block, 'replacement')
-		const scope = extractArray(block, 'scope')
-		const allow = extractArray(block, 'allow')
-		const entry: RetiredEntry = { term, since, replacement }
-		if (scope.length) entry.scope = scope
-		if (allow.length) entry.allow = allow
-		return entry
-	})
-}
-
-/** Reads and parses the registry at `<root>/.agents/sdd/retired-terms.toml`. An absent file yields
- * `[]` (an "an absent registry sweeps clean" registry, not an error). A present-but-malformed file
- * throws `RegistryParseError` — the caller must surface that loudly and exit non-zero. */
-export function readRegistry(root: string): RetiredEntry[] {
-	const file = join(root, REGISTRY_PATH)
-	if (!existsSync(file)) return []
-	return parseRegistryToml(readFileSync(file, 'utf8'))
-}
-
-// ── Built-in exclusions — always applied, never configurable ──
-// The rule: a surface whose job is to name the retired term is not drift. Two kinds qualify:
-// (a) the guard's own definition — the registry, this engine's source + test, and this node's own
-//     README + .feature (it states the banned text to define it), and
-// (b) durable provenance — every ledger/ directory, and everything under .agents/plans/.
-// Nothing else is excluded: a spec README that merely *mentions* a retired convention is drift.
-
-const ENGINE_SOURCE = 'plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.mts'
-const ENGINE_TEST = 'plugins/sdd/skills/check-retired-terms/scripts/check-retired-terms.test.mts'
-const NODE_README = '.agents/specs/sdd/corpus/retired-terms/README.md'
-const NODE_FEATURE = '.agents/specs/sdd/corpus/retired-terms/retired-terms.feature'
-
-const DEFAULT_BUILTIN_EXCLUDED_FILES: readonly string[] = [
-	REGISTRY_PATH,
-	ENGINE_SOURCE,
-	ENGINE_TEST,
-	NODE_README,
-	NODE_FEATURE,
-]
-
-const DEFAULT_BUILTIN_EXCLUDED_PREFIXES: readonly string[] = ['.agents/plans/']
-
-// Any file sitting inside a directory literally named "ledger", at any depth (e.g.
-// ".agents/specs/aced/ledger/x.jsonl") — durable provenance, not a directory this guard walks by
-// prefix from the root.
-function isUnderLedgerDir(relPath: string): boolean {
-	const segs = relPath.split('/')
-	return segs.slice(0, -1).includes('ledger')
-}
-
-function isBuiltinExcluded(
-	relPath: string,
-	excludedFiles: readonly string[],
-	excludedPrefixes: readonly string[],
-): boolean {
-	if (excludedFiles.includes(relPath)) return true
-	if (excludedPrefixes.some((p) => relPath.startsWith(p))) return true
-	if (isUnderLedgerDir(relPath)) return true
-	return false
-}
-
-// ── Scope + allow ──
-
-function inScope(relPath: string, scope?: string[]): boolean {
-	if (!scope || scope.length === 0) return true
-	return scope.some((prefix) => relPath.startsWith(prefix))
-}
-
-interface ParsedAllow {
-	file: string
-	substring?: string
-}
-
-function parseAllowEntry(raw: string): ParsedAllow {
-	const idx = raw.indexOf('::')
-	if (idx === -1) return { file: raw.trim() }
-	return { file: raw.slice(0, idx).trim(), substring: raw.slice(idx + 2).trim() }
-}
-
-// A bare-path allow entry sanctions every line of that file; a `path :: substring` entry sanctions
-// only lines carrying that substring, leaving the rest of the file guarded.
-function isAllowed(relPath: string, lineText: string, allow: string[] | undefined): boolean {
-	if (!allow) return false
-	for (const raw of allow) {
-		const parsed = parseAllowEntry(raw)
-		if (parsed.file !== relPath) continue
-		if (parsed.substring === undefined) return true
-		if (lineText.includes(parsed.substring)) return true
-	}
-	return false
-}
-
-// ── Tracked files ──
-
-/** The git-tracked file set, repo-relative, one per line. An untracked file is outside the sweep
- * by construction — it is never in this list. */
-export function listTrackedFiles(root: string): string[] {
-	const out = execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8' })
-	return out.split('\n').filter((l) => l !== '')
-}
-
-// ── Sweep ──
-
-export interface Violation {
-	file: string
-	line: number
-	term: string
-	replacement: string
-}
-
-export interface SweepOptions {
-	/** Substitute the tracked-file lister (tests inject a fixed list instead of shelling to git). */
-	listTrackedFiles?: (root: string) => string[]
-	/** Substitute the built-in excluded-file set (tests probe the exclusion mechanism in isolation). */
-	builtinExcludedFiles?: readonly string[]
-	/** Substitute the built-in excluded-prefix set. */
-	builtinExcludedPrefixes?: readonly string[]
-}
-
-/** Sweeps `root` for survivors of every entry in `entries`. `options` lets callers (tests)
- * substitute fixture-scoped config — the tracked-file source and the built-in exclusion lists —
- * in place of the real repo and the real defaults, mirroring `findMetaphorViolations`'s
- * `ScanOptions` (packages/cyberlegion/src/metaphor-free.ts). */
-export function sweep(root: string, entries: RetiredEntry[], options: SweepOptions = {}): Violation[] {
-	const listFiles = options.listTrackedFiles ?? listTrackedFiles
-	const excludedFiles = options.builtinExcludedFiles ?? DEFAULT_BUILTIN_EXCLUDED_FILES
-	const excludedPrefixes = options.builtinExcludedPrefixes ?? DEFAULT_BUILTIN_EXCLUDED_PREFIXES
-
-	const violations: Violation[] = []
-	for (const relPath of listFiles(root)) {
-		if (isBuiltinExcluded(relPath, excludedFiles, excludedPrefixes)) continue
-
-		let text: string
-		try {
-			text = readFileSync(join(root, relPath), 'utf8')
-		} catch {
-			continue
-		}
-		const lines = text.split('\n')
-
-		for (const entry of entries) {
-			if (!inScope(relPath, entry.scope)) continue
-			lines.forEach((lineText, i) => {
-				if (!lineText.includes(entry.term)) return
-				if (isAllowed(relPath, lineText, entry.allow)) return
-				violations.push({ file: relPath, line: i + 1, term: entry.term, replacement: entry.replacement })
-			})
-		}
-	}
-	return violations.sort((a, b) => (a.file !== b.file ? (a.file < b.file ? -1 : 1) : a.line - b.line))
-}
-
-// ── CLI ──
-
-/** Renders `--list` output: one line per registered term with its `since` and `replacement`, or a
- * definitive empty-state line when nothing is registered — never silence. */
-export function formatList(entries: RetiredEntry[]): string {
-	if (entries.length === 0) return 'check-retired-terms: no term is registered\n'
-	return entries.map((e) => `${e.term}  (since ${e.since})  -> ${e.replacement}\n`).join('')
-}
-
-/** Renders the sweep report: `file:line:term` plus the declared replacement, one per survivor
- * (every survivor, not just the first), then a count summary. */
-export function formatViolations(violations: Violation[]): string {
-	const lines = violations.map((v) => `${v.file}:${v.line}:${v.term} — replace with: ${v.replacement}\n`)
-	lines.push(`check-retired-terms: ${violations.length} survivor(s) found\n`)
-	return lines.join('')
-}
-
-export function main(argv: string[]): number {
-	const root = argv.includes('--root') ? (argv[argv.indexOf('--root') + 1] ?? '.') : '.'
-	const list = argv.includes('--list')
-
-	let entries: RetiredEntry[]
-	try {
-		entries = readRegistry(root)
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err)
-		process.stderr.write(`check-retired-terms: malformed registry — ${message}\n`)
-		return 1
-	}
-
-	if (list) {
-		process.stdout.write(formatList(entries))
-		return 0
-	}
-
-	const violations = sweep(root, entries)
-	if (violations.length === 0) {
-		process.stdout.write('check-retired-terms: clean — no survivors found\n')
-		return 0
-	}
-	process.stdout.write(formatViolations(violations))
-	return 1
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}

package/skills/check-scenario-overlap/scripts/check-scenario-overlap.bundle.mjs

@@ -1,175 +0,0 @@
-#!/usr/bin/env node
-import { readFileSync, readdirSync, realpathSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-//#region skills/check-scenario-overlap/scripts/check-scenario-overlap.mts
-const SKIP_DIRS = /* @__PURE__ */ new Set([
-	"node_modules",
-	".git",
-	"dist",
-	".turbo",
-	".next",
-	"coverage"
-]);
-function normalize(s) {
-	return s.trim().replace(/\s+/g, " ").toLowerCase();
-}
-const STEP = /^\s*(Given|When|Then|And|But)\s+(.*\S)\s*$/;
-const SCENARIO = /^\s*Scenario(?: Outline)?:\s*(.*\S)\s*$/;
-const TABLE_ROW = /^\s*\|(.*)\|\s*$/;
-function normalizeRow(line) {
-	return (TABLE_ROW.exec(line)?.[1] ?? line).split("|").map((cell) => normalize(cell)).join("|");
-}
-function parseFeature(featureText) {
-	const scenarios = [];
-	let title = null;
-	let steps = [];
-	let exampleRows = [];
-	const flush = () => {
-		if (title !== null) {
-			const fingerprint = exampleRows.length === 0 ? steps.map(normalize).join("\n") : `${steps.map(normalize).join("\n")}\n EXAMPLES \n${exampleRows.join("\n")}`;
-			scenarios.push({
-				title,
-				titleKey: normalize(title),
-				fingerprint
-			});
-		}
-		title = null;
-		steps = [];
-		exampleRows = [];
-	};
-	for (const line of featureText.split("\n")) {
-		const sc = SCENARIO.exec(line);
-		if (sc) {
-			flush();
-			title = sc[1];
-			continue;
-		}
-		if (title === null) continue;
-		const st = STEP.exec(line);
-		if (st) {
-			steps.push(st[2]);
-			continue;
-		}
-		if (TABLE_ROW.test(line)) exampleRows.push(normalizeRow(line));
-	}
-	flush();
-	return scenarios;
-}
-function displayPath(relPath) {
-	const p = relPath.replace(/\\/g, "/");
-	return p.endsWith("/README.md") ? p.slice(0, -9) : p;
-}
-function scanSuites(specDir) {
-	const suites = [];
-	walk(specDir, specDir, suites);
-	return suites.sort((a, b) => a.node.localeCompare(b.node));
-}
-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);
-			continue;
-		}
-		if (!entry.name.endsWith(".feature")) continue;
-		const scenarios = parseFeature(readFileSync(full, "utf8"));
-		if (scenarios.length === 0) continue;
-		const relDir = dir.slice(specDir.length + 1).replace(/\\/g, "/");
-		out.push({
-			node: displayPath(`${relDir}/`),
-			scenarios
-		});
-	}
-}
-function detect(suites) {
-	const byFingerprint = /* @__PURE__ */ new Map();
-	const byTitle = /* @__PURE__ */ new Map();
-	for (const suite of suites) for (const sc of suite.scenarios) {
-		if (sc.fingerprint !== "") {
-			let m = byFingerprint.get(sc.fingerprint);
-			if (!m) byFingerprint.set(sc.fingerprint, m = /* @__PURE__ */ new Map());
-			if (!m.has(suite.node)) m.set(suite.node, sc.title);
-		}
-		let t = byTitle.get(sc.titleKey);
-		if (!t) byTitle.set(sc.titleKey, t = /* @__PURE__ */ new Map());
-		let e = t.get(suite.node);
-		if (!e) t.set(suite.node, e = {
-			fps: /* @__PURE__ */ new Set(),
-			title: sc.title
-		});
-		e.fps.add(sc.fingerprint);
-	}
-	const candidates = [];
-	for (const [, nodeMap] of byFingerprint) {
-		if (nodeMap.size < 2) continue;
-		const nodes = [...nodeMap.keys()].sort();
-		for (let i = 0; i < nodes.length; i++) for (let j = i + 1; j < nodes.length; j++) candidates.push({
-			kind: "exact-duplicate",
-			severity: "blocking",
-			nodes: [nodes[i], nodes[j]],
-			scenario: nodeMap.get(nodes[i]) ?? "",
-			detail: "identical step fingerprint — the same behavior is specified in both nodes; one behavior = one owning node"
-		});
-	}
-	for (const [, nodeMap] of byTitle) {
-		if (nodeMap.size < 2) continue;
-		const nodes = [...nodeMap.keys()].sort();
-		for (let i = 0; i < nodes.length; i++) for (let j = i + 1; j < nodes.length; j++) {
-			const a = nodeMap.get(nodes[i]);
-			const b = nodeMap.get(nodes[j]);
-			if (!a || !b) continue;
-			if ([...a.fps].some((fp) => b.fps.has(fp))) continue;
-			candidates.push({
-				kind: "title-overlap",
-				severity: "advisory",
-				nodes: [nodes[i], nodes[j]],
-				scenario: a.title,
-				detail: "same scenario title, differing steps — a weaker overlap hint the Warden judges"
-			});
-		}
-	}
-	return candidates;
-}
-function hasBlocking(candidates) {
-	return candidates.some((c) => c.severity === "blocking");
-}
-function renderCandidates(candidates, specDir) {
-	const blocking = candidates.filter((c) => c.severity === "blocking");
-	const advisory = candidates.filter((c) => c.severity === "advisory");
-	const lines = [`check-scenario-overlap: spec-dir=${specDir}`];
-	lines.push(`blocking[${blocking.length}]:`);
-	for (const c of blocking) lines.push(`  ${c.nodes[0]} <-> ${c.nodes[1]} — ${c.kind}: "${c.scenario}" — ${c.detail}`);
-	lines.push(`advisory[${advisory.length}]:`);
-	for (const c of advisory) lines.push(`  ${c.nodes[0]} <-> ${c.nodes[1]} — ${c.kind}: "${c.scenario}" — ${c.detail}`);
-	lines.push("note: advisory — candidates feed the Warden formation pass; the engine writes nothing");
-	return lines.join("\n");
-}
-function main(argv) {
-	let specDir = ".";
-	let mode = "audit";
-	let format = "toon";
-	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 === "--format") format = argv[++i] ?? "toon";
-	}
-	const candidates = detect(scanSuites(specDir));
-	if (mode === "check") {
-		if (hasBlocking(candidates)) {
-			process.stderr.write(`check-scenario-overlap: ${candidates.filter((c) => c.severity === "blocking").length} exact-duplicate candidate(s)\n`);
-			return 1;
-		}
-		process.stdout.write("check-scenario-overlap: no exact-duplicate candidates\n");
-		return 0;
-	}
-	if (format === "json") process.stdout.write(`${JSON.stringify(candidates)}\n`);
-	else process.stdout.write(`${renderCandidates(candidates, 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 { detect, hasBlocking, main, normalize, parseFeature, renderCandidates, scanSuites };