al-sem 0.0.1

package/src/engine/uncertainty-util.ts

@@ -0,0 +1,54 @@
+import type { Uncertainty } from "../model/summary.ts";
+
+/** Stable string key for an Uncertainty — kind plus whichever id field it carries. */
+export function uncertaintyKey(u: Uncertainty): string {
+	if ("callsiteId" in u) return `${u.kind}|${u.callsiteId}`;
+	if ("operationId" in u) return `${u.kind}|${u.operationId}`;
+	return `${u.kind}|${u.routineId}`;
+}
+
+/**
+ * De-duplicate a list of Uncertainty values by key (keep first seen), then sort by key.
+ * The sort uses `compareStrings` for locale-independent, byte-stable ordering.
+ */
+export function dedupeUncertainties(list: Uncertainty[]): Uncertainty[] {
+	const byKey = new Map<string, Uncertainty>();
+	for (const u of list) byKey.set(uncertaintyKey(u), u);
+	return [...byKey.values()].sort((a, b) => compareStrings(uncertaintyKey(a), uncertaintyKey(b)));
+}
+
+/**
+ * Locale-independent string comparator. Returns -1 / 0 / 1 based on JS byte order,
+ * ensuring deterministic sort output across all environments regardless of locale settings.
+ */
+export function compareStrings(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Compare two strings naturally: split each into runs of letters and digits, compare
+ * digit runs numerically and letter runs lexicographically. Stable for equal prefixes.
+ * Used for detector ids ("d2" < "d10") and other dN-style keys.
+ */
+export function compareNatural(a: string, b: string): number {
+	const re = /(\d+)|(\D+)/g;
+	const pa = a.match(re) ?? [];
+	const pb = b.match(re) ?? [];
+	const len = Math.min(pa.length, pb.length);
+	for (let i = 0; i < len; i++) {
+		const ta = pa[i] as string;
+		const tb = pb[i] as string;
+		const aIsNum = /^\d/.test(ta);
+		const bIsNum = /^\d/.test(tb);
+		if (aIsNum && bIsNum) {
+			const na = Number.parseInt(ta, 10);
+			const nb = Number.parseInt(tb, 10);
+			if (na !== nb) return na < nb ? -1 : 1;
+		} else if (aIsNum !== bIsNum) {
+			return aIsNum ? -1 : 1;
+		} else {
+			if (ta !== tb) return ta < tb ? -1 : 1;
+		}
+	}
+	return pa.length - pb.length;
+}

package/src/hash.ts

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+
+/** SHA-256 hex digest of a string. */
+export function sha256Hex(input: string): string {
+	return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+/**
+ * SHA-256 hex digest of a raw byte slice. Equivalent to `sha256Hex(utf8-decode(bytes))`
+ * when `bytes` is valid UTF-8 (Node's createHash treats strings as UTF-8). Skips the
+ * intermediate JS string allocation for callers that already hold a byte buffer (e.g.
+ * tree-sitter Node text via `tree.sourceBytes.subarray(start, end)`).
+ */
+export function sha256HexBytes(bytes: Uint8Array): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * SHA-256 hex digest of an ordered list of strings.
+ * Uses a length-prefixed encoding so concatenation is unambiguous:
+ * ["ab","c"] and ["a","bc"] produce different digests.
+ */
+export function sha256OfStrings(parts: string[]): string {
+	const h = createHash("sha256");
+	for (const part of parts) {
+		h.update(String(part.length));
+		h.update(":");
+		h.update(part, "utf8");
+	}
+	return h.digest("hex");
+}

package/src/index/attribute-from-node.ts

@@ -0,0 +1,141 @@
+// src/index/attribute-from-node.ts
+// Build a structured `AttributeInfo` from a tree-sitter `attribute_item` node.
+//
+// Grammar shape (tree-sitter-al):
+//   attribute_item
+//     '['
+//     attribute_content
+//       name: identifier
+//       arguments?: attribute_arguments
+//         '('
+//         attribute_argument_list?
+//           <_attribute_argument>, ...
+//         ')'
+//     ']'
+//
+// `_attribute_argument` is a closed choice — boolean / integer / string_literal /
+// identifier / quoted_identifier / qualified_enum_value / database_reference /
+// member_expression — all surfaced as typed nodes. We map each into a typed
+// `AttributeArg`; consumers query through `findAttribute` / `stringArg` /
+// `qualifiedArg` helpers instead of switching on positional indices.
+
+import type { AttributeArg, AttributeArgKind, AttributeInfo } from "../model/attributes.ts";
+import type { Node as SyntaxNode } from "../parser/native/wrapper.ts";
+
+/** Strip surrounding single or double quotes from a string_literal / quoted_identifier. */
+function stripQuoteChars(text: string): string {
+	if (text.length < 2) return text;
+	const first = text[0];
+	const last = text[text.length - 1];
+	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+		return text.slice(1, -1);
+	}
+	return text;
+}
+
+/** Classify a grammar node type into the AttributeArgKind enum. */
+function kindOf(nodeType: string): AttributeArgKind {
+	switch (nodeType) {
+		case "boolean":
+		case "integer":
+		case "string_literal":
+		case "identifier":
+		case "quoted_identifier":
+		case "qualified_enum_value":
+		case "database_reference":
+		case "member_expression":
+			return nodeType;
+		default:
+			return "unknown";
+	}
+}
+
+/**
+ * Pull the unquoted/derived `value` and optional `qualifier`/`member` out of an arg node.
+ * Tree-sitter exposes the structurally-relevant pieces as field children
+ * (`enum_type`/`value` for `qualified_enum_value`, `keyword`/`table_name` for
+ * `database_reference`), so we read those directly — no further text shredding.
+ */
+function deriveValueParts(
+	node: SyntaxNode,
+	kind: AttributeArgKind,
+	text: string,
+): { value?: string; qualifier?: string; member?: string } {
+	switch (kind) {
+		case "boolean":
+		case "integer":
+		case "identifier":
+			return { value: text };
+		case "string_literal":
+		case "quoted_identifier":
+			return { value: stripQuoteChars(text) };
+		case "qualified_enum_value": {
+			const qualifier = node.childForFieldName("enum_type")?.text;
+			const memberRaw = node.childForFieldName("value")?.text;
+			const member = memberRaw !== undefined ? stripQuoteChars(memberRaw) : undefined;
+			return {
+				value: member,
+				...(qualifier !== undefined ? { qualifier } : {}),
+				...(member !== undefined ? { member } : {}),
+			};
+		}
+		case "database_reference": {
+			const qualifier = node.childForFieldName("keyword")?.text;
+			const memberRaw = node.childForFieldName("table_name")?.text;
+			const member = memberRaw !== undefined ? stripQuoteChars(memberRaw) : undefined;
+			return {
+				value: member,
+				...(qualifier !== undefined ? { qualifier } : {}),
+				...(member !== undefined ? { member } : {}),
+			};
+		}
+		case "member_expression":
+		case "unknown":
+			return {};
+	}
+}
+
+/** Build an `AttributeArg` from a single argument node inside `attribute_argument_list`. */
+function argFromNode(node: SyntaxNode): AttributeArg {
+	const kind = kindOf(node.type);
+	const text = node.text;
+	const parts = deriveValueParts(node, kind, text);
+	return {
+		kind,
+		text,
+		...(parts.value !== undefined ? { value: parts.value } : {}),
+		...(parts.qualifier !== undefined ? { qualifier: parts.qualifier } : {}),
+		...(parts.member !== undefined ? { member: parts.member } : {}),
+	};
+}
+
+/**
+ * Build an `AttributeInfo` from an `attribute_item` (or `var_attribute_item`) node.
+ *
+ * Returns null only when the grammar shape is unrecognizable — a parse error
+ * inside the attribute. In that case callers should fall back to the raw text
+ * (kept on `Routine.attributes`) for diagnostics; semantic consumers will see
+ * the routine as if the attribute were absent, matching prior regex-miss behavior.
+ */
+export function attributeInfoFromNode(item: SyntaxNode): AttributeInfo | null {
+	const content = item.childForFieldName("attribute");
+	if (content === null) return null;
+	const nameNode = content.childForFieldName("name");
+	const name = nameNode?.text ?? "";
+	if (name === "") return null;
+
+	const args: AttributeArg[] = [];
+	const argsNode = content.childForFieldName("arguments");
+	if (argsNode !== null) {
+		// `attribute_arguments` wraps `(` `attribute_argument_list?` `)`. The list
+		// node is the single named child; its named children are the args.
+		const list = argsNode.namedChildren.find((c) => c?.type === "attribute_argument_list");
+		if (list) {
+			for (const child of list.namedChildren) {
+				if (child !== null) args.push(argFromNode(child));
+			}
+		}
+	}
+
+	return { name, args, raw: item.text };
+}

package/src/index/callee-from-node.ts

@@ -0,0 +1,181 @@
+// src/index/callee-from-node.ts
+// Build a structured `Callee` from a tree-sitter `call_expression` node.
+//
+// Grammar shape (tree-sitter-al ≥ v2.5.2):
+//   call_expression
+//     function: identifier              → bare procedure call
+//             | member_expression       → method call OR object-run dispatch
+//                 object:  identifier / keyword_identifier / member_expression / ...
+//                 member:  identifier (`Run` for object-run; method name otherwise)
+//     argument_list
+//       <args>...
+//
+// Object-run dispatch (`Codeunit.Run(...)` / `Page.Run(...)` / `Report.Run(...)`)
+// is unambiguous in the grammar because the object position is a
+// `keyword_identifier` (wrapping `codeunit_keyword` / `page_keyword` /
+// `report_keyword`) — distinct from a plain `identifier` like `Sales` in
+// `Sales.Run()`. The first argument's shape — `database_reference` with a
+// `table_name` of kind `quoted_identifier` (quoted name), `identifier`
+// (unquoted name), or `integer` (numeric id) — pins down the target.
+//
+// No regex anywhere — every distinction comes from `node.type` / field children.
+
+import type { Callee, ObjectRunKind } from "../model/callee.ts";
+import type { Node as SyntaxNode } from "../parser/native/wrapper.ts";
+
+/** Strip a single layer of surrounding double/single quotes. */
+function stripQuoteChars(text: string): string {
+	if (text.length < 2) return text;
+	const first = text[0];
+	const last = text[text.length - 1];
+	if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+		return text.slice(1, -1);
+	}
+	return text;
+}
+
+/**
+ * True when `objNode` is a `keyword_identifier` whose inner keyword node is
+ * one of `codeunit_keyword` / `page_keyword` / `report_keyword`. Returns the
+ * properly-cased object-kind label, or null if not an object-run prefix.
+ *
+ * Grammar fact: object-run prefixes use `keyword_identifier` (an alias around
+ * the bare keyword tokens), while a variable named `Sales` uses plain
+ * `identifier`. The two are syntactically distinct, so this check cannot
+ * misclassify a regular variable as a `.Run` dispatch.
+ */
+function objectRunKindOfReceiver(objNode: SyntaxNode): ObjectRunKind | null {
+	if (objNode.type !== "keyword_identifier") return null;
+	for (const child of objNode.namedChildren) {
+		if (child === null) continue;
+		switch (child.type) {
+			case "codeunit_keyword":
+				return "Codeunit";
+			case "page_keyword":
+				return "Page";
+			case "report_keyword":
+				return "Report";
+		}
+	}
+	return null;
+}
+
+/**
+ * Classify the first argument of a `.Run(...)` call into the object-run target
+ * fields. The grammar surfaces three node kinds inside `database_reference`'s
+ * `table_name` field:
+ *   - `quoted_identifier` → quoted name (e.g. `Codeunit::"Sales-Post"`)
+ *   - `identifier`        → unquoted name (e.g. `Codeunit::SalesPost`)
+ *   - `integer`           → numeric id (e.g. `Codeunit::80`)
+ *
+ * Anything else — a variable, a function call, an arithmetic expression —
+ * leaves the target dynamic (`targetRef: undefined`).
+ */
+function classifyObjectRunFirstArg(
+	firstArg: SyntaxNode | undefined,
+	objectKind: ObjectRunKind,
+): { targetType: ObjectRunKind; targetRef?: string; targetIsName: boolean } {
+	if (firstArg === undefined || firstArg.type !== "database_reference") {
+		return { targetType: objectKind, targetRef: undefined, targetIsName: false };
+	}
+	const tableNameNode = firstArg.childForFieldName("table_name");
+	if (tableNameNode === null) {
+		return { targetType: objectKind, targetRef: undefined, targetIsName: false };
+	}
+	const text = tableNameNode.text;
+	switch (tableNameNode.type) {
+		case "integer":
+			return { targetType: objectKind, targetRef: text, targetIsName: false };
+		case "quoted_identifier":
+			return { targetType: objectKind, targetRef: stripQuoteChars(text), targetIsName: true };
+		default:
+			// identifier / quoted-identifier-like contextual-keyword forms — unquoted name.
+			return { targetType: objectKind, targetRef: text, targetIsName: true };
+	}
+}
+
+/**
+ * Find the first positional argument of a `call_expression`. The
+ * `argument_list` is a named child whose own named children are the args.
+ * Returns undefined for an empty argument list (`Foo()`).
+ */
+function firstArgumentNode(callNode: SyntaxNode): SyntaxNode | undefined {
+	const argList = callNode.namedChildren.find((c) => c !== null && c.type === "argument_list");
+	if (argList === undefined || argList === null) return undefined;
+	for (const child of argList.namedChildren) {
+		if (child !== null) return child;
+	}
+	return undefined;
+}
+
+/**
+ * Build the `member`-shaped Callee for a `member_expression` (object + member),
+ * with the object-run dispatch upgrade when the receiver is a keyword. `callNode`
+ * is the enclosing `call_expression` when one exists — used to inspect the first
+ * argument for object-run targeting. When invoked on a parameterless method-call
+ * statement (`Customer.SetRecFilter;`, no surrounding `call_expression`), pass
+ * the `member_expression` itself as `callNode` and the target stays dynamic.
+ */
+function calleeFromMemberExpression(memberExpr: SyntaxNode, callNode: SyntaxNode | null): Callee {
+	const objNode = memberExpr.childForFieldName("object") ?? memberExpr.namedChildren[0] ?? null;
+	const memberNode = memberExpr.childForFieldName("member") ?? memberExpr.namedChildren[1] ?? null;
+	if (objNode === null || memberNode === null) return { kind: "unknown" };
+
+	const memberLc = memberNode.text.toLowerCase();
+	const objectKind = objectRunKindOfReceiver(objNode);
+	if (objectKind !== null && memberLc === "run") {
+		const firstArg = callNode !== null ? firstArgumentNode(callNode) : undefined;
+		const parts = classifyObjectRunFirstArg(firstArg, objectKind);
+		return {
+			kind: "object-run",
+			objectKind,
+			targetType: parts.targetType,
+			...(parts.targetRef !== undefined ? { targetRef: parts.targetRef } : {}),
+			targetIsName: parts.targetIsName,
+		};
+	}
+
+	return {
+		kind: "member",
+		receiver: objNode.text,
+		method: stripQuoteChars(memberNode.text),
+	};
+}
+
+/**
+ * Classify a call expression or bare-method-call shape into a structured `Callee`.
+ *
+ * Accepts either:
+ *  - a `call_expression` node (the common case — `Foo(a, b)`, `Sales.Post(x)`,
+ *    `Codeunit.Run(Codeunit::80)`); or
+ *  - a `member_expression` node in statement position (`Customer.SetRecFilter;`
+ *    — parameterless method call written without parens).
+ *
+ * Returns `{ kind: "unknown" }` for malformed shapes — mirrors the prior regex
+ * behavior of falling through to unknown rather than throwing.
+ */
+export function calleeFromNode(node: SyntaxNode): Callee {
+	if (node.type === "member_expression") {
+		return calleeFromMemberExpression(node, null);
+	}
+
+	if (node.type !== "call_expression") return { kind: "unknown" };
+
+	const funcNode = node.childForFieldName("function") ?? node.namedChildren[0] ?? null;
+	if (funcNode === null) return { kind: "unknown" };
+
+	if (funcNode.type === "identifier") {
+		return { kind: "bare", name: stripQuoteChars(funcNode.text) };
+	}
+
+	// `quoted_identifier` callee (rare — `"My Routine"`(...)) — still a bare call.
+	if (funcNode.type === "quoted_identifier") {
+		return { kind: "bare", name: stripQuoteChars(funcNode.text) };
+	}
+
+	if (funcNode.type === "member_expression") {
+		return calleeFromMemberExpression(funcNode, node);
+	}
+
+	return { kind: "unknown" };
+}

