al-sem 0.0.1

package/src/cli/index.ts

@@ -0,0 +1,566 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { pruneCache } from "../deps/dependency-cache.ts";
+import { ALL_DETECTORS, DEFAULT_DETECTORS } from "../detectors/registry.ts";
+import { analyzeWorkspace } from "../index.ts";
+import type { Scope } from "../model/entities.ts";
+import { filterFindings } from "../projection/finding-filters.ts";
+import { groupFindings } from "../projection/finding-groups.ts";
+import type { FindingSummary } from "../projection/finding-summary.ts";
+import { projectFinding } from "../projection/finding-summary.ts";
+import { applyBaseline, loadBaseline, saveBaseline } from "./baseline.ts";
+import { runDiff } from "./diff.ts";
+import { runEventsChains } from "./events-chains.ts";
+import { runEventsFanout } from "./events-fanout.ts";
+import { computeExitCode, parseFailOn } from "./exit-code.ts";
+import { runFingerprint } from "./fingerprint.ts";
+import { formatCompactJson } from "./format-compact-json.ts";
+import { formatHtml } from "./format-html.ts";
+import { formatFullModelJson } from "./format-json.ts";
+import { formatSarif } from "./format-sarif.ts";
+import { formatTerminal } from "./format-terminal.ts";
+import { runPolicyCheck, runPolicyExplain } from "./policy.ts";
+
+const SCOPE_VALUES = ["primary", "all"] as const;
+
+const program = new Command();
+
+program
+	.name("al-sem")
+	.description("Static semantic analysis engine for Microsoft Business Central AL code");
+
+program
+	.command("analyze")
+	.argument("<workspace>", "path to the AL workspace root")
+	.option("--alpackages <dir>", "path to the .alpackages directory")
+	.option("--format <format>", "output format: auto | terminal | json | sarif | html", "auto")
+	.option("--deterministic", "pin timestamps for byte-stable output", false)
+	.option("--no-dep-summaries", "skip the behavioral dependency cold run (structural ABI only)")
+	.option("--no-roots-config", "ignore roots.config.json overlay even if present")
+	.option(
+		"--dep-cache-dir <dir>",
+		"override the dependency cache directory (default ~/.al-sem/cache/)",
+	)
+	.option("--dump-model", "emit the full SemanticModel (debug-only, can be >500 MB)")
+	.option(
+		"--min-severity <sev>",
+		"drop findings below this severity: critical|high|medium|low|info",
+	)
+	.option(
+		"--detector <ids>",
+		"comma-separated allow-list of detector ids (e.g. d1-db-op-in-loop,d3-missing-setloadfields)",
+	)
+	.option(
+		"--scope <scope>",
+		"primary (default) drops findings anchored in a dependency; all keeps them",
+		"primary",
+	)
+	.option("--limit <n>", "cap output at first N findings (after filtering)", (v: string) =>
+		Number.parseInt(v, 10),
+	)
+	.option("--group-by <by>", "group terminal output by: object | routine | table | detector | file")
+	.option("--baseline <file>", "baseline file (fingerprints to suppress on this run)")
+	.option("--update-baseline", "rewrite the baseline file from this run's findings", false)
+	.option(
+		"--fail-on <sev>",
+		"exit 1 if any finding at this severity or above (after baseline / filters)",
+	)
+	.action(
+		async (
+			workspace: string,
+			opts: {
+				alpackages?: string;
+				format: string;
+				deterministic: boolean;
+				depSummaries: boolean;
+				rootsConfig: boolean;
+				depCacheDir?: string;
+				dumpModel?: boolean;
+				minSeverity?: string;
+				detector?: string;
+				scope: string;
+				limit?: number;
+				groupBy?: string;
+				baseline?: string;
+				updateBaseline: boolean;
+				failOn?: string;
+			},
+		) => {
+			// --- enum flag validation ---
+			const SEVERITY_VALUES = ["critical", "high", "medium", "low", "info"] as const;
+			if (opts.minSeverity !== undefined && !SEVERITY_VALUES.includes(opts.minSeverity as never)) {
+				process.stderr.write(
+					`al-sem: invalid --min-severity '${opts.minSeverity}'. Expected one of: ${SEVERITY_VALUES.join(", ")}\n`,
+				);
+				process.exitCode = 1;
+				return;
+			}
+
+			if (!SCOPE_VALUES.includes(opts.scope as never)) {
+				process.stderr.write(
+					`al-sem: invalid --scope '${opts.scope}'. Expected one of: ${SCOPE_VALUES.join(", ")}\n`,
+				);
+				process.exitCode = 1;
+				return;
+			}
+
+			const GROUP_BY_VALUES = ["object", "routine", "table", "detector", "file"] as const;
+			if (opts.groupBy !== undefined && !GROUP_BY_VALUES.includes(opts.groupBy as never)) {
+				process.stderr.write(
+					`al-sem: invalid --group-by '${opts.groupBy}'. Expected one of: ${GROUP_BY_VALUES.join(", ")}\n`,
+				);
+				process.exitCode = 1;
+				return;
+			}
+
+			let failOn: FindingSummary["severity"] | undefined;
+			if (opts.failOn !== undefined) {
+				try {
+					failOn = parseFailOn(opts.failOn);
+				} catch (err) {
+					process.stderr.write(`al-sem: ${(err as Error).message}\n`);
+					process.exitCode = 1;
+					return;
+				}
+			}
+
+			if (opts.updateBaseline === true && opts.baseline === undefined) {
+				process.stderr.write("al-sem: --update-baseline has no effect without --baseline\n");
+			}
+
+			// Safe casts — values validated above
+			const minSeverity = opts.minSeverity as FindingSummary["severity"] | undefined;
+			const scope = opts.scope as "primary" | "all";
+			const groupBy = opts.groupBy as
+				| "object"
+				| "routine"
+				| "table"
+				| "detector"
+				| "file"
+				| undefined;
+
+			// If the user explicitly opted into a detector via `--detector` that isn't in
+			// DEFAULT_DETECTORS (e.g. d40-transitive-load-missing), run the union — otherwise
+			// the registry would silently never produce that detector's findings even though
+			// the user asked for them. Default registry remains in effect when --detector
+			// is absent or only names default-registry detectors.
+			const requestedDetectors = opts.detector
+				? opts.detector.split(",").map((s: string) => s.trim())
+				: undefined;
+			const defaultNames = new Set(DEFAULT_DETECTORS.map((d) => d.name));
+			const needsOptIn = requestedDetectors?.some((n) => !defaultNames.has(n)) ?? false;
+			const detectorList = needsOptIn ? ALL_DETECTORS : undefined;
+
+			const result = await analyzeWorkspace({
+				workspaceRoot: workspace,
+				alpackagesDir: opts.alpackages,
+				deterministic: opts.deterministic,
+				noDepSummaries: opts.depSummaries === false,
+				noRootsConfig: opts.rootsConfig === false,
+				dependencyCacheDir: opts.depCacheDir,
+				detectors: detectorList,
+			});
+			if (opts.dumpModel === true) {
+				process.stdout.write(`${formatFullModelJson(result)}\n`);
+				return;
+			}
+
+			// --- filter pipeline ---
+			// First pass: severity + detector (no limit yet)
+			const projected = result.findings.map((f) => projectFinding(f, result.model));
+			const filtered = filterFindings(projected, {
+				minSeverity,
+				detectors: opts.detector
+					? opts.detector.split(",").map((s: string) => s.trim())
+					: undefined,
+			});
+
+			// scope filter: primary (default) drops findings whose primaryLocation object is in a dep
+			const objectsById = new Map(result.model.objects.map((o) => [o.id, o]));
+			const scoped =
+				scope === "all"
+					? filtered
+					: filtered.filter((f) => {
+							const objId = f.primaryLocation.objectId;
+							if (!objId) return true; // unknown object — keep (don't silently drop)
+							return objectsById.get(objId)?.analysisRole !== "dependency";
+						});
+
+			// Second pass: limit only (applied after scope drop so users get expected count)
+			const limited = opts.limit !== undefined ? scoped.slice(0, opts.limit) : scoped;
+
+			// --- baseline suppression ---
+			const baseline = opts.baseline ? loadBaseline(opts.baseline) : new Set<string>();
+			const newFindings = applyBaseline(limited, baseline);
+			if (opts.updateBaseline && opts.baseline) {
+				// Save the current scoped+filtered set (not just new ones) — this becomes the new floor.
+				saveBaseline(opts.baseline, limited);
+			}
+
+			const filteredIds = new Set(newFindings.map((f) => f.id));
+			const filteredResult = {
+				...result,
+				findings: result.findings.filter((f) => filteredIds.has(f.id)),
+			};
+
+			const format =
+				opts.format === "auto" ? (process.stdout.isTTY ? "terminal" : "json") : opts.format;
+
+			// group-by terminal rendering
+			if (groupBy && format === "terminal") {
+				const groups = groupFindings(newFindings, groupBy);
+				const cov = result.model.coverage;
+				const lines: string[] = [];
+				lines.push(
+					`Analysed ${cov.routinesTotal} routines (${cov.routinesBodyAvailable} with bodies, ${cov.routinesParseIncomplete.length} parse-incomplete); ${cov.sourceUnitsParsed}/${cov.sourceUnitsTotal} source units parsed; ${cov.opaqueApps.length} opaque app(s).`,
+				);
+				lines.push("");
+				lines.push(`Grouped by ${groupBy} (top ${groups.length}):`);
+				for (const g of groups) {
+					lines.push(`  ${g.key}: ${g.findings.length}`);
+				}
+				process.stdout.write(`${lines.join("\n")}\n`);
+				// still apply exit-code for group-by path
+				if (failOn) {
+					process.exitCode = computeExitCode(newFindings, failOn);
+				}
+				return;
+			}
+
+			if (format === "json") {
+				process.stdout.write(`${formatCompactJson(filteredResult)}\n`);
+			} else if (format === "terminal") {
+				process.stdout.write(`${formatTerminal(filteredResult)}\n`);
+			} else if (format === "sarif") {
+				process.stdout.write(`${formatSarif(filteredResult)}\n`);
+			} else if (format === "html") {
+				process.stdout.write(`${formatHtml(filteredResult)}\n`);
+			} else {
+				process.stderr.write(
+					`al-sem: unknown format '${format}'. Expected: auto, terminal, json, sarif, html\n`,
+				);
+				process.exitCode = 1;
+				return;
+			}
+
+			// --- exit-code gate ---
+			if (failOn) {
+				process.exitCode = computeExitCode(newFindings, failOn);
+			}
+		},
+	);
+
+program
+	.command("fingerprint")
+	.description("Show the per-root capability fingerprint for a workspace (Phase 1 §4.4 surface)")
+	.argument("<workspace>", "path to the AL workspace root")
+	.option("--format <fmt>", "output format: human | json | cbor | cbor.gz")
+	.option("--out <path>", "output file or shard directory")
+	.option("--shard <mode>", "primary-only | all")
+	.option("--deterministic", "pin generatedAt for byte-stable output", false)
+	.option("--alsem-version <v>", "version string in output", "0.0.0")
+	.option("--no-roots-config", "ignore roots.config.json overlay")
+	.option("--roots <kinds>", "comma-separated RootKind list (human only)")
+	.option(
+		"--routine <selector>",
+		"routine selector (display or StableRoutineId); repeatable",
+		collectRoutine,
+		[],
+	)
+	.option("--include-inherited", "include inherited facts (default)", true)
+	.option("--no-include-inherited", "direct facts only")
+	.option("--witness <mode>", "false | 0 | <1..256> | all", "3")
+	.option("--strict", "exit non-zero on any analyzer error-severity diagnostic", false)
+	.option("--debug", "print stack on internal error", false)
+	.option("--verbosity <v>", "compact | full (human only)", "compact")
+	.option("--color", "force color output", false)
+	.action(
+		async (
+			workspace: string,
+			cmdOpts: {
+				format?: string;
+				out?: string;
+				shard?: string;
+				deterministic?: boolean;
+				alsemVersion?: string;
+				rootsConfig: boolean;
+				roots?: string;
+				routine?: string[];
+				includeInherited?: boolean;
+				witness?: string;
+				strict?: boolean;
+				debug?: boolean;
+				verbosity?: string;
+				color?: boolean;
+			},
+		) => {
+			const specified = new Set<string>();
+			if (cmdOpts.roots !== undefined) specified.add("roots");
+			if (Array.isArray(cmdOpts.routine) && cmdOpts.routine.length > 0)
+				specified.add("routineSelectors");
+			if (cmdOpts.includeInherited === false) specified.add("includeInherited");
+			if (cmdOpts.witness !== undefined && cmdOpts.witness !== "3") specified.add("witness");
+			const witness =
+				cmdOpts.witness === undefined
+					? undefined
+					: cmdOpts.witness === "false"
+						? false
+						: cmdOpts.witness === "all"
+							? ("all" as const)
+							: Number.parseInt(cmdOpts.witness, 10);
+			const exitCode = await runFingerprint({
+				workspace,
+				format: cmdOpts.format as never,
+				out: cmdOpts.out,
+				shard: cmdOpts.shard as "primary-only" | "all" | undefined,
+				deterministic: cmdOpts.deterministic === true,
+				alsemVersion: cmdOpts.alsemVersion,
+				noRootsConfig: cmdOpts.rootsConfig === false,
+				roots:
+					cmdOpts.roots !== undefined
+						? String(cmdOpts.roots)
+								.split(",")
+								.map((s) => s.trim())
+								.filter((s) => s.length > 0)
+						: undefined,
+				routineSelectors:
+					Array.isArray(cmdOpts.routine) && cmdOpts.routine.length > 0
+						? cmdOpts.routine
+						: undefined,
+				includeInherited: cmdOpts.includeInherited !== false,
+				witness,
+				strict: cmdOpts.strict === true,
+				debug: cmdOpts.debug === true,
+				verbosity: cmdOpts.verbosity as "compact" | "full" | undefined,
+				color: cmdOpts.color === true,
+				_specifiedFlags: specified,
+			});
+			process.exit(exitCode);
+		},
+	);
+
+program
+	.command("diff")
+	.argument("<old>", "snapshot file or workspace directory")
+	.argument("<new>", "snapshot file or workspace directory")
+	.option("--format <fmt>", "output format: human | json | sarif", "human")
+	.option("--out <path>", "write output to file instead of stdout")
+	.option("--coverage-policy <policy>", "loose | strict", "loose")
+	.option("--renames <path>", "rename overlay JSON file")
+	.option("--fail-on <sev>", "exit 1 if any finding ≥ severity")
+	.option("--strict", "exit 1 on analyzer error-severity diagnostic", false)
+	.option("--deterministic", "pin generatedAt for byte-stable output", false)
+	.option("--alsem-version <v>", "version string in output", "0.0.0")
+	.option("--debug", "print stack on internal error", false)
+	.action(
+		async (
+			oldArg: string,
+			newArg: string,
+			cmdOpts: {
+				format?: string;
+				out?: string;
+				coveragePolicy?: string;
+				renames?: string;
+				failOn?: string;
+				strict?: boolean;
+				deterministic?: boolean;
+				alsemVersion?: string;
+				debug?: boolean;
+			},
+		) => {
+			const exitCode = await runDiff({
+				oldArg,
+				newArg,
+				format: cmdOpts.format as never,
+				out: cmdOpts.out,
+				coveragePolicy: cmdOpts.coveragePolicy as never,
+				renamesPath: cmdOpts.renames,
+				failOn: cmdOpts.failOn as never,
+				strict: cmdOpts.strict === true,
+				deterministic: cmdOpts.deterministic === true,
+				alsemVersion: cmdOpts.alsemVersion,
+				debug: cmdOpts.debug === true,
+			});
+			process.exit(exitCode);
+		},
+	);
+
+const events = program.command("events").description("Event blast-radius reports");
+
+events
+	.command("fanout")
+	.description("Per-publisher fanout report (direct subscribers + coverage)")
+	.argument("<workspace>", "path to the AL workspace root")
+	.option("--format <fmt>", "human | json", "human")
+	.option("--out <path>", "output file")
+	.option("--coverage-policy <p>", "warn | strict | ignore", "warn")
+	.option("--deterministic", "pin generated_at for byte-stable output", false)
+	.option("--alsem-version <v>", "version string in output", "0.0.0")
+	.option("--strict", "exit 1 on analyzer error-severity diagnostic", false)
+	.option(
+		"--scope <scope>",
+		"primary (default) drops dependency-only events; all keeps them",
+		"primary",
+	)
+	.action(async (workspace: string, cmdOpts: Record<string, unknown>) => {
+		if (!SCOPE_VALUES.includes(cmdOpts.scope as never)) {
+			process.stderr.write(
+				`al-sem: invalid --scope '${cmdOpts.scope}'. Expected one of: ${SCOPE_VALUES.join(", ")}\n`,
+			);
+			process.exit(1);
+		}
+		const exitCode = await runEventsFanout({
+			workspace,
+			format: cmdOpts.format as never,
+			out: cmdOpts.out as string | undefined,
+			coveragePolicy: cmdOpts.coveragePolicy as never,
+			deterministic: cmdOpts.deterministic === true,
+			alsemVersion: cmdOpts.alsemVersion as string | undefined,
+			strict: cmdOpts.strict === true,
+			scope: cmdOpts.scope as Scope,
+		});
+		process.exit(exitCode);
+	});
+
+events
+	.command("chains")
+	.description("Per-publisher chain tree (event → subscriber → ...)")
+	.argument("<workspace>", "path to the AL workspace root")
+	.option("--format <fmt>", "human | json", "human")
+	.option("--out <path>", "output file")
+	.option("--coverage-policy <p>", "warn | strict | ignore", "warn")
+	.option("--max-depth <n>", "maximum tree depth (0..256)", (v: string) => Number.parseInt(v, 10))
+	.option("--deterministic", "pin generated_at for byte-stable output", false)
+	.option("--alsem-version <v>", "version string in output", "0.0.0")
+	.option("--strict", "exit 1 on analyzer error-severity diagnostic", false)
+	.option(
+		"--scope <scope>",
+		"primary (default) drops dependency-only events; all keeps them",
+		"primary",
+	)
+	.action(async (workspace: string, cmdOpts: Record<string, unknown>) => {
+		if (!SCOPE_VALUES.includes(cmdOpts.scope as never)) {
+			process.stderr.write(
+				`al-sem: invalid --scope '${cmdOpts.scope}'. Expected one of: ${SCOPE_VALUES.join(", ")}\n`,
+			);
+			process.exit(1);
+		}
+		const exitCode = await runEventsChains({
+			workspace,
+			format: cmdOpts.format as never,
+			out: cmdOpts.out as string | undefined,
+			coveragePolicy: cmdOpts.coveragePolicy as never,
+			maxDepth: cmdOpts.maxDepth as number | undefined,
+			deterministic: cmdOpts.deterministic === true,
+			alsemVersion: cmdOpts.alsemVersion as string | undefined,
+			strict: cmdOpts.strict === true,
+			scope: cmdOpts.scope as Scope,
+		});
+		process.exit(exitCode);
+	});
+
+const policy = program
+	.command("policy")
+	.description("Declarative policy rules over capability facts");
+
+policy
+	.command("check")
+	.description("Check workspace against effective policy")
+	.argument("<workspace>", "path to the AL workspace root")
+	.option("--policy <path>", "explicit policy file")
+	.option("--no-policy", "disable all policy evaluation")
+	.option("--format <fmt>", "human | json | sarif", "human")
+	.option("--out <path>", "output file")
+	.option("--deterministic", "pin generated_at", false)
+	.option("--alsem-version <v>", "version string in output", "0.0.0")
+	.option("--strict", "exit 1 on analyzer error-severity diagnostic", false)
+	.option(
+		"--scope <scope>",
+		"primary (default) drops dependency-anchored findings; all keeps them",
+		"primary",
+	)
+	.action(async (workspace: string, cmdOpts: Record<string, unknown>) => {
+		if (!SCOPE_VALUES.includes(cmdOpts.scope as never)) {
+			process.stderr.write(
+				`al-sem: invalid --scope '${cmdOpts.scope}'. Expected one of: ${SCOPE_VALUES.join(", ")}\n`,
+			);
+			process.exit(1);
+		}
+		// commander's --no-X flips the value to false. Detect that as "disable".
+		const policyArg = cmdOpts.policy;
+		const noPolicy = policyArg === false;
+		const policyPath = typeof policyArg === "string" ? policyArg : undefined;
+		const exitCode = await runPolicyCheck({
+			workspace,
+			policyPath,
+			noPolicy,
+			format: cmdOpts.format as never,
+			out: cmdOpts.out as string | undefined,
+			deterministic: cmdOpts.deterministic === true,
+			alsemVersion: cmdOpts.alsemVersion as string | undefined,
+			strict: cmdOpts.strict === true,
+			scope: cmdOpts.scope as Scope,
+		});
+		process.exit(exitCode);
+	});
+
+policy
+	.command("explain")
+	.description("Explain a policy rule's semantics + matches")
+	.argument("<rule-id>", "rule id to explain")
+	.argument("<workspace>", "path to the AL workspace root")
+	.option("--policy <path>", "explicit policy file")
+	.option("--routine <selector>", "narrow trace to one routine")
+	.option("--finding <id>", "narrow trace to one finding id")
+	.option("--format <fmt>", "human | json", "human")
+	.action(async (ruleId: string, workspace: string, cmdOpts: Record<string, unknown>) => {
+		const exitCode = await runPolicyExplain({
+			workspace,
+			ruleId,
+			policyPath: typeof cmdOpts.policy === "string" ? cmdOpts.policy : undefined,
+			routine: cmdOpts.routine as string | undefined,
+			findingId: cmdOpts.finding as string | undefined,
+			format: cmdOpts.format as never,
+		});
+		process.exit(exitCode);
+	});
+
+const cache = program.command("cache").description("Inspect and maintain the dependency cache");
+
+cache
+	.command("prune")
+	.description(
+		"Remove dependency cache entries this build can no longer use (version mismatch, corrupt files, tampered content hash). Kept entries are not touched.",
+	)
+	.option(
+		"--dep-cache-dir <dir>",
+		"override the dependency cache directory (default ~/.al-sem/cache/)",
+	)
+	.option("--dry-run", "report what would be removed without deleting anything", false)
+	.action((opts: { depCacheDir?: string; dryRun: boolean }) => {
+		const result = pruneCache(opts.depCacheDir, { dryRun: opts.dryRun });
+		const kb = (n: number): string => `${(n / 1024).toFixed(1)} KB`;
+		const verb = opts.dryRun ? "would remove" : "removed";
+		process.stdout.write(`al-sem cache: ${result.cacheDir}\n`);
+		if (result.entries.length === 0) {
+			process.stdout.write("  (empty)\n");
+			return;
+		}
+		const removed = result.entries.filter((e) => e.status !== "kept");
+		const kept = result.entries.length - removed.length;
+		process.stdout.write(
+			`  ${verb} ${result.filesRemoved} file(s) totalling ${kb(result.bytesFreed)}; kept ${kept}.\n`,
+		);
+		for (const e of removed) {
+			process.stdout.write(`  - ${e.file}  (${kb(e.bytes)})  ${e.status}\n`);
+		}
+	});
+
+function collectRoutine(value: string, prev: string[]): string[] {
+	return [...prev, value];
+}
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+	process.stderr.write(`al-sem: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exitCode = 1;
+});