al-sem 0.0.1

package/src/cli/fingerprint.ts

@@ -0,0 +1,292 @@
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { analyzeWorkspace } from "../index.ts";
+import type { Diagnostic } from "../model/finding.ts";
+import type { SemanticModel } from "../model/model.ts";
+import { ROOT_KIND_VALUES, type RootKind } from "../model/root-classification.ts";
+import { buildPrimaryAppModel } from "../snapshot/app-snapshot.ts";
+import { composeSnapshot } from "../snapshot/compose.ts";
+import { serializeCborGz } from "../snapshot/serialize-cbor-gz.ts";
+import { serializeCbor } from "../snapshot/serialize-cbor.ts";
+import { serializeJson } from "../snapshot/serialize-json.ts";
+import { serializeSharded } from "../snapshot/shard.ts";
+import type { SnapshotFormat } from "../snapshot/types.ts";
+import { type FingerprintFilters, fingerprintQuery } from "./fingerprint-query.ts";
+import { formatFingerprint } from "./format-fingerprint.ts";
+
+export type FingerprintOutputFormat = "human" | SnapshotFormat;
+
+export interface FingerprintOptions {
+	workspace: string;
+	format?: FingerprintOutputFormat;
+	out?: string;
+	shard?: "primary-only" | "all";
+	deterministic?: boolean;
+	alsemVersion?: string;
+	/**
+	 * Skip loading `roots.config.json` even when it exists on disk. When
+	 * both this flag is set AND the config file exists, the snapshot's
+	 * `inputsMetadata.rootsConfigIgnored` is set to true so consumers can
+	 * tell "config ignored" from "no config at all".
+	 */
+	noRootsConfig?: boolean;
+	roots?: readonly string[];
+	routineSelectors?: readonly string[];
+	includeInherited?: boolean;
+	witness?: false | number | "all";
+	strict?: boolean;
+	debug?: boolean;
+	verbosity?: "compact" | "full";
+	color?: boolean;
+	/** Internal flag used by tests to record whether flags were user-specified. */
+	_specifiedFlags?: ReadonlySet<string>;
+}
+
+export class FingerprintCliError extends Error {
+	constructor(
+		public exitCode: 1 | 2,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+const VALID_OUTPUT_FORMATS: readonly FingerprintOutputFormat[] = [
+	"human",
+	"json",
+	"cbor",
+	"cbor.gz",
+];
+
+function isSerializerFormat(f: FingerprintOutputFormat): f is SnapshotFormat {
+	return f === "json" || f === "cbor" || f === "cbor.gz";
+}
+
+function validateRoots(values: readonly string[]): RootKind[] {
+	const valid = new Set<string>(ROOT_KIND_VALUES);
+	const out: RootKind[] = [];
+	for (const v of values) {
+		if (!valid.has(v)) {
+			throw new FingerprintCliError(
+				1,
+				`unknown root kind '${v}'; valid: ${ROOT_KIND_VALUES.join(", ")}`,
+			);
+		}
+		out.push(v as RootKind);
+	}
+	return out;
+}
+
+function normalizeWitness(w: FingerprintOptions["witness"]): false | number | "all" {
+	if (w === undefined) return 3;
+	if (w === false || w === "all") return w;
+	if (typeof w === "number") {
+		if (w < 0 || w > 256) {
+			throw new FingerprintCliError(1, `--witness must be in 0..256 or 'all' (got ${w})`);
+		}
+		return w;
+	}
+	throw new FingerprintCliError(1, "invalid --witness value");
+}
+
+function rejectIllegalCombos(opts: FingerprintOptions, format: FingerprintOutputFormat): void {
+	const specified = opts._specifiedFlags ?? new Set<string>();
+	const queryFlags: readonly string[] = [
+		"roots",
+		"routineSelectors",
+		"witness",
+		"includeInherited",
+	];
+	if (opts.shard !== undefined) {
+		for (const f of queryFlags) {
+			if (specified.has(f)) {
+				throw new FingerprintCliError(
+					1,
+					`--shard cannot be combined with --${f === "routineSelectors" ? "routine" : f === "includeInherited" ? "include-inherited" : f}`,
+				);
+			}
+		}
+		if (format === "human") {
+			throw new FingerprintCliError(1, "--shard requires --format=json|cbor|cbor.gz");
+		}
+	}
+	if (isSerializerFormat(format)) {
+		for (const f of queryFlags) {
+			if (specified.has(f)) {
+				throw new FingerprintCliError(
+					1,
+					`--${f === "routineSelectors" ? "routine" : f === "includeInherited" ? "include-inherited" : f} is only valid with --format=human`,
+				);
+			}
+		}
+	}
+}
+
+function defaultFormat(opts: FingerprintOptions): FingerprintOutputFormat {
+	if (opts.format !== undefined) {
+		if (!VALID_OUTPUT_FORMATS.includes(opts.format)) {
+			throw new FingerprintCliError(
+				1,
+				`unknown --format '${opts.format}'; valid: ${VALID_OUTPUT_FORMATS.join(", ")}`,
+			);
+		}
+		return opts.format;
+	}
+	return opts.shard !== undefined ? "json" : "human";
+}
+
+export async function runFingerprint(opts: FingerprintOptions): Promise<number> {
+	let format: FingerprintOutputFormat;
+	try {
+		format = defaultFormat(opts);
+		rejectIllegalCombos(opts, format);
+	} catch (err) {
+		if (err instanceof FingerprintCliError) {
+			process.stderr.write(`${err.message}\n`);
+			return err.exitCode;
+		}
+		throw err;
+	}
+
+	const noRootsConfig = opts.noRootsConfig === true;
+	const isApp =
+		existsSync(opts.workspace) &&
+		statSync(opts.workspace).isFile() &&
+		opts.workspace.toLowerCase().endsWith(".app");
+	let model: SemanticModel;
+	let analyzeDiagnostics: Diagnostic[];
+	try {
+		const r = isApp
+			? await buildPrimaryAppModel(opts.workspace)
+			: await analyzeWorkspace({ workspaceRoot: opts.workspace, noRootsConfig });
+		model = r.model;
+		analyzeDiagnostics = r.diagnostics;
+	} catch (err) {
+		process.stderr.write(
+			`fingerprint: failed to load ${isApp ? ".app" : "workspace"}: ${(err as Error).message}\n`,
+		);
+		if (opts.debug) process.stderr.write(`${(err as Error).stack ?? ""}\n`);
+		return 1;
+	}
+
+	if (opts.strict === true) {
+		const fatal = analyzeDiagnostics.find((d) => d.severity === "error");
+		if (fatal !== undefined) {
+			for (const d of analyzeDiagnostics) {
+				process.stderr.write(`${d.severity}: ${d.message}\n`);
+			}
+			return 1;
+		}
+	}
+
+	const rootsConfigIgnored =
+		!isApp && noRootsConfig && existsSync(resolve(opts.workspace, "roots.config.json"));
+	const snap = composeSnapshot(model, {
+		workspaceDir: opts.workspace,
+		alsemVersion: opts.alsemVersion ?? "0.0.0",
+		deterministic: opts.deterministic ?? false,
+		rootsConfigIgnored,
+	});
+
+	if (isSerializerFormat(format)) {
+		// Existing JSON/CBOR/shard paths — byte-identical to Phase 0c.
+		if (opts.shard !== undefined) {
+			if (opts.out === undefined) {
+				process.stderr.write("--shard requires --out <directory>\n");
+				return 1;
+			}
+			const files = serializeSharded(snap, { format, primaryOnly: opts.shard === "primary-only" });
+			try {
+				for (const [name, bytes] of files) {
+					writeFileSync(join(opts.out, name), bytes);
+				}
+			} catch (err) {
+				process.stderr.write(`failed to write shard files: ${(err as Error).message}\n`);
+				return 1;
+			}
+			return 0;
+		}
+		let bytes: Uint8Array;
+		if (format === "json") bytes = new TextEncoder().encode(serializeJson(snap));
+		else if (format === "cbor") bytes = serializeCbor(snap);
+		else bytes = serializeCborGz(snap);
+		try {
+			if (opts.out !== undefined) writeFileSync(opts.out, bytes);
+			else process.stdout.write(bytes);
+		} catch (err) {
+			process.stderr.write(`failed to write: ${(err as Error).message}\n`);
+			return 1;
+		}
+		for (const d of analyzeDiagnostics) {
+			process.stderr.write(`${d.severity}: ${d.message}\n`);
+		}
+		return 0;
+	}
+
+	// --- human format ---
+	let validatedRoots: RootKind[] = [];
+	try {
+		validatedRoots = opts.roots !== undefined ? validateRoots(opts.roots) : [];
+	} catch (err) {
+		if (err instanceof FingerprintCliError) {
+			process.stderr.write(`${err.message}\n`);
+			return err.exitCode;
+		}
+		throw err;
+	}
+	let witness: false | number | "all";
+	try {
+		witness = normalizeWitness(opts.witness);
+	} catch (err) {
+		if (err instanceof FingerprintCliError) {
+			process.stderr.write(`${err.message}\n`);
+			return err.exitCode;
+		}
+		throw err;
+	}
+	const filters: FingerprintFilters = {
+		roots: validatedRoots.length > 0 ? new Set(validatedRoots) : undefined,
+		routineSelectors: opts.routineSelectors,
+		includeInherited: opts.includeInherited ?? true,
+		witnessLimit: witness,
+	};
+	const result = fingerprintQuery(snap, filters);
+
+	const selectorErrors = result.diagnostics.filter(
+		(d) => d.kind === "selector-unresolved" || d.kind === "selector-ambiguous",
+	);
+	if (selectorErrors.length > 0) {
+		for (const d of selectorErrors) {
+			if (d.kind === "selector-unresolved") {
+				process.stderr.write(
+					`error: --routine '${d.selector}' did not match any routine (tried: ${d.triedForms.join(", ")})\n`,
+				);
+			} else if (d.kind === "selector-ambiguous") {
+				process.stderr.write(
+					`error: --routine '${d.selector}' is ambiguous (matched via ${d.matchedForm}); candidates:\n`,
+				);
+				for (const c of d.candidates) {
+					process.stderr.write(`  - ${c.display}  (${c.stableId})\n`);
+				}
+			}
+		}
+		return 2;
+	}
+
+	const text = formatFingerprint(result, {
+		deterministic: opts.deterministic,
+		color: opts.color ?? false,
+		verbosity: opts.verbosity ?? "compact",
+	});
+	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 analyzeDiagnostics) {
+		process.stderr.write(`${d.severity}: ${d.message}\n`);
+	}
+	return 0;
+}

package/src/cli/format-compact-json.ts

@@ -0,0 +1,45 @@
+import type { AnalyzeWorkspaceResult } from "../index.ts";
+import type { DetectorStats } from "../model/finding.ts";
+import { type FindingSummary, projectFinding } from "../projection/finding-summary.ts";
+
+export interface CompactReport {
+	summary: {
+		totalFindings: number;
+		bySeverity: Record<string, number>;
+		byDetector: Record<string, number>;
+		routinesAnalyzed: number;
+		sourceUnitsParsed: number;
+		opaqueApps: string[];
+		detectorStats: DetectorStats[];
+	};
+	findings: FindingSummary[];
+	diagnostics: AnalyzeWorkspaceResult["diagnostics"];
+}
+
+export function buildCompactReport(result: AnalyzeWorkspaceResult): CompactReport {
+	const findings = result.findings.map((f) => projectFinding(f, result.model));
+	const bySeverity: Record<string, number> = {};
+	const byDetector: Record<string, number> = {};
+	for (const f of findings) {
+		bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+		byDetector[f.detector] = (byDetector[f.detector] ?? 0) + 1;
+	}
+	const coverage = result.model.coverage;
+	return {
+		summary: {
+			totalFindings: findings.length,
+			bySeverity,
+			byDetector,
+			routinesAnalyzed: coverage.routinesTotal,
+			sourceUnitsParsed: coverage.sourceUnitsParsed,
+			opaqueApps: coverage.opaqueApps,
+			detectorStats: result.detectorStats,
+		},
+		findings,
+		diagnostics: result.diagnostics,
+	};
+}
+
+export function formatCompactJson(result: AnalyzeWorkspaceResult): string {
+	return JSON.stringify(buildCompactReport(result), null, 2);
+}

package/src/cli/format-events.ts

@@ -0,0 +1,77 @@
+import type { ChainNode, ChainReport, FanoutReport } from "../engine/event-flow.ts";
+
+export interface EventsFormatOptions {
+	format: "human" | "json";
+	coveragePolicy?: "warn" | "strict" | "ignore";
+	deterministic?: boolean;
+	alsemVersion?: string;
+}
+
+function coverageGlyph(s: "complete" | "partial" | "unknown"): string {
+	if (s === "complete") return "✓";
+	if (s === "partial") return "≈";
+	return "?";
+}
+
+export function formatFanout(report: FanoutReport, opts: EventsFormatOptions): string {
+	if (opts.format === "json") {
+		const payload = {
+			al_sem_version: opts.alsemVersion ?? "0.0.0",
+			generated_at: opts.deterministic ? "0" : new Date().toISOString(),
+			kind: "events.fanout",
+			summary: report.summary,
+			entries: report.entries,
+		};
+		return JSON.stringify(payload, undefined, 2);
+	}
+	const lines: string[] = [];
+	lines.push(
+		`Event fanout report  (${report.summary.totalPublishers} publishers, ${report.summary.totalEvents} events, ${report.summary.hotEvents} hot)`,
+	);
+	lines.push("");
+	for (const e of report.entries) {
+		const cov = `[${coverageGlyph(e.coverage.dispatchEdges)}${coverageGlyph(e.coverage.subscriberDiscovery)}${coverageGlyph(e.coverage.capabilityComposition)}]`;
+		lines.push(
+			`  ${e.eventName}  (${e.eventKind}) → ${e.directSubscriberCount} subscriber(s) ${cov}`,
+		);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function renderChain(node: ChainNode, depth: number, lines: string[]): void {
+	const indent = "  ".repeat(depth);
+	if (node.kind === "root") {
+		lines.push(`${indent}root ${node.routineId ?? "?"}`);
+	} else if (node.kind === "event-dispatch") {
+		const tail = node.depthTruncated ? "  (depth truncated)" : "";
+		lines.push(`${indent}↪ ${node.eventName ?? node.eventId}${tail}`);
+	} else if (node.kind === "subscriber") {
+		const marker = node.cycleDetected
+			? "  (cycle)"
+			: node.depthTruncated
+				? "  (depth truncated)"
+				: "";
+		lines.push(`${indent}• ${node.routineId}${marker}`);
+	}
+	for (const c of node.children) renderChain(c, depth + 1, lines);
+}
+
+export function formatChains(report: ChainReport, opts: EventsFormatOptions): string {
+	if (opts.format === "json") {
+		const payload = {
+			al_sem_version: opts.alsemVersion ?? "0.0.0",
+			generated_at: opts.deterministic ? "0" : new Date().toISOString(),
+			kind: "events.chains",
+			summary: report.summary,
+			chains: report.chains,
+		};
+		return JSON.stringify(payload, undefined, 2);
+	}
+	const lines: string[] = [];
+	lines.push(
+		`Event chains report  (${report.summary.totalRoots} roots, max depth ${report.summary.maxChainDepth}, ${report.summary.cyclesDetected} cycles, ${report.summary.depthTruncatedNodes} depth-truncated)`,
+	);
+	lines.push("");
+	for (const c of report.chains) renderChain(c, 0, lines);
+	return `${lines.join("\n")}\n`;
+}