al-sem 0.0.1

package/scripts/precision-sample.ts

@@ -0,0 +1,99 @@
+// scripts/precision-sample.ts
+// Stratified sampler for precision-study rounds. Reads compact JSON output
+// from `analyze --format json --deterministic`, filters to a detector, and
+// prints a manageable sample with the anchor + evidence path so a reviewer
+// can open each one and judge TP/FP.
+//
+// Stratification: deterministic sample — first N per (severity, rootCause
+// shape) bucket to ensure breadth across the finding distribution.
+
+import { readFileSync } from "node:fs";
+
+interface Location {
+	file: string;
+	line: number;
+	column: number;
+	objectName?: string;
+	routineName?: string;
+}
+interface Finding {
+	id: string;
+	detector: string;
+	severity: string;
+	title?: string;
+	rootCause: string;
+	primaryLocation: Location;
+	terminalLocation?: Location;
+	pathCount?: number;
+	affectedTables?: string[];
+}
+interface RunJson {
+	findings: Finding[];
+}
+
+function shortLoc(a: Location | undefined): string {
+	if (!a) return "<no-anchor>";
+	const file = a.file.replace(/^ws:/, "");
+	const where = a.objectName && a.routineName ? ` (${a.objectName} :: ${a.routineName})` : "";
+	return `${file}:${a.line}:${a.column}${where}`;
+}
+
+function rootCauseShape(rc: string): string {
+	// Strip noun-phrase variables — keep the rule's verbal skeleton.
+	// Goal: cluster findings that hit the same antipattern with different operands.
+	return rc
+		.replace(/[A-Z][A-Za-z0-9_]*(\s+[A-Z][A-Za-z0-9_]*)*/g, "<Name>")
+		.replace(/'[^']*'/g, "<str>")
+		.replace(/"[^"]*"/g, "<str>")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function main(): void {
+	const [path, detectorFilter, perBucketStr] = process.argv.slice(2);
+	if (!path || !detectorFilter) {
+		console.error("usage: precision-sample.ts <run.json> <detector-id> [perBucket=3]");
+		process.exit(2);
+	}
+	const perBucket = Number(perBucketStr ?? 3);
+	const run = JSON.parse(readFileSync(path, "utf8")) as RunJson;
+	const matching = run.findings.filter((f) => f.detector === detectorFilter);
+
+	// Bucket by (severity, rootCauseShape) for stratified sampling.
+	const buckets = new Map<string, Finding[]>();
+	for (const f of matching) {
+		const key = `${f.severity}|${rootCauseShape(f.rootCause)}`;
+		const arr = buckets.get(key) ?? [];
+		arr.push(f);
+		buckets.set(key, arr);
+	}
+
+	console.log(`# Sample for ${detectorFilter} — ${matching.length} total, ${buckets.size} buckets`);
+	console.log("");
+	const sortedKeys = [...buckets.keys()].sort();
+	let sampleCount = 0;
+	for (const key of sortedKeys) {
+		const all = buckets.get(key) ?? [];
+		const take = all.slice(0, perBucket);
+		const [sev, shape] = key.split("|", 2);
+		console.log(`## bucket: severity=${sev}, total=${all.length}`);
+		console.log(`shape: ${shape}`);
+		console.log("");
+		for (const f of take) {
+			sampleCount++;
+			console.log(`### finding ${sampleCount}`);
+			console.log(`anchor:   ${shortLoc(f.primaryLocation)}`);
+			if (f.terminalLocation) console.log(`terminal: ${shortLoc(f.terminalLocation)}`);
+			console.log(`rootCause: ${f.rootCause}`);
+			if (f.pathCount && f.pathCount > 1) console.log(`pathCount: ${f.pathCount}`);
+			console.log("");
+		}
+		if (all.length > perBucket) {
+			console.log(`(... + ${all.length - perBucket} more in this bucket)`);
+			console.log("");
+		}
+	}
+	console.log(`# Sampled ${sampleCount} of ${matching.length} findings.`);
+}
+
+main();

package/scripts/precision-study.ts

