al-sem 0.0.1

package/src/diff/diff-renames.ts

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+export interface RenameOverlay {
+	readonly [oldId: string]: string;
+}
+
+export interface RenameEntry {
+	newId: string;
+	applied: boolean;
+}
+
+export type RenameTable = Map<string, RenameEntry>;
+
+export type RenameDiagnostic =
+	| { kind: "rename-overlay-chain"; from: string; via: string; to: string }
+	| { kind: "rename-overlay-overlap"; targets: readonly string[] }
+	| { kind: "rename-overlay-stale"; staleId: string; reason: "not-in-old" | "not-in-new" };
+
+/** Load + parse the overlay file. Engine-never-throws: parse failures surface
+ *  as a thrown CliError in the orchestrator, not here. */
+export async function loadRenameOverlay(
+	path: string | undefined,
+): Promise<{ overlay?: RenameOverlay; fingerprint?: string }> {
+	if (path === undefined) return { overlay: undefined, fingerprint: undefined };
+	const text = await readFile(path, "utf8");
+	const overlay = JSON.parse(text) as RenameOverlay;
+	return { overlay, fingerprint: overlayFingerprint(overlay) };
+}
+
+/** Build a normalized rename table from a raw overlay map. Detects chains and
+ *  overlaps; stale-id detection (vs actual snapshots) lives in diff-indexes
+ *  since that's where snapshot membership is known. */
+export function buildRenameTable(overlay: RenameOverlay): {
+	table: RenameTable;
+	diagnostics: RenameDiagnostic[];
+} {
+	const table: RenameTable = new Map();
+	const diagnostics: RenameDiagnostic[] = [];
+	const newToOlds = new Map<string, string[]>();
+
+	for (const [oldId, newId] of Object.entries(overlay)) {
+		if (oldId === newId) continue; // identity mapping
+		table.set(oldId, { newId, applied: true });
+		const olds = newToOlds.get(newId) ?? [];
+		olds.push(oldId);
+		newToOlds.set(newId, olds);
+	}
+
+	// Detect chains: any newId that also appears as an oldId in the overlay.
+	for (const [oldId, entry] of table) {
+		if (table.has(entry.newId)) {
+			const next = table.get(entry.newId);
+			if (next !== undefined) {
+				diagnostics.push({
+					kind: "rename-overlay-chain",
+					from: oldId,
+					via: entry.newId,
+					to: next.newId,
+				});
+			}
+		}
+	}
+
+	// Detect overlaps: any newId with multiple oldIds mapping to it.
+	for (const [newId, olds] of newToOlds) {
+		if (olds.length > 1) {
+			diagnostics.push({
+				kind: "rename-overlay-overlap",
+				targets: [...olds, newId],
+			});
+		}
+	}
+
+	return { table, diagnostics };
+}
+
+/** Validate the overlay against actual snapshot stable-id sets and emit
+ *  stale-reference diagnostics. Called by diff-indexes once both snapshots
+ *  are loaded. */
+export function validateOverlayAgainstSnapshots(
+	overlay: RenameOverlay,
+	oldStableIds: ReadonlySet<string>,
+	newStableIds: ReadonlySet<string>,
+): RenameDiagnostic[] {
+	const diagnostics: RenameDiagnostic[] = [];
+	for (const [oldId, newId] of Object.entries(overlay)) {
+		if (oldId === newId) continue;
+		if (!oldStableIds.has(oldId)) {
+			diagnostics.push({ kind: "rename-overlay-stale", staleId: oldId, reason: "not-in-old" });
+		}
+		if (!newStableIds.has(newId)) {
+			diagnostics.push({ kind: "rename-overlay-stale", staleId: newId, reason: "not-in-new" });
+		}
+	}
+	return diagnostics;
+}
+
+/** Stable SHA-256(16-hex) fingerprint over a key-sorted JSON serialization. */
+export function overlayFingerprint(overlay: RenameOverlay): string {
+	const keys = Object.keys(overlay).sort();
+	const canonical = JSON.stringify(keys.map((k) => [k, overlay[k]]));
+	return createHash("sha256").update(canonical, "utf8").digest("hex").slice(0, 16);
+}

package/src/diff/diff-schema.ts

