al-sem 0.0.1

package/src/projection/actionable-anchor.ts

@@ -0,0 +1,48 @@
+import { type Routine, roleOf } from "../model/entities.ts";
+import type { EvidenceStep, Finding } from "../model/finding.ts";
+import type { SourceAnchor } from "../model/identity.ts";
+import type { RoutineId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+
+/**
+ * Per-model routine index, memoized by model identity. `pickActionableAnchor` is called once
+ * per finding by detectors that build many findings (D1 builds hundreds); rebuilding the 100k+
+ * routine map per call dominated. The model is immutable during detection, so a WeakMap keyed
+ * on it builds the map once and reuses it; entries are GC'd with the model.
+ */
+const routinesByModel = new WeakMap<SemanticModel, Map<RoutineId, Routine>>();
+
+function routinesFor(model: SemanticModel): Map<RoutineId, Routine> {
+	let m = routinesByModel.get(model);
+	if (m === undefined) {
+		m = new Map(model.routines.map((r) => [r.id, r]));
+		routinesByModel.set(model, m);
+	}
+	return m;
+}
+
+/**
+ * Pick the first evidence step whose owning routine is in the primary app.
+ * Walk forward through `evidencePath`; returns undefined when primaryLocation
+ * is already primary (caller leaves `actionableAnchor` unset to signal "use
+ * primaryLocation as-is").
+ */
+export function pickActionableAnchor(
+	finding: Pick<Finding, "primaryLocation" | "evidencePath">,
+	model: SemanticModel,
+): SourceAnchor | undefined {
+	const routinesById = routinesFor(model);
+	const isPrimaryRoutine = (id: RoutineId): boolean => {
+		const r = routinesById.get(id);
+		return r !== undefined && roleOf(r) === "primary";
+	};
+
+	// primaryLocation.enclosingRoutineId is the terminal routine — if it's primary, no anchor needed.
+	if (isPrimaryRoutine(finding.primaryLocation.enclosingRoutineId)) return undefined;
+
+	// Walk the evidence path; return the first step that belongs to a primary routine.
+	for (const step of finding.evidencePath) {
+		if (isPrimaryRoutine((step as EvidenceStep).routineId)) return step.sourceAnchor;
+	}
+	return undefined;
+}

package/src/projection/finding-filters.ts

@@ -0,0 +1,44 @@
+import type { FindingSummary } from "./finding-summary.ts";
+
+const SEV_RANK: Record<FindingSummary["severity"], number> = {
+	critical: 5,
+	high: 4,
+	medium: 3,
+	low: 2,
+	info: 1,
+};
+
+export interface FilterOptions {
+	minSeverity?: FindingSummary["severity"];
+	detectors?: string[];
+	objectIds?: string[];
+	tableIds?: string[];
+	files?: string[]; // matches by suffix
+	limit?: number;
+}
+
+export function filterFindings(findings: FindingSummary[], opts: FilterOptions): FindingSummary[] {
+	let out = findings;
+	if (opts.minSeverity !== undefined) {
+		const min = SEV_RANK[opts.minSeverity];
+		out = out.filter((f) => SEV_RANK[f.severity] >= min);
+	}
+	if (opts.detectors && opts.detectors.length > 0) {
+		const allow = new Set(opts.detectors);
+		out = out.filter((f) => allow.has(f.detector));
+	}
+	if (opts.objectIds && opts.objectIds.length > 0) {
+		const allow = new Set(opts.objectIds);
+		out = out.filter((f) => f.affectedObjects.some((o) => allow.has(o)));
+	}
+	if (opts.tableIds && opts.tableIds.length > 0) {
+		const allow = new Set(opts.tableIds);
+		out = out.filter((f) => f.affectedTables.some((t) => allow.has(t)));
+	}
+	if (opts.files && opts.files.length > 0) {
+		const suffixes = opts.files;
+		out = out.filter((f) => suffixes.some((s) => f.primaryLocation.file.endsWith(s)));
+	}
+	if (opts.limit !== undefined) out = out.slice(0, opts.limit);
+	return out;
+}

package/src/projection/finding-fingerprint.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import type { ObjectDecl, Routine } from "../model/entities.ts";
+import type { Finding } from "../model/finding.ts";
+import type { ObjectId, RoutineId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+
+interface FingerprintIndex {
+	routinesById: Map<RoutineId, Routine>;
+	objectsById: Map<ObjectId, ObjectDecl>;
+}
+
+/**
+ * Per-model id indexes, memoized by model identity. `fingerprintOf` is called once per finding
+ * by every detector (and the policy engine) — tens of thousands of calls per run on a large
+ * workspace. Rebuilding `new Map(model.routines.map(...))` (100k+ entries) on every call was the
+ * dominant cost of the detector pass. The model is immutable during detection, so a WeakMap
+ * keyed on it builds the indexes once and reuses them; entries are GC'd with the model.
+ */
+const indexByModel = new WeakMap<SemanticModel, FingerprintIndex>();
+
+function indexFor(model: SemanticModel): FingerprintIndex {
+	let idx = indexByModel.get(model);
+	if (idx === undefined) {
+		idx = {
+			routinesById: new Map(model.routines.map((r) => [r.id, r])),
+			objectsById: new Map(model.objects.map((o) => [o.id, o])),
+		};
+		indexByModel.set(model, idx);
+	}
+	return idx;
+}
+
+/**
+ * Compute a stable edit-survival key for a finding. Designed so adding blank lines,
+ * renaming files, or rebuilding from a different workspace root yields the same key
+ * for the same logical finding. Excludes line/column numbers and any field embedding
+ * them (e.g. operationId).
+ *
+ * Components (joined with `|`, sha256, first 16 hex chars):
+ *   detector | objectType/objectNumber | routineName | affectedTables.join(",") | rootCauseKey
+ */
+export function fingerprintOf(finding: Finding, model: SemanticModel): string {
+	const { routinesById, objectsById } = indexFor(model);
+	const routine = routinesById.get(finding.primaryLocation.enclosingRoutineId);
+	const obj = routine ? objectsById.get(routine.objectId) : undefined;
+	const parts = [
+		finding.detector,
+		obj ? `${obj.objectType}/${obj.objectNumber}` : "",
+		routine?.name ?? "",
+		finding.affectedTables.join(","),
+		finding.rootCauseKey,
+	];
+	return createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 16);
+}

package/src/projection/finding-groups.ts

@@ -0,0 +1,41 @@
+import type { FindingSummary } from "./finding-summary.ts";
+
+export type GroupBy = "object" | "routine" | "table" | "detector" | "file";
+
+export interface FindingGroup {
+	key: string;
+	label?: string;
+	findings: FindingSummary[];
+}
+
+function keyFor(f: FindingSummary, by: GroupBy): string {
+	switch (by) {
+		case "object":
+			return f.primaryLocation.objectId ?? "(unknown)";
+		case "routine":
+			return f.primaryLocation.routineId ?? "(unknown)";
+		case "table":
+			return f.affectedTables[0] ?? "(none)";
+		case "detector":
+			return f.detector;
+		case "file":
+			return f.primaryLocation.file;
+	}
+}
+
+export function groupFindings(findings: FindingSummary[], by: GroupBy): FindingGroup[] {
+	const map = new Map<string, FindingSummary[]>();
+	for (const f of findings) {
+		const k = keyFor(f, by);
+		const list = map.get(k);
+		if (list) list.push(f);
+		else map.set(k, [f]);
+	}
+	const groups: FindingGroup[] = [...map.entries()].map(([key, list]) => ({
+		key,
+		findings: list,
+	}));
+	// largest first, then alphabetical for determinism
+	groups.sort((a, b) => b.findings.length - a.findings.length || (a.key < b.key ? -1 : 1));
+	return groups;
+}

package/src/projection/finding-summary.ts

@@ -0,0 +1,110 @@
+import type { ObjectDecl, Routine } from "../model/entities.ts";
+import type { Finding, FixOption } from "../model/finding.ts";
+import type { SourceAnchor } from "../model/identity.ts";
+import type { ObjectId, RoutineId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+
+export interface FindingLocation {
+	file: string; // sourceUnitId, e.g. "ws:Al/Codeunit/Foo.Codeunit.al"
+	line: number; // 1-based, for display
+	column: number; // 1-based, for display
+	objectId?: string;
+	objectName?: string;
+	routineId?: string;
+	routineName?: string;
+}
+
+export interface FindingSummary {
+	id: string;
+	fingerprint: string; // edit-survival key — Phase 4 fills in real fingerprint
+	detector: string;
+	title: string;
+	rootCause: string;
+	severity: Finding["severity"];
+	confidence: { level: Finding["confidence"]["level"]; cappedBy?: string[] };
+	primaryLocation: FindingLocation;
+	terminalLocation?: FindingLocation;
+	affectedObjects: string[];
+	affectedTables: string[];
+	fixHint?: FixOption;
+	/**
+	 * How many reaching paths the underlying Finding carries. Undefined / 1 for
+	 * the typical case (single evidencePath). > 1 means the detector (D1, D2)
+	 * collapsed multiple in-loop ancestor traces into one canonical Finding plus
+	 * additionalPaths — surfaced here so terminal/SARIF can render
+	 * "also reached from N other paths". Consumers should treat undefined as 1.
+	 */
+	pathCount?: number;
+}
+
+interface ProjectionIndex {
+	objectsById: Map<ObjectId, ObjectDecl>;
+	routinesById: Map<RoutineId, Routine>;
+}
+
+/**
+ * Per-model id indexes, memoized by model identity. `projectFinding` is called once per finding
+ * by every CLI/SARIF/MCP output path; on a large workspace with thousands of findings, rebuilding
+ * the 100k+ routine/object maps per call dominated output time. The model is immutable at
+ * projection time, so a WeakMap keyed on it builds the indexes once and reuses them.
+ */
+const indexByModel = new WeakMap<SemanticModel, ProjectionIndex>();
+
+function indexFor(model: SemanticModel): ProjectionIndex {
+	let idx = indexByModel.get(model);
+	if (idx === undefined) {
+		idx = {
+			objectsById: new Map(model.objects.map((o) => [o.id, o])),
+			routinesById: new Map(model.routines.map((r) => [r.id, r])),
+		};
+		indexByModel.set(model, idx);
+	}
+	return idx;
+}
+
+/** Project a Finding into a compact summary. Used by every CLI/SARIF/MCP output. */
+export function projectFinding(finding: Finding, model: SemanticModel): FindingSummary {
+	const { objectsById, routinesById } = indexFor(model);
+
+	const toLocation = (anchor: SourceAnchor): FindingLocation => {
+		const routine = routinesById.get(anchor.enclosingRoutineId);
+		const object = routine ? objectsById.get(routine.objectId) : undefined;
+		return {
+			file: anchor.sourceUnitId,
+			line: anchor.range.startLine + 1,
+			column: anchor.range.startColumn + 1,
+			objectId: object?.id,
+			objectName: object?.name,
+			routineId: routine?.id,
+			routineName: routine?.name,
+		};
+	};
+
+	const primary =
+		finding.actionableAnchor !== undefined
+			? toLocation(finding.actionableAnchor)
+			: toLocation(finding.primaryLocation);
+	const terminal =
+		finding.actionableAnchor !== undefined
+			? toLocation(finding.primaryLocation) // when actionable differs, keep original as terminal
+			: undefined;
+
+	return {
+		id: finding.id,
+		fingerprint: finding.fingerprint ?? finding.id, // Phase 4 fills in real fingerprint
+		detector: finding.detector,
+		title: finding.title,
+		rootCause: finding.rootCause,
+		severity: finding.severity,
+		confidence: {
+			level: finding.confidence.level,
+			cappedBy: finding.confidence.cappedBy,
+		},
+		primaryLocation: primary,
+		terminalLocation: terminal,
+		affectedObjects: finding.affectedObjects,
+		affectedTables: finding.affectedTables,
+		fixHint: finding.fixOptions[0],
+		pathCount: 1 + (finding.additionalPaths?.length ?? 0),
+	};
+}

package/src/projection/rollup-findings.ts

@@ -0,0 +1,105 @@
+import { compareStrings } from "../engine/uncertainty-util.ts";
+import type { FindingLocation, FindingSummary } from "./finding-summary.ts";
+
+/**
+ * Inter-detector rollup. Multiple detectors firing at the same source location
+ * on the same affected tables usually mean ONE underlying problem viewed from
+ * different angles — e.g. D1 (db-op-in-loop) + D5 (set-based opportunity) +
+ * D10 (self-modifying loop) all fire on a single `repeat … Modify … until
+ * Next() = 0`. The user fixes one thing and all three findings disappear.
+ *
+ * Grouping is purely presentational. Each contributing Finding stays
+ * untouched in the underlying model — baselines, SARIF, and MCP
+ * `list_findings` still see per-detector identity. The rollup is what a
+ * human (or LLM tool) reads when they want the consolidated view.
+ *
+ * Group key: `(file, line, column, sortedAffectedTables.join(","))`.
+ *   - Strict enough that two findings on the same line but DIFFERENT
+ *     tables stay separate (e.g. two record-modifying loops side-by-side).
+ *   - Loose enough to catch the D1+D5+D10 case where the file/line/column
+ *     match exactly and affectedTables share the modified table.
+ *
+ * A group with exactly one contributor is returned as `kind: "single"`.
+ * Two or more share a `kind: "rolled"` entry with `contributors` sorted by
+ * severity descending (ties broken by detector id ascending so terminal
+ * output stays deterministic).
+ */
+const SEV_RANK = { critical: 5, high: 4, medium: 3, low: 2, info: 1 } as const;
+type Severity = keyof typeof SEV_RANK;
+
+export type RolledOrSingle =
+	| { kind: "single"; finding: FindingSummary }
+	| {
+			kind: "rolled";
+			primaryLocation: FindingLocation;
+			affectedTables: string[];
+			/** Max severity across contributors — drives sort order in output. */
+			severity: Severity;
+			/** Sorted: highest-severity first, then by detector id ascending for determinism. */
+			contributors: FindingSummary[];
+	  };
+
+/** Build the grouping key. Defined as a constant so callers reading the
+ * code understand what counts as "the same problem". */
+function rollupKey(f: FindingSummary): string {
+	const p = f.primaryLocation;
+	const tables = [...f.affectedTables].sort().join(",");
+	return `${p.file}|${p.line}|${p.column}|${tables}`;
+}
+
+/**
+ * Group findings by `(file, line, column, sorted-tables)`. Returns the
+ * groups in MAX-SEVERITY-DESCENDING order with detector-id ascending as the
+ * tiebreaker, so callers can render them top-to-bottom without re-sorting.
+ *
+ * Singleton groups pass through as `{ kind: "single", finding }`. The output
+ * length is the number of distinct rollup keys present — typically less
+ * than the input length when inter-detector overlap exists.
+ */
+export function rollupFindings(findings: FindingSummary[]): RolledOrSingle[] {
+	const groups = new Map<string, FindingSummary[]>();
+	for (const f of findings) {
+		const k = rollupKey(f);
+		const list = groups.get(k);
+		if (list === undefined) groups.set(k, [f]);
+		else list.push(f);
+	}
+	const out: RolledOrSingle[] = [];
+	for (const list of groups.values()) {
+		if (list.length === 0) continue;
+		const first = list[0];
+		if (first === undefined) continue; // type-narrowing
+		if (list.length === 1) {
+			out.push({ kind: "single", finding: first });
+			continue;
+		}
+		// Multi-contributor rollup. Sort contributors deterministically.
+		const sorted = [...list].sort((a, b) => {
+			const r = SEV_RANK[b.severity] - SEV_RANK[a.severity];
+			if (r !== 0) return r;
+			return compareStrings(a.detector, b.detector);
+		});
+		const canonical = sorted[0];
+		if (canonical === undefined) continue;
+		out.push({
+			kind: "rolled",
+			primaryLocation: canonical.primaryLocation,
+			affectedTables: canonical.affectedTables,
+			severity: canonical.severity,
+			contributors: sorted,
+		});
+	}
+	// Order rollups + singles together: max severity first, then file/line for stability.
+	out.sort((a, b) => {
+		const sevA = a.kind === "rolled" ? a.severity : a.finding.severity;
+		const sevB = b.kind === "rolled" ? b.severity : b.finding.severity;
+		const r = SEV_RANK[sevB] - SEV_RANK[sevA];
+		if (r !== 0) return r;
+		const locA = a.kind === "rolled" ? a.primaryLocation : a.finding.primaryLocation;
+		const locB = b.kind === "rolled" ? b.primaryLocation : b.finding.primaryLocation;
+		if (locA.file !== locB.file) return compareStrings(locA.file, locB.file);
+		if (locA.line !== locB.line) return locA.line - locB.line;
+		return locA.column - locB.column;
+	});
+	return out;
+}

package/src/providers/discover.ts

@@ -0,0 +1,88 @@
+import { sha256Hex, sha256OfStrings } from "../hash.ts";
+import type { AppIdentity, ModelIdentity } from "../model/identity.ts";
+import type { ExternalSourceProvider } from "./external.ts";
+import type { ProviderDiagnostic, SourceUnit } from "./types.ts";
+import { WorkspaceProvider } from "./workspace.ts";
+
+/** al-sem schema/version constants. Bump SCHEMA_VERSION when the serialized model changes. */
+export const SCHEMA_VERSION = "1";
+export const ANALYZER_VERSION = "0.0.1";
+export const GRAMMAR_VERSION = "tree-sitter-al-v2.5.2-native";
+export const SYMBOL_READER_VERSION = "1";
+
+export interface DiscoverOptions {
+	workspaceRoot: string;
+	alpackagesDir?: string;
+	externalProvider?: ExternalSourceProvider;
+}
+
+export interface DiscoverResult {
+	units: SourceUnit[];
+	identity: ModelIdentity;
+	modelInstanceId: string;
+	diagnostics: ProviderDiagnostic[];
+}
+
+/** Merge AppIdentity records by appGuid; first occurrence wins for source-bearing fields. */
+function mergeApps(lists: AppIdentity[][]): AppIdentity[] {
+	const byGuid = new Map<string, AppIdentity>();
+	for (const list of lists) {
+		for (const app of list) {
+			if (!byGuid.has(app.appGuid)) byGuid.set(app.appGuid, app);
+		}
+	}
+	return [...byGuid.values()];
+}
+
+/**
+ * Run all source providers, merge results, and build the ModelIdentity. The
+ * modelInstanceId is derived from the discovered apps + unit ids so it is stable for
+ * identical inputs and changes when inputs change.
+ *
+ * Precondition: callers must pass an already-normalized absolute `workspaceRoot` —
+ * `workspace.rootHash` hashes the raw path, so non-canonical paths (trailing slash,
+ * symlink) would produce a different hash. (Task 19's `analyzeWorkspace` normalizes
+ * before calling.)
+ */
+export async function discoverSources(options: DiscoverOptions): Promise<DiscoverResult> {
+	const { workspaceRoot, externalProvider } = options;
+	const diagnostics: ProviderDiagnostic[] = [];
+
+	const wsResult = await new WorkspaceProvider().collect(workspaceRoot);
+	diagnostics.push(...wsResult.diagnostics);
+
+	const extResult = externalProvider
+		? await externalProvider.collect(workspaceRoot)
+		: { units: [], apps: [], diagnostics: [] };
+	diagnostics.push(...extResult.diagnostics);
+
+	const units = [...wsResult.units, ...extResult.units];
+	const apps = mergeApps([wsResult.apps, extResult.apps]);
+
+	// Workspace app is the primary app.
+	// undefined when WorkspaceProvider could not read app.json — a diagnostic was already pushed
+	const primaryApp = wsResult.apps[0];
+
+	const dependencyGraphHash = sha256OfStrings(apps.map((a) => `${a.appGuid}@${a.version}`).sort());
+
+	const modelInstanceId = sha256OfStrings([
+		dependencyGraphHash,
+		...units.map((u) => u.id).sort(),
+	]).slice(0, 16);
+
+	const identity: ModelIdentity = {
+		schemaVersion: SCHEMA_VERSION,
+		analyzerVersion: ANALYZER_VERSION,
+		grammarVersion: GRAMMAR_VERSION,
+		symbolReaderVersion: SYMBOL_READER_VERSION,
+		createdAt: new Date(0).toISOString(), // fixed for determinism; callers may override
+		workspace: {
+			rootHash: sha256Hex(workspaceRoot),
+		},
+		primaryApp,
+		apps,
+		dependencyGraphHash,
+	};
+
+	return { units, identity, modelInstanceId, diagnostics };
+}

package/src/providers/external.ts

@@ -0,0 +1,46 @@
+import type { AppIdentity } from "../model/identity.ts";
+import type { ProviderResult, SourceProvider, SourceUnit } from "./types.ts";
+
+export interface ExternalSourceInjection {
+	appGuid: string;
+	publisher?: string;
+	name?: string;
+	version?: string;
+	/** Relative path -> .al content. */
+	files: Record<string, string>;
+}
+
+/**
+ * Seam for external AL source (e.g. Microsoft base-app source from a downloaded history
+ * repo). Phase 1 is a stub: no downloader is built. Source can be injected directly,
+ * which is how a future downloader — or a test — feeds it in without changing callers.
+ */
+export class ExternalSourceProvider implements SourceProvider {
+	readonly name = "external-source" as const;
+
+	constructor(private readonly injection?: ExternalSourceInjection) {}
+
+	async collect(_rootPath: string): Promise<ProviderResult> {
+		if (!this.injection) {
+			return { units: [], apps: [], diagnostics: [] };
+		}
+
+		const { appGuid, publisher, name, version, files } = this.injection;
+		const units: SourceUnit[] = Object.entries(files).map(([relativePath, content]) => ({
+			id: `ext:${appGuid}:${relativePath}`,
+			kind: "source",
+			appGuid,
+			relativePath,
+			content,
+			sourceProvider: "external-source",
+		}));
+		const identity: AppIdentity = {
+			appGuid,
+			publisher: publisher ?? "unknown",
+			name: name ?? "unknown",
+			version: version ?? "0.0.0.0",
+			sourceKind: "external-source",
+		};
+		return { units, apps: [identity], diagnostics: [] };
+	}
+}

package/src/providers/types.ts

@@ -0,0 +1,36 @@
+import type { AppIdentity } from "../model/identity.ts";
+
+/**
+ * One unit of AL input. `kind: "source"` carries `.al` text to parse and index.
+ * `kind: "symbol-only"` marks a dependency whose bodies are opaque (no source available).
+ */
+export interface SourceUnit {
+	id: string; // stable per analysis run, e.g. "ws:<relpath>" or "app:<guid>:<relpath>"
+	kind: "source" | "symbol-only";
+	appGuid: string;
+	relativePath: string;
+	absolutePath?: string; // present for workspace files
+	content?: string; // present when kind === "source"
+	sourceProvider: "workspace" | "app-package" | "external-source";
+	/** "primary" (workspace, under analysis) or "dependency" (context only). Absent ⇒ primary. */
+	analysisRole?: "primary" | "dependency";
+}
+
+export interface ProviderResult {
+	units: SourceUnit[];
+	apps: AppIdentity[];
+	diagnostics: ProviderDiagnostic[];
+}
+
+export interface ProviderDiagnostic {
+	severity: "error" | "warning" | "info";
+	message: string;
+	sourceRef?: string;
+}
+
+/** A source of AL input. Each implementation knows one origin of AL. */
+export interface SourceProvider {
+	readonly name: "workspace" | "app-package" | "external-source";
+	/** Enumerate all source units this provider can offer for the given root. */
+	collect(rootPath: string): Promise<ProviderResult>;
+}