al-sem 0.0.1

package/src/diff/diff-engine.ts

@@ -0,0 +1,146 @@
+import type { CapabilitySnapshot } from "../snapshot/types.ts";
+import { type AbiFinding, diffAbi } from "./diff-abi.ts";
+import { type CapabilityFinding, diffCapabilities } from "./diff-capabilities.ts";
+import { type EventFinding, diffEvents } from "./diff-events.ts";
+import { DiffCategory, type DiffKind } from "./diff-identity.ts";
+import { buildDiffIndexes } from "./diff-indexes.ts";
+import { type PermissionFinding, diffPermissions } from "./diff-permissions.ts";
+import { type PolicyDiagnostic, applyCoveragePolicy } from "./diff-policy.ts";
+import { type PreflightDiagnostic, runPreflight } from "./diff-preflight.ts";
+import { type RenameDiagnostic, type RenameOverlay, buildRenameTable } from "./diff-renames.ts";
+import { type SchemaFinding, diffSchema } from "./diff-schema.ts";
+
+export type DiffFinding =
+	| AbiFinding
+	| SchemaFinding
+	| EventFinding
+	| CapabilityFinding
+	| PermissionFinding;
+
+export type DiffDiagnostic = PreflightDiagnostic | RenameDiagnostic | PolicyDiagnostic;
+
+export interface DiffEngineOptions {
+	coveragePolicy: "loose" | "strict";
+	deterministic: boolean;
+	renameOverlay?: RenameOverlay;
+}
+
+export interface DiffEngineResult {
+	findings: readonly DiffFinding[];
+	diagnostics: readonly DiffDiagnostic[];
+	summary: {
+		findingsByCategory: Record<DiffCategory, number>;
+		findingsBySeverity: Record<DiffFinding["severity"], number>;
+		coverageIncompleteCones: number;
+		renamesApplied: number;
+	};
+}
+
+const SEVERITY_RANK: Record<DiffFinding["severity"], number> = {
+	critical: 0,
+	high: 1,
+	medium: 2,
+	low: 3,
+	info: 4,
+};
+
+export function runDiffEngine(
+	oldSnap: CapabilitySnapshot,
+	newSnap: CapabilitySnapshot,
+	opts: DiffEngineOptions,
+): DiffEngineResult {
+	const diagnostics: DiffDiagnostic[] = [];
+
+	const preflight = runPreflight(oldSnap, newSnap, { coveragePolicy: opts.coveragePolicy });
+	diagnostics.push(...preflight.diagnostics);
+	if (preflight.fatal) {
+		return {
+			findings: [],
+			diagnostics,
+			summary: emptySummary(),
+		};
+	}
+
+	const { table: renameTable, diagnostics: renameDiagnostics } = buildRenameTable(
+		opts.renameOverlay ?? {},
+	);
+	diagnostics.push(...renameDiagnostics);
+
+	const indexes = buildDiffIndexes(oldSnap, newSnap, renameTable);
+	diagnostics.push(...indexes.renameDiagnostics);
+
+	const findings: DiffFinding[] = [];
+	findings.push(...diffAbi(oldSnap, newSnap, indexes, opts));
+	findings.push(...diffSchema(oldSnap, newSnap, indexes, opts));
+	findings.push(...diffEvents(oldSnap, newSnap, indexes, opts));
+	findings.push(...diffCapabilities(oldSnap, newSnap, indexes, opts));
+	findings.push(...diffPermissions(oldSnap, newSnap, indexes, opts));
+
+	// PolicyFinding requires an index signature; cast through unknown to satisfy the constraint.
+	const { findings: policyFindings, diagnostics: policyDiagnostics } = applyCoveragePolicy(
+		findings as unknown as import("./diff-policy.ts").PolicyFinding[],
+		indexes,
+		{ coveragePolicy: opts.coveragePolicy },
+	);
+	diagnostics.push(...policyDiagnostics);
+
+	const sorted = (policyFindings as unknown as DiffFinding[]).slice().sort((a, b) => {
+		const sevDelta =
+			SEVERITY_RANK[a.severity as DiffFinding["severity"]] -
+			SEVERITY_RANK[b.severity as DiffFinding["severity"]];
+		if (sevDelta !== 0) return sevDelta;
+		const ac = a.category as string;
+		const bc = b.category as string;
+		if (ac !== bc) return ac < bc ? -1 : 1;
+		const ak = a.kind as string;
+		const bk = b.kind as string;
+		if (ak !== bk) return ak < bk ? -1 : 1;
+		return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+	});
+
+	return {
+		findings: sorted,
+		diagnostics,
+		summary: computeSummary(sorted, policyDiagnostics, renameTable.size),
+	};
+}
+
+function emptySummary(): DiffEngineResult["summary"] {
+	const byCategory: Record<DiffCategory, number> = {
+		[DiffCategory.ABI]: 0,
+		[DiffCategory.Schema]: 0,
+		[DiffCategory.Events]: 0,
+		[DiffCategory.Capabilities]: 0,
+		[DiffCategory.Permissions]: 0,
+	};
+	const bySeverity: Record<DiffFinding["severity"], number> = {
+		critical: 0,
+		high: 0,
+		medium: 0,
+		low: 0,
+		info: 0,
+	};
+	return {
+		findingsByCategory: byCategory,
+		findingsBySeverity: bySeverity,
+		coverageIncompleteCones: 0,
+		renamesApplied: 0,
+	};
+}
+
+function computeSummary(
+	findings: readonly DiffFinding[],
+	policyDiagnostics: readonly PolicyDiagnostic[],
+	renamesApplied: number,
+): DiffEngineResult["summary"] {
+	const summary = emptySummary();
+	for (const f of findings) {
+		summary.findingsByCategory[f.category]++;
+		summary.findingsBySeverity[f.severity]++;
+	}
+	summary.coverageIncompleteCones = policyDiagnostics.filter(
+		(d) => d.kind === "coverage-incomplete",
+	).length;
+	summary.renamesApplied = renamesApplied;
+	return summary;
+}