@@ -0,0 +1,232 @@
+import type { SchemaFact } from "../snapshot/types.ts";
+import type { DiffEngineOptions } from "./diff-abi.ts";
+import { DiffCategory, DiffKind, computeDiffFingerprint } from "./diff-identity.ts";
+import type { DiffIndexes } from "./diff-indexes.ts";
+
+export interface SchemaDetails {
+	kind:
+		| DiffKind.TableFieldRemoved
+		| DiffKind.TableFieldTypeNarrowed
+		| DiffKind.TableFieldTypeWidened
+		| DiffKind.TableFieldDataClassificationTightened
+		| DiffKind.TableFieldDataClassificationRelaxed
+		| DiffKind.EnumValueRemoved
+		| DiffKind.EnumValueRenumbered
+		| DiffKind.TableFieldAdded
+		| DiffKind.EnumValueAdded;
+	oldShapeFingerprint?: string;
+	newShapeFingerprint?: string;
+	oldDataClassification?: string;
+	newDataClassification?: string;
+}
+
+export interface SchemaFinding {
+	id: string;
+	category: DiffCategory.Schema;
+	kind: DiffKind;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	subject: {
+		normalizedStableId: string;
+		oldOriginalStableId?: string;
+		newStableId?: string;
+		displayName: string;
+	};
+	comparisonCone: readonly string[];
+	details: SchemaDetails;
+}
+
+const SEVERITY: Partial<Record<DiffKind, SchemaFinding["severity"]>> = {
+	[DiffKind.TableFieldRemoved]: "critical",
+	[DiffKind.TableFieldTypeNarrowed]: "critical",
+	[DiffKind.EnumValueRemoved]: "critical",
+	[DiffKind.EnumValueRenumbered]: "critical",
+	[DiffKind.TableFieldDataClassificationTightened]: "high",
+	[DiffKind.TableFieldTypeWidened]: "low",
+	[DiffKind.TableFieldDataClassificationRelaxed]: "info",
+	[DiffKind.TableFieldAdded]: "info",
+	[DiffKind.EnumValueAdded]: "info",
+};
+
+/**
+ * DataClassification rank — higher rank = more sensitive.
+ * Tightened: new rank > old rank (more sensitive = restrict more access).
+ * Relaxed: new rank < old rank (less sensitive = expose more data).
+ *
+ * AL's DataClassification values in ascending sensitivity order:
+ * SystemMetadata < AccountData < OrganizationIdentifiableInformation <
+ * EndUserPseudonymousIdentifiers < EndUserIdentifiableInformation < CustomerContent
+ */
+const DATA_CLASS_RANK: Record<string, number> = {
+	SystemMetadata: 0,
+	AccountData: 1,
+	OrganizationIdentifiableInformation: 2,
+	EndUserPseudonymousIdentifiers: 3,
+	EndUserIdentifiableInformation: 4,
+	CustomerContent: 5,
+};
+
+function makeFinding(
+	kind: SchemaDetails["kind"],
+	stableId: string,
+	indexes: DiffIndexes,
+	details: SchemaDetails,
+): SchemaFinding {
+	const origin = indexes.originByNormalized.get(stableId);
+	const display =
+		indexes.newDisplayByStableId.get(stableId) ??
+		indexes.oldDisplayByStableId.get(stableId) ??
+		stableId;
+	return {
+		id: computeDiffFingerprint({
+			category: DiffCategory.Schema,
+			kind,
+			normalizedStableId: stableId,
+		}),
+		category: DiffCategory.Schema,
+		kind,
+		severity: SEVERITY[kind] ?? "medium",
+		subject: {
+			normalizedStableId: stableId,
+			oldOriginalStableId: origin?.oldOriginalStableId,
+			newStableId: origin?.newStableId,
+			displayName: display,
+		},
+		comparisonCone: [stableId],
+		details,
+	};
+}
+
+/**
+ * Diff schema facts between two snapshots.
+ *
+ * SchemaFact shape uses `stableId` as the primary key and `shapeFingerprint`
+ * (SHA-256 of the shape) for change detection. Individual field names, types,
+ * and ordinals are not stored separately — only the fingerprint is available.
+ *
+ * As a result:
+ * - TableField removed/added: detected by stableId presence.
+ * - TableField shape changed: fingerprint differs → emits TableFieldTypeNarrowed
+ *   (conservative for consumers; we cannot distinguish narrow vs widen without
+ *   parsing the stored type, which is in the fingerprint hash).
+ * - TableFieldDataClassificationTightened/Relaxed: detected via the optional
+ *   `dataClassification` field when present on both sides.
+ * - EnumValue removed/added: detected by stableId presence.
+ * - EnumValue renumbered: fingerprint differs (ordinal is part of the shape).
+ */
+export function diffSchema(
+	_oldSnap: unknown,
+	_newSnap: unknown,
+	indexes: DiffIndexes,
+	_opts: DiffEngineOptions,
+): SchemaFinding[] {
+	const out: SchemaFinding[] = [];
+
+	// Walk OLD schema facts — detect removals and in-place changes.
+	for (const [stableId, oldFacts] of indexes.oldSchemaBySubject) {
+		// Each stableId maps to exactly one fact (schema facts are per-entity).
+		const oldFact = oldFacts[0] as SchemaFact | undefined;
+		if (oldFact === undefined) continue;
+
+		const newFacts = indexes.newSchemaBySubject.get(stableId);
+		const newFact = newFacts?.[0] as SchemaFact | undefined;
+
+		const oldKind = oldFact.kind;
+
+		if (newFact === undefined) {
+			// Removal.
+			if (oldKind === "field") {
+				out.push(
+					makeFinding(DiffKind.TableFieldRemoved, stableId, indexes, {
+						kind: DiffKind.TableFieldRemoved,
+					}),
+				);
+			} else if (oldKind === "enum-value") {
+				out.push(
+					makeFinding(DiffKind.EnumValueRemoved, stableId, indexes, {
+						kind: DiffKind.EnumValueRemoved,
+					}),
+				);
+			}
+			// "table", "enum", "key" removals are not tracked by this module.
+			continue;
+		}
+
+		// In-place change detection.
+		const oldFp = oldFact.shapeFingerprint;
+		const newFp = newFact.shapeFingerprint;
+
+		if (oldKind === "field") {
+			if (oldFp !== newFp) {
+				// Shape changed — emit conservative TableFieldTypeNarrowed since we
+				// cannot distinguish narrow vs widen from the fingerprint alone.
+				out.push(
+					makeFinding(DiffKind.TableFieldTypeNarrowed, stableId, indexes, {
+						kind: DiffKind.TableFieldTypeNarrowed,
+						oldShapeFingerprint: oldFp,
+						newShapeFingerprint: newFp,
+					}),
+				);
+			}
+
+			// Data classification change — detectable when the optional field is present.
+			const oldDc = oldFact.dataClassification;
+			const newDc = newFact.dataClassification;
+			if (oldDc !== undefined && newDc !== undefined && oldDc !== newDc) {
+				const oldRank = DATA_CLASS_RANK[oldDc] ?? 0;
+				const newRank = DATA_CLASS_RANK[newDc] ?? 0;
+				if (newRank > oldRank) {
+					out.push(
+						makeFinding(DiffKind.TableFieldDataClassificationTightened, stableId, indexes, {
+							kind: DiffKind.TableFieldDataClassificationTightened,
+							oldDataClassification: oldDc,
+							newDataClassification: newDc,
+						}),
+					);
+				} else if (newRank < oldRank) {
+					out.push(
+						makeFinding(DiffKind.TableFieldDataClassificationRelaxed, stableId, indexes, {
+							kind: DiffKind.TableFieldDataClassificationRelaxed,
+							oldDataClassification: oldDc,
+							newDataClassification: newDc,
+						}),
+					);
+				}
+			}
+		} else if (oldKind === "enum-value") {
+			if (oldFp !== newFp) {
+				// Enum value shape changed — most likely a renumbering.
+				out.push(
+					makeFinding(DiffKind.EnumValueRenumbered, stableId, indexes, {
+						kind: DiffKind.EnumValueRenumbered,
+						oldShapeFingerprint: oldFp,
+						newShapeFingerprint: newFp,
+					}),
+				);
+			}
+		}
+	}
+
+	// Walk NEW schema facts to find additions.
+	for (const [stableId, newFacts] of indexes.newSchemaBySubject) {
+		if (indexes.oldSchemaBySubject.has(stableId)) continue;
+		const newFact = newFacts[0] as SchemaFact | undefined;
+		if (newFact === undefined) continue;
+
+		const newKind = newFact.kind;
+		if (newKind === "field") {
+			out.push(
+				makeFinding(DiffKind.TableFieldAdded, stableId, indexes, {
+					kind: DiffKind.TableFieldAdded,
+				}),
+			);
+		} else if (newKind === "enum-value") {
+			out.push(
+				makeFinding(DiffKind.EnumValueAdded, stableId, indexes, {
+					kind: DiffKind.EnumValueAdded,
+				}),
+			);
+		}
+	}
+
+	return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/src/diff/format-diff.ts

@@ -0,0 +1,148 @@
+import type { DiffEngineResult, DiffFinding } from "./diff-engine.ts";
+
+export interface DiffRenderOptions {
+	format: "human" | "json" | "sarif";
+	deterministic: boolean;
+	/** Reserved for a future ANSI rendering pass. Currently ignored. */
+	color?: boolean;
+	verbosity?: "compact" | "full";
+}
+
+export function formatDiff(result: DiffEngineResult, opts: DiffRenderOptions): string {
+	if (opts.format === "json") return renderJson(result);
+	if (opts.format === "sarif") return renderSarif(result);
+	return renderHuman(result, opts);
+}
+
+function renderHuman(result: DiffEngineResult, opts: DiffRenderOptions): string {
+	const lines: string[] = [];
+	if (result.findings.length === 0 && result.diagnostics.length === 0) {
+		lines.push("No diff findings.");
+		return `${lines.join("\n")}\n`;
+	}
+	if (result.diagnostics.length > 0) {
+		lines.push("diagnostics:");
+		for (const d of result.diagnostics) {
+			lines.push(`  ${d.kind}: ${JSON.stringify(d)}`);
+		}
+		lines.push("");
+	}
+	if (result.findings.length === 0) {
+		return `${lines.join("\n")}\n`;
+	}
+	const s = result.summary;
+	lines.push(
+		`Diff: ${result.findings.length} finding(s). critical=${s.findingsBySeverity.critical} high=${s.findingsBySeverity.high} medium=${s.findingsBySeverity.medium} low=${s.findingsBySeverity.low} info=${s.findingsBySeverity.info}`,
+	);
+	lines.push("");
+
+	// Group: Contract (abi/schema/events) then Effects (capabilities/permissions).
+	const contract = result.findings.filter(
+		(f) => f.category === "abi" || f.category === "schema" || f.category === "events",
+	);
+	const effects = result.findings.filter(
+		(f) => f.category === "capabilities" || f.category === "permissions",
+	);
+	if (contract.length > 0) {
+		lines.push("Contract:");
+		for (const f of contract) lines.push(formatFinding(f));
+		lines.push("");
+	}
+	if (effects.length > 0) {
+		lines.push("Effects:");
+		for (const f of effects) lines.push(formatFinding(f));
+		lines.push("");
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function formatFinding(f: DiffFinding): string {
+	// coverageState is attached dynamically by the policy pass (not present on the static type).
+	const coverageState = (f as { coverageState?: { old: string; new: string } }).coverageState;
+	const renameNote =
+		f.subject.oldOriginalStableId !== undefined &&
+		f.subject.oldOriginalStableId !== f.subject.normalizedStableId
+			? ` (renamed from ${f.subject.oldOriginalStableId})`
+			: "";
+	const coverageNote =
+		coverageState !== undefined &&
+		(coverageState.old !== "complete" || coverageState.new !== "complete")
+			? ` [cov old=${coverageState.old} new=${coverageState.new}]`
+			: "";
+	return `  [${f.severity}] ${f.kind}: ${f.subject.displayName}${renameNote}${coverageNote}`;
+}
+
+function renderJson(result: DiffEngineResult): string {
+	// Use a stable key order.
+	const payload = {
+		findings: result.findings,
+		diagnostics: result.diagnostics,
+		summary: result.summary,
+	};
+	return `${JSON.stringify(payload, sortReplacer, 2)}\n`;
+}
+
+function sortReplacer(_key: string, value: unknown): unknown {
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value as Record<string, unknown>;
+		const sorted: Record<string, unknown> = {};
+		for (const k of Object.keys(obj).sort()) sorted[k] = obj[k];
+		return sorted;
+	}
+	return value;
+}
+
+function renderSarif(result: DiffEngineResult): string {
+	const rules: Array<{ id: string; name: string; shortDescription: { text: string } }> = [];
+	const rulesSeen = new Set<string>();
+	const results: Array<Record<string, unknown>> = [];
+
+	for (const f of result.findings) {
+		const ruleId = `${f.category}.${f.kind}`;
+		if (!rulesSeen.has(ruleId)) {
+			rulesSeen.add(ruleId);
+			rules.push({
+				id: ruleId,
+				name: f.kind,
+				shortDescription: { text: `${f.category} ${f.kind}` },
+			});
+		}
+		results.push({
+			ruleId,
+			level: severityToSarifLevel(f.severity),
+			message: { text: `${f.kind}: ${f.subject.displayName}` },
+			fingerprints: { default: f.id },
+		});
+	}
+
+	const sarif = {
+		$schema: "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
+		version: "2.1.0",
+		runs: [
+			{
+				tool: {
+					driver: {
+						name: "al-sem-diff",
+						informationUri: "https://github.com/anthropics/al-sem",
+						rules,
+					},
+				},
+				results,
+			},
+		],
+	};
+	return `${JSON.stringify(sarif, sortReplacer, 2)}\n`;
+}
+
+function severityToSarifLevel(severity: DiffFinding["severity"]): string {
+	switch (severity) {
+		case "critical":
+		case "high":
+			return "error";
+		case "medium":
+			return "warning";
+		case "low":
+		case "info":
+			return "note";
+	}
+}

package/src/engine/attribute-parser.ts

@@ -0,0 +1,50 @@
+import { findAttribute, hasAttribute, stringArg } from "../model/attributes.ts";
+import type { Routine } from "../model/entities.ts";
+
+export interface RoutineAttributes {
+	obsoleteState?: "Pending" | "Removed";
+	obsoleteReason?: string;
+	internalProc: boolean;
+}
+
+/**
+ * Parse structured information out of a routine's `attributesParsed`. Recognises:
+ *  - `[Obsolete(reason, version[, ObsoleteState::Removed])]` — reason from arg 0,
+ *    state from arg 2 (defaults to Pending when omitted, Removed only when the
+ *    third argument is the qualified enum value `ObsoleteState::Removed`).
+ *  - `[InternalProc]` — presence flag.
+ *
+ * Used by D13 (cross-app Internal call, alongside `Routine.accessModifier`) and
+ * D16 / D38 (obsolete routine call, transitive). All arguments come from the
+ * tree-sitter-built `AttributeInfo` model — no `[…]` text shredding.
+ */
+export function parseRoutineAttributes(
+	routine: Pick<Routine, "attributesParsed">,
+): RoutineAttributes {
+	let obsoleteState: RoutineAttributes["obsoleteState"];
+	let obsoleteReason: string | undefined;
+
+	const obsolete = findAttribute(routine.attributesParsed, "Obsolete");
+	if (obsolete !== undefined) {
+		obsoleteReason = stringArg(obsolete, 0);
+		// State is Removed only when the third arg is a qualified enum value whose
+		// member is "Removed" (e.g. `ObsoleteState::Removed`). Anything else — absent,
+		// `ObsoleteState::Pending`, or any other shape — means Pending, which is also
+		// AL's default Obsolete severity.
+		const stateArg = obsolete.args[2];
+		obsoleteState =
+			stateArg !== undefined &&
+			stateArg.kind === "qualified_enum_value" &&
+			(stateArg.member ?? "").toLowerCase() === "removed"
+				? "Removed"
+				: "Pending";
+	}
+
+	const internalProc = hasAttribute(routine.attributesParsed, "InternalProc");
+
+	return {
+		...(obsoleteState !== undefined ? { obsoleteState } : {}),
+		...(obsoleteReason !== undefined ? { obsoleteReason } : {}),
+		internalProc,
+	};
+}