@orangepro/orangepro-mcp 0.1.0

package/dist/local/resolve/importGraph.js

@@ -0,0 +1,347 @@
+// Import graph + per-category resolution metrics (Gate 1 / G-RESOLVE, Phase 1).
+//
+// Two layers, kept separate from the resolver (resolver.ts is the source of truth
+// for resolution targets):
+//   1. classifySpecifier — bucket each import specifier by INTENT (asset, relative,
+//      path-alias, baseUrl-internal, bare-external, node-builtin), using tsconfig
+//      context for the alias/baseUrl categories. Ported from the resolver spike.
+//   2. buildImportGraph — extract imports per file via a `ts.createSourceFile`
+//      pass (type-only vs runtime aware, with imported binding names), resolve
+//      each via resolver.ts, and aggregate the per-category gate metrics.
+//
+// The `test_to_source` axis gates static association diagnostics
+// (see private/spikes/gate-specs-digest.md §resolver B). The internal denominator
+// EXCLUDES asset, node-builtin, and bare-external/external — those are not modules
+// we expect to resolve inside the repo.
+//
+// Phase 1 PR-2 (this file): the `barrel_terminal` and `workspace_package` gate
+// axes are computed here, the former by walking each test->source barrel import
+// through the barrel walker (barrelWalker.ts) to a terminal defining file. The
+// remaining `changed_scope` axis needs a diff (a later PR), and wiring these
+// resolved terminals into the analyzer's TESTED_BY edges is Phase 2.
+import ts from "typescript";
+import fs from "node:fs";
+import path from "node:path";
+import { loadTsConfigFor, resolveImport } from "./resolver.js";
+import { computeResolverGate } from "./resolverCache.js";
+import { buildExportIndex } from "./exportIndex.js";
+import { walkBarrel } from "./barrelWalker.js";
+import { isTestFile } from "../analyze/classify.js";
+const EMPTY_CONTEXT = { pathAliasKeys: [], baseUrlTopLevel: new Set() };
+const ASSET_RE = /\.(scss|sass|css|less|styl|png|jpe?g|gif|svg|webp|ico|bmp|woff2?|ttf|eot|otf|mp4|webm|mp3|wav|avif)$/i;
+function isAssetSpecifier(spec) {
+    return ASSET_RE.test(spec);
+}
+function matchesPathAlias(spec, keys) {
+    return keys.some((k) => {
+        if (k.includes("*")) {
+            const base = k.slice(0, k.indexOf("*")); // TS wildcard = prefix match
+            return spec.startsWith(base);
+        }
+        return spec === k; // exact alias: exact match only
+    });
+}
+function isBaseUrlInternal(spec, ctx) {
+    if (ctx.baseUrlTopLevel.size === 0)
+        return false;
+    const firstSeg = spec.split("/")[0];
+    return ctx.baseUrlTopLevel.has(firstSeg);
+}
+/**
+ * Classify an import specifier by intent. `ctx` supplies the tsconfig `paths`
+ * keys and `baseUrl` top-level names so alias/baseUrl-internal specifiers are
+ * recognized even when (webpack-only) aliases fail TS resolution.
+ */
+export function classifySpecifier(spec, ctx = EMPTY_CONTEXT) {
+    if (isAssetSpecifier(spec))
+        return "asset";
+    if (spec.startsWith(".") || path.isAbsolute(spec)) {
+        if (/\.(js|jsx|mjs|cjs)$/.test(spec))
+            return "rel-js-specifier"; // NodeNext .js -> .ts hazard
+        if (/\.(ts|tsx|mts|cts)$/.test(spec))
+            return "rel-ts-ext";
+        return "rel-extensionless";
+    }
+    if (/^node:/.test(spec))
+        return "node-builtin";
+    if (matchesPathAlias(spec, ctx.pathAliasKeys))
+        return "path-alias";
+    if (isBaseUrlInternal(spec, ctx))
+        return "baseurl-internal";
+    return "bare-external";
+}
+/**
+ * Build the classify context (path-alias keys + baseUrl top-level names) for a
+ * file from its nearest tsconfig scope. Cached implicitly via loadTsConfigFor.
+ */
+export function classifyContextFor(file) {
+    const scope = loadTsConfigFor(file);
+    const options = scope.options;
+    const pathAliasKeys = Object.keys(options.paths ?? {});
+    const baseUrlTopLevel = new Set();
+    if (options.baseUrl) {
+        const baseUrlDir = path.resolve(scope.configPath.startsWith("<") ? process.cwd() : path.dirname(scope.configPath), options.baseUrl);
+        try {
+            for (const entry of fs.readdirSync(baseUrlDir, { withFileTypes: true })) {
+                baseUrlTopLevel.add(entry.name.replace(/\.[mc]?[tj]sx?$/, ""));
+            }
+        }
+        catch {
+            /* no baseUrl dir on disk */
+        }
+    }
+    return { pathAliasKeys, baseUrlTopLevel };
+}
+/**
+ * Extract imports from a file via a lightweight `ts.createSourceFile` pass (no
+ * Program / no typecheck). Unlike `ts.preProcessFile`, this distinguishes
+ * `import type` / type-only re-exports from runtime imports — type-only edges
+ * must NOT count toward static assertion diagnostics — and carries each static import's
+ * binding names. Covers static imports/exports, dynamic `import("lit")`, and
+ * `require("lit")` with a string-literal argument.
+ */
+export function extractImports(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, /*setParentNodes*/ false);
+    const imports = [];
+    const moduleText = (node) => node && ts.isStringLiteralLike(node) ? node.text : null;
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node)) {
+            const specifier = moduleText(node.moduleSpecifier);
+            if (specifier !== null) {
+                imports.push({ specifier, kind: importDeclarationKind(node), bindings: importBindings(node) });
+            }
+        }
+        else if (ts.isExportDeclaration(node) && node.moduleSpecifier) {
+            // Re-export: `export ... from "lit"`. Type-only when `export type ... from`.
+            const specifier = moduleText(node.moduleSpecifier);
+            if (specifier !== null) {
+                imports.push({ specifier, kind: node.isTypeOnly ? "type" : "runtime", bindings: [] });
+            }
+        }
+        else if (ts.isCallExpression(node)) {
+            // Dynamic `import("lit")` or `require("lit")` with a string-literal arg.
+            const isDynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+            const isRequire = ts.isIdentifier(node.expression) && node.expression.text === "require";
+            // TODO(low): a concatenated dynamic-import arg yields a phantom specifier; ignored.
+            if (isDynamicImport || isRequire) {
+                const specifier = moduleText(node.arguments[0]);
+                if (specifier !== null)
+                    imports.push({ specifier, kind: "runtime", bindings: [] });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return imports;
+}
+/**
+ * Imported binding names for a static import: a default binding, a namespace
+ * (`* as ns`, recorded as imported "*"), and/or named imports (carrying any
+ * `as` rename's SOURCE name). Side-effect imports bind nothing.
+ */
+function importBindings(node) {
+    const clause = node.importClause;
+    if (!clause)
+        return [];
+    const out = [];
+    if (clause.name)
+        out.push({ local: clause.name.text, imported: "default" });
+    const named = clause.namedBindings;
+    if (named && ts.isNamespaceImport(named)) {
+        out.push({ local: named.name.text, imported: "*" });
+    }
+    else if (named && ts.isNamedImports(named)) {
+        for (const el of named.elements) {
+            if (el.isTypeOnly)
+                continue; // `import { type X }`: a type binding, not a runtime use
+            out.push({ local: el.name.text, imported: (el.propertyName ?? el.name).text });
+        }
+    }
+    return out;
+}
+/**
+ * Type-only iff the clause is `import type ...`, OR there is no default binding
+ * AND no namespace import AND it has named bindings of which EVERY element is
+ * itself `isTypeOnly` (i.e. `import { type A, type B } from ...`). Otherwise runtime.
+ */
+function importDeclarationKind(node) {
+    const clause = node.importClause;
+    if (!clause)
+        return "runtime"; // side-effect import: `import "lit"` runs code
+    if (clause.isTypeOnly)
+        return "type";
+    const named = clause.namedBindings;
+    const hasNamedElements = named !== undefined && ts.isNamedImports(named);
+    if (clause.name === undefined && !(named && ts.isNamespaceImport(named)) && hasNamedElements) {
+        const elements = named.elements;
+        if (elements.length > 0 && elements.every((el) => el.isTypeOnly))
+            return "type";
+    }
+    return "runtime";
+}
+/**
+ * Thin specifier-only wrapper over `extractImports`, preserving the original
+ * `string[]` shape for callers that do not need the runtime/type distinction.
+ */
+export function extractSpecifiers(file) {
+    return extractImports(file).map((imp) => imp.specifier);
+}
+/** An internal-intent specifier is expected to resolve inside the repo. */
+function isInternalCategory(category) {
+    return (category === "rel-js-specifier" ||
+        category === "rel-ts-ext" ||
+        category === "rel-extensionless" ||
+        category === "path-alias" ||
+        category === "baseurl-internal");
+}
+/** An edge counts toward the INTERNAL denominator: internal-intent AND not external. */
+function isInternalEdge(edge) {
+    return isInternalCategory(edge.category) && !edge.external;
+}
+function axis(edges, predicate) {
+    const subset = edges.filter(predicate);
+    const resolved = subset.filter((e) => e.resolved).length;
+    const n = subset.length;
+    return { n, resolved, pct: n ? Number(((100 * resolved) / n).toFixed(1)) : null };
+}
+/**
+ * workspace_package axis: of path-alias + baseUrl-internal imports (the
+ * workspace/project-ref style), how many resolve to an INTERNAL target. An
+ * alias that RESOLVES into node_modules is conclusively a vendor shim, not
+ * workspace code — it leaves the DENOMINATOR entirely (it is not a
+ * workspace-resolution failure). An UNRESOLVED alias stays in the denominator:
+ * it was internal-intent and genuinely failed.
+ */
+function workspacePackageAxis(edges) {
+    const subset = edges.filter((e) => (e.category === "path-alias" || e.category === "baseurl-internal") && !(e.resolved && e.external));
+    const n = subset.length;
+    const resolved = subset.filter((e) => e.resolved).length;
+    return { n, resolved, pct: n ? Number(((100 * resolved) / n).toFixed(1)) : null };
+}
+/**
+ * barrel_terminal axis: among test->source RUNTIME imports that resolve to a
+ * BARREL file and carry at least one named/default binding, how many walk
+ * through the re-export chain so that EVERY such binding reaches a COVERS-eligible terminal
+ * (runtime; type-only terminals and type-only re-export hops do NOT count). Namespace-only imports are excluded (cannot be attributed to a
+ * single terminal without binding-use analysis). This is a health metric; the
+ * per-link COVERS upgrade lands in Phase 2.
+ */
+function barrelTerminalAxis(edges) {
+    let n = 0;
+    let resolved = 0;
+    for (const e of edges) {
+        if (e.fromRole !== "test")
+            continue;
+        if (!isInternalEdge(e))
+            continue;
+        if (e.importKind !== "runtime")
+            continue;
+        if (!e.resolved || !e.target)
+            continue;
+        if (e.targetRole === "test")
+            continue;
+        const namedOrDefault = e.bindings.filter((b) => b.imported !== "*");
+        if (namedOrDefault.length === 0)
+            continue; // namespace-only: cannot attribute to one terminal
+        if (!buildExportIndex(e.target).isBarrel)
+            continue; // only barrel targets are "barrel imports"
+        n += 1;
+        const target = e.target;
+        const allCovered = namedOrDefault.every((b) => walkBarrel(target, b.imported).covered);
+        if (allCovered)
+            resolved += 1;
+    }
+    return { n, resolved, pct: n ? Number(((100 * resolved) / n).toFixed(1)) : null };
+}
+const ALL_CATEGORIES = [
+    "rel-js-specifier",
+    "rel-ts-ext",
+    "rel-extensionless",
+    "path-alias",
+    "baseurl-internal",
+    "bare-external",
+    "node-builtin",
+    "asset"
+];
+/**
+ * Build the import graph for a set of role-tagged files: extract imports,
+ * classify and resolve each, then aggregate the per-category gate metrics.
+ * Returns the edges, the gate axes (`metrics`), and raw per-category counts.
+ */
+export function buildImportGraph(files, opts = {}) {
+    const { repoRoot } = opts;
+    const roleByPath = new Map();
+    for (const f of files)
+        roleByPath.set(path.resolve(f.path), f.role);
+    // Validate the resolution cache against the current filesystem shape + config (gate);
+    // a structural/config change discards all cached resolutions (no stale survival). The
+    // gate + known-target set come from the FULL walked file set (incl. tsconfig/package.json),
+    // so a config edit busts the cache and a cached internal target must be a real walked file.
+    const rcache = opts.resolverCache;
+    const gateFiles = opts.gateFiles ?? files.map((f) => f.path);
+    if (rcache)
+        rcache.useGate(computeResolverGate(gateFiles));
+    const targetRoleOf = (target) => {
+        if (!target)
+            return null;
+        const known = roleByPath.get(path.resolve(target));
+        if (known)
+            return known;
+        // Classify on a repo-relative path (or basename fallback) so `tests/`/`spec/`
+        // ANCESTOR dir segments in the absolute path don't misclassify a source target.
+        const rel = repoRoot ? path.relative(repoRoot, target) : path.basename(target);
+        return isTestFile(rel) ? "test" : "source";
+    };
+    const edges = [];
+    for (const file of files) {
+        const ctx = classifyContextFor(file.path);
+        for (const imp of extractImports(file.path)) {
+            const category = classifySpecifier(imp.specifier, ctx);
+            const r = rcache
+                ? rcache.resolve(path.dirname(file.path), imp.specifier, () => resolveImport(imp.specifier, file.path))
+                : resolveImport(imp.specifier, file.path);
+            edges.push({
+                from: file.path,
+                fromRole: file.role,
+                specifier: imp.specifier,
+                category,
+                importKind: imp.kind,
+                bindings: imp.bindings,
+                resolved: r.resolved,
+                target: r.resolvedFileName,
+                targetRole: targetRoleOf(r.resolvedFileName),
+                external: r.isExternal
+            });
+        }
+    }
+    const isTestInternal = (e) => e.fromRole === "test" && isInternalEdge(e);
+    const metrics = {
+        all_internal: axis(edges, isInternalEdge),
+        test_file: axis(edges, (e) => e.fromRole === "test"),
+        // All internal imports from a test file — the test-health denominator.
+        test_internal: axis(edges, isTestInternal),
+        // Internal test imports that resolve to another test file (test helpers etc.).
+        test_to_test: axis(edges, (e) => isTestInternal(e) && e.resolved && e.targetRole === "test"),
+        // THE confirmed-coverage gate: internal RUNTIME test imports that are not
+        // test->test. Type-only and test->test are excluded; an unresolved-internal
+        // still counts in the denom, so a real resolution failure lowers the gate.
+        test_to_source: axis(edges, (e) => isTestInternal(e) && e.importKind === "runtime" && !(e.resolved && e.targetRole === "test")),
+        // Diagnostic: internal test imports that failed to resolve at all.
+        test_unresolved_internal: axis(edges, (e) => isTestInternal(e) && !e.resolved),
+        source_to_source: axis(edges, (e) => e.fromRole === "source" && isInternalEdge(e)),
+        barrel_terminal: barrelTerminalAxis(edges),
+        workspace_package: workspacePackageAxis(edges)
+    };
+    const byCategory = {};
+    for (const cat of ALL_CATEGORIES) {
+        byCategory[cat] = axis(edges, (e) => e.category === cat);
+    }
+    return { edges, metrics, byCategory };
+}

package/dist/local/resolve/resolver.js

@@ -0,0 +1,122 @@
+// TypeScript import resolver (Gate 1 / G-RESOLVE, Phase 1 PR-1).
+//
+// Source of truth for "what does this import point to." Uses the TypeScript
+// compiler API (`ts.resolveModuleName`) — the same resolver the rewrite adopts
+// for "confirmed" coverage. This module is SEPARATE from any parser: the parser
+// extracts specifiers (see importGraph.ts), this module turns a specifier +
+// containing file into a resolved terminal file.
+//
+// Productionized from private/spikes/resolver/resolve-spike.mjs (spiked GREEN:
+// test->source resolution ~100% on this NodeNext repo and the Mattermost bundler
+// repo). It honors each file's NEAREST tsconfig so NodeNext (.js->.ts rewrite)
+// and bundler (paths/baseUrl) repos each resolve under their own options.
+import ts from "typescript";
+import fs from "node:fs";
+import path from "node:path";
+/** Sane NodeNext defaults when no tsconfig is found walking up from a file. */
+const FALLBACK_OPTIONS = {
+    module: ts.ModuleKind.NodeNext,
+    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    target: ts.ScriptTarget.ES2022,
+    esModuleInterop: true,
+    allowJs: true
+};
+const FALLBACK_KEY = "<nodenext-fallback>";
+// Cache by `configPath + ":" + mtimeMs` (or the fallback key). Walking up the dir
+// tree repeatedly is cheap, but parsing a tsconfig + building a resolution cache is
+// not — so each distinct scope is parsed exactly once per (path, mtime) pair. Keying
+// on mtime means an edited tsconfig busts its own cache entry, so a long-lived MCP
+// process never resolves with a stale tsconfig after edits.
+const scopeCache = new Map();
+// Memoize the nearest-tsconfig lookup per containing directory.
+const nearestConfigByDir = new Map();
+/** Cache key for a tsconfig path: path + its current mtime (0 if unreadable). */
+function scopeCacheKey(configPath) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = fs.statSync(configPath).mtimeMs;
+    }
+    catch {
+        /* unreadable tsconfig — key on mtime 0 */
+    }
+    return `${configPath}:${mtimeMs}`;
+}
+function makeScope(configPath, options) {
+    const moduleResolutionCache = ts.createModuleResolutionCache(path.dirname(configPath === FALLBACK_KEY ? process.cwd() : configPath), (x) => x, options);
+    return { configPath, options, moduleResolutionCache };
+}
+function fallbackScope() {
+    const existing = scopeCache.get(FALLBACK_KEY);
+    if (existing)
+        return existing;
+    const scope = makeScope(FALLBACK_KEY, FALLBACK_OPTIONS);
+    scopeCache.set(FALLBACK_KEY, scope);
+    return scope;
+}
+/** Walk up from `dir` to find the nearest tsconfig.json. Memoized per dir. */
+function findNearestTsConfig(dir) {
+    const memo = nearestConfigByDir.get(dir);
+    if (memo !== undefined)
+        return memo;
+    const found = ts.findConfigFile(dir, ts.sys.fileExists, "tsconfig.json") ?? null;
+    nearestConfigByDir.set(dir, found);
+    return found;
+}
+/** Parse a tsconfig into compiler options, building+caching its scope. */
+function loadScopeForConfig(configPath) {
+    // Key on (path, mtime) so an edited tsconfig busts the cache (stale-scope fix).
+    const key = scopeCacheKey(configPath);
+    const cached = scopeCache.get(key);
+    if (cached)
+        return cached;
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error) {
+        // Unparseable tsconfig — fall back rather than throw; resolution still works
+        // for plain relative/NodeNext imports under defaults.
+        return fallbackScope();
+    }
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath));
+    const scope = makeScope(configPath, parsed.options);
+    scopeCache.set(key, scope);
+    return scope;
+}
+/**
+ * Find the nearest tsconfig.json walking up from `file`'s directory, parse it,
+ * and return its scope (options + a shared module-resolution cache). The scope is
+ * cached by resolved tsconfig path. Falls back to NodeNext defaults when none is
+ * found.
+ */
+export function loadTsConfigFor(file) {
+    const dir = path.dirname(path.resolve(file));
+    const configPath = findNearestTsConfig(dir);
+    if (!configPath)
+        return fallbackScope();
+    return loadScopeForConfig(configPath);
+}
+/**
+ * Resolve a single import `specifier` as seen from `containingFile`, using
+ * `ts.resolveModuleName` under the containing file's nearest-tsconfig options.
+ * `isExternal` comes from TypeScript's own `isExternalLibraryImport` flag.
+ */
+export function resolveImport(specifier, containingFile) {
+    const scope = loadTsConfigFor(containingFile);
+    const result = ts.resolveModuleName(specifier, containingFile, scope.options, ts.sys, scope.moduleResolutionCache);
+    const mod = result.resolvedModule;
+    if (!mod) {
+        return { resolvedFileName: null, isExternal: false, resolved: false };
+    }
+    return {
+        resolvedFileName: mod.resolvedFileName,
+        isExternal: !!mod.isExternalLibraryImport,
+        resolved: true
+    };
+}
+/**
+ * Clear the process-level scope/config caches. Call at the START of each analyze
+ * run so a long-lived MCP process re-reads tsconfigs (and re-walks for new ones)
+ * from a clean slate, in addition to the per-entry mtime invalidation above.
+ */
+export function resetResolverCaches() {
+    scopeCache.clear();
+    nearestConfigByDir.clear();
+}

