cyber-sdd 0.7.0 → 0.7.2

package/skills/spec-gate/scripts/classify-edit-class.mts

@@ -1,414 +0,0 @@
-#!/usr/bin/env node
-// classify-edit-class — the structural edit-class classifier for a touched frozen `.feature`
-// (the "Structural edit-class classification (freeze integrity)" section of the SDD project spec's
-// `authoring/spec-gate` node, repo-only). Classifies each touched file's change against its
-// committed baseline so the gate can route: additive / no-content-change self-clear; narrowing /
-// mixed take the existing narrowing -> Clearance path. This engine only CLASSIFIES — it fires no
-// verdict and adds no new floor.
-//
-// The classification is STRUCTURAL, never a raw git line-diff. A raw line-diff is fooled by a
-// trailing step orphaned off a frozen scenario onto a newly added adjacent scenario: the orphan
-// shows no `-` line and reads as purely additive, so a narrowing self-clears silently and
-// Clearance never fires. The pinned `gherkin-cli` `diffFeatures(paths, {base})` is AST-level
-// and is not fooled — it reports the losing baseline scenario as `modified` (`addOnly: false`).
-//
-// The pin is load-bearing, not incidental. Through `0.0.1` the differ's scenario identity covered
-// step keyword + text only, so a step's DocString / DataTable could be rewritten while the scenario
-// still reported `unchanged` — and a `@rubric` lives wholly inside a DocString, which put every
-// graded scenario outside the freeze. `0.0.2` hashes what an argument SAYS (content, media type) and
-// still excludes how it is WRITTEN (delimiter, table padding, source locations), so a reformat does
-// not fire Clearance. Both directions are bound by the frozen scenarios in this engine's suite;
-// moving the pin backwards fails three of them.
-//
-// Classifications:
-//   unfrozen-skip    — the file carries no feature-level @frozen tag in the baseline OR the
-//                       working version; the edit-class routing does not apply to it.
-//   additive         — addOnly true and at least one whole scenario was added; no baseline
-//                       scenario was modified or removed.
-//   no-content-change — a pure rename (git rename detection, 100% content match) or a diff with
-//                       zero added/modified/removed scenarios.
-//   narrowing        — at least one baseline scenario is modified or removed (no scenario added).
-//   mixed            — both a whole-scenario addition AND a modified/removed baseline scenario.
-//
-// Pure functions are exported for node:test; running the file directly drives the CLI.
-
-import { execFileSync } from 'node:child_process'
-import { readFileSync, realpathSync } from 'node:fs'
-import { dirname, join, relative, resolve, sep } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { GitError, diff as gherkinDiff, type ReadsGitDiff } from '../vendor/gherkin-cli.mjs'
-
-// ─── types ────────────────────────────────────────────────────────────────────
-
-export type EditClassification =
-	| 'unfrozen-skip'
-	| 'additive'
-	| 'no-content-change'
-	| 'narrowing'
-	| 'mixed'
-	| 'unclassifiable'
-
-export type ScenarioChangeKind = 'added' | 'modified' | 'removed' | 'unchanged'
-
-export interface ScenarioChange {
-	name: string
-	change: ScenarioChangeKind
-}
-
-export interface GherkinDiffFileResult {
-	file: string
-	addOnly: boolean
-	scenarios: ScenarioChange[]
-	// Present when the differ could not parse one side of the comparison for this file. Its
-	// presence must be checked BEFORE reading `scenarios` — an unparseable file yields an EMPTY
-	// `scenarios` array, and empty reads as "nothing changed" (see classifyFromDiff) whether the
-	// file genuinely did not change or the differ simply could not see it. That emptiness is
-	// structurally guaranteed here, not measured, so it is not evidence of anything.
-	error?: { code: string; message: string }
-}
-
-export interface GherkinDiffOutput {
-	summary: { addOnly: boolean }
-	files: GherkinDiffFileResult[]
-}
-
-export interface ClassificationResult {
-	file: string
-	classification: EditClassification
-	scenarios: ScenarioChange[]
-	// Set only for `unclassifiable` — why the differ's result could not be trusted.
-	reason?: string
-}
-
-// ─── feature-level @frozen tag ─────────────────────────────────────────────────
-
-// A feature-level tag sits on the contiguous block of `@tag` lines immediately above the
-// `Feature:` line (blank lines between tags and Feature: are tolerated). Only that block is
-// consulted — a scenario-level tag further down the file is not a feature-level freeze marker.
-export function hasFeatureFrozenTag(text: string): boolean {
-	const lines = text.split('\n')
-	const featureIdx = lines.findIndex((l) => /^\s*Feature:/i.test(l))
-	if (featureIdx === -1) return false
-	const tags: string[] = []
-	for (let i = featureIdx - 1; i >= 0; i--) {
-		const line = lines[i].trim()
-		if (line === '') continue
-		if (line.startsWith('@')) {
-			tags.push(...line.split(/\s+/).filter(Boolean))
-			continue
-		}
-		break
-	}
-	return tags.includes('@frozen')
-}
-
-// ─── structural classification from a gherkin-cli diff result ─────────────────
-
-// Classifies purely from the per-scenario `change` array a gherkin-cli diff reports — never from
-// a raw line count. `additive` requires at least one whole-scenario addition and zero
-// modified/removed baseline scenarios; `narrowing` is any modified/removed baseline scenario with
-// no addition; both together is `mixed`; neither is `no-content-change` (a diff against the
-// baseline with nothing structurally different).
-export function classifyFromDiff(fileResult: { addOnly: boolean; scenarios: ScenarioChange[] }): EditClassification {
-	const added = fileResult.scenarios.some((s) => s.change === 'added')
-	const narrowed = fileResult.scenarios.some((s) => s.change === 'modified' || s.change === 'removed')
-	if (added && narrowed) return 'mixed'
-	if (narrowed) return 'narrowing'
-	if (added) return 'additive'
-	return 'no-content-change'
-}
-
-// ─── the escalation boundary — an input the classifier cannot classify ────────
-
-// A file the differ reports a parse error for, or does not report at all, is not "no change" —
-// it is an input the classifier has no evidence about, and absence of evidence never reads as
-// evidence of no change. `error` is checked FIRST, before `scenarios` is read at all: an
-// unparseable file gives the differ nothing to compare, so it reports an empty `scenarios` array
-// (and a top-level `summary.addOnly: true`), which classifyFromDiff would otherwise read as
-// `no-content-change`. That emptiness is structurally guaranteed by the parse failure rather than
-// measured against the baseline — which is how a rewritten suite came to self-clear.
-export function classifyFromFileResult(fileResult: GherkinDiffFileResult | undefined): {
-	classification: EditClassification
-	reason?: string
-} {
-	if (fileResult === undefined) {
-		return { classification: 'unclassifiable', reason: 'the structural differ returned no result for this file' }
-	}
-	if (fileResult.error) {
-		return {
-			classification: 'unclassifiable',
-			reason: `cannot parse (${fileResult.error.code}): ${fileResult.error.message}`,
-		}
-	}
-	return { classification: classifyFromDiff(fileResult) }
-}
-
-// ─── pure rename detection (git, not gherkin-cli) ──────────────────────────────
-// gherkin-cli diff reads the base ref's content AT THE SAME PATH — a renamed file has no content
-// at its new path in the base ref, so gherkin-cli alone reports every scenario as freshly
-// "added" (addOnly: true) for a pure rename, indistinguishable from a genuinely new file. Git's
-// own rename detection (`-M`) pairs the old and new paths across the whole tree and scores their
-// similarity; a 100% score is a zero-content-delta pure rename.
-
-export interface RenameStatus {
-	score: number
-	oldPath: string
-	newPath: string
-}
-
-export function parseRenameStatus(nameStatusOutput: string): RenameStatus[] {
-	const out: RenameStatus[] = []
-	for (const line of nameStatusOutput.split('\n')) {
-		const m = /^R(\d+)\t([^\t]+)\t([^\t]+)$/.exec(line)
-		if (m) out.push({ score: Number(m[1]), oldPath: m[2], newPath: m[3] })
-	}
-	return out
-}
-
-function detectPureRename(base: string, path: string, cwd: string): boolean {
-	try {
-		const out = execFileSync('git', ['diff', '--name-status', '-M', base], {
-			encoding: 'utf8',
-			cwd,
-			stdio: ['ignore', 'pipe', 'ignore'],
-		})
-		return parseRenameStatus(out).some((r) => r.newPath === path && r.score === 100)
-	} catch {
-		return false
-	}
-}
-
-// Reads a path's content at a given git ref (the committed baseline). Any failure (new file at
-// base, path not tracked at base, git absent) returns '' — the safe default that reads as
-// "no baseline", matching check-spec-state.mts's readBaselineFromGit convention.
-function readGitShow(base: string, path: string, cwd: string): string {
-	try {
-		return execFileSync('git', ['show', `${base}:${path}`], {
-			encoding: 'utf8',
-			cwd,
-			stdio: ['ignore', 'pipe', 'ignore'],
-		})
-	} catch {
-		return ''
-	}
-}
-
-// Thin boundary around the pinned `gherkin-cli` `diff` — never a re-implemented differ.
-// classifyFromDiff / classifyFromFileResult carry the tested logic; this only wires the engine in.
-// Takes a batch of paths (`diff` is already variadic over paths) so a multi-file caller
-// pays for one parse pass, not one per file.
-export type GherkinDiffRunner = (base: string, paths: string[], cwd: string) => GherkinDiffOutput
-
-// `diff`'s default reader resolves each path via `path.resolve(file)` against
-// `process.cwd()` and derives git's own cwd from THAT resolved location (`dirname` of the
-// resolved path, then `git ls-files --full-name` to recover the repo-relative path) — it never
-// trusts a caller-supplied cwd for the git commands at all. That self-derivation is why the
-// original CLI boundary tolerated a caller's relative-path bookkeeping being off: whatever `file`
-// resolves to, the reader walks UP from there to find the right repo and the right relative path.
-// This reader is the library's own extension seam ("Injectable so tests can skip git"), replicated
-// verbatim with the one substitution that matters here — `resolve(cwd, file)` instead of
-// `resolve(file)` — so a caller's `cwd` participates without discarding that self-correction.
-function makeCwdReader(cwd: string): ReadsGitDiff['readDiff'] {
-	return (file, base) => {
-		const abs = resolve(cwd, file)
-		const dir = dirname(abs)
-		let head: string | undefined
-		try {
-			head = readFileSync(abs, 'utf8')
-		} catch {
-			head = undefined
-		}
-		const gitIo = {
-			cwd: dir,
-			encoding: 'utf8' as const,
-			stdio: ['ignore', 'pipe', 'ignore'] as ['ignore', 'pipe', 'ignore'],
-		}
-		let rel: string
-		try {
-			rel = execFileSync('git', ['ls-files', '--full-name', '--', abs], gitIo).trim()
-		} catch (err) {
-			throw new GitError(`git ls-files failed for ${file}: ${(err as Error).message}`)
-		}
-		if (rel === '') {
-			const top = execFileSync('git', ['rev-parse', '--show-toplevel'], gitIo).trim()
-			rel = relative(top, abs).split(sep).join('/')
-		}
-		let baseText: string | undefined
-		try {
-			baseText = execFileSync('git', ['show', `${base}:${rel}`], gitIo)
-		} catch {
-			try {
-				execFileSync('git', ['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd: dir, stdio: 'ignore' })
-				baseText = undefined
-			} catch {
-				throw new GitError(`git could not resolve base ref '${base}'`)
-			}
-		}
-		return { head, base: baseText }
-	}
-}
-
-export const runGherkinDiff: GherkinDiffRunner = (base, paths, cwd) =>
-	gherkinDiff(paths, { base, full: true }, { readDiff: makeCwdReader(cwd) })
-
-// ─── per-file classification ────────────────────────────────────────────────────
-
-// The frozen-tag and rename checks a path resolves before ever needing a diff. `early` is set when
-// those checks alone decide the classification (no gherkin-cli call needed); its absence means the
-// caller still owes this path a diff lookup.
-interface PreCheckedFile {
-	path: string
-	early?: ClassificationResult
-}
-
-function preCheckFile(path: string, base: string, cwd: string): PreCheckedFile {
-	let currentText: string
-	try {
-		currentText = readFileSync(join(cwd, path), 'utf8')
-	} catch {
-		currentText = ''
-	}
-	const baselineText = readGitShow(base, path, cwd)
-
-	// Skip files carrying no feature-level @frozen tag in EITHER the baseline or the working
-	// version — the edit-class routing this engine feeds only applies to frozen files.
-	if (!hasFeatureFrozenTag(currentText) && !hasFeatureFrozenTag(baselineText)) {
-		return { path, early: { file: path, classification: 'unfrozen-skip', scenarios: [] } }
-	}
-
-	// A pure rename is not a gate-able edit regardless of what gherkin-cli would (mis)report at
-	// the new path — check git's rename detection before ever calling gherkin-cli.
-	if (detectPureRename(base, path, cwd)) {
-		return { path, early: { file: path, classification: 'no-content-change', scenarios: [] } }
-	}
-
-	return { path }
-}
-
-// The CLI echoes each path as given, so an exact match is the expected case. A diff that reports
-// under a different path (rather than omitting it) still resolves for a single-file batch — but
-// with multiple files reported and no exact match, which one is "this file" is not knowable, so it
-// falls through to `undefined` and classifyFromFileResult's no-result escalation.
-function classifyFromDiffOutput(path: string, diff: GherkinDiffOutput): ClassificationResult {
-	const fileResult = diff.files.find((f) => f.file === path) ?? (diff.files.length === 1 ? diff.files[0] : undefined)
-	const { classification, reason } = classifyFromFileResult(fileResult)
-	return { file: path, classification, scenarios: fileResult?.scenarios ?? [], reason }
-}
-
-// `diff` is injected so the tests can drive the differ's failure branch — a binary that exits
-// without a readable result is a real, reachable path (a bad base ref makes the CLI exit nonzero
-// with no `files` array), and it must escalate rather than resolve to a reassuring class.
-export function classifyFile(
-	path: string,
-	base: string,
-	cwd = '.',
-	diffWith: GherkinDiffRunner = runGherkinDiff,
-): ClassificationResult {
-	const pre = preCheckFile(path, base, cwd)
-	if (pre.early) return pre.early
-
-	let diff: GherkinDiffOutput
-	try {
-		diff = diffWith(base, [path], cwd)
-	} catch {
-		return {
-			file: path,
-			classification: 'unclassifiable',
-			scenarios: [],
-			reason: 'the structural differ produced no readable result',
-		}
-	}
-	return classifyFromDiffOutput(path, diff)
-}
-
-// The classification is scoped to the CR's touched .feature files only — a caller passes the
-// explicit touched-path list, never a tree-wide sweep. Pre-checks (frozen tag, rename) run per file
-// with no subprocess cost; only the paths still needing a structural diff after that are batched
-// into a SINGLE `gherkin-cli diff` call, so an N-file touch set pays for one parse pass, not N.
-export function classifyFiles(
-	paths: string[],
-	base: string,
-	cwd = '.',
-	diffWith: GherkinDiffRunner = runGherkinDiff,
-): ClassificationResult[] {
-	const preChecked = paths.filter((p) => p.endsWith('.feature')).map((path) => preCheckFile(path, base, cwd))
-	const needsDiff = preChecked.filter((r) => r.early === undefined).map((r) => r.path)
-
-	let diff: GherkinDiffOutput | undefined
-	if (needsDiff.length > 0) {
-		try {
-			diff = diffWith(base, needsDiff, cwd)
-		} catch {
-			diff = undefined
-		}
-	}
-
-	return preChecked.map(({ path, early }) => {
-		if (early) return early
-		if (diff === undefined) {
-			return {
-				file: path,
-				classification: 'unclassifiable',
-				scenarios: [],
-				reason: 'the structural differ produced no readable result',
-			}
-		}
-		return classifyFromDiffOutput(path, diff)
-	})
-}
-
-// ─── output ──────────────────────────────────────────────────────────────────
-
-export function formatText(results: ClassificationResult[]): string {
-	const lines: string[] = []
-	for (const r of results) {
-		lines.push(`${r.classification.toUpperCase().padEnd(18)} ${r.file}`)
-		if (r.reason) lines.push(`  ${r.reason}`)
-		for (const s of r.scenarios) {
-			if (s.change !== 'unchanged') lines.push(`  ${s.change.padEnd(10)} ${s.name}`)
-		}
-	}
-	return lines.join('\n')
-}
-
-// ─── CLI entry ────────────────────────────────────────────────────────────────
-
-function parseFilesArg(argv: string[]): string[] {
-	const idx = argv.indexOf('--files')
-	if (idx === -1) return []
-	const paths: string[] = []
-	for (let i = idx + 1; i < argv.length; i++) {
-		if (argv[i].startsWith('--')) break
-		paths.push(argv[i])
-	}
-	return paths
-}
-
-export function main(argv: string[]): number {
-	const paths = parseFilesArg(argv)
-	if (paths.length === 0) {
-		console.error('✗ --files requires at least one .feature path')
-		return 1
-	}
-	const base = argv.includes('--base') ? argv[argv.indexOf('--base') + 1] : 'HEAD'
-	const format = argv.includes('--format') ? argv[argv.indexOf('--format') + 1] : 'text'
-
-	const results = classifyFiles(paths, base)
-
-	if (format === 'json') {
-		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`)
-	} else {
-		process.stdout.write(`${formatText(results)}\n`)
-	}
-
-	const unclassifiable = results.filter((r) => r.classification === 'unclassifiable')
-	if (unclassifiable.length) {
-		for (const r of unclassifiable) console.error(`✗ ${r.file}: unclassifiable — ${r.reason}`)
-		return 1
-	}
-	return 0
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}

package/skills/spec-gate/vendor/gherkin-cli.d.mts

@@ -1,2 +0,0 @@
-// Types for the bundled gherkin-cli beside this file: the same module, so the same types.
-export * from 'gherkin-cli'