al-sem 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Torben Leth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+# al-sem — Static semantic analyzer for AL (Microsoft Business Central)
+
+[![TypeScript](https://img.shields.io/badge/typescript-5.6-blue)](https://typescriptlang.org)
+[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e1)](https://bun.sh)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Find cross-file performance, correctness, and compatibility bugs in an AL workspace —
+the kind per-file linters can't catch because they require the whole call graph:
+DB-ops-inside-loops walked across procedures, Commit inside a posting transaction span,
+event-subscriber cycles, integration events with no subscribers anywhere, MinVersion
+drift against actual call sites, and ten more. Pure static analysis (no profile, no
+runtime), but accurate enough to be actionable in CI and in an editor.
+
+34 default detectors plus 1 opt-in (D40), 35 total. Tuned on a real Continia BC extension — see
+[precision study](docs/superpowers/precision-study-do-cloud.md).
+
+Beyond `analyze`, al-sem also ships four standalone surfaces over the same `SemanticModel`:
+declarative **`policy`** rules over capability facts, event blast-radius reports (**`events
+fanout`** / **`events chains`**), a cross-version snapshot **`diff`**, and **`fingerprint`** (emit a
+`CapabilitySnapshot`). `diff` and `fingerprint` accept either a workspace directory or a raw `.app`
+symbol package, so two `.app` versions can be compared with no source checkout.
+
+**Status (2026-06-02):** code-complete through Phase 4 (record-flow framework) plus the L6 policy
+layer, event blast-radius, snapshot diff/fingerprint, and HTML report surfaces. 1828 tests pass;
+`tsc` and Biome clean. See [STATUS](docs/superpowers/STATUS.md).
+
+## Install
+
+```bash
+bun add al-sem
+```
+
+al-sem ships a native tree-sitter parser per platform that downloads via a postinstall
+hook. Bun requires you to opt in:
+
+```jsonc
+// package.json
+{ "trustedDependencies": ["al-sem"] }
+```
+
+**Supported platforms:** `win32-x64`, `linux-x64`, `darwin-arm64` shipped today;
+`darwin-x64` (Intel macOS) is pending the next `tree-sitter-al` release. Other
+platforms fail at first parse with a clear `NativeParserUnavailableError`.
+
+**Install-time environment overrides (for air-gapped / mirrored environments):**
+
+- `AL_SEM_NATIVE_PARSER_PATH=/abs/path/to/lib` — use a preseeded artifact, skip download.
+- `AL_SEM_NATIVE_PARSER_OFFLINE=1` — require the canonical artifact to already exist; never download.
+- `AL_SEM_NATIVE_PARSER_BASE_URL=https://internal-mirror/...` — fetch from an internal mirror instead of GitHub.
+
+If `trustedDependencies` is not configured, preseed the artifact via `AL_SEM_NATIVE_PARSER_PATH`.
+
+## Quick start
+
+```bash
+bunx al-sem analyze . --min-severity high --format terminal
+```
+
+Or run the bundled demo against a small intentionally-buggy workspace:
+`bash demo/run-demos.sh all` — walks the cross-file detectors the standard
+AL cops can't replicate and writes a sample HTML report to `demo/report.html`.
+
+Sample output:
+
+```text
+Analysed 1234 routines (1230 with bodies, 4 parse-incomplete); 251/251 source units parsed; 0 opaque app(s).
+
+HIGH (12):
+  [d1-db-op-in-loop] Database operation inside a loop — A loop in PostSalesDoc reaches FindSet on Sales Line.
+    ws:src/Codeunit/SalesPostHelper.Codeunit.al:204:13 in Sales-Post Helper :: PostSalesDoc
+    confidence: likely
+    fix (medium): Move the database operation outside the loop, or batch it into a set-based operation.
+  [d3-missing-setloadfields] Missing SetLoadFields ...
+```
+
+By default `--format auto` emits terminal on a TTY and compact JSON on a pipe.
+`--format json` always emits the compact summary; `--format sarif` emits SARIF
+2.1.0 for GitHub code-scanning; `--format html` emits a self-contained visual
+report (per-finding interprocedural evidence-path flows + a publisher→subscriber
+event graph, no external assets) for sharing or blog embedding; `--dump-model`
+opts into the legacy full-model dump (debug-only, can exceed 500 MB).
+
+## CI integration
+
+```yaml
+- name: al-sem
+  run: |
+    bunx al-sem analyze . \
+      --baseline .al-sem-baseline.json \
+      --fail-on high \
+      --format sarif > al-sem.sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: al-sem.sarif }
+```
+
+The first run is noisy by design — generate a baseline once and commit it:
+
+```bash
+bunx al-sem analyze . --baseline .al-sem-baseline.json --update-baseline
+```
+
+Subsequent runs report only NEW findings; the baseline survives nearby edits
+because fingerprints exclude line numbers. `--update-baseline` without
+`--baseline` is a no-op and writes a warning to stderr.
+
+## CLI options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--alpackages <dir>` | `<ws>/.alpackages` if present | Explicit path to the dependency `.alpackages` directory. |
+| `--format <fmt>` | `auto` | `auto` \| `terminal` \| `json` \| `sarif` \| `html`. `html` emits a self-contained visual report (evidence-path flows + event graph). |
+| `--deterministic` | off | Pin timestamps for byte-stable output. |
+| `--no-dep-summaries` | off | Skip behavioral dependency cold run (structural ABI only). Cached separately from the full-mode cache, so the second run with this flag is warm. |
+| `--dep-cache-dir <dir>` | `~/.al-sem/cache/` | Override the dependency cache directory. |
+| `--dump-model` | off | Emit the full SemanticModel (debug-only, can be >500 MB). |
+| `--min-severity <sev>` | none | Drop findings below `critical \| high \| medium \| low \| info`. |
+| `--detector <ids>` | all | Comma-separated allow-list of detector ids. |
+| `--scope <scope>` | `primary` | `primary` drops findings whose actionable anchor is in a dependency. |
+| `--limit <n>` | unlimited | Cap output at the first N findings (after filtering and scope). |
+| `--group-by <by>` | off | Terminal-only grouped output: `object \| routine \| table \| detector \| file`. |
+| `--baseline <file>` | none | Suppress fingerprints present in the baseline file. |
+| `--update-baseline` | off | Rewrite the baseline file from this run's findings. |
+| `--fail-on <sev>` | none | Exit 1 if any finding at this severity or above (after baseline / filters). |
+
+## Cache maintenance
+
+```bash
+bunx al-sem cache prune              # remove stale dep-cache entries
+bunx al-sem cache prune --dry-run    # classify without deleting
+```
+
+Stale = version-stamp mismatch with this build, corrupt file, mis-named file, or
+tampered content hash. Valid current-version artifacts are kept untouched.
+`--dep-cache-dir <dir>` overrides the cache location for both `analyze` and
+`cache prune`.
+
+## Other commands
+
+All of these run the same pipeline as `analyze` and reuse the dependency cache.
+
+### `policy` — declarative rules over capability facts
+
+```bash
+bunx al-sem policy check .                 # workspace's own app(s), bundled default rules
+bunx al-sem policy check . --scope all     # include dependency-anchored findings
+bunx al-sem policy explain no-commit-in-event-subscribers
+```
+
+A policy is a YAML file of rules whose `when`/`except` predicates match capability facts
+(op, resource, root kind, confidence, …) under Kleene tri-state semantics. al-sem auto-detects
+`al-sem.policy.yaml` in the workspace, else applies the 8 bundled defaults (no Commit in event
+subscribers / triggers, no interactive UI or ledger writes from API roots, etc.). `--format
+human | json | sarif`. Like `analyze`, `policy check` defaults to `--scope primary` (the
+workspace's own app); `--scope all` reports model-wide.
+
+### `events` — event blast-radius reports
+
+```bash
+bunx al-sem events fanout .     # per-event publisher → subscriber counts + coverage
+bunx al-sem events chains .     # publisher → subscriber relay trees (cycle/depth-bounded)
+```
+
+Both default to `--scope primary` ("primary participates": the publisher or any subscriber is in
+the workspace's own app); `--scope all` enumerates the entire merged event graph. `--format
+human | json`.
+
+### `diff` — compare two snapshots / workspaces / `.app` files
+
+```bash
+bunx al-sem diff old.app new.app           # cross-version .app diff (no checkout needed)
+bunx al-sem diff ./baseline.cbor.gz .      # persisted snapshot vs live workspace
+```
+
+Each side may be a workspace directory, a persisted snapshot artifact, or a raw `.app`. Reports
+deltas across five axes — ABI/contract, schema, events, capabilities, permissions — with
+`--format human | json | sarif` and `--fail-on <sev>`.
+
+### `fingerprint` — emit a CapabilitySnapshot
+
+```bash
+bunx al-sem fingerprint . --format cbor.gz --out snapshot.cbor.gz
+bunx al-sem fingerprint some.app --format json   # snapshot a raw .app directly
+```
+
+Persist a snapshot for later `diff` (the CI-friendly path: snapshot each release, diff the
+artifacts) or inspect per-root capability fingerprints (`--format human`). Accepts a workspace
+directory or a `.app` file.
+
+## Library usage
+
+```ts
+import {
+  analyzeWorkspace,
+  projectFinding,
+  filterFindings,
+  applyBaseline,
+  loadBaseline,
+  computeExitCode,
+} from "al-sem";
+
+const result = await analyzeWorkspace({ workspaceRoot: "./", deterministic: true });
+const compact = result.findings.map((f) => projectFinding(f, result.model));
+const high = filterFindings(compact, { minSeverity: "high" });
+
+// CI gate: load a baseline, drop known findings, fail on remaining "high" or worse.
+const baseline = loadBaseline(".al-sem-baseline.json");
+const newOnly = applyBaseline(high, baseline);
+process.exitCode = computeExitCode(newOnly, "high");
+```
+
+Re-exports from the package root, by area:
+
+| Area | Exports |
+|------|---------|
+| Pipeline | `analyzeWorkspace`, `indexWorkspace`, `AnalyzeWorkspaceOptions`, `AnalyzeWorkspaceResult`, `IndexWorkspaceResult` |
+| Model types | `Finding`, `FindingSummary`, `FindingLocation`, `Diagnostic`, `DetectorStats`, `SemanticModel`, `Routine`, `ObjectDecl`, `Table`, `SourceAnchor`, … (everything from `./model/index.ts`) |
+| Projection | `projectFinding`, `filterFindings`, `FilterOptions`, `groupFindings`, `FindingGroup`, `GroupBy`, `fingerprintOf` |
+| Output | `buildCompactReport`, `CompactReport`, `formatCompactJson`, `formatSarif` |
+| Baseline / CI | `loadBaseline`, `saveBaseline`, `applyBaseline`, `BaselineFile`, `computeExitCode`, `parseFailOn` |
+| Sources | `SourceUnit`, `SourceProvider`, `ExternalSourceProvider` |
+
+`indexWorkspace(options)` stops after L2 (discovery + indexing only), for callers
+that drive `resolveModel` themselves. `analyzeWorkspace` runs the full pipeline.
+
+## MCP server
+
+al-sem also ships an MCP server (`bunx al-sem-mcp` or `bun run src/mcp/server.ts`)
+exposing seven progressive-disclosure tools — `list_findings`, `list_rollups`
+(multi-detector view), `get_finding`, `list_hotspots`, `get_routine_summary`,
+`explain_path`, `get_analysis_health`. See [docs/MCP.md](docs/MCP.md) for wiring
+instructions.
+
+## Detectors
+
+| Detector | Category | Flags |
+|----------|----------|-------|
+| `d1-db-op-in-loop` | Performance | Database operation reachable inside a loop, interprocedurally; severity by op class. |
+| `d2-event-fanout-in-loop` | Performance | Event raised inside a loop whose subscribers touch the database. |
+| `d3-missing-setloadfields` | Performance | Record retrieval whose loaded field set doesn't cover the fields accessed (same routine + directly-resolved callees). |
+| `d4-repeated-lookup-in-loop` | Performance | Identical Get/FindFirst/FindLast called repeatedly in a loop with a literal key. |
+| `d5-set-based-opportunity` | Performance | Loop body is a single Modify on the iterating record — ModifyAll candidate. |
+| `d7-recursive-event-expansion` | Correctness | Event subscriber chain forms a cycle (runtime infinite recursion). |
+| `d8-commit-in-transaction` | Correctness | Commit inside a posting transaction span — breaks atomicity. |
+| `d9-transaction-span-summary` | Info | Transaction span describes its routine / table / event reach. |
+| `d10-self-modifying-loop` | Correctness | Modify/Validate/Delete on the loop-iterating record. |
+| `d11-modify-without-get` | Correctness | Modify/Validate on a record that was never loaded (no Get/Find/Init/Insert) in this routine. |
+| `d12-dead-integration-event` | Hygiene | Published IntegrationEvent has no subscribers anywhere. |
+| `d13-cross-app-internal-call` | Hygiene | Calls a routine marked Access=Internal in another app. |
+| `d14-dead-routine` | Hygiene | `local procedure` unreachable from any entry-point or non-local procedure. |
+| `d16-obsolete-routine-call` | Compatibility | Calls a routine marked [Obsolete(...)] (info Pending, high Removed). |
+| `d17-min-version-drift` | Compatibility | Calls into a dependency whose installed version exceeds the declared MinVersion (app-level precision; per-routine pending upstream metadata). |
+| `d18-constant-filter-in-loop` | Performance | `SetRange`/`SetFilter` with literal-only arguments inside a loop — the same filter is applied every iteration; hoist it out. |
+| `d19-unused-parameter` | Hygiene | Procedure parameter declared but never referenced in the body. Skips triggers and event-subscribers (signatures dictated by the publisher). |
+| `d20-unreachable-after-exit` | Correctness | Statement that follows `Exit;`, `Error(...)`, or `CurrReport.Quit` at the same nesting level — control leaves the routine before it can run. |
+| `d21-read-without-load` | Correctness | `TestField` / `CalcFields` / `CalcSums` on a record never loaded earlier in the routine — read returns the AL default. D11's read-side sibling. |
+| `d22-flowfield-without-calcfields` | Correctness | Reads a FlowField with no prior `CalcFields(<that field>)` on the same record-var — silent zero/empty result. |
+| `d29-subscriber-modify-on-event-record` | Correctness | Subscriber to an `OnAfter*Modify` / `OnBefore*Delete` event mutates the inbound record parameter — re-fires the same event, recursive-trigger risk. |
+| `d32-constant-boolean-parameter` | Hygiene | `local procedure` Boolean parameter where every resolved primary-app caller passes the same literal — dead parameter, candidate for flattening. |
+| `d33-unfiltered-bulk-write` | Correctness | `DeleteAll` (critical) or `ModifyAll` (high) on a local non-temp record with no prior SetRange/SetFilter since the last Reset — whole-table impact. |
+| `d34-commit-in-loop` | Correctness | `Commit` inside a loop, direct or transitive via callee summary. Per-iteration commits break atomicity; nested-loop case escalates to critical. |
+| `d35-commit-in-event-subscriber` | Correctness | `Commit` reachable from an `[EventSubscriber]` routine. Publisher cannot roll back what the subscriber committed. |
+| `d36-late-setloadfields` | Performance | `SetLoadFields` / `AddLoadFields` placed AFTER a Get/Find, with no later load — the partial-record optimisation cannot apply. |
+| `d37-validate-without-persist` | Correctness | `Validate` on a record with no subsequent Modify/Insert before the record is reloaded or the routine exits — the field write is silently discarded. |
+| `d38-subscriber-to-obsolete-event` | Upgrade | `[EventSubscriber]` bound to a publisher routine carrying `[Obsolete(...)]`. Pending → info (plan migration); Removed → high (subscriber will stop firing). |
+| `d39-record-left-dirty-across-chain` | Correctness | Caller forwards a record to a helper that exits dirty (path-proven `Validate` with no subsequent `Modify`/`Insert` on at least one exit path), and the caller never persists after the call — the field write is silently discarded across the chain. Strictly interprocedural; only fires on path-proven `dirtyAtExit === "yes"` from the P6.T2 walker. |
+| `d40-transitive-load-missing` *(opt-in)* | Correctness | Caller forwards a record to a helper that reads or mutates without loading. Strictly interprocedural — closes D11/D21's by-var-parameter precision gap. Currently opt-in (Phase 4 straight-line walker; Phase 6's full walker re-enables by default after the loop-loaded false-positive class is closed). Enable via `--detector d40-transitive-load-missing`. |
+| `d41-transitive-filter-loss` | Correctness | Caller sets filters on a record, forwards it by-var to a helper that calls Reset, and then performs a filter-sensitive op (FindFirst/FindLast/FindSet/Find/Next/CalcSums/DeleteAll/ModifyAll/Count/IsEmpty) on the record without re-filtering — the filters are silently lost and the subsequent op runs on the unfiltered set. Strictly interprocedural; the post-call-use requirement prevents flagging intentional reset helpers. |
+| `d42-cross-call-wrong-setloadfields` | Performance | Caller narrowed a record's load via SetLoadFields/AddLoadFields then forwards it to a helper that reads a field outside the narrow — the runtime issues an extra SQL round-trip to fetch the missing field, defeating the partial-load optimisation. Strictly interprocedural; only fires when both sides are concrete (caller narrow and callee `requiredLoadedFieldsAtEntry` from the Phase 6 walker). |
+| `d43-event-ishandled-skip` | Correctness | Invoker raises an `IsHandled`-guarded integration event whose subscriber set may set the guard, skipping the invoker's own guarded table writes — the writes are silently bypassed. Dispatch-site (invoker-centric) analysis. |
+| `d44-event-multi-subscriber-overlap` | Correctness | Multiple subscribers to one event write the same table (execution-order-dependent outcome), plus a read-after-write hazard class across subscribers. |
+| `d45-event-transitive-table-exposure` | Correctness | A primary publisher's event reaches, via an N-hop subscriber→publisher relay chain, a subscriber that writes a sensitive table — transitive table exposure the publisher doesn't see locally. |
+
+---
+
+## Architecture (advanced)
+
+A layered pipeline, each layer a pure transform over the previous:
+
+```
+L0  parser / symbols      parse AL + read .app symbol packages
+L1  providers             discover workspace + external sources
+L1.5  deps                cached dependency artifacts merged into the index
+L2  index                 → SemanticIndex   (objects, routines, tables, features)
+L3  resolve               → SemanticModel    (call graph, event graph, coverage)
+L4  engine                combined graph → Tarjan SCC → fixed-point RoutineSummary
+L5  detectors             walk the model + summaries → Finding[] (scoped to primary)
+L6  projection            compact FindingSummary + filter + group + fingerprint
+```
+
+`analyzeWorkspace` runs the whole pipeline:
+
+```
+discoverSources → buildSemanticIndex → resolveModel
+  → buildCombinedGraph → computeSummaries → runDetectors
+  → { model, findings, diagnostics, detectorStats }
+```
+
+### Key design principles
+
+- **The engine never throws.** Failures — unparseable files, missing symbols, resolution
+  gaps — surface as `Diagnostic[]`, never exceptions. There is no "silent clean".
+- **Determinism is a contract.** With `deterministic: true`, output is byte-stable:
+  timestamps are pinned, every derived collection has a canonical sort, Map/Set iteration
+  never leaks into output unsorted. `test/e2e.test.ts` guards this.
+- **Detectors are pure queries** over the `SemanticModel` + summaries. They prune via
+  `RoutineSummary`, then use the shared path-walker with a detector-specific policy to
+  build evidence-backed `Finding`s. Each detector dedupes findings by `id` before sorting.
+- **L4 summaries** compose per-routine effects bottom-up over the call graph's SCC
+  condensation, using a finite monotone fixed-point so recursive cycles converge.
+- **Dependency direction is one-way**: al-sem knows nothing of al-perf. al-perf
+  consumes al-sem as a library.
+
+### Source layout
+
+```
+src/
+  parser/      AL parsing (native bun:ffi tree-sitter) + AST helpers
+  symbols/     .app symbol-package reader
+  providers/   workspace + external source discovery
+  deps/        L1.5 — dependency artifact types, cache, pipeline orchestration
+  index/       SemanticIndex construction (objects, routines, intraprocedural features)
+  resolve/     call resolution, event graph, record types, coverage → SemanticModel
+  engine/      L4 — combined graph, SCC, effect lattice, summary engine, path-walker,
+                    reverse call graph, entry points, transaction spans, attribute parser
+  detectors/   L5 — 34 default detectors plus 1 opt-in (D40), 35 total + shared
+                    DetectorContext, confidence mapping, registry
+  policy/      L6 — declarative capability-fact rules (Kleene tri-state evaluator)
+  snapshot/    CapabilitySnapshot compose + serialize (json/cbor/cbor.gz)
+  diff/        cross-snapshot delta engine (ABI, schema, events, capabilities, permissions)
+  model/       shared types — entities, graph, summary, finding, identity, ids, analysisRole
+  cli/         commander CLI + terminal / JSON / SARIF formatters
+  mcp/         MCP server (seven tools, progressive-disclosure)
+  index.ts     public library entry point
+```
+
+## Development
+
+```bash
+bun install
+bun test            # run all tests
+bun run typecheck   # bunx tsc --noEmit
+bun run lint        # bunx biome check src test
+bun run format      # bunx biome format --write src test
+```
+
+**Tech stack:** Bun · TypeScript · `bun:ffi` + native `tree-sitter-al` shared library ·
+`commander` · `fflate` (`.app` package extraction) · `bun:test` · Biome.
+
+Design specs and implementation plans live under `docs/superpowers/` —
+`specs/` for designs, `plans/` for the phased TDD implementation plans.
+
+## Status
+
+See [docs/superpowers/STATUS.md](docs/superpowers/STATUS.md) for the current phase
+status and roadmap.
+
+---
+
+**Author**: Torben Leth
+**License**: MIT (see [LICENSE](LICENSE))

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "al-sem",
+  "version": "0.0.1",
+  "description": "Static semantic analysis engine for Microsoft Business Central AL code",
+  "license": "MIT",
+  "author": "Torben Leth",
+  "keywords": [
+    "business-central",
+    "al",
+    "static-analysis",
+    "semantic-analysis",
+    "call-graph",
+    "performance",
+    "linter",
+    "dynamics-365",
+    "bun"
+  ],
+  "files": [
+    "src",
+    "!src/parser/native/lib-*",
+    "!src/parser/native/lib.*",
+    "scripts",
+    "tsconfig.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SShadowS/al-sem.git"
+  },
+  "homepage": "https://github.com/SShadowS/al-sem#readme",
+  "bugs": {
+    "url": "https://github.com/SShadowS/al-sem/issues"
+  },
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "al-sem": "src/cli/index.ts",
+    "al-sem-mcp": "src/mcp/server.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx biome check src test",
+    "format": "bunx biome format --write src test",
+    "postinstall": "bun run scripts/fetch-native-parser.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cbor-x": "^1.6.4",
+    "commander": "^14.0.3",
+    "fflate": "^0.8.2",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  }
+}

package/scripts/d40-diff.ts

@@ -0,0 +1,44 @@
+// scripts/d40-diff.ts
+// One-shot diff between two precision runs (Round N vs Round N+1).
+// Prints the count of added/removed findings + a sample of removed rootCauses
+// so the reviewer can confirm a fix targeted the intended FP class.
+
+import { readFileSync } from "node:fs";
+
+interface FindingLike {
+	id: string;
+	severity: string;
+	rootCause: string;
+}
+interface RunJson {
+	findings: FindingLike[];
+}
+
+const [beforePath, afterPath] = process.argv.slice(2);
+if (!beforePath || !afterPath) {
+	console.error("usage: d40-diff.ts <before.json> <after.json>");
+	process.exit(2);
+}
+
+const before = JSON.parse(readFileSync(beforePath, "utf8")) as RunJson;
+const after = JSON.parse(readFileSync(afterPath, "utf8")) as RunJson;
+
+const idsBefore = new Set(before.findings.map((f) => f.id));
+const idsAfter = new Set(after.findings.map((f) => f.id));
+const removed = before.findings.filter((f) => !idsAfter.has(f.id));
+const added = after.findings.filter((f) => !idsBefore.has(f.id));
+
+console.log(`before: ${before.findings.length}, after: ${after.findings.length}`);
+console.log(`removed: ${removed.length}, added: ${added.length}`);
+console.log("");
+console.log("=== Sample of removed findings (first 10) ===");
+for (const f of removed.slice(0, 10)) {
+	console.log(`- [${f.severity}] ${f.rootCause}`);
+}
+if (added.length > 0) {
+	console.log("");
+	console.log("=== Sample of added findings (first 10) ===");
+	for (const f of added.slice(0, 10)) {
+		console.log(`- [${f.severity}] ${f.rootCause}`);
+	}
+}

package/scripts/fetch-native-parser.ts

@@ -0,0 +1,179 @@
+// scripts/fetch-native-parser.ts
+// Postinstall: idempotent provisioning of the fat shim for the current platform.
+// Resolution order:
+//   1. AL_SEM_NATIVE_PARSER_PATH  — copy from absolute path, write meta.
+//   2. AL_SEM_NATIVE_PARSER_OFFLINE=1 — require canonical lib; normalize meta if absent.
+//   3. AL_SEM_NATIVE_PARSER_BASE_URL — override download base URL.
+//   4. Default: download from GH releases.
+// Failures other than offline-missing-lib soft-fail (warn + exit 0). Runtime
+// surfaces the missing parser as a single NativeParserUnavailableError.
+
+import {
+  copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { platform as nodePlatform, arch as nodeArch } from "node:process";
+
+export const TREE_SITTER_AL_RELEASE_TAG = "v2.5.2-shim";
+
+const SUPPORTED: Record<string, string> = {
+  "win32-x64":    "tree-sitter-al-win32-x64.dll",
+  "linux-x64":    "tree-sitter-al-linux-x64.so",
+  "darwin-x64":   "tree-sitter-al-darwin-x64.dylib",
+  "darwin-arm64": "tree-sitter-al-darwin-arm64.dylib",
+};
+
+export function resolveAssetName(platform: string, arch: string): string {
+  const key = `${platform}-${arch}`;
+  const name = SUPPORTED[key];
+  if (!name) {
+    throw new Error(
+      `al-sem: native parser unavailable for ${key}. Supported: ${Object.keys(SUPPORTED).join(", ")}. ` +
+      `File an issue at https://github.com/SShadowS/tree-sitter-al/issues to add this platform.`,
+    );
+  }
+  return name;
+}
+
+export interface LibMeta {
+  tag: string;
+  platform: string;
+  arch: string;
+  asset: string;
+  sha256: string;
+}
+
+function sha256Hex(buf: Buffer): string {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+export function normalizeMeta(
+  libPath: string,
+  ref: { tag: string; platform: string; arch: string },
+): LibMeta {
+  const bytes = readFileSync(libPath);
+  return {
+    tag: ref.tag,
+    platform: ref.platform,
+    arch: ref.arch,
+    asset: resolveAssetName(ref.platform, ref.arch),
+    sha256: sha256Hex(bytes),
+  };
+}
+
+export function writeMeta(nativeDir: string, meta: LibMeta): void {
+  writeFileSync(join(nativeDir, "lib.meta.json"), JSON.stringify(meta, null, 2));
+}
+
+export function readMeta(nativeDir: string): LibMeta | null {
+  const p = join(nativeDir, "lib.meta.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as LibMeta;
+  } catch {
+    return null;
+  }
+}
+
+export function libFilename(tag: string, platform: string, arch: string): string {
+  const asset = SUPPORTED[`${platform}-${arch}`] ?? "";
+  const ext = asset.split(".").pop() ?? "so";
+  return `lib-${tag}-${platform}-${arch}.${ext}`;
+}
+
+async function downloadTo(url: string, destPath: string): Promise<void> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, buf);
+}
+
+async function main(): Promise<void> {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const nativeDir = join(here, "..", "src", "parser", "native");
+  mkdirSync(nativeDir, { recursive: true });
+  const platform = nodePlatform;
+  const arch = nodeArch;
+  const tag = TREE_SITTER_AL_RELEASE_TAG;
+
+  let asset: string;
+  try {
+    asset = resolveAssetName(platform, arch);
+  } catch (err) {
+    process.stderr.write(`${(err as Error).message}\n`);
+    process.exit(0); // soft-fail; runtime surfaces it
+  }
+
+  const targetFile = libFilename(tag, platform, arch);
+  const targetPath = join(nativeDir, targetFile);
+
+  // 1. AL_SEM_NATIVE_PARSER_PATH override
+  const explicit = process.env.AL_SEM_NATIVE_PARSER_PATH;
+  if (explicit) {
+    if (!existsSync(explicit)) {
+      process.stderr.write(`al-sem: AL_SEM_NATIVE_PARSER_PATH=${explicit} does not exist\n`);
+      process.exit(1);
+    }
+    copyFileSync(explicit, targetPath);
+    writeMeta(nativeDir, normalizeMeta(targetPath, { tag, platform, arch }));
+    return;
+  }
+
+  // 2. Offline mode
+  if (process.env.AL_SEM_NATIVE_PARSER_OFFLINE === "1") {
+    if (!existsSync(targetPath)) {
+      process.stderr.write(
+        `al-sem: AL_SEM_NATIVE_PARSER_OFFLINE=1 but ${targetPath} is missing. ` +
+        `Preseed the artifact or unset the env var.\n`,
+      );
+      process.exit(1);
+    }
+    if (!readMeta(nativeDir)) {
+      writeMeta(nativeDir, normalizeMeta(targetPath, { tag, platform, arch }));
+    }
+    return;
+  }
+
+  // 3. Idempotent check
+  const meta = readMeta(nativeDir);
+  if (
+    meta &&
+    meta.tag === tag &&
+    meta.platform === platform &&
+    meta.arch === arch &&
+    existsSync(targetPath)
+  ) {
+    const actual = sha256Hex(readFileSync(targetPath));
+    if (actual === meta.sha256) return;
+    process.stderr.write(`al-sem: cache mismatch — re-downloading ${targetFile}\n`);
+    try { unlinkSync(targetPath); } catch {}
+  }
+
+  // 4. Download
+  const baseUrl =
+    process.env.AL_SEM_NATIVE_PARSER_BASE_URL ??
+    "https://github.com/SShadowS/tree-sitter-al/releases/download/";
+  const url = `${baseUrl}${tag}/${asset}`;
+  try {
+    await downloadTo(url, targetPath);
+    writeMeta(nativeDir, normalizeMeta(targetPath, { tag, platform, arch }));
+  } catch (err) {
+    process.stderr.write(
+      `al-sem: could not fetch ${url}: ${(err as Error).message}. ` +
+      `Re-run bun install with network, or set AL_SEM_NATIVE_PARSER_BASE_URL ` +
+      `(mirror) or AL_SEM_NATIVE_PARSER_PATH (preseeded artifact).\n`,
+    );
+    process.exit(0); // soft-fail; defer to runtime
+  }
+}
+
+// Allow `bun run scripts/fetch-native-parser.ts` AND `import` (for tests).
+if (import.meta.main) {
+  main().catch((err) => {
+    process.stderr.write(`al-sem postinstall: ${err}\n`);
+    process.exit(0);
+  });
+}