package/dist/local/resolve/resolverCache.js

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { hashString } from "../util/hash.js";
+/**
+ * Phase 5.4.3 — persistent module-RESOLUTION cache for `ts.resolveModuleName`.
+ *
+ * `ts.resolveModuleName` walks the filesystem, so its answer can change with NO
+ * change to the importer, tsconfig, or package.json — e.g. a NEW file shadows an
+ * older extension (`./foo.js` -> `./foo.ts` once `foo.ts` is added), or the target
+ * is moved/deleted. A naive (importer, specifier, tsconfig) key would silently
+ * serve a stale resolution -> a wrong COVERS edge.
+ *
+ * The invalidation story is a GLOBAL GATE: the whole cache is trusted only while
+ * the filesystem SHAPE and resolution config are unchanged. The gate =
+ * RESOLVER_VERSION + the sorted file-path set + the content of every JSON config
+ * (and lockfile). Any of:
+ *   - a file added / removed / renamed (path set changes)   -> new-file shadow, target moved/deleted
+ *   - a tsconfig/jsconfig paths/baseUrl edit                 -> path-alias change
+ *   - an EXTENDED base config edit (tsconfig extends ./base.json) -> conservatively covered
+ *   - a package.json exports / lockfile edit                 -> package-export change
+ * busts the ENTIRE cache. We hash ALL walked `.json` (plus lockfiles), not only the
+ * tsconfig/package files, because a tsconfig can `extends` an arbitrarily-named JSON
+ * file whose edit changes resolution (Codex 5.4.3) — conservative over-busting is
+ * the safe failure mode. Within a stable gate, resolution is path-level, so a
+ * content-only edit to a non-JSON source keeps its hits.
+ *
+ * TRUST BOUNDARY (deliberately narrow — see Codex 5.4.3 round-4, consistent with the
+ * parse cache): this file is TRUSTED LOCAL WORKSPACE STATE, the same trust level as
+ * `.orangepro/graph.json` (read back and trusted wholesale). The GATE handles real
+ * staleness (FS shape / config), and shape validation handles corruption — but we do
+ * NOT claim tamper-resistance. A "membership" check (target is in the walked set) was
+ * tried and removed: it only catches foreign/deleted targets the gate already busts on,
+ * and cannot prove a same-gate entry resolves to the RIGHT target — i.e. it was theater.
+ */
+// Bump when resolveImport's resolution behavior changes.
+export const RESOLVER_VERSION = 1;
+// Files whose content can change module resolution: ALL JSON configs (tsconfig +
+// transitive `extends` bases, jsconfig, package.json, *.json referenced by config)
+// plus the non-JSON lockfiles. Conservative by design.
+const CONFIG_RE = /(\.json$)|((^|\/)(yarn\.lock|pnpm-lock\.yaml)$)/i;
+/** The gate hash: resolver version + filesystem shape + resolution-config content. */
+export function computeResolverGate(filePaths) {
+    const sorted = [...filePaths].sort();
+    const configDigest = sorted
+        .filter((p) => CONFIG_RE.test(p.replace(/\\/g, "/")))
+        .map((p) => {
+        try {
+            return `${p}:${hashString(readFileSync(p, "utf8"))}`;
+        }
+        catch {
+            return `${p}:?`;
+        }
+    });
+    return hashString(`v${RESOLVER_VERSION}\n${sorted.join("\n")}\n${configDigest.join("\n")}`);
+}
+/** Strict shape validation — the persisted file is untrusted input. */
+function validResolvedImport(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    if (typeof o.resolved !== "boolean" || typeof o.isExternal !== "boolean")
+        return null;
+    if (o.resolvedFileName !== null && typeof o.resolvedFileName !== "string")
+        return null;
+    // A "resolved" entry must name a target; an unresolved one must not.
+    if (o.resolved !== (typeof o.resolvedFileName === "string"))
+        return null;
+    return o;
+}
+export class ResolverCache {
+    entries;
+    gate;
+    hits = 0;
+    misses = 0;
+    constructor(data) {
+        this.gate = data?.gate ?? "";
+        this.entries = new Map();
+        // Persisted entries are untrusted FOR SHAPE: drop anything off-shape (miss + recompute).
+        if (data?.entries && typeof data.entries === "object") {
+            for (const [k, raw] of Object.entries(data.entries)) {
+                const valid = validResolvedImport(raw);
+                if (valid)
+                    this.entries.set(k, valid);
+            }
+        }
+    }
+    /** Validate against the current run's gate; a mismatch discards ALL entries so no stale
+     *  resolution can survive a structural or config change. Call once before resolving. */
+    useGate(currentGate) {
+        if (this.gate !== currentGate) {
+            this.entries = new Map();
+            this.gate = currentGate;
+        }
+    }
+    /** Resolution is determined by the containing DIRECTORY (nearest tsconfig + relative base)
+     *  plus the specifier — files in the same dir share a result for the same specifier. Within a
+     *  stable gate the entry is trusted (the gate already busts on any FS-shape/config change that
+     *  could alter resolution); shape was validated on load. */
+    resolve(containingDir, specifier, compute) {
+        const key = `${containingDir} ${specifier}`;
+        const hit = this.entries.get(key);
+        if (hit) {
+            this.hits++;
+            return hit;
+        }
+        this.misses++;
+        const value = compute();
+        this.entries.set(key, value);
+        return value;
+    }
+    hitRate() {
+        const total = this.hits + this.misses;
+        return total === 0 ? 0 : Math.round((this.hits / total) * 1000) / 10;
+    }
+    toData() {
+        return { gate: this.gate, entries: Object.fromEntries(this.entries) };
+    }
+}