any-doctor 0.0.1 → 0.0.3

package/CONTEXT.md

@@ -19,11 +19,65 @@ results can vary across engine upgrades.
 
 ## RunOutcome
 
-One scan invocation's batch of results, assembled once and rendered by the
-report and the dashboard alike: the ReportGroups that ran, the doctor ids
-that crashed (data, named), the slugs Confinement skipped, the doctor
+One scan invocation's batch of results, assembled once by the Cohort and
+rendered by the report and the dashboard alike: the ReportGroups that
+ran, the doctors that crashed (data — each named, with the full error
+detail riding along), the slugs Confinement skipped, the doctor
 id → program path map for re-run commands, and the target's file count and
-the batch's wall-clock duration — one defined meaning per field.
+the batch's wall-clock duration — one defined meaning per field. A run also
+records whether the identity engine could power it
+(`analysisAvailable`) — the data behind "narrowed" rendering.
+
+## Cohort
+
+The module that turns chosen doctor programs plus a target into one
+RunOutcome — a single doctor is a cohort of one, so the single-path and
+batch commands share one semantics. The command layer chooses the
+doctors (a path, the picker, --all) and picks the surface (report or
+dashboard); everything from first spawn to last settle lives behind one
+call: the runner's bounded pool, the crash fold (a crash is data — id
+plus full error detail, never a throw), the process-wide analysis fold,
+the per-doctor paths, the file-count policy, and the timing. Progress
+events (settle order) are the only side channel — the live line renders
+them, it never joins the fold. Skips are a discovery fact, so the
+command layer, which owns discovery, patches `skippedUnsafe` onto the
+outcome.
+
+## Summary
+
+The derived view of a RunOutcome — everything a surface renders,
+computed once: the deduplicated severity-ordered groups, the total and
+hidden-duplicate counts, the Score and its header lines, the severity
+counts and category rollup, each group's check buckets, the narrowed
+check ids, and the empty-scan flag. One derivation, N adapters: the
+report string, the dashboard tree, and the JSON surface render it —
+never re-deriving. Pure —
+deriving twice from one RunOutcome yields one Summary; rendering
+(colors, prose, trees) belongs to the adapters, never to the
+derivation. The facts a gate needs (`--fail-on` severity counts,
+baseline-diffable shapes) live here as data, not inside rendering.
+
+## Gate
+
+A run's exit policy — one module (src/gate.ts), one law. Findings are
+advisory by default: `--fail-on none` (the default) reports everything
+and exits 0, because a scanner that reds CI on first adoption gets
+uninstalled. `--fail-on error|warning|info` sets a severity bar ("at or
+above") that findings must clear for the run to pass. Crashes and
+Confinement skips fail ALWAYS, regardless of the bar — an
+infrastructure failure is not a finding and must never paint a run
+green. Diff mode (`--base <ref>`) judges only what a change ADDED: the
+same cohort scans the merge base of the ref and HEAD (a stateless
+baseline — nothing committed, nothing stale), the two deduped finding
+sets compare through the verify gate's own rule-aware multiset, and the
+bar counts added findings only; a change is not blamed for the debt it
+was born into. A partial base never gates: any base-scan crash aborts
+the run loudly (exit 1, no report, no JSON), because a baseline
+missing findings would dress pre-existing debt up as "added" — and a
+crashed HEAD doctor skips the diff for the same reason: its findings
+are absent, and absence must never read as "resolved". Machine
+output rides `--format json` — one schema-tagged object on stdout,
+diagnostics on stderr.
 
 ## Confinement
 
@@ -48,11 +102,14 @@ lives in the program's meta, not in individual findings.
 ## Check
 
 One rule within a doctor program. A finding names its check via `rule`;
-the check's meta supplies description, severity, impact, why, and fix;
-the doctor's meta supplies the defaults when a finding names no check.
-A check id is a short kebab-case noun phrase over [a-z0-9-], unique
-within its doctor, naming the defect (fetch-calls-without-abortsignal,
-filter-table-scan). One doctor program, many checks.
+the check's meta supplies description, severity, impact, why, and fix —
+and, when the check uses the identity engine at full power, its
+declaration of that need (`needs`), which is what renders "narrowed"
+when the engine is absent; the doctor's meta supplies the defaults when
+a finding names no check. A check id is a short kebab-case noun phrase
+over [a-z0-9-], unique within its doctor, naming the defect
+(fetch-calls-without-abortsignal, filter-table-scan). One doctor
+program, many checks.
 
 ## Doctor contract
 
@@ -67,14 +124,87 @@ repo-scoped file access, structural search, and a finding emitter.
 Confinement enforces it: outside ctx there is nothing — no imports, no
 writes, no subprocesses, no network.
 
+`ctx.files.list()` and `ctx.search` exclude test paths by default
+(test-named code files — `*.test.*`/`*.spec.*` with a code extension —
+and `test/`, `tests/`, `__tests__/` directories): tests mimic production
+shapes without being production reads. The one law (`isTestPath`) and
+the one derivation (`includeTestsFor`) live in contract.ts; every read
+capability applies them. A Doctor run opts back in with
+`--include-tests`; `ctx.files.read()` is never filtered — an explicit
+path is a deliberate choice. `ctx.files.readMasked()` is the one
+masking implementation (comments and strings blanked, offsets and
+length preserved — a masked position addresses the same char in the
+source); doctors carry no private copies — the bundled pack's remaining
+copies migrate on the recorded triggers. Verify always sees everything
+its fixtures seed: the sandbox is the doctor's own world, and a seed
+named `*.test.ts` is deliberate test data.
+
+## Rule query
+
+A composite structural question asked through `ctx.search.rule`: a
+pattern to match, optionally constrained by `inside` (the enclosing
+construct, scanned to that node's end by default — `stopBy`,
+deliberately not ast-grep's own neighbor default). Answers arrive as
+Matches carrying end positions and metavariable captures;
+multi-metavariables (`$$$NAME`) arrive as arrays of nodes under the bare
+NAME, separator commas filtered at the seam. The surface is curated —
+pattern + inside — and validated: unknown keys fail loudly with the
+allowed list. The plural form (`ctx.search.rules`) asks many named
+rules in one engine invocation — every match tagged with its ruleId —
+because each call is a process spawn and batching is how a many-shape
+check stays fast.
+
+## Analysis query
+
+An identity question asked through `ctx.analysis`: which **Binding** a
+name resolves to, and every **Reference** to it. `ctx.analysis.bindings(file)`
+returns the file's whole identity model in one answer — every binding
+with its declaration span and its references (positions in ctx.search's
+convention, plus read/write). The engine is optional (oxc-parser +
+eslint-scope behind the Engine seam's second adapter): checks declare
+the analysis they need on their CheckMeta (`needs`), narrow without it,
+and the report renders "narrowed" — a degraded run is visible, never
+silent. References answer by position, so analysis queries compose with
+rule queries: shapes from one engine, identities from the other.
+
 ## Engine
 
 The structural-search backend a DoctorCtx uses to answer ctx.search.
-ast-grep is the engine today; oxc is a candidate for TypeScript-heavy
-repos. Engine selection is invisible to doctor programs: one doctor
-program runs unchanged on any engine. One module owns the invocation
-(src/engine.ts); the search host sits on it, and the sdk asks the host —
-there is exactly one path, with no unconfined fallback.
+ast-grep is the engine today; the identity engine (ctx.analysis) is its
+second adapter — oxc-parser + eslint-scope, optional by design. Engine
+selection is invisible to doctor programs: one doctor program runs
+unchanged on any engine. One module owns each invocation
+(src/engine.ts, src/analysis.ts); the search and analysis hosts sit on
+them, and the sdk asks the hosts — there is exactly one path, with no
+unconfined fallback.
+
+## Score
+
+The share of scanned files with no findings, weighted by each affected
+file's worst severity (error 1, warning 0.5, info 0.1). One sentence,
+locally computed: "491/628 files clean" is a 78. Zero findings is 100 by
+anchor; an empty scan computes 100 but renders n/a — "Score: n/a — no
+files scanned," yellow tone, empty bar, and no clean claim anywhere
+(nothing was measured, so nothing is Excellent); the report also carries
+the one-copy empty-scan warning naming the extensions and the skips.
+The denominator is the target's file
+count as the doctors scanned it (default extensions); findings naming
+files outside that count can push the raw value negative, so the result
+is floored into 0–100 — and floored, never rounded, so any finding costs
+at least one point. Findings duplicated across doctors at the same
+file:line are deduplicated before scoring — the first-sorted copy wins
+(groups sort by the first finding carrying an explicit severity
+override, else the doctor's declared default; equal-severity groups
+fall back to input order) and a hidden duplicate's severity does not
+contribute. Each doctor also carries its own score — its findings
+against the same denominator — shown on its dashboard row; the
+dashboard header carries the selected doctor's score, never a cohort
+total (a total mixed doctors into one number that read as whichever row
+was on screen). A doctor's score is its own health, not a share of the
+repo score (a file's worst finding counts once repo-wide). The report
+header keeps the repo-wide score — one number for a run is the job
+there. The score summarizes health — the findings are the work; the two
+are reported together, never conflated.
 
 ## Meta
 
@@ -92,8 +222,21 @@ known input.
 ## Fixture
 
 One seed plus the findings expected from running a doctor program against
-it. Expected findings match exactly on (file, line): a missing expected
-finding is a recall failure; an unexpected finding is a precision failure.
+it. Expected findings match exactly on (rule, file, line), duplicates
+counted: a missing expected finding is a recall failure; an unexpected
+finding is a precision failure. The rule in an expectation is part of the
+match — a wrong-check finding at the right line fails the gate. A fixture
+also declares its analysis mode (D20 Stage 2): "on" (default) pins the
+full-power path and skips with a named notice where the engine is not
+installed; "off" forces the degraded path, whose expectations may
+legitimately differ.
+
+## Counter-fixture
+
+A fixture authored adversarially after the doctor is green: lookalikes,
+same-line variants, and semantic traps, each expectation reasoned from the
+intent alone — never from what the doctor currently reports. The generate
+workflow's second pass; a doctor ships only after surviving its attack.
 
 ## Verify
 
@@ -105,7 +248,11 @@ passes.
 
 The process boundary that loads a doctor program, injects ctx, and
 returns framed results. Today a local node child process; the same
-contract must hold for any future sandbox.
+contract must hold for any future sandbox. A cohort run also exposes a
+settle-order progress side channel — one event per doctor as it settles
+(out of order under concurrency), carrying programPath, ok, durationMs,
+total — consumed by presentation (the live line); the runner never
+blocks on it and results stay order-preserved.
 
 ## Registry
 
@@ -116,13 +263,17 @@ discovery reads it directly, with no separate index or cache.
 ## Scope
 
 Where a doctor program lives: repo-local (`./doctors/`, committed with
-the consuming repo) or user-global (`~/.any-doctor/doctors/`, available
-in every repo). Repo-local wins slug collisions. Scanning a target repo
+the consuming repo), user-global (`~/.any-doctor/doctors/`, available
+in every repo), or bundled (the first-party pack inside the package,
+read-only — a starting point, not a dependency). Repo-local wins slug
+collisions, then user-global, then bundled. Scanning a target repo
 never writes to any scope.
 
 ## Skill
 
 The instructions any-doctor provides so an agent can create a doctor that
-fits the contract. Planted as `AGENTS.md` in a scope directory and also
-served verbatim by `generate`. Any Doctor equips agents with the skill;
+fits the contract. Planted as `AGENTS.md` behind a one-line provenance
+marker; `generate` refreshes a copy it planted (the marker is the
+boundary) and never touches a copy without one. The generation prompt
+embeds the skill verbatim. Any Doctor equips agents with the skill;
 it never launches, deploys, or speaks for an agent.

package/README.md

@@ -2,67 +2,130 @@
 
 > Your agent writes the analyzer. Fixtures prove it. CI reruns it forever.
 
-Any Doctor turns a one-sentence convention ("find `.map(async ...)` results
-that are never awaited") into a **doctor program** — a small piece of
-analysis code your LLM writes against our typed `ctx` API. The CLI runs it
-and renders a React-Doctor-style report: score, grouped findings with
-file:line evidence, declared blind spots, an interactive review browser,
-and a copy-paste handoff so your agent can fix what was found. The saved
-program reruns deterministically in CI with zero inference.
+Your LLM writes code fast and roughly. **Doctors** are small deterministic
+programs that catch what it keeps getting wrong — and any-doctor ships with
+five of them covering the disciplines LLMs fumble most.
 
-Any Doctor equips agents; it never deploys them. Everything runs locally.
-No Cloudflare, no API keys, no server.
+When none of them covers the convention you keep explaining in code review,
+your agent writes a new doctor for it — against a typed `ctx` API, gated by
+fixtures, rerun forever in CI with zero inference. **A skill without a doctor
+is a suggestion.**
 
-## Usage
+Everything runs locally. No account, no API key, no telemetry, no network.
+
+[![npm version](https://img.shields.io/npm/v/any-doctor.svg)](https://www.npmjs.com/package/any-doctor)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#)
+
+## Quick start
+
+```bash
+npx any-doctor@latest
+```
+
+That's it — a selector lists every doctor (bundled plus anything in your
+repo's `doctors/`), you pick with the space bar, `a` takes all, and the
+findings land in an interactive review tree: doctors → checks → findings,
+each with impact, why, fix, and the honest blind spots. `enter` copies a
+fix prompt for your agent.
+
+```bash
+npx any-doctor@latest run slop-doctor   # one doctor, straight to the report
+```
+
+Non-terminals and CI never see a prompt — output is stable and pipeable
+(`--format json`, or `ANY_DOCTOR_HEADLESS=1`).
+
+## The bundled pack
+
+| Doctor | Discipline | Checks |
+|---|---|---:|
+| **slop-doctor** | The recurring failures of LLM-written code: identical helpers copied across modules, dead exports, unread bindings, hostname-sniffed environments, careless substring matching, collapsed boolean states | 8 |
+| **convex-doctor** | Convex discipline: indexed reads, bounded collects, validated args, awaited writes, honest runtime boundaries | 15 |
+| **effect-v4-doctor** | Effect v4 discipline — the mechanical rules of the [kitlangton Effect skill](https://www.ui-skills.com/skills/kitlangton/effect), enforced | 10 |
+| **openrouter-doctor** | OpenRouter discipline: stream errors surfaced, keep-alives skipped, cancellations that stop billing | 5 |
+| **async-doctor** | Async and concurrency: dropped promise results, uncleared timers, fetch hygiene | 3 |
+
+Every check ships with fixtures proving both directions — it fires on the
+shapes it claims (recall) and stays silent on innocent lookalikes
+(precision). 144 fixtures across the pack, run by `verify` as an exact
+multiset on `rule:file:line`. slop-doctor's checks were born from 1,368
+Bugbot findings across 182 reviewed PRs — every check carries its evidence.
+
+## Write your own
 
 ```bash
-any-doctor generate "find fetch calls without an AbortSignal"   # copies the exact prompt for your agent
-any-doctor verify doctors/fetch-without-abort-signal.mjs        # fixture gate (exact-set)
-any-doctor run doctors/fetch-without-abort-signal.mjs path/to/repo   # scan + score + report + review menu
+npx any-doctor@latest generate "find .map(async ...) results that are never awaited"
 ```
 
-`generate` plants the skill as `AGENTS.md` in the scope dir (agents load it
-natively) and copies the generation prompt — paste it into your own agent
-session, any agent, GUI or CLI. When it has written the doctor + fixtures,
-`verify` gates it: missing expected findings fail recall, unexpected ones
-fail precision. `run` and `verify` never touch a model or an agent — pipe
-the output (or set `ANY_DOCTOR_HEADLESS=1`) for stable CI output. Requires
-Node ≥ 18.
-
-A doctor program is `<name>.mjs` (exports `meta` + `doctor(ctx)`) next to
-its fixture module `<name>.fixtures.mjs` (seeds + expected findings).
-See [CONTEXT.md](CONTEXT.md) for the vocabulary and
-[doctors/async-doctor.mjs](doctors/async-doctor.mjs) for a working
-example: one doctor, many checks — async hygiene as a category, with
-per-check fixtures and the interactive check tree in `run`.
+`generate` plants the authoring skill as `AGENTS.md` (agents load it
+natively) and copies a prompt. Paste it into any agent session. The agent
+writes two files:
+
+- `doctors/your-doctor.mjs` — the analyzer: `meta` (checks, blind spots,
+  severity) + `doctor(ctx)`. One self-contained file; `ctx` is its entire
+  world (files, structural search via ast-grep, binding analysis, findings).
+- `doctors/your-doctor.fixtures.mjs` — the proof: seed codebases plus the
+  findings the doctor must produce, and the lookalikes it must ignore.
+
+Then the loop agents love:
+
+```bash
+npx any-doctor@latest verify doctors/your-doctor.mjs
+#   ✖ flags a bare discarded map result
+#     missing expected finding src/a.ts:3        ← your error list
+#   ✔ accepts an awaited result
+```
+
+`missing` fails recall, `unexpected` fails precision, the exit code stays
+non-zero until every fixture passes — and the skill teaches the sharp edges
+(scope-analysis semantics, fixture-seed worlds, the adversarial
+counter-fixture pass) so the loop converges fast. No install needed;
+`verify` sandboxes everything.
+
+## CI: the gate
+
+```bash
+npx any-doctor@latest run --all --fail-on warning --base origin/main
+```
+
+- `--fail-on none|error|warning|info` — the severity bar
+- `--base <git ref>` — a stateless diff baseline: **only findings your
+  change introduced fail the build**, not your existing backlog
+- `--format json` — machine output for pipelines
+
+```yaml
+# .github/workflows/doctor.yml
+- run: npx any-doctor@latest run --all --fail-on warning --base origin/main
+```
+
+## Why trust a finding
+
+- **Deterministic.** The same doctor on the same commit produces the same
+  report — no model runs at scan time, ever.
+- **Fixtures gate everything.** A doctor that hasn't passed `verify` doesn't
+  exist; discovery lists it as broken, not as a tool.
+- **Blind spots are data.** Every doctor declares what it cannot see, and
+  the report renders those declarations beside the findings.
+- **Doctors are confined.** The runtime capability gate refuses to execute
+  a doctor that imports, writes, spawns, or touches the network — a
+  malicious doctor is refused before it runs, with no override.
+- **The score is the share of clean files**, per doctor and overall —
+  health and work are reported together, never conflated.
 
 ## Docs
 
 | Doc | What it holds |
 |---|---|
+| [skill/any-doctor.skill.md](skill/any-doctor.skill.md) | The authoring contract — what your agent reads to write doctors |
 | [CONTEXT.md](CONTEXT.md) | Domain glossary — canonical terms |
-| [docs/decisions.md](docs/decisions.md) | Decision log (D1–D16). Read first; don't relitigate |
-| [docs/vision.md](docs/vision.md) | Product idea and the lifecycle novelty |
-| [docs/features.md](docs/features.md) | Doctor discovery & registry spec + status |
-| [docs/research.md](docs/research.md) | Landscape, React Doctor teardown |
+| [docs/decisions.md](docs/decisions.md) | Decision log (D1–D20). Read first; don't relitigate |
+| [docs/vision.md](docs/vision.md) | The product idea and lifecycle novelty |
 | [docs/kill-test.md](docs/kill-test.md) + [docs/RESULTS.md](docs/RESULTS.md) | The validation experiment and its numbers |
-| [docs/REPAIR-LOG.md](docs/REPAIR-LOG.md) | Generation-bug categories — feeds the generation skill |
+| [docs/REPAIR-LOG.md](docs/REPAIR-LOG.md) | Generation-bug categories — feeds the authoring skill |
 | [docs/example-catalog.md](docs/example-catalog.md) | Rule intents across the JS ecosystem |
 
-## Where we are (2026-09-03)
-
-1. ✅ Contract v0, verify harness, pilot doctor, kill test, packaging
-2. ✅ Generation: skill + prompt handoff (D14 — copy-based, agent-agnostic)
-3. ✅ UI layer: score header, category rollup, review browser, post-report menu
-4. ✅ Discovery & registry: fuzzy picker, repo-local + global scopes, `--all` batch modes
-5. ⬜ Frozen-fixture protocol + authored eval corpus (the trust upgrade — first-shot 10/10 is currently self-graded)
-6. ⬜ Grow `ctx`: symbols/imports resolution, JS-family languages
-7. ⬜ Publish: npm, GitHub, CI workflow, launch post
-
-## Principles
+## Status
 
-- The report comes from the generated program's evidence, not the LLM's opinion.
-- Fixtures gate everything: a doctor that hasn't passed `verify` doesn't exist.
-- Programs declare their blind spots as data.
-- Any Doctor equips agents; it never launches, deploys, or speaks for them.
-- Everything runs locally. The runner seam (today a node child process) is where any future sandbox plugs in.
+Pre-1.0 and moving fast — the decision log is the honest history. Next on
+the ladder: the registry (`any-doctor add <slug>`), adoption (`init`), and
+a growing pack. MIT.

package/bin/analysis-host.d.ts

@@ -0,0 +1,20 @@
+import { AnalysisFile, Mode } from "./contract.js";
+import { analysisStatus, analyzeBindings } from "./analysis.js";
+type Analyzer = typeof analyzeBindings;
+type Status = typeof analysisStatus;
+export declare function clearAnalysisCache(): void;
+export interface AnalysisRequestBody {
+    kind?: unknown;
+    file?: unknown;
+    root?: unknown;
+}
+export type AnalysisResponse = {
+    available: boolean;
+    reason?: string;
+} | {
+    file: AnalysisFile;
+} | {
+    error: string;
+};
+export declare function handleAnalysisRequest(req: AnalysisRequestBody, mode: Mode, analyzer?: Analyzer, status?: Status): AnalysisResponse;
+export {};

package/bin/analysis-host.js

@@ -0,0 +1,56 @@
+import * as fs from "fs";
+import * as path from "path";
+import { analysisStatus, analyzeBindings } from "./analysis.js";
+import { searchBase, withinBase } from "./search-host.js";
+// One cache per host process. The host lives in the runner process, so
+// the lifetime is the any-doctor invocation; across a cohort's doctors
+// the same unchanged file answers from memory.
+const modelCache = new Map();
+// Test seam: the model cache is keyed by mtime+size for the process
+// lifetime; tests bust it between cases. Invisible to slop-doctor's
+// default run (test-file consumers are the documented narrowing).
+export function clearAnalysisCache() {
+    modelCache.clear();
+}
+export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, status = analysisStatus) {
+    const base = searchBase(mode);
+    const root = typeof req.root === "string" ? path.resolve(req.root) : "";
+    if (base === "" || !withinBase(root, base)) {
+        return { error: "ctx.analysis failed: analysis root is outside the allowed target" };
+    }
+    if (req.kind === "available") {
+        const s = status();
+        return s.available ? { available: true } : { available: false, reason: s.reason };
+    }
+    if (req.kind === "bindings") {
+        if (typeof req.file !== "string" || req.file === "") {
+            return { error: 'ctx.analysis.bindings needs a "file" path' };
+        }
+        const abs = path.resolve(root, req.file);
+        if (!withinBase(abs, root)) {
+            return { error: `ctx.analysis failed: file is outside the search root: ${req.file}` };
+        }
+        let source;
+        let mtimeMs;
+        let size;
+        try {
+            const stat = fs.statSync(abs);
+            mtimeMs = stat.mtimeMs;
+            size = stat.size;
+            const cached = modelCache.get(abs);
+            if (cached && cached.mtimeMs === mtimeMs && cached.size === size)
+                return { file: cached.file };
+            source = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            return { error: `ctx.analysis failed: cannot read ${req.file}` };
+        }
+        const rel = path.relative(root, abs);
+        const r = analyzer(rel, source);
+        if (!r.ok)
+            return { error: r.error };
+        modelCache.set(abs, { mtimeMs, size, file: r.file });
+        return { file: r.file };
+    }
+    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: available, bindings` };
+}

package/bin/analysis.d.ts

@@ -0,0 +1,18 @@
+import { AnalysisFile, BindingInfo, BindingRef } from "./contract.js";
+export type { AnalysisFile, BindingInfo, BindingRef };
+export interface AnalysisStatus {
+    available: true;
+}
+export type AnalysisStatusResult = AnalysisStatus | {
+    available: false;
+    reason: string;
+};
+export declare function analysisStatus(): AnalysisStatusResult;
+export type AnalysisResult = {
+    ok: true;
+    file: AnalysisFile;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function analyzeBindings(file: string, source: string): AnalysisResult;

package/bin/analysis.js

@@ -0,0 +1,143 @@
+import { createRequire } from "module";
+let loaded = null;
+const require_ = createRequire(import.meta.url);
+function loadStack() {
+    if (loaded !== null)
+        return loaded;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { parseSync } = require_("oxc-parser");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { analyze } = require_("eslint-scope");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const keys = require_("eslint-visitor-keys");
+        loaded = { parseSync, analyze, keys };
+    }
+    catch (e) {
+        loaded = { error: `the analysis engine is not installed (${e instanceof Error ? e.message : String(e)}) — npm install oxc-parser` };
+    }
+    return loaded;
+}
+export function analysisStatus() {
+    const stack = loadStack();
+    return stack.error !== undefined ? { available: false, reason: stack.error } : { available: true };
+}
+// One file in, one identity model out: every binding (declarations,
+// parameters, imports) with the span of its declaring node and every
+// reference to it, read or write. Type-position identifiers never become
+// references (eslint-scope only resolves value positions); TS-only
+// declarations (enums, namespaces) are not modeled — declared blind-spot
+// territory for checks that care.
+export function analyzeBindings(file, source) {
+    var _a;
+    const stack = loadStack();
+    if (stack.error !== undefined)
+        return { ok: false, error: stack.error };
+    let program;
+    try {
+        program = stack.parseSync(file, source, { sourceType: "module" }).program;
+    }
+    catch (e) {
+        return { ok: false, error: `analysis failed to parse ${file}: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    addRanges(program);
+    let scopeManager;
+    try {
+        scopeManager = stack.analyze(program, {
+            sourceType: "module",
+            ecmaVersion: 2026,
+            childVisitorKeys: stack.keys.KEYS,
+        });
+    }
+    catch (e) {
+        return { ok: false, error: `analysis failed to resolve scopes in ${file}: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const pos = positioner(source);
+    const bindings = [];
+    const global = scopeManager.globalScope;
+    if (global === null)
+        return { ok: false, error: `analysis failed to resolve scopes in ${file}` };
+    for (const scope of allScopes(global)) {
+        for (const variable of scope.variables) {
+            const def = variable.defs[0];
+            if (def === undefined)
+                continue; // builtins and implicit globals carry no def
+            // The declaration's own extent: for variables the declarator (so a
+            // binding's span contains its initializer), for parameters the
+            // identifier itself (eslint-scope hands the whole function node for
+            // params, which would swallow the body).
+            const node = def.node;
+            const span = def.type === "Parameter" ? def.name.range : ((_a = node === null || node === void 0 ? void 0 : node.range) !== null && _a !== void 0 ? _a : def.name.range);
+            if (span === undefined)
+                continue;
+            bindings.push({
+                name: variable.name,
+                kind: def.type,
+                line: pos.line(span[0]),
+                column: pos.column(span[0]),
+                endLine: pos.line(span[1]),
+                endColumn: pos.column(span[1]),
+                references: variable.references
+                    .filter((r) => r.identifier.range !== undefined)
+                    .map((r) => ({
+                    line: pos.line(r.identifier.range[0]),
+                    column: pos.column(r.identifier.range[0]),
+                    endLine: pos.line(r.identifier.range[1]),
+                    endColumn: pos.column(r.identifier.range[1]),
+                    write: r.isWrite(),
+                })),
+            });
+        }
+    }
+    return { ok: true, file: { file, bindings } };
+}
+// eslint-scope expects `range: [start, end]` on nodes; oxc emits start/end.
+function addRanges(node) {
+    if (!node || typeof node !== "object")
+        return;
+    const n = node;
+    if (typeof n.start === "number" && typeof n.end === "number")
+        n.range = [n.start, n.end];
+    for (const key of Object.keys(n)) {
+        if (key === "range" || key === "start" || key === "end")
+            continue;
+        const v = n[key];
+        if (Array.isArray(v)) {
+            for (const child of v)
+                addRanges(child);
+        }
+        else if (v && typeof v === "object" && typeof v.type === "string") {
+            addRanges(v);
+        }
+    }
+}
+function allScopes(scope, out = []) {
+    out.push(scope);
+    for (const child of scope.childScopes)
+        allScopes(child, out);
+    return out;
+}
+// Byte offset → ctx position conventions, one index per file.
+function positioner(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i += 1) {
+        if (source[i] === "\n")
+            starts.push(i + 1);
+    }
+    return {
+        line: (offset) => lowerBound(starts, offset) + 1,
+        column: (offset) => offset - starts[lowerBound(starts, offset)],
+    };
+}
+function lowerBound(sorted, value) {
+    let lo = 0;
+    let hi = sorted.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (sorted[mid] <= value)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}