al-sem 0.0.1

package/src/symbols/symbol-reader.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import { type Unzipped, unzipSync } from "fflate";
+import { sha256Hex } from "../hash.ts";
+import type { AppIdentity } from "../model/identity.ts";
+
+export interface SymbolPackage {
+	identity: AppIdentity;
+	hasEmbeddedSource: boolean;
+	/** Relative paths of embedded .al files (empty when symbol-only). */
+	embeddedSourceFiles: string[];
+	/** Raw SymbolReference.json text — parsed in Phase 2 by the resolver. */
+	symbolReferenceJson: string | null;
+	/** Decoded embedded .al file contents, keyed by relative path. */
+	embeddedSource: Record<string, string>;
+}
+
+/** BC .app files may carry a binary header before the ZIP. The ZIP starts at PK\x03\x04. */
+function stripAppHeader(bytes: Uint8Array): Uint8Array {
+	// Find the ZIP local-file-header magic: 0x50 0x4B 0x03 0x04
+	const limit = Math.min(bytes.length - 4, 4096);
+	for (let i = 0; i < limit; i++) {
+		if (
+			bytes[i] === 0x50 &&
+			bytes[i + 1] === 0x4b &&
+			bytes[i + 2] === 0x03 &&
+			bytes[i + 3] === 0x04
+		) {
+			return i === 0 ? bytes : bytes.subarray(i);
+		}
+	}
+	return bytes; // assume it is already a plain ZIP
+}
+
+/** Read attribute value from a single XML tag, tolerant of attribute order. */
+function readXmlAttr(xml: string, tag: string, attr: string): string {
+	const tagMatch = xml.match(new RegExp(`<${tag}\\b[^>]*>`, "i"));
+	if (!tagMatch) return "";
+	const attrMatch = tagMatch[0].match(new RegExp(`${attr}\\s*=\\s*"([^"]*)"`, "i"));
+	return attrMatch?.[1] ?? "";
+}
+
+const textDecoder = new TextDecoder("utf-8");
+
+/** Read a .app symbol package: app identity, embedded-source flag, raw symbol JSON. */
+export async function readSymbolPackage(appPath: string): Promise<SymbolPackage> {
+	const raw = new Uint8Array(readFileSync(appPath));
+	const packageHash = sha256Hex(Buffer.from(raw).toString("base64"));
+	const zipBytes = stripAppHeader(raw);
+
+	let entries: Unzipped;
+	try {
+		entries = unzipSync(zipBytes);
+	} catch (err) {
+		throw new Error(`Failed to unzip .app at ${appPath}: ${(err as Error).message}`);
+	}
+
+	// Entry keys may use either path separator; normalize to forward slashes.
+	const norm = (k: string) => k.replace(/\\/g, "/");
+	const byName = new Map<string, Uint8Array>();
+	for (const [k, v] of Object.entries(entries)) {
+		byName.set(norm(k).toLowerCase(), v);
+	}
+
+	const manifestBytes = byName.get("navxmanifest.xml") ?? byName.get("./navxmanifest.xml");
+	const manifestXml = manifestBytes ? textDecoder.decode(manifestBytes) : "";
+
+	const appGuid = readXmlAttr(manifestXml, "App", "Id");
+	const name = readXmlAttr(manifestXml, "App", "Name");
+	const publisher = readXmlAttr(manifestXml, "App", "Publisher");
+	const version = readXmlAttr(manifestXml, "App", "Version");
+
+	const embeddedSource: Record<string, string> = {};
+	for (const [k, v] of byName) {
+		if (k.endsWith(".al")) {
+			embeddedSource[k] = textDecoder.decode(v);
+		}
+	}
+	const embeddedSourceFiles = Object.keys(embeddedSource);
+	const hasEmbeddedSource = embeddedSourceFiles.length > 0;
+
+	const symbolRefBytes = byName.get("symbolreference.json") ?? byName.get("./symbolreference.json");
+	const symbolReferenceJson = symbolRefBytes ? textDecoder.decode(symbolRefBytes) : null;
+
+	const identity: AppIdentity = {
+		appGuid,
+		publisher,
+		name,
+		version,
+		packageHash,
+		symbolReferenceHash: symbolReferenceJson ? sha256Hex(symbolReferenceJson) : undefined,
+		sourceKind: hasEmbeddedSource ? "app-source" : "symbol-only",
+	};
+
+	return {
+		identity,
+		hasEmbeddedSource,
+		embeddedSourceFiles,
+		symbolReferenceJson,
+		embeddedSource,
+	};
+}