@@ -0,0 +1,42 @@
+// scripts/precision-study.ts
+//
+// Sample N findings per detector from a workspace and emit a CSV the developer can
+// fill in with manual classifications. Used to drive evidence-based detector tuning.
+//
+// Usage:
+//   bun run scripts/precision-study.ts <workspace> [N]
+//
+// N defaults to 30. Output is CSV to stdout.
+
+import { analyzeWorkspace } from "../src/index.ts";
+import { projectFinding } from "../src/projection/finding-summary.ts";
+
+const workspaceRoot = process.argv[2];
+if (!workspaceRoot) {
+    process.stderr.write("usage: bun run scripts/precision-study.ts <workspace> [N]\n");
+    process.exit(1);
+}
+const N = Number.parseInt(process.argv[3] ?? "30", 10);
+
+const result = await analyzeWorkspace({ workspaceRoot, deterministic: true });
+
+const byDetector = new Map<string, typeof result.findings>();
+for (const f of result.findings) {
+    const list = byDetector.get(f.detector);
+    if (list) list.push(f);
+    else byDetector.set(f.detector, [f]);
+}
+
+process.stdout.write("detector,severity,file,line,object,routine,table,classification,notes\n");
+for (const [detector, list] of byDetector) {
+    for (const raw of list.slice(0, N)) {
+        const f = projectFinding(raw, result.model);
+        const file = f.primaryLocation.file.replaceAll(",", ";"); // CSV-safe
+        const object = (f.primaryLocation.objectName ?? "").replaceAll(",", ";");
+        const routine = (f.primaryLocation.routineName ?? "").replaceAll(",", ";");
+        const table = (f.affectedTables[0] ?? "").replaceAll(",", ";");
+        process.stdout.write(
+            `${detector},${f.severity},${file},${f.primaryLocation.line},${object},${routine},${table},,\n`,
+        );
+    }
+}

package/scripts/precision-tabulate.ts

@@ -0,0 +1,52 @@
+// scripts/precision-tabulate.ts
+// Per-detector + per-severity tabulation for precision-study rounds.
+// Reads compact JSON output from `analyze --format json --deterministic`.
+
+import { readFileSync } from "node:fs";
+
+interface FindingLike {
+	detector: string;
+	severity: string;
+}
+interface RunJson {
+	findings: FindingLike[];
+	[k: string]: unknown;
+}
+
+function load(path: string): RunJson {
+	const raw = readFileSync(path, "utf8");
+	return JSON.parse(raw) as RunJson;
+}
+
+function tabulate(label: string, run: RunJson): void {
+	const total = run.findings.length;
+	const byDet = new Map<string, Map<string, number>>();
+	for (const f of run.findings) {
+		const sevMap = byDet.get(f.detector) ?? new Map<string, number>();
+		sevMap.set(f.severity, (sevMap.get(f.severity) ?? 0) + 1);
+		byDet.set(f.detector, sevMap);
+	}
+	const SEV_ORDER = ["critical", "high", "medium", "low", "info"];
+	const dets = [...byDet.keys()].sort();
+	console.log(`\n=== ${label} — total ${total} ===`);
+	console.log(
+		`${"detector".padEnd(40)} ${"total".padStart(6)} ${SEV_ORDER.map((s) => s.padStart(8)).join(" ")}`,
+	);
+	console.log("-".repeat(40 + 7 + SEV_ORDER.length * 9));
+	for (const det of dets) {
+		const sevMap = byDet.get(det) ?? new Map();
+		const detTotal = [...sevMap.values()].reduce((a, b) => a + b, 0);
+		const cells = SEV_ORDER.map((s) => String(sevMap.get(s) ?? 0).padStart(8));
+		console.log(`${det.padEnd(40)} ${String(detTotal).padStart(6)} ${cells.join(" ")}`);
+	}
+}
+
+const args = process.argv.slice(2);
+for (const arg of args) {
+	const [label, path] = arg.split("=");
+	if (label === undefined || path === undefined) {
+		console.error(`bad arg: ${arg} — expected label=path`);
+		process.exit(2);
+	}
+	tabulate(label, load(path));
+}