package/src/diff/diff-events.ts

@@ -0,0 +1,323 @@
+import type { EventDeclaration } 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 EventDetails {
+	kind:
+		| DiffKind.EventPublisherRemoved
+		| DiffKind.EventPublisherSignatureChanged
+		| DiffKind.EventPublisherAdded
+		| DiffKind.EventSubscriberInducedCapabilityGained
+		| DiffKind.EventSubscriberInducedCapabilityLost
+		| DiffKind.EventContractChangedWithAffectedSubscribers;
+	publisherObject: string;
+	eventName: string;
+	oldEventId?: string;
+	newEventId?: string;
+}
+
+export interface EventFinding {
+	id: string;
+	category: DiffCategory.Events;
+	kind: DiffKind;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	subject: {
+		normalizedStableId: string;
+		oldOriginalStableId?: string;
+		newStableId?: string;
+		displayName: string;
+	};
+	comparisonCone: readonly string[];
+	details: EventDetails;
+}
+
+const SEVERITY: Partial<Record<DiffKind, EventFinding["severity"]>> = {
+	[DiffKind.EventPublisherSignatureChanged]: "critical",
+	[DiffKind.EventPublisherRemoved]: "medium",
+	[DiffKind.EventPublisherAdded]: "info",
+	[DiffKind.EventContractChangedWithAffectedSubscribers]: "critical",
+	[DiffKind.EventSubscriberInducedCapabilityGained]: "medium",
+	[DiffKind.EventSubscriberInducedCapabilityLost]: "low",
+};
+
+/** Parse `${publisherObject}::${eventName}::${shapeHash}` → first two parts as
+ *  identity (publisher + event name). The shape hash is the part that changes
+ *  on signature drift. */
+function parseEventIdentity(eventId: string): {
+	publisherObject: string;
+	eventName: string;
+	shapeHash: string;
+} {
+	// Split on `::`; if the publisher object name contains `::` (rare), the last
+	// two segments are eventName + shapeHash and everything before is publisher.
+	const parts = eventId.split("::");
+	if (parts.length < 3) {
+		return { publisherObject: parts[0] ?? "", eventName: parts[1] ?? "", shapeHash: "" };
+	}
+	const shapeHash = parts[parts.length - 1] ?? "";
+	const eventName = parts[parts.length - 2] ?? "";
+	const publisherObject = parts.slice(0, parts.length - 2).join("::");
+	return { publisherObject, eventName, shapeHash };
+}
+
+/** Identity key for matching event publishers across snapshots: publisher +
+ *  event name, ignoring shape hash. Two declarations with the same (object,
+ *  name) but different shape are signature-changed, not remove+add. */
+function publisherIdentityKey(decl: EventDeclaration): string {
+	const parsed = parseEventIdentity(decl.eventId);
+	return `${parsed.publisherObject}::${parsed.eventName}`;
+}
+
+function makeFinding(
+	kind: EventDetails["kind"],
+	subjectId: string,
+	indexes: DiffIndexes,
+	details: EventDetails,
+	secondaryKey: string,
+): EventFinding {
+	const origin = indexes.originByNormalized.get(subjectId);
+	const display =
+		indexes.newDisplayByStableId.get(subjectId) ??
+		indexes.oldDisplayByStableId.get(subjectId) ??
+		subjectId;
+	return {
+		id: computeDiffFingerprint({
+			category: DiffCategory.Events,
+			kind,
+			normalizedStableId: subjectId,
+			secondaryKey,
+		}),
+		category: DiffCategory.Events,
+		kind,
+		severity: SEVERITY[kind] ?? "medium",
+		subject: {
+			normalizedStableId: subjectId,
+			oldOriginalStableId: origin?.oldOriginalStableId,
+			newStableId: origin?.newStableId,
+			displayName: display,
+		},
+		comparisonCone: [subjectId],
+		details,
+	};
+}
+
+export function diffEvents(
+	_oldSnap: unknown,
+	_newSnap: unknown,
+	indexes: DiffIndexes,
+	_opts: DiffEngineOptions,
+): EventFinding[] {
+	const out: EventFinding[] = [];
+
+	const oldPublishers = new Map<string, EventDeclaration>();
+	const newPublishers = new Map<string, EventDeclaration>();
+
+	for (const decls of indexes.oldEventsBySubject.values()) {
+		for (const decl of decls) {
+			if (decl.kind !== "publisher") continue;
+			oldPublishers.set(publisherIdentityKey(decl), decl);
+		}
+	}
+	for (const decls of indexes.newEventsBySubject.values()) {
+		for (const decl of decls) {
+			if (decl.kind !== "publisher") continue;
+			newPublishers.set(publisherIdentityKey(decl), decl);
+		}
+	}
+
+	for (const [key, oldDecl] of oldPublishers) {
+		const newDecl = newPublishers.get(key);
+		const parsed = parseEventIdentity(oldDecl.eventId);
+		if (newDecl === undefined) {
+			out.push(
+				makeFinding(
+					DiffKind.EventPublisherRemoved,
+					oldDecl.routine,
+					indexes,
+					{
+						kind: DiffKind.EventPublisherRemoved,
+						publisherObject: parsed.publisherObject,
+						eventName: parsed.eventName,
+						oldEventId: oldDecl.eventId,
+					},
+					parsed.eventName,
+				),
+			);
+			continue;
+		}
+		if (oldDecl.eventId !== newDecl.eventId) {
+			out.push(
+				makeFinding(
+					DiffKind.EventPublisherSignatureChanged,
+					newDecl.routine,
+					indexes,
+					{
+						kind: DiffKind.EventPublisherSignatureChanged,
+						publisherObject: parsed.publisherObject,
+						eventName: parsed.eventName,
+						oldEventId: oldDecl.eventId,
+						newEventId: newDecl.eventId,
+					},
+					parsed.eventName,
+				),
+			);
+		}
+	}
+
+	for (const [key, newDecl] of newPublishers) {
+		if (oldPublishers.has(key)) continue;
+		const parsed = parseEventIdentity(newDecl.eventId);
+		out.push(
+			makeFinding(
+				DiffKind.EventPublisherAdded,
+				newDecl.routine,
+				indexes,
+				{
+					kind: DiffKind.EventPublisherAdded,
+					publisherObject: parsed.publisherObject,
+					eventName: parsed.eventName,
+					newEventId: newDecl.eventId,
+				},
+				parsed.eventName,
+			),
+		);
+	}
+
+	// Phase 3: build per-event subscriber lookups (key = `${publisherObject}::${eventName}`)
+	const oldSubsByEvent = new Map<string, EventDeclaration[]>();
+	const newSubsByEvent = new Map<string, EventDeclaration[]>();
+	for (const decls of indexes.oldEventsBySubject.values()) {
+		for (const d of decls) {
+			if (d.kind !== "subscriber") continue;
+			const parsed = parseEventIdentity(d.eventId);
+			const k = `${parsed.publisherObject}::${parsed.eventName}`;
+			const bag = oldSubsByEvent.get(k) ?? [];
+			bag.push(d);
+			oldSubsByEvent.set(k, bag);
+		}
+	}
+	for (const decls of indexes.newEventsBySubject.values()) {
+		for (const d of decls) {
+			if (d.kind !== "subscriber") continue;
+			const parsed = parseEventIdentity(d.eventId);
+			const k = `${parsed.publisherObject}::${parsed.eventName}`;
+			const bag = newSubsByEvent.get(k) ?? [];
+			bag.push(d);
+			newSubsByEvent.set(k, bag);
+		}
+	}
+
+	// Specialization: signature-change WITH subscribers → ContractChangedWithAffectedSubscribers,
+	// suppress the generic EventPublisherSignatureChanged for the same event key.
+	const suppressSignatureKeys = new Set<string>();
+	const contractFindings: EventFinding[] = [];
+	for (const [key, oldDecl] of oldPublishers) {
+		const newDecl = newPublishers.get(key);
+		if (newDecl === undefined) continue;
+		if (oldDecl.eventId === newDecl.eventId) continue;
+		const hasSubs =
+			(oldSubsByEvent.get(key)?.length ?? 0) + (newSubsByEvent.get(key)?.length ?? 0) > 0;
+		if (!hasSubs) continue;
+		suppressSignatureKeys.add(key);
+		const parsed = parseEventIdentity(newDecl.eventId);
+		contractFindings.push(
+			makeFinding(
+				DiffKind.EventContractChangedWithAffectedSubscribers,
+				newDecl.routine,
+				indexes,
+				{
+					kind: DiffKind.EventContractChangedWithAffectedSubscribers,
+					publisherObject: parsed.publisherObject,
+					eventName: parsed.eventName,
+					oldEventId: oldDecl.eventId,
+					newEventId: newDecl.eventId,
+				},
+				parsed.eventName,
+			),
+		);
+	}
+
+	// Filter out signature findings for suppressed keys.
+	const filtered = out.filter((f) => {
+		if (f.kind !== DiffKind.EventPublisherSignatureChanged) return true;
+		const det = f.details;
+		const k = `${det.publisherObject}::${det.eventName}`;
+		return !suppressSignatureKeys.has(k);
+	});
+	out.length = 0;
+	out.push(...filtered, ...contractFindings);
+
+	// Subscriber-induced capability delta — emit gained/lost per (event, table, op).
+	const oldCapBySubject = indexes.oldCapabilityFactsBySubject;
+	const newCapBySubject = indexes.newCapabilityFactsBySubject;
+
+	function writesOf(
+		subs: EventDeclaration[] | undefined,
+		capMap: typeof oldCapBySubject,
+	): Map<string, Set<string>> {
+		// tableId → set of ops
+		const m = new Map<string, Set<string>>();
+		for (const s of subs ?? []) {
+			const facts = capMap.get(s.routine) ?? [];
+			for (const f of facts) {
+				if (f.resourceKind !== "table") continue;
+				if (!(f.op === "insert" || f.op === "modify" || f.op === "delete")) continue;
+				if (typeof f.resourceId !== "string") continue;
+				const set = m.get(f.resourceId) ?? new Set<string>();
+				set.add(f.op);
+				m.set(f.resourceId, set);
+			}
+		}
+		return m;
+	}
+
+	const matchedEventKeys = new Set([...oldSubsByEvent.keys(), ...newSubsByEvent.keys()]);
+	for (const key of matchedEventKeys) {
+		const oldWrites = writesOf(oldSubsByEvent.get(key), oldCapBySubject);
+		const newWrites = writesOf(newSubsByEvent.get(key), newCapBySubject);
+		const [publisherObject, eventName] = key.split("::", 2);
+		const subject = (newPublishers.get(key) ?? oldPublishers.get(key))?.routine;
+		if (subject === undefined) continue;
+		for (const [table, ops] of newWrites) {
+			const oldOps = oldWrites.get(table) ?? new Set();
+			for (const op of ops) {
+				if (oldOps.has(op)) continue;
+				out.push(
+					makeFinding(
+						DiffKind.EventSubscriberInducedCapabilityGained,
+						subject,
+						indexes,
+						{
+							kind: DiffKind.EventSubscriberInducedCapabilityGained,
+							publisherObject: publisherObject ?? "",
+							eventName: eventName ?? "",
+						},
+						`${eventName}|${table}|${op}`,
+					),
+				);
+			}
+		}
+		for (const [table, ops] of oldWrites) {
+			const newOps = newWrites.get(table) ?? new Set();
+			for (const op of ops) {
+				if (newOps.has(op)) continue;
+				out.push(
+					makeFinding(
+						DiffKind.EventSubscriberInducedCapabilityLost,
+						subject,
+						indexes,
+						{
+							kind: DiffKind.EventSubscriberInducedCapabilityLost,
+							publisherObject: publisherObject ?? "",
+							eventName: eventName ?? "",
+						},
+						`${eventName}|${table}|${op}`,
+					),
+				);
+			}
+		}
+	}
+
+	return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/src/diff/diff-identity.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+
+export enum DiffCategory {
+	ABI = "abi",
+	Schema = "schema",
+	Events = "events",
+	Capabilities = "capabilities",
+	Permissions = "permissions",
+}
+
+export enum DiffKind {
+	// ABI
+	ObjectRemoved = "object-removed",
+	ObjectAccessibilityNarrowed = "object-accessibility-narrowed",
+	ProcedureRemoved = "procedure-removed",
+	ProcedureSignatureChanged = "procedure-signature-changed",
+	ProcedureVarDirectionChanged = "procedure-var-direction-changed",
+	ProcedureObsoletionRegressed = "procedure-obsoletion-regressed",
+	ProcedureObsoletionProgressed = "procedure-obsoletion-progressed",
+	ObjectAdded = "object-added",
+	ProcedureAdded = "procedure-added",
+	// Schema
+	TableFieldRemoved = "table-field-removed",
+	TableFieldTypeNarrowed = "table-field-type-narrowed",
+	TableFieldTypeWidened = "table-field-type-widened",
+	TableFieldDataClassificationTightened = "table-field-data-classification-tightened",
+	TableFieldDataClassificationRelaxed = "table-field-data-classification-relaxed",
+	EnumValueRemoved = "enum-value-removed",
+	EnumValueRenumbered = "enum-value-renumbered",
+	TableFieldAdded = "table-field-added",
+	EnumValueAdded = "enum-value-added",
+	// Events
+	EventPublisherRemoved = "event-publisher-removed",
+	EventPublisherSignatureChanged = "event-publisher-signature-changed",
+	EventPublisherAdded = "event-publisher-added",
+	EventSubscriberInducedCapabilityGained = "event-subscriber-induced-capability-gained",
+	EventSubscriberInducedCapabilityLost = "event-subscriber-induced-capability-lost",
+	EventContractChangedWithAffectedSubscribers = "event-contract-changed-with-affected-subscribers",
+	// Capabilities
+	CapabilityGainedWrite = "capability-gained-write",
+	CapabilityGainedRead = "capability-gained-read",
+	CapabilityGainedCommit = "capability-gained-commit",
+	CapabilityGainedHttp = "capability-gained-http",
+	CapabilityGainedTelemetry = "capability-gained-telemetry",
+	CapabilityGainedIsolatedStorage = "capability-gained-isolated-storage",
+	CapabilityGainedFile = "capability-gained-file",
+	CapabilityGainedDynamicDispatch = "capability-gained-dynamic-dispatch",
+	CapabilityGainedEventPublish = "capability-gained-event-publish",
+	CapabilityLost = "capability-lost",
+	CapabilityLostUnderCoverage = "capability-lost-under-coverage",
+	// Permissions
+	PermissionRightsExpanded = "permission-rights-expanded",
+	PermissionRightsContracted = "permission-rights-contracted",
+	PermissionTargetAdded = "permission-target-added",
+	PermissionTargetRemoved = "permission-target-removed",
+}
+
+export interface DiffFingerprintInput {
+	category: DiffCategory;
+	kind: DiffKind;
+	normalizedStableId: string;
+	secondaryKey?: string;
+}
+
+/**
+ * SHA-256(category|kind|normalizedStableId|secondaryKey) truncated to 16 hex.
+ * Matches the al-sem analyze fingerprintOf algorithm in spirit; pipe separators
+ * avoid collision when fields contain the same characters.
+ */
+export function computeDiffFingerprint(input: DiffFingerprintInput): string {
+	const payload = `${input.category}|${input.kind}|${input.normalizedStableId}|${input.secondaryKey ?? ""}`;
+	return createHash("sha256").update(payload, "utf8").digest("hex").slice(0, 16);
+}