package/src/index/capability/background.ts

@@ -0,0 +1,90 @@
+import type { CapabilityConfidence, CapabilityFact, ValueSource } from "../../model/capability.ts";
+import type { CoverageReason } from "../../model/coverage.ts";
+import type { ExtractionContext } from "./extractor.ts";
+import { classifyValueSource } from "./value-source.ts";
+
+/**
+ * Phase 0b-β background family extractor. Detects background-job kickoff calls:
+ *   - `TaskScheduler.CreateTask(CodeunitId, ...)` — member callee, receiver = "TaskScheduler"
+ *   - `Session.StartSession(out NewSessionID, CodeunitId, ...)` — member callee, receiver = "Session"
+ *   - `StartSession(out NewSessionID, CodeunitId, ...)` — bare callee
+ *
+ * Emits one CapabilityFact per match:
+ *   op: "start", resourceKind: "background"
+ *   resourceArgSource: classifyValueSource on the codeunit-id argument
+ *     - arg[0] for TaskScheduler.CreateTask
+ *     - arg[1] for Session.StartSession / bare StartSession (arg[0] is the OUT session-id var)
+ *   confidence derived from codeunit-id ValueSource kind
+ *   provenance: "direct", via: "self", witnessCallsiteId: cs.id
+ *
+ * No BackgroundExtra is defined — `extra` is omitted.
+ *
+ * Never throws.
+ */
+export function extractBackground(ctx: ExtractionContext): {
+	facts: CapabilityFact[];
+	reasons: CoverageReason[];
+} {
+	try {
+		const facts: CapabilityFact[] = [];
+		for (const cs of ctx.routine?.features?.callSites ?? []) {
+			const callee = cs.callee;
+			if (!callee) continue;
+
+			let codeunitArgIdx: number | undefined;
+
+			if (callee.kind === "member") {
+				const receiverLc = callee.receiver.toLowerCase();
+				const methodLc = callee.method.toLowerCase();
+				if (receiverLc === "taskscheduler" && methodLc === "createtask") {
+					codeunitArgIdx = 0;
+				} else if (receiverLc === "session" && methodLc === "startsession") {
+					codeunitArgIdx = 1;
+				}
+			} else if (callee.kind === "bare") {
+				if (typeof callee.name === "string" && callee.name.toLowerCase() === "startsession") {
+					codeunitArgIdx = 1;
+				}
+			}
+
+			if (codeunitArgIdx === undefined) continue;
+
+			const codeunitArgInfo = cs.argumentInfos?.[codeunitArgIdx];
+			const codeunitArgSource: ValueSource =
+				codeunitArgInfo !== undefined
+					? classifyValueSource(codeunitArgInfo, ctx)
+					: { kind: "unknown" };
+
+			facts.push({
+				subject: ctx.routine.id,
+				op: "start",
+				resourceKind: "background",
+				resourceArgSource: codeunitArgSource,
+				confidence: confidenceFromSource(codeunitArgSource),
+				provenance: "direct",
+				via: "self",
+				witnessCallsiteId: cs.id,
+			});
+		}
+		return { facts, reasons: [] };
+	} catch {
+		return { facts: [], reasons: ["extraction-failed"] };
+	}
+}
+
+function confidenceFromSource(vs: ValueSource): CapabilityConfidence {
+	switch (vs.kind) {
+		case "literal":
+		case "enum":
+			return "static";
+		case "constant-var":
+			return confidenceFromSource(vs.initializer);
+		case "parameter":
+			return "userDynamic";
+		case "table-field":
+			return "configDynamic";
+		case "expression":
+		case "unknown":
+			return "unresolved";
+	}
+}