package/src/cli/baseline.ts

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { FindingSummary } from "../projection/finding-summary.ts";
+
+export interface BaselineFile {
+	schemaVersion: "1";
+	generatedAt: string;
+	fingerprints: string[];
+}
+
+/** Load a baseline file. Missing or empty file → empty set, no error. */
+export function loadBaseline(path: string): Set<string> {
+	if (!existsSync(path)) return new Set();
+	const parsed = JSON.parse(readFileSync(path, "utf8")) as BaselineFile;
+	return new Set(parsed.fingerprints);
+}
+
+/** Write a baseline file with sorted, deduped fingerprints from `findings`. */
+export function saveBaseline(path: string, findings: FindingSummary[]): void {
+	const fingerprints = [...new Set(findings.map((f) => f.fingerprint))].sort();
+	const file: BaselineFile = {
+		schemaVersion: "1",
+		generatedAt: new Date(0).toISOString(), // pinned for determinism
+		fingerprints,
+	};
+	writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`);
+}
+
+/** Return only findings whose fingerprint is not in the baseline. */
+export function applyBaseline(findings: FindingSummary[], baseline: Set<string>): FindingSummary[] {
+	return findings.filter((f) => !baseline.has(f.fingerprint));
+}

package/src/cli/diff.ts

@@ -0,0 +1,199 @@
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { type DiffEngineResult, runDiffEngine } from "../diff/diff-engine.ts";
+import { loadRenameOverlay } from "../diff/diff-renames.ts";
+import { formatDiff } from "../diff/format-diff.ts";
+import { analyzeWorkspace } from "../index.ts";
+import { loadSnapshotFromApp } from "../snapshot/app-snapshot.ts";
+import { composeSnapshot } from "../snapshot/compose.ts";
+import { deserializeSnapshot } from "../snapshot/deserialize.ts";
+import type { CapabilitySnapshot, SnapshotFormat } from "../snapshot/types.ts";
+
+export type DiffFormat = "human" | "json" | "sarif";
+
+export interface DiffCliOptions {
+	oldArg: string;
+	newArg: string;
+	format?: DiffFormat;
+	out?: string;
+	coveragePolicy?: "loose" | "strict";
+	renamesPath?: string;
+	failOn?: "critical" | "high" | "medium" | "low" | "info";
+	strict?: boolean;
+	deterministic?: boolean;
+	alsemVersion?: string;
+	debug?: boolean;
+}
+
+export class DiffCliError extends Error {
+	constructor(
+		public exitCode: 1 | 2,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+const VALID_FORMATS: readonly DiffFormat[] = ["human", "json", "sarif"];
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 } as const;
+
+function detectInputKind(arg: string): "snapshot" | "workspace" | "app" {
+	if (!existsSync(arg)) {
+		throw new DiffCliError(1, `input not found: ${arg}`);
+	}
+	const stat = statSync(arg);
+	if (stat.isDirectory()) return "workspace";
+	if (arg.toLowerCase().endsWith(".app")) return "app";
+	return "snapshot";
+}
+
+async function loadSnapshotFromPath(path: string): Promise<CapabilitySnapshot> {
+	const ext = extname(path).toLowerCase();
+	const formatHint: SnapshotFormat | undefined =
+		ext === ".json"
+			? "json"
+			: ext === ".cbor"
+				? "cbor"
+				: ext === ".gz" || path.endsWith(".cbor.gz")
+					? "cbor.gz"
+					: undefined;
+	const bytes = new Uint8Array(await readFile(path));
+	return deserializeSnapshot(bytes, formatHint);
+}
+
+async function loadSnapshotFromWorkspace(
+	dir: string,
+	alsemVersion: string,
+	deterministic: boolean,
+): Promise<{ snapshot: CapabilitySnapshot; diagnostics: { severity: string; message: string }[] }> {
+	const { model, diagnostics } = await analyzeWorkspace({ workspaceRoot: dir });
+	const snapshot = composeSnapshot(model, {
+		workspaceDir: dir,
+		alsemVersion,
+		deterministic,
+	});
+	return { snapshot, diagnostics };
+}
+
+export async function runDiff(opts: DiffCliOptions): Promise<number> {
+	// Validate flags up-front.
+	const format: DiffFormat = opts.format ?? "human";
+	if (!VALID_FORMATS.includes(format)) {
+		process.stderr.write(`unknown --format '${format}'; valid: ${VALID_FORMATS.join(", ")}\n`);
+		return 1;
+	}
+	const coveragePolicy = opts.coveragePolicy ?? "loose";
+	if (coveragePolicy !== "loose" && coveragePolicy !== "strict") {
+		process.stderr.write(`--coverage-policy must be loose|strict (got '${coveragePolicy}')\n`);
+		return 1;
+	}
+	if (opts.failOn !== undefined && !(opts.failOn in SEVERITY_RANK)) {
+		process.stderr.write("--fail-on must be one of: critical|high|medium|low|info\n");
+		return 1;
+	}
+	const deterministic = opts.deterministic ?? false;
+	const alsemVersion = opts.alsemVersion ?? "0.0.0";
+
+	let oldSnap: CapabilitySnapshot;
+	let newSnap: CapabilitySnapshot;
+	const analyzerDiagnostics: { severity: string; message: string }[] = [];
+	let workspaceMode = false;
+	try {
+		const oldKind = detectInputKind(opts.oldArg);
+		const newKind = detectInputKind(opts.newArg);
+		if (
+			oldKind === "workspace" ||
+			newKind === "workspace" ||
+			oldKind === "app" ||
+			newKind === "app"
+		) {
+			workspaceMode = true;
+		}
+		if (oldKind === "workspace") {
+			const r = await loadSnapshotFromWorkspace(opts.oldArg, alsemVersion, deterministic);
+			oldSnap = r.snapshot;
+			analyzerDiagnostics.push(...r.diagnostics);
+		} else if (oldKind === "app") {
+			const r = await loadSnapshotFromApp(opts.oldArg, alsemVersion, deterministic);
+			oldSnap = r.snapshot;
+			analyzerDiagnostics.push(...r.diagnostics);
+		} else {
+			oldSnap = await loadSnapshotFromPath(opts.oldArg);
+		}
+		if (newKind === "workspace") {
+			const r = await loadSnapshotFromWorkspace(opts.newArg, alsemVersion, deterministic);
+			newSnap = r.snapshot;
+			analyzerDiagnostics.push(...r.diagnostics);
+		} else if (newKind === "app") {
+			const r = await loadSnapshotFromApp(opts.newArg, alsemVersion, deterministic);
+			newSnap = r.snapshot;
+			analyzerDiagnostics.push(...r.diagnostics);
+		} else {
+			newSnap = await loadSnapshotFromPath(opts.newArg);
+		}
+	} catch (err) {
+		if (err instanceof DiffCliError) {
+			process.stderr.write(`${err.message}\n`);
+			return err.exitCode;
+		}
+		process.stderr.write(`failed to load snapshot: ${(err as Error).message}\n`);
+		if (opts.debug) process.stderr.write(`${(err as Error).stack ?? ""}\n`);
+		return 1;
+	}
+
+	// Optional rename overlay.
+	let renameOverlay: Record<string, string> | undefined;
+	try {
+		const r = await loadRenameOverlay(opts.renamesPath);
+		renameOverlay = r.overlay;
+	} catch (err) {
+		process.stderr.write(`failed to load rename overlay: ${(err as Error).message}\n`);
+		return 1;
+	}
+
+	if (opts.strict === true) {
+		const fatal = analyzerDiagnostics.find((d) => d.severity === "error");
+		if (fatal !== undefined) {
+			for (const d of analyzerDiagnostics) {
+				process.stderr.write(`${d.severity}: ${d.message}\n`);
+			}
+			return 1;
+		}
+	}
+
+	const result: DiffEngineResult = runDiffEngine(oldSnap, newSnap, {
+		coveragePolicy,
+		deterministic,
+		renameOverlay,
+	});
+
+	const text = formatDiff(result, { format, deterministic });
+	try {
+		if (opts.out !== undefined) writeFileSync(opts.out, text);
+		else process.stdout.write(text);
+	} catch (err) {
+		process.stderr.write(`failed to write: ${(err as Error).message}\n`);
+		return 1;
+	}
+
+	for (const d of analyzerDiagnostics) {
+		process.stderr.write(`${d.severity}: ${d.message}\n`);
+	}
+	if (workspaceMode) {
+		process.stderr.write(
+			"note: workspace-mode reanalyzes both sides; for CI, persist snapshots with 'al-sem fingerprint --format cbor.gz' and diff those instead.\n",
+		);
+	}
+
+	// Exit code: --fail-on severity OR strict-coverage diagnostic.
+	const strictCoverageFailed = result.diagnostics.some((d) => d.kind === "coverage-incomplete");
+	if (coveragePolicy === "strict" && strictCoverageFailed) return 1;
+	if (opts.failOn !== undefined) {
+		const threshold = SEVERITY_RANK[opts.failOn];
+		for (const f of result.findings) {
+			if (SEVERITY_RANK[f.severity] <= threshold) return 1;
+		}
+	}
+	return 0;
+}

package/src/cli/events-chains.ts

@@ -0,0 +1,56 @@
+import { writeFileSync } from "node:fs";
+import { buildEventFlowIndexes, computeChainReport } from "../engine/event-flow.ts";
+import { analyzeWorkspace } from "../index.ts";
+import type { EventsFanoutOptions } from "./events-fanout.ts";
+import { formatChains } from "./format-events.ts";
+
+export interface EventsChainsOptions extends EventsFanoutOptions {
+	maxDepth?: number;
+	maxNodes?: number;
+}
+
+const VALID_FORMATS = new Set(["human", "json"]);
+const VALID_COVERAGE = new Set(["warn", "strict", "ignore"]);
+
+export async function runEventsChains(opts: EventsChainsOptions): Promise<number> {
+	const format = opts.format ?? "human";
+	if (!VALID_FORMATS.has(format)) {
+		process.stderr.write(`al-sem events chains: invalid --format '${format}'\n`);
+		return 1;
+	}
+	const coverage = opts.coveragePolicy ?? "warn";
+	if (!VALID_COVERAGE.has(coverage)) {
+		process.stderr.write(`al-sem events chains: invalid --coverage-policy '${coverage}'\n`);
+		return 1;
+	}
+	if (opts.maxDepth !== undefined && (opts.maxDepth < 0 || opts.maxDepth > 256)) {
+		process.stderr.write("al-sem events chains: --max-depth must be in 0..256\n");
+		return 1;
+	}
+	const { model, diagnostics } = await analyzeWorkspace({ workspaceRoot: opts.workspace });
+	if (opts.strict === true && diagnostics.some((d) => d.severity === "error")) {
+		for (const d of diagnostics) process.stderr.write(`${d.severity}: ${d.message}\n`);
+		return 1;
+	}
+	const ix = buildEventFlowIndexes(model);
+	const report = computeChainReport(ix, {
+		maxDepth: opts.maxDepth,
+		maxNodes: opts.maxNodes,
+		scope: opts.scope ?? "primary",
+	});
+	const text = formatChains(report, {
+		format,
+		coveragePolicy: coverage,
+		deterministic: opts.deterministic,
+		alsemVersion: opts.alsemVersion,
+	});
+	try {
+		if (opts.out !== undefined) writeFileSync(opts.out, text);
+		else process.stdout.write(text);
+	} catch (err) {
+		process.stderr.write(`failed to write: ${(err as Error).message}\n`);
+		return 1;
+	}
+	for (const d of diagnostics) process.stderr.write(`${d.severity}: ${d.message}\n`);
+	return 0;
+}

package/src/cli/events-fanout.ts

@@ -0,0 +1,87 @@
+import { writeFileSync } from "node:fs";
+import { buildEventFlowIndexes, computeFanoutReport } from "../engine/event-flow.ts";
+import { analyzeWorkspace } from "../index.ts";
+import type { Scope } from "../model/entities.ts";
+import { formatFanout } from "./format-events.ts";
+
+export interface EventsFanoutOptions {
+	workspace: string;
+	format?: "human" | "json";
+	out?: string;
+	coveragePolicy?: "warn" | "strict" | "ignore";
+	deterministic?: boolean;
+	alsemVersion?: string;
+	strict?: boolean;
+	debug?: boolean;
+	scope?: Scope;
+}
+
+const VALID_FORMATS = new Set(["human", "json"]);
+const VALID_COVERAGE = new Set(["warn", "strict", "ignore"]);
+
+export async function runEventsFanout(opts: EventsFanoutOptions): Promise<number> {
+	const format = opts.format ?? "human";
+	if (!VALID_FORMATS.has(format)) {
+		process.stderr.write(`al-sem events fanout: invalid --format '${format}'\n`);
+		return 1;
+	}
+	const coverage = opts.coveragePolicy ?? "warn";
+	if (!VALID_COVERAGE.has(coverage)) {
+		process.stderr.write(`al-sem events fanout: invalid --coverage-policy '${coverage}'\n`);
+		return 1;
+	}
+	const { model, diagnostics } = await analyzeWorkspace({ workspaceRoot: opts.workspace });
+	if (opts.strict === true && diagnostics.some((d) => d.severity === "error")) {
+		for (const d of diagnostics) process.stderr.write(`${d.severity}: ${d.message}\n`);
+		return 1;
+	}
+	const ix = buildEventFlowIndexes(model);
+	let report = computeFanoutReport(model, ix, { scope: opts.scope ?? "primary" });
+
+	let coverageExitElevated = false;
+	if (coverage === "strict") {
+		const partial = report.entries.filter(
+			(e) =>
+				e.coverage.dispatchEdges === "partial" || e.coverage.capabilityComposition === "partial",
+		);
+		if (partial.length > 0) {
+			for (const e of partial) {
+				process.stderr.write(
+					`coverage-incomplete: event ${e.eventId} dispatchEdges=${e.coverage.dispatchEdges} capability=${e.coverage.capabilityComposition}\n`,
+				);
+			}
+			const partialSet = new Set(partial);
+			report = { ...report, entries: report.entries.filter((e) => !partialSet.has(e)) };
+			coverageExitElevated = true;
+		}
+	}
+	if (coverage === "ignore") {
+		report = {
+			...report,
+			entries: report.entries.map((e) => ({
+				...e,
+				coverage: {
+					dispatchEdges: "complete" as const,
+					subscriberDiscovery: "complete" as const,
+					capabilityComposition: "complete" as const,
+				},
+			})),
+		};
+	}
+
+	const text = formatFanout(report, {
+		format,
+		coveragePolicy: coverage,
+		deterministic: opts.deterministic,
+		alsemVersion: opts.alsemVersion,
+	});
+	try {
+		if (opts.out !== undefined) writeFileSync(opts.out, text);
+		else process.stdout.write(text);
+	} catch (err) {
+		process.stderr.write(`failed to write: ${(err as Error).message}\n`);
+		return 1;
+	}
+	for (const d of diagnostics) process.stderr.write(`${d.severity}: ${d.message}\n`);
+	return coverageExitElevated ? 1 : 0;
+}

package/src/cli/exit-code.ts

@@ -0,0 +1,30 @@
+import type { FindingSummary } from "../projection/finding-summary.ts";
+
+const SEV_RANK = { critical: 5, high: 4, medium: 3, low: 2, info: 1 } as const;
+
+const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low", "info"] as const);
+
+/**
+ * Map filtered findings + a `--fail-on` threshold to a process exit code.
+ * - No `failOn` set → exit 0 always.
+ * - Any finding at the threshold severity or higher → exit 1.
+ * - Otherwise → exit 0.
+ */
+export function computeExitCode(
+	findings: FindingSummary[],
+	failOn?: FindingSummary["severity"],
+): number {
+	if (failOn === undefined) return 0;
+	const min = SEV_RANK[failOn];
+	return findings.some((f) => SEV_RANK[f.severity] >= min) ? 1 : 0;
+}
+
+/** Validate a --fail-on string. Returns the typed severity or throws (caller catches and emits usage error). */
+export function parseFailOn(input: string): FindingSummary["severity"] {
+	if (!VALID_SEVERITIES.has(input as never)) {
+		throw new Error(
+			`invalid --fail-on '${input}'. Expected: critical | high | medium | low | info`,
+		);
+	}
+	return input as FindingSummary["severity"];
+}