al-sem 0.0.1

package/src/cli/policy.ts

@@ -0,0 +1,204 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { analyzeWorkspace } from "../index.ts";
+import type { Scope } from "../model/entities.ts";
+import { runPolicy } from "../policy/policy-engine.ts";
+import { loadPolicyFromFile } from "../policy/policy-loader.ts";
+import type { PolicyDoc, PolicyRunResult } from "../policy/policy-types.ts";
+import { formatPolicy } from "./format-policy.ts";
+
+const VALID_FORMATS = new Set(["human", "json", "sarif"]);
+
+export interface PolicyCheckOptions {
+	workspace: string;
+	policyPath?: string;
+	noPolicy?: boolean;
+	format?: "human" | "json" | "sarif";
+	out?: string;
+	deterministic?: boolean;
+	alsemVersion?: string;
+	strict?: boolean;
+	scope?: Scope;
+}
+
+export async function runPolicyCheck(opts: PolicyCheckOptions): Promise<number> {
+	const format = opts.format ?? "human";
+	if (!VALID_FORMATS.has(format)) {
+		process.stderr.write(`al-sem policy check: invalid --format '${format}'\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;
+	}
+
+	// Resolve effective policy.
+	let policy: PolicyDoc | undefined;
+	let source: string;
+	if (opts.noPolicy === true) {
+		policy = undefined;
+		source = "disabled";
+	} else if (opts.policyPath !== undefined) {
+		const abs = resolve(opts.policyPath);
+		const loaded = loadPolicyFromFile(abs);
+		if (!loaded.ok) {
+			for (const e of loaded.errors) process.stderr.write(`policy load error: ${e}\n`);
+			return 1;
+		}
+		policy = loaded.policy;
+		source = `explicit:${abs}`;
+	} else {
+		// Auto-detect workspace policy.
+		const candidates = ["al-sem.policy.yaml", "al-sem.policy.yml"];
+		let foundPath: string | undefined;
+		for (const name of candidates) {
+			const candidate = resolve(opts.workspace, name);
+			if (existsSync(candidate)) {
+				foundPath = candidate;
+				break;
+			}
+		}
+		if (foundPath !== undefined) {
+			const loaded = loadPolicyFromFile(foundPath);
+			if (!loaded.ok) {
+				for (const e of loaded.errors) process.stderr.write(`policy load error: ${e}\n`);
+				return 1;
+			}
+			policy = loaded.policy;
+			source = `auto:${foundPath}`;
+		} else {
+			// Use bundled default.
+			const defaultPath = fileURLToPath(new URL("../policy/policy-default.yaml", import.meta.url));
+			if (!existsSync(defaultPath)) {
+				process.stderr.write(
+					`al-sem policy check: bundled default policy not found at ${defaultPath} (use --policy or --no-policy)\n`,
+				);
+				return 1;
+			}
+			const loaded = loadPolicyFromFile(defaultPath);
+			if (!loaded.ok) {
+				for (const e of loaded.errors)
+					process.stderr.write(`bundled default policy load error: ${e}\n`);
+				return 1;
+			}
+			policy = loaded.policy;
+			source = "default";
+		}
+	}
+
+	const result: PolicyRunResult = runPolicy(model, policy, source, {
+		scope: opts.scope ?? "primary",
+	});
+	const text = formatPolicy(result, {
+		format,
+		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;
+}
+
+export interface PolicyExplainOptions {
+	workspace: string;
+	ruleId: string;
+	policyPath?: string;
+	routine?: string;
+	findingId?: string;
+	format?: "human" | "json";
+}
+
+export async function runPolicyExplain(opts: PolicyExplainOptions): Promise<number> {
+	const format = opts.format ?? "human";
+	if (!new Set(["human", "json"]).has(format)) {
+		process.stderr.write(`al-sem policy explain: invalid --format '${format}'\n`);
+		return 1;
+	}
+
+	// Resolve effective policy (mirrors runPolicyCheck's resolution).
+	let policy: PolicyDoc;
+	let source: string;
+	if (opts.policyPath !== undefined) {
+		const abs = resolve(opts.policyPath);
+		const loaded = loadPolicyFromFile(abs);
+		if (!loaded.ok) {
+			for (const e of loaded.errors) process.stderr.write(`policy load error: ${e}\n`);
+			return 1;
+		}
+		policy = loaded.policy;
+		source = `explicit:${abs}`;
+	} else {
+		// Auto-detect workspace policy.
+		const candidates = ["al-sem.policy.yaml", "al-sem.policy.yml"];
+		let foundPath: string | undefined;
+		for (const name of candidates) {
+			const candidate = resolve(opts.workspace, name);
+			if (existsSync(candidate)) {
+				foundPath = candidate;
+				break;
+			}
+		}
+		if (foundPath !== undefined) {
+			const loaded = loadPolicyFromFile(foundPath);
+			if (!loaded.ok) {
+				for (const e of loaded.errors) process.stderr.write(`policy load error: ${e}\n`);
+				return 1;
+			}
+			policy = loaded.policy;
+			source = `auto:${foundPath}`;
+		} else {
+			// Use bundled default.
+			const defaultPath = fileURLToPath(new URL("../policy/policy-default.yaml", import.meta.url));
+			if (!existsSync(defaultPath)) {
+				process.stderr.write(
+					"al-sem policy explain: bundled default policy not found (use --policy)\n",
+				);
+				return 1;
+			}
+			const loaded = loadPolicyFromFile(defaultPath);
+			if (!loaded.ok) {
+				for (const e of loaded.errors)
+					process.stderr.write(`bundled default policy load error: ${e}\n`);
+				return 1;
+			}
+			policy = loaded.policy;
+			source = "default";
+		}
+	}
+
+	const rule = policy.rules.find((r) => r.id === opts.ruleId);
+	if (rule === undefined) {
+		process.stderr.write(
+			`al-sem policy explain: rule '${opts.ruleId}' not found in effective policy (${source})\n`,
+		);
+		return 1;
+	}
+
+	// Rule-level summary output.
+	// Targeted --routine / --finding deep-trace rendering is deferred to Phase 4 follow-ups.
+	const lines: string[] = [];
+	lines.push(`Rule: ${rule.id}`);
+	if (rule.title !== undefined) lines.push(`Title: ${rule.title}`);
+	lines.push(`Severity: ${rule.severity}`);
+	lines.push(`Coverage gate: ${rule.requireCoverage ?? policy.defaults?.requireCoverage ?? "any"}`);
+	lines.push(`On unknown: ${rule.onUnknown ?? policy.defaults?.onUnknown ?? "fail-closed"}`);
+	lines.push(`Effective policy: ${source}`);
+	lines.push("");
+	lines.push("Normalized AST:");
+	lines.push(JSON.stringify(rule.when, undefined, 2));
+	if (rule.except !== undefined) {
+		lines.push("Except:");
+		lines.push(JSON.stringify(rule.except, undefined, 2));
+	}
+	process.stdout.write(`${lines.join("\n")}\n`);
+	return 0;
+}

package/src/config/roots-config.ts

@@ -0,0 +1,302 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Diagnostic } from "../model/finding.ts";
+import type { ObjectId, RoutineId } from "../model/ids.ts";
+import { ROOT_KIND_VALUES, type RootKind } from "../model/root-classification.ts";
+
+/**
+ * Top-level shape of `roots.config.json` — workspace-rooted file that lets a
+ * developer assert routines as entry-point roots beyond what AST classification
+ * (`src/engine/root-classifier.ts`) can derive on its own. Loaded at workspace
+ * discovery time alongside `app.json`; resolution (target → routine match) and
+ * overlay merge with AST classifications happens downstream.
+ */
+export interface RootsConfig {
+	version: 1;
+	roots: RootsConfigEntry[];
+}
+
+export interface RootsConfigEntry {
+	/** Stable identifier — surfaces in diagnostics and `RootClassification.configEntryId`. */
+	id: string;
+	target: RootsConfigTarget;
+	kinds: RootKind[];
+	/** Defaults to true downstream (config entries are typically external assertions). */
+	externallyReachable?: boolean;
+	note?: string;
+}
+
+export type RootsConfigTarget =
+	| { routineId: RoutineId }
+	| { objectId: ObjectId; routineName: string };
+
+export interface LoadedRootsConfig {
+	/** `undefined` if the file is missing or malformed at the top level. */
+	config: RootsConfig | undefined;
+	/** sha256 of the raw file bytes; `undefined` if the file is missing. */
+	contentHash: string | undefined;
+	/** Absolute path to the loaded file; `undefined` if the file is missing. */
+	path: string | undefined;
+	/**
+	 * Per-entry validation diagnostics. NOT resolution errors — those belong to
+	 * the overlay (Task 6).
+	 */
+	diagnostics: Diagnostic[];
+}
+
+/**
+ * Set of accepted kind strings, derived from `ROOT_KIND_VALUES` so the
+ * validator's accepted set is exactly the `RootKind` union — no drift.
+ */
+const VALID_KINDS = new Set<string>(ROOT_KIND_VALUES);
+
+/**
+ * Loads and validates `roots.config.json` from `<workspaceRoot>/roots.config.json`.
+ *
+ * Pure: never throws. All file-I/O and parse failures surface as `Diagnostic[]`
+ * (matching the engine-never-throws contract).
+ *
+ * Missing file is the common case and not an error: returns a clean empty
+ * result with no diagnostics. The returned `contentHash` is the sha256 of the
+ * raw file bytes (no whitespace normalization) so it is byte-stable for the
+ * workspaceFingerprint pipeline (Task 7).
+ */
+export function loadRootsConfig(workspaceRoot: string): LoadedRootsConfig {
+	const path = resolve(workspaceRoot, "roots.config.json");
+	if (!existsSync(path)) {
+		return { config: undefined, contentHash: undefined, path: undefined, diagnostics: [] };
+	}
+
+	let bytes: Buffer;
+	try {
+		bytes = readFileSync(path);
+	} catch (err) {
+		return {
+			config: undefined,
+			contentHash: undefined,
+			path,
+			diagnostics: [
+				diag(
+					"error",
+					`[roots-config/read-error] Cannot read roots.config.json: ${(err as Error).message}`,
+					path,
+				),
+			],
+		};
+	}
+
+	const contentHash = createHash("sha256").update(bytes).digest("hex");
+	// `contentHash` is over the RAW bytes (BOM included) so the workspaceFingerprint
+	// pipeline sees every byte-level change. The parser input strips a leading BOM
+	// so `JSON.parse` doesn't choke on `` at position 0 — mirrors `decodeText`
+	// in `src/symbols/symbol-reference-reader.ts`.
+	const rawText = bytes.toString("utf8");
+	const text = rawText.charCodeAt(0) === 0xfeff ? rawText.slice(1) : rawText;
+	const diagnostics: Diagnostic[] = [];
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (err) {
+		diagnostics.push(diag("error", `[roots-config/parse-error] ${(err as Error).message}`, path));
+		return { config: undefined, contentHash, path, diagnostics };
+	}
+
+	const validated = validateRootsConfig(parsed, path);
+	diagnostics.push(...validated.diagnostics);
+	return { config: validated.config, contentHash, path, diagnostics };
+}
+
+function diag(severity: Diagnostic["severity"], message: string, sourceRef: string): Diagnostic {
+	return { severity, stage: "discover", message, sourceRef };
+}
+
+function validateRootsConfig(
+	parsed: unknown,
+	path: string,
+): { config: RootsConfig | undefined; diagnostics: Diagnostic[] } {
+	const diagnostics: Diagnostic[] = [];
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		diagnostics.push(
+			diag(
+				"error",
+				"[roots-config/invalid-top-level] roots.config.json top level must be an object.",
+				path,
+			),
+		);
+		return { config: undefined, diagnostics };
+	}
+
+	const obj = parsed as Record<string, unknown>;
+	if (obj.version !== 1) {
+		diagnostics.push(
+			diag(
+				"error",
+				`[roots-config/unsupported-version] roots.config.json version must be 1 (got ${JSON.stringify(obj.version)}).`,
+				path,
+			),
+		);
+		return { config: undefined, diagnostics };
+	}
+
+	if (!Array.isArray(obj.roots)) {
+		diagnostics.push(
+			diag(
+				"error",
+				'[roots-config/invalid-roots] roots.config.json "roots" field must be an array.',
+				path,
+			),
+		);
+		return { config: undefined, diagnostics };
+	}
+
+	const entries: RootsConfigEntry[] = [];
+	const seenIds = new Set<string>();
+
+	for (let i = 0; i < obj.roots.length; i++) {
+		const entryUnknown = obj.roots[i];
+		if (entryUnknown === null || typeof entryUnknown !== "object" || Array.isArray(entryUnknown)) {
+			diagnostics.push(
+				diag(
+					"warning",
+					`[roots-config/invalid-root-shape] roots[${i}] is not an object; skipping.`,
+					path,
+				),
+			);
+			continue;
+		}
+		const entry = entryUnknown as Record<string, unknown>;
+
+		if (typeof entry.id !== "string") {
+			diagnostics.push(
+				diag(
+					"warning",
+					`[roots-config/invalid-root-shape] roots[${i}] missing string "id"; skipping.`,
+					path,
+				),
+			);
+			continue;
+		}
+
+		if (seenIds.has(entry.id)) {
+			diagnostics.push(
+				diag(
+					"warning",
+					`[roots-config/duplicate-entry-id] roots[${i}] duplicates id "${entry.id}"; skipping duplicate.`,
+					path,
+				),
+			);
+			continue;
+		}
+
+		const target = parseTarget(entry.target);
+		if (target === undefined) {
+			diagnostics.push(
+				diag(
+					"warning",
+					`[roots-config/invalid-target] roots[${i}] ("${entry.id}") has invalid target; skipping.`,
+					path,
+				),
+			);
+			continue;
+		}
+
+		if (!Array.isArray(entry.kinds)) {
+			diagnostics.push(
+				diag(
+					"warning",
+					`[roots-config/invalid-root-shape] roots[${i}] ("${entry.id}") "kinds" must be an array; skipping.`,
+					path,
+				),
+			);
+			continue;
+		}
+
+		// Canonicalize `kinds`: dedup (silent — mirrors AST classifier behaviour) and
+		// sort in `ROOT_KIND_VALUES` declaration order. This matches the invariant
+		// documented on `RootClassification.kinds` so AST and config paths produce
+		// byte-identical kind arrays for equivalent inputs.
+		const seenKinds = new Set<RootKind>();
+		for (const k of entry.kinds) {
+			if (typeof k === "string" && VALID_KINDS.has(k)) {
+				seenKinds.add(k as RootKind);
+			} else {
+				diagnostics.push(
+					diag(
+						"warning",
+						`[roots-config/unknown-root-kind] roots[${i}] ("${entry.id}") kind ${JSON.stringify(k)} is not a known RootKind; dropping.`,
+						path,
+					),
+				);
+			}
+		}
+		const kinds: RootKind[] = ROOT_KIND_VALUES.filter((k) => seenKinds.has(k));
+
+		if (kinds.length === 0) {
+			diagnostics.push(
+				diag(
+					"warning",
+					`[roots-config/invalid-root-shape] roots[${i}] ("${entry.id}") has no valid kinds; skipping entry.`,
+					path,
+				),
+			);
+			continue;
+		}
+
+		const validEntry: RootsConfigEntry = {
+			id: entry.id,
+			target,
+			kinds,
+		};
+		// Optional fields: present-and-correctly-typed → carry through;
+		// absent → omit; present-but-wrong-typed → drop the field AND emit a
+		// warning so authors notice typos like `externallyReachable: "true"`.
+		if (entry.externallyReachable !== undefined) {
+			if (typeof entry.externallyReachable === "boolean") {
+				validEntry.externallyReachable = entry.externallyReachable;
+			} else {
+				diagnostics.push(
+					diag(
+						"warning",
+						`[roots-config/invalid-root-shape] roots[${i}] ("${entry.id}") "externallyReachable" must be a boolean (got ${JSON.stringify(entry.externallyReachable)}); dropping field.`,
+						path,
+					),
+				);
+			}
+		}
+		if (entry.note !== undefined) {
+			if (typeof entry.note === "string") {
+				validEntry.note = entry.note;
+			} else {
+				diagnostics.push(
+					diag(
+						"warning",
+						`[roots-config/invalid-root-shape] roots[${i}] ("${entry.id}") "note" must be a string (got ${JSON.stringify(entry.note)}); dropping field.`,
+						path,
+					),
+				);
+			}
+		}
+		entries.push(validEntry);
+		seenIds.add(entry.id);
+	}
+
+	return { config: { version: 1, roots: entries }, diagnostics };
+}
+
+/**
+ * Parse a target object into one of two accepted shapes. When both `routineId`
+ * and `objectId + routineName` are present, `routineId` takes precedence
+ * (the stable id is more specific than the name-based lookup).
+ */
+function parseTarget(t: unknown): RootsConfigTarget | undefined {
+	if (t === null || typeof t !== "object" || Array.isArray(t)) return undefined;
+	const obj = t as Record<string, unknown>;
+	if (typeof obj.routineId === "string") return { routineId: obj.routineId };
+	if (typeof obj.objectId === "string" && typeof obj.routineName === "string") {
+		return { objectId: obj.objectId, routineName: obj.routineName };
+	}
+	return undefined;
+}

package/src/deps/cache-versions.ts

@@ -0,0 +1,74 @@
+import { ANALYZER_VERSION, GRAMMAR_VERSION } from "../providers/discover.ts";
+
+/**
+ * Cache-affecting version stamps. Every stamp here is folded into a DependencyArtifact's
+ * cache key. Ownership (bump when…):
+ *  - analyzer:       release identity (already bumped per release).
+ *  - grammar:        tree-sitter-al grammar behaviour changes.
+ *  - symbolReader:   .app extraction / manifest / SymbolReference projection changes.
+ *  - summarySchema:  RoutineSummary shape OR semantics — lattice, residuals, transfer
+ *                    functions, fixed-point — changes.
+ *  - depCache:       artifact serialization format, canonicalization rules, or key structure
+ *                    changes.
+ *  - resourcePolicy: the deterministic preflight-limit constants in dependency-pipeline.ts
+ *                    change.
+ *
+ * `symbolReader` is bumped from "1" to "2" in this phase because the .app reader was
+ * replaced (app-package-zip + the new readers).
+ */
+export const CACHE_VERSIONS = {
+	analyzer: ANALYZER_VERSION,
+	grammar: GRAMMAR_VERSION,
+	// symbolReader "6": Phase 0b-β — dep extraction now emits CapabilityFact[]
+	// via extractCapabilities on dep routines with embedded source. Extends
+	// RoutineSummary with capabilityFactsDirect / capabilityFactsInherited /
+	// coverage fields populated by per-family extractors + SCC composers.
+	// symbolReader "7": Phase 1 §4.3 — ObjectDecl gains objectSubtype (Codeunit
+	// Subtype property) and pageType (Page PageType property), extracted from
+	// AL source and from .app SymbolReference JSON. Required for root-classifier
+	// to identify install-codeunit / upgrade-codeunit / api-page kinds.
+	symbolReader: "7",
+	// summarySchema "6": Phase 1c — RoutineSummary's legacy boolean lattice
+	// (touchesDb, commits, writesTables, publishesEvents) deleted. The fields
+	// have been replaced by Phase 1a capability-query helpers (touchesDbOf,
+	// mayCommit, writesTablesOf, publishesEventsOf, reachableCoverage). Producer
+	// code in summary-engine.ts + summary-runner.ts simplified accordingly;
+	// fingerprint hash format changes — fixed-point convergence count may
+	// shift but final summaries are functionally equivalent.
+	// summarySchema "7": Phase 3 — IntraproceduralFeatures gained varAssignments
+	// (drives D43 IsHandled-skip detection).
+	// summarySchema "8": Phase 3.1 — IntraproceduralFeatures gained conditionReferences
+	// (drives D43 dispatch-site guard detection).
+	// summarySchema "9": capability-cone propagation — capabilityFactsInherited is now
+	// computed by bottom-up SCC-condensation cone propagation (shortest-path-wins
+	// attribution) and canonically sorted; coverage cones share the same pass. Witness/via
+	// on equal-distance ties and array order change vs the legacy per-routine BFS.
+	summarySchema: "9",
+	// depCache "2": canonical-json now omits undefined-valued object keys (was: rendered as
+	// `null` + key kept). Dependency-artifact bytes change; absent optional fields (e.g. fact
+	// resourceId) round-trip as undefined, restoring the model invariant.
+	depCache: "2",
+	resourcePolicy: "1",
+} as const;
+
+/** A stable, human-readable rendering of the version tuple — used in keys and the snapshot test. */
+export function cacheVersionTuple(): string {
+	return [
+		`analyzer=${CACHE_VERSIONS.analyzer}`,
+		`grammar=${CACHE_VERSIONS.grammar}`,
+		`symbolReader=${CACHE_VERSIONS.symbolReader}`,
+		`summarySchema=${CACHE_VERSIONS.summarySchema}`,
+		`depCache=${CACHE_VERSIONS.depCache}`,
+		`resourcePolicy=${CACHE_VERSIONS.resourcePolicy}`,
+	].join(";");
+}
+
+/**
+ * A per-build fingerprint folded into the cache key for non-release (dev) builds, so local
+ * logic changes never silently reuse a stale artifact. Release builds (where
+ * `process.env.AL_SEM_RELEASE === "1"`) return "" — they are protected by `analyzer`.
+ */
+export function devFingerprint(): string {
+	if (process.env.AL_SEM_RELEASE === "1") return "";
+	return process.env.AL_SEM_DEV_FINGERPRINT ?? "dev";
+}

package/src/deps/canonical-json.ts

@@ -0,0 +1,27 @@
+/**
+ * Deterministic JSON: object keys sorted recursively, arrays kept in order, object keys
+ * with an `undefined` value are omitted (standard JSON); `undefined` array elements render
+ * as `null`. The basis of artifact content-addressing.
+ */
+export function canonicalStringify(value: unknown): string {
+	if (value === undefined || value === null) return "null";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) return "null";
+		return Object.is(value, -0) ? "0" : String(value);
+	}
+	if (typeof value === "boolean") return value ? "true" : "false";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalStringify).join(",")}]`;
+	if (typeof value === "object") {
+		const obj = value as Record<string, unknown>;
+		// Omit undefined-valued keys (standard JSON.stringify semantics). The previous behavior
+		// kept the key and rendered the value as `null`, which round-tripped absent optional
+		// fields (e.g. CapabilityFact.resourceId) back as `null` and violated the
+		// "absent ⇒ undefined" model invariant. Array undefined elements still render as `null`.
+		const keys = Object.keys(obj)
+			.filter((k) => obj[k] !== undefined)
+			.sort();
+		return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalStringify(obj[k])}`).join(",")}}`;
+	}
+	return "null";
+}