package/src/index/capability/commit.ts

@@ -0,0 +1,44 @@
+import type { CapabilityFact } from "../../model/capability.ts";
+import type { CoverageReason } from "../../model/coverage.ts";
+import type { ExtractionContext } from "./extractor.ts";
+
+/**
+ * Phase 0b-β commit family extractor. Emits one CapabilityFact per Commit
+ * statement / call in the routine body.
+ *
+ * Detection: iterates ctx.routine.features.operationSites looking for
+ * kind === "commit". AL's `Commit;` and `Commit()` both produce an
+ * OperationSite with kind "commit" at L2 index time (confirmed by probe).
+ * They do NOT appear in callSites.
+ *
+ * The witness is witnessOperationId (the OperationSite.id), not
+ * witnessCallsiteId, because commit is classified as an operation rather
+ * than a general call.
+ *
+ * Never throws.
+ */
+export function extractCommit(ctx: ExtractionContext): {
+	facts: CapabilityFact[];
+	reasons: CoverageReason[];
+} {
+	try {
+		const facts: CapabilityFact[] = [];
+		const operationSites = ctx.routine?.features?.operationSites ?? [];
+		for (const op of operationSites) {
+			if (op.kind === "commit") {
+				facts.push({
+					subject: ctx.routine.id,
+					op: "commit",
+					resourceKind: "transaction",
+					confidence: "static",
+					provenance: "direct",
+					via: "self",
+					witnessOperationId: op.id,
+				});
+			}
+		}
+		return { facts, reasons: [] };
+	} catch {
+		return { facts: [], reasons: ["extraction-failed"] };
+	}
+}