package/src/symbols/symbol-reference-parser.ts

@@ -0,0 +1,378 @@
+import type { AttributeArg, AttributeArgKind, AttributeInfo } from "../model/attributes.ts";
+import type { RoutineKind } from "../model/ids.ts";
+
+/** A parameter signature as carried by SymbolReference.json — no per-run ids. */
+export interface AbiParameter {
+	name: string;
+	typeText: string;
+	isVar: boolean;
+}
+
+/** A routine signature from SymbolReference.json. No body, no source anchor, no per-run id. */
+export interface AbiRoutine {
+	name: string;
+	kind: RoutineKind;
+	/** "integration" | "business" | "unknown" — only meaningful when kind === "event-publisher". */
+	eventKind: "integration" | "business" | "unknown";
+	parameters: AbiParameter[];
+	returnTypeText?: string;
+	isLocal: boolean;
+	isInternal: boolean;
+	/**
+	 * Reconstructed attribute strings, e.g. "[IntegrationEvent(False, False)]". Kept for
+	 * back-compat / display; semantic consumers must read `attributesParsed` instead.
+	 */
+	attributes: string[];
+	/**
+	 * Structured attributes synthesized from the structured `RawAttr` JSON — same model
+	 * shape as the native AL path's `AttributeInfo[]`, so event-graph, attribute-parser,
+	 * and detectors traverse one normalized representation regardless of routine source.
+	 */
+	attributesParsed: AttributeInfo[];
+}
+
+/** An ABI field — table column metadata. */
+export interface AbiField {
+	fieldNumber: number;
+	name: string;
+	dataType: string;
+	fieldClass: "Normal" | "FlowField" | "FlowFilter";
+	isBlobLike: boolean;
+}
+
+/** An ABI key — references fields by name; index is array position. */
+export interface AbiKey {
+	name: string;
+	fieldNames: string[];
+}
+
+/** An ABI object — codeunit/page/table/etc. Tables additionally appear in `SymbolReferenceAbi.tables`. */
+export interface AbiObject {
+	objectType: string; // "Codeunit" | "Table" | "Page" | "Report" | "XMLport" | "Query" | "Interface" | "Enum" | ...
+	objectNumber: number;
+	name: string;
+	routines: AbiRoutine[];
+	/**
+	 * Codeunit Subtype property value from the SymbolReference JSON (e.g. "Install", "Upgrade").
+	 * Undefined when not present in the JSON or for non-codeunit objects.
+	 */
+	objectSubtype?: string;
+	/**
+	 * Page PageType property value from the SymbolReference JSON (e.g. "API", "List", "Card").
+	 * Undefined when not present in the JSON or for non-page objects.
+	 */
+	pageType?: string;
+}
+
+/** An ABI table — physical table layout. */
+export interface AbiTable {
+	objectNumber: number;
+	name: string;
+	fields: AbiField[];
+	keys: AbiKey[];
+}
+
+/** The neutral DTO `parseSymbolReference` produces — no model entities, no anchors, no ids. */
+export interface SymbolReferenceAbi {
+	appGuid: string;
+	name: string;
+	publisher: string;
+	version: string;
+	objects: AbiObject[];
+	tables: AbiTable[];
+	/** Set when the JSON could not be parsed; objects/tables are then empty. */
+	error?: string;
+}
+
+const BLOB_LIKE = new Set(["blob", "media", "mediaset"]);
+
+interface RawAttr {
+	Name?: string;
+	Arguments?: { Value?: unknown }[];
+}
+interface RawMethod {
+	Name?: string;
+	Parameters?: { Name?: string; IsVar?: boolean; TypeDefinition?: { Name?: string } }[];
+	ReturnTypeDefinition?: { Name?: string };
+	Attributes?: RawAttr[];
+	IsLocal?: boolean;
+	IsInternal?: boolean;
+}
+interface RawField {
+	Id?: number;
+	Name?: string;
+	TypeDefinition?: { Name?: string };
+	Properties?: { Name?: string; Value?: string }[];
+}
+interface RawKey {
+	Name?: string;
+	FieldNames?: string[];
+}
+interface RawObject {
+	Id?: number;
+	Name?: string;
+	Methods?: RawMethod[];
+	Fields?: RawField[];
+	Keys?: RawKey[];
+	Properties?: { Name?: string; Value?: string }[];
+}
+
+/**
+ * Read a named property value from a SymbolReference JSON object's `Properties` array.
+ * Comparison is case-insensitive. Returns the `Value` string or undefined when absent.
+ */
+function rawObjectProperty(
+	properties: { Name?: string; Value?: string }[] | undefined,
+	propertyName: string,
+): string | undefined {
+	if (!properties) return undefined;
+	const lc = propertyName.toLowerCase();
+	for (const p of properties) {
+		if ((p.Name ?? "").toLowerCase() === lc) return p.Value;
+	}
+	return undefined;
+}
+
+/** Reconstruct an attribute string from a raw Attributes entry, e.g. "[IntegrationEvent(False, False)]". */
+function attrString(a: RawAttr): string {
+	const name = a.Name ?? "";
+	const args = (a.Arguments ?? []).map((x) => String(x.Value ?? "")).join(", ");
+	return args === "" ? `[${name}]` : `[${name}(${args})]`;
+}
+
+/**
+ * Object-type keywords that distinguish a `database_reference` (e.g. `Codeunit::"X"`)
+ * from a generic `qualified_enum_value` (e.g. `ObjectType::Codeunit`). Mirrors the
+ * `object_type_keyword` alias in tree-sitter-al's grammar.
+ */
+const OBJECT_TYPE_KEYWORDS = new Set([
+	"database",
+	"page",
+	"report",
+	"codeunit",
+	"xmlport",
+	"query",
+	"table",
+]);
+
+/** True if every char in `s` is `0-9` (and `s` is non-empty, optional leading minus). */
+function isIntegerText(s: string): boolean {
+	if (s.length === 0) return false;
+	let i = 0;
+	if (s.charCodeAt(0) === 45 /* '-' */) {
+		i = 1;
+		if (i === s.length) return false;
+	}
+	for (; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 48 || c > 57) return false;
+	}
+	return true;
+}
+
+/**
+ * Classify a single `RawAttr.Arguments[].Value` into a typed `AttributeArg`. The
+ * SymbolReference JSON stores values as primitives (booleans/numbers) or already-
+ * tokenized AL text (`'name'`, `Codeunit::"X"`, `ObjectType::Codeunit`); we map
+ * each shape onto the same kinds tree-sitter-al exposes, so consumers see one
+ * model whether the routine came from native source or an `.app` symbol package.
+ */
+function classifyAbiArg(raw: unknown): AttributeArg {
+	if (typeof raw === "boolean") {
+		const text = raw ? "true" : "false";
+		return { kind: "boolean", text, value: text };
+	}
+	if (typeof raw === "number" && Number.isFinite(raw) && Number.isInteger(raw)) {
+		const text = String(raw);
+		return { kind: "integer", text, value: text };
+	}
+
+	const text = String(raw ?? "");
+	const trimmed = text.trim();
+	if (trimmed === "") return { kind: "unknown", text };
+
+	const lower = trimmed.toLowerCase();
+	if (lower === "true" || lower === "false") {
+		return { kind: "boolean", text: trimmed, value: lower };
+	}
+	if (isIntegerText(trimmed)) {
+		return { kind: "integer", text: trimmed, value: trimmed };
+	}
+	if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) {
+		return { kind: "string_literal", text: trimmed, value: trimmed.slice(1, -1) };
+	}
+	if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+		return { kind: "quoted_identifier", text: trimmed, value: trimmed.slice(1, -1) };
+	}
+
+	const colonIdx = trimmed.indexOf("::");
+	if (colonIdx > 0) {
+		const qualifier = trimmed.slice(0, colonIdx).trim();
+		const memberRaw = trimmed.slice(colonIdx + 2).trim();
+		const member =
+			memberRaw.length >= 2 && memberRaw.startsWith('"') && memberRaw.endsWith('"')
+				? memberRaw.slice(1, -1)
+				: memberRaw;
+		const kind: AttributeArgKind = OBJECT_TYPE_KEYWORDS.has(qualifier.toLowerCase())
+			? "database_reference"
+			: "qualified_enum_value";
+		return { kind, text: trimmed, value: member, qualifier, member };
+	}
+
+	// Bare token — treat as identifier. .app values are well-formed, no shape check needed.
+	return { kind: "identifier", text: trimmed, value: trimmed };
+}
+
+/** Build an `AttributeInfo` from a structured `RawAttr` JSON entry. */
+function abiAttributeInfo(a: RawAttr): AttributeInfo {
+	const name = a.Name ?? "";
+	const args = (a.Arguments ?? []).map((x) => classifyAbiArg(x.Value));
+	const raw = args.length === 0 ? `[${name}]` : `[${name}(${args.map((x) => x.text).join(", ")})]`;
+	return { name, args, raw };
+}
+
+/** Classify a method as a routine, deriving event-publisher kind from its attributes. */
+function parseMethod(m: RawMethod): AbiRoutine {
+	const rawAttrs = m.Attributes ?? [];
+	const attributes = rawAttrs.map(attrString);
+	const attributesParsed = rawAttrs.map(abiAttributeInfo);
+
+	let kind: RoutineKind = "procedure";
+	let eventKind: AbiRoutine["eventKind"] = "unknown";
+	for (const info of attributesParsed) {
+		const nameLc = info.name.toLowerCase();
+		if (nameLc === "integrationevent") {
+			kind = "event-publisher";
+			eventKind = "integration";
+		} else if (nameLc === "businessevent") {
+			kind = "event-publisher";
+			eventKind = "business";
+		} else if (nameLc === "eventsubscriber") {
+			kind = "event-subscriber";
+		}
+	}
+	return {
+		name: m.Name ?? "",
+		kind,
+		eventKind,
+		parameters: (m.Parameters ?? []).map((p) => ({
+			name: p.Name ?? "",
+			typeText: p.TypeDefinition?.Name ?? "",
+			isVar: p.IsVar === true,
+		})),
+		returnTypeText: m.ReturnTypeDefinition?.Name,
+		isLocal: m.IsLocal === true,
+		isInternal: m.IsInternal === true,
+		attributes,
+		attributesParsed,
+	};
+}
+
+function parseField(f: RawField): AbiField {
+	const dataType = f.TypeDefinition?.Name ?? "";
+	let fieldClass: AbiField["fieldClass"] = "Normal";
+	for (const p of f.Properties ?? []) {
+		if ((p.Name ?? "").toLowerCase() === "fieldclass") {
+			if (/flowfield/i.test(p.Value ?? "")) fieldClass = "FlowField";
+			else if (/flowfilter/i.test(p.Value ?? "")) fieldClass = "FlowFilter";
+		}
+	}
+	return {
+		fieldNumber: f.Id ?? 0,
+		name: f.Name ?? "",
+		dataType,
+		fieldClass,
+		isBlobLike: BLOB_LIKE.has((dataType.split("[")[0] ?? dataType).toLowerCase()),
+	};
+}
+
+/** Parse the raw SymbolReference.json text into the neutral ABI DTO. Never throws. */
+export function parseSymbolReference(json: string): SymbolReferenceAbi {
+	let raw: Record<string, unknown>;
+	try {
+		raw = JSON.parse(json) as Record<string, unknown>;
+	} catch (err) {
+		return {
+			appGuid: "",
+			name: "",
+			publisher: "",
+			version: "",
+			objects: [],
+			tables: [],
+			error: `SymbolReference.json parse failed: ${(err as Error).message}`,
+		};
+	}
+
+	const objects: AbiObject[] = [];
+	const tables: AbiTable[] = [];
+
+	// Routine-bearing object arrays → AbiObject with routines.
+	const ROUTINE_BEARING: [key: string, objectType: string][] = [
+		["Codeunits", "Codeunit"],
+		["Pages", "Page"],
+		["Reports", "Report"],
+		["XmlPorts", "XMLport"],
+		["Queries", "Query"],
+		["Interfaces", "Interface"],
+	];
+	for (const [key, objectType] of ROUTINE_BEARING) {
+		for (const o of (raw[key] as RawObject[] | undefined) ?? []) {
+			const abiObject: AbiObject = {
+				objectType,
+				objectNumber: o.Id ?? 0,
+				name: o.Name ?? "",
+				routines: (o.Methods ?? []).map(parseMethod),
+			};
+			if (objectType === "Codeunit") {
+				const subtype = rawObjectProperty(o.Properties, "Subtype");
+				if (subtype !== undefined) abiObject.objectSubtype = subtype;
+			}
+			if (objectType === "Page") {
+				const pt = rawObjectProperty(o.Properties, "PageType");
+				if (pt !== undefined) abiObject.pageType = pt;
+			}
+			objects.push(abiObject);
+		}
+	}
+
+	// Tables → both an AbiTable (layout) and an AbiObject (so the symbol table can resolve them).
+	for (const t of (raw.Tables as RawObject[] | undefined) ?? []) {
+		const objectNumber = t.Id ?? 0;
+		tables.push({
+			objectNumber,
+			name: t.Name ?? "",
+			fields: (t.Fields ?? []).map(parseField),
+			keys: (t.Keys ?? []).map((k) => ({ name: k.Name ?? "", fieldNames: k.FieldNames ?? [] })),
+		});
+		objects.push({
+			objectType: "Table",
+			objectNumber,
+			name: t.Name ?? "",
+			routines: (t.Methods ?? []).map(parseMethod),
+		});
+	}
+
+	// Bare object arrays — no routines al-sem summarises; projected for resolution completeness.
+	const BARE: [key: string, objectType: string][] = [
+		["EnumTypes", "Enum"],
+		["ControlAddIns", "ControlAddIn"],
+		["PermissionSets", "PermissionSet"],
+		["PermissionSetExtensions", "PermissionSetExtension"],
+		["ReportExtensions", "ReportExtension"],
+		["DotNetPackages", "DotNetPackage"],
+	];
+	for (const [key, objectType] of BARE) {
+		for (const o of (raw[key] as RawObject[] | undefined) ?? []) {
+			objects.push({ objectType, objectNumber: o.Id ?? 0, name: o.Name ?? "", routines: [] });
+		}
+	}
+
+	return {
+		appGuid: String(raw.AppId ?? ""),
+		name: String(raw.Name ?? ""),
+		publisher: String(raw.Publisher ?? ""),
+		version: String(raw.Version ?? ""),
+		objects,
+		tables,
+	};
+}

package/src/symbols/symbol-reference-reader.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { filteredUnzip } from "./app-package-zip.ts";
+
+/** Decode bytes as UTF-8 and strip a leading BOM if present. */
+function decodeText(bytes: Uint8Array): string {
+	const text = new TextDecoder("utf-8").decode(bytes);
+	return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** Extract the SymbolReference.json text from raw .app bytes. Returns null if absent. */
+export function extractSymbolReferenceJson(appBytes: Uint8Array): string | null {
+	const entries = filteredUnzip(appBytes, (name) =>
+		name.toLowerCase().endsWith("symbolreference.json"),
+	);
+	const key = Object.keys(entries)[0];
+	const bytes = key ? entries[key] : undefined;
+	return bytes === undefined ? null : decodeText(bytes);
+}
+
+/** Read SymbolReference.json from a .app on disk. Returns null if absent. Never throws. */
+export function readSymbolReferenceJson(appPath: string): string | null {
+	try {
+		return extractSymbolReferenceJson(new Uint8Array(readFileSync(appPath)));
+	} catch {
+		return null;
+	}
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "target": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src", "test"]
+}