gitnexus 1.6.10-rc.217 → 1.6.10-rc.218

package/dist/core/group/extractors/http-patterns/node.js

@@ -1,7 +1,10 @@
+import Parser from 'tree-sitter';
 import JavaScript from 'tree-sitter-javascript';
 import TypeScript from 'tree-sitter-typescript';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
+import { MAX_FOLD_LENGTH } from '../../../ingestion/route-extractors/constant-resolver.js';
 import { DATA_ROUTE_TABLE_SOURCE, scanDataRouteTables, } from '../../../ingestion/route-extractors/data-route-table.js';
+import { buildJsRepoFacts, extractJsModuleFacts, isAxiosNamespace, isHttpClientRef, resolveJsPathExpression, } from '../../../ingestion/route-extractors/js-const-resolver.js';
 /**
  * Node.js / TypeScript HTTP plugin family. Handles:
  *   - NestJS `@Controller('prefix')` classes with `@Get(':id')` methods
@@ -79,15 +82,28 @@ const FETCH_WITH_OPTIONS_SPEC = {
             value: (string) @http_method))))
   `,
 };
-// ─── Consumer: axios.get/post/... ────────────────────────────────────
-const AXIOS_SPEC = {
+// ─── Consumer: <httpClient>.get/post/... ─────────────────────────────
+// Widened from a literal `axios` receiver with a literal path. Application
+// code satisfies neither: it calls through a configured instance
+// (`const api = axios.create({ baseURL })`, imported at the call site under
+// whatever name the app chose) and passes the path by reference from a shared
+// route table (`api.get(API_ROUTE_PATH.LINKS)`). The query therefore matches
+// ANY identifier receiver with an HTTP-verb method and ANY first argument;
+// `scanBundle` admits a match only after PROVING the receiver is an axios
+// instance and resolving the argument to a path.
+//
+// The proof gate is load-bearing, not belt-and-braces: EXPRESS_SPEC above
+// matches `router.get('/x', handler)` / `app.post(...)` as PROVIDERS. A
+// receiver admitted on spelling alone would re-emit every Express route in the
+// repo as a consumer of itself, on both sides of every cross-repo pair.
+const HTTP_CLIENT_SPEC = {
     meta: {},
     query: `
     (call_expression
       function: (member_expression
-        object: (identifier) @obj (#eq? @obj "axios")
+        object: (identifier) @obj
         property: (property_identifier) @http_method (#match? @http_method "^(get|post|put|delete|patch)$"))
-      arguments: (arguments . [(string) (template_string)] @path))
+      arguments: (arguments . (_) @path))
   `,
 };
 // ─── Consumer: jQuery shorthand $.get(url) / $.post(url, ...) ────────
@@ -141,7 +157,7 @@ function compileBundle(language, name) {
         express: mk(EXPRESS_SPEC, 'express'),
         fetchNoOptions: mk(FETCH_NO_OPTIONS_SPEC, 'fetch-no-options'),
         fetchWithOptions: mk(FETCH_WITH_OPTIONS_SPEC, 'fetch-with-options'),
-        axios: mk(AXIOS_SPEC, 'axios'),
+        httpClient: mk(HTTP_CLIENT_SPEC, 'http-client'),
         jqueryShorthand: mk(JQUERY_SHORTHAND_SPEC, 'jquery-shorthand'),
         jqueryAjax: mk(JQUERY_AJAX_SPEC, 'jquery-ajax'),
         axiosObject: mk(AXIOS_OBJECT_SPEC, 'axios-object'),
@@ -281,12 +297,22 @@ function findDecoratedMethod(decoratorNode) {
  */
 function buildImportMap(tree) {
     const map = new Map();
-    const walk = (node) => {
+    // Both walks are explicit-stack, not recursive. They visit EVERY node of the
+    // file, so their depth is the source's nesting depth — and `scan` may not
+    // throw: a `RangeError` here escapes to `sync.ts`, which records the repo as
+    // an unexplained "missing repo" and drops every contract of every kind for
+    // it, silently. A file nesting template substitutions ~4 000 deep (well
+    // inside what tree-sitter will parse) was enough.
+    const stack = [tree.rootNode];
+    while (stack.length > 0) {
+        const node = stack.pop();
         if (node.type === 'import_statement') {
             const sourceNode = node.childForFieldName('source');
             const module = sourceNode ? unquoteLiteral(sourceNode.text) : null;
             if (module !== null) {
-                const collect = (n) => {
+                const inner = [node];
+                while (inner.length > 0) {
+                    const n = inner.pop();
                     if (n.type === 'import_specifier') {
                         const nameNode = n.childForFieldName('name');
                         const aliasNode = n.childForFieldName('alias');
@@ -295,26 +321,213 @@ function buildImportMap(tree) {
                             map.set(local.text, { name: nameNode.text, module });
                         }
                     }
-                    for (let i = 0; i < n.namedChildCount; i++) {
-                        const c = n.namedChild(i);
-                        if (c)
-                            collect(c);
-                    }
-                };
-                collect(node);
+                    for (const c of n.namedChildren)
+                        inner.push(c);
+                }
             }
+            // An import statement cannot contain another one, and the inner loop has
+            // already visited its whole subtree.
+            continue;
         }
-        for (let i = 0; i < node.namedChildCount; i++) {
-            const c = node.namedChild(i);
-            if (c)
-                walk(c);
+        for (const c of node.namedChildren)
+            stack.push(c);
+    }
+    return map;
+}
+/**
+ * Shared across the three JS/TS plugins.
+ *
+ * JS, TS and TSX are distinct `HttpLanguagePlugin` objects, and the
+ * orchestrator caches `prepareRepo` output per plugin NAME — so a polyglot
+ * frontend would build this identical map three times. All three are called
+ * with the same memoized file-list array within one extraction run, so keying
+ * on that array's identity collapses the work to a single pass. A later run
+ * passes a different array and correctly rebuilds; the weak key lets the old
+ * map be collected with it.
+ */
+const REPO_CONTEXT_BY_FILE_LIST = new WeakMap();
+/**
+ * Skip ceiling for the pre-pass, mirroring the analyzer's default
+ * `--max-file-size`. A minified bundle is megabytes on one line and defines no
+ * route table a human wrote; parsing it costs far more than it can return.
+ */
+const MAX_PREPASS_FILE_BYTES = 512 * 1024;
+/** Repo-relative path in the same POSIX form the fact map is keyed by. */
+function normalizeRel(rel) {
+    return rel.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** The grammar a JS/TS-family file should be parsed with, or null if not one. */
+function grammarForFile(rel) {
+    const lower = rel.toLowerCase();
+    if (lower.endsWith('.tsx'))
+        return TypeScript.tsx;
+    if (/\.[cm]?ts$/.test(lower))
+        return TypeScript.typescript;
+    if (/\.[cm]?jsx?$/.test(lower))
+        return JavaScript;
+    return null;
+}
+function buildNodeRepoContext(args) {
+    const cached = REPO_CONTEXT_BY_FILE_LIST.get(args.files);
+    if (cached)
+        return cached;
+    const byFile = new Map();
+    const parsers = new Map();
+    const parserFor = (language) => {
+        let parser = parsers.get(language);
+        if (!parser) {
+            parser = new Parser();
+            parser.setLanguage(language);
+            parsers.set(language, parser);
         }
+        return parser;
     };
-    walk(tree.rootNode);
-    return map;
+    // Cost gate, in the spirit of the sibling `python.ts` pre-pass: every fact
+    // this map holds exists to prove a receiver is an axios instance or to fold a
+    // path for one. A repo where the string `axios` appears nowhere can prove no
+    // receiver, so every parse below is dead work — and parsing is the expensive
+    // half (measured 4.36 s / +258 MB RSS over 827 TypeScript files, on top of
+    // the parse `getScanInput` already does).
+    // Only the file's identity is carried between the passes, never its text: a
+    // large monorepo's whole source tree held in one array at once is the shape
+    // that produced the analyzer's scale problems, and the second read is cheap
+    // beside the parse it gates.
+    const eligible = [];
+    let sawAxios = false;
+    for (const rel of args.files) {
+        const language = grammarForFile(rel);
+        if (language === null)
+            continue;
+        const content = args.readFile(rel);
+        // `MAX_PREPASS_FILE_BYTES` is a BYTE ceiling; `String.length` counts UTF-16
+        // code units, which under-counts every multi-byte source.
+        if (content === null || Buffer.byteLength(content, 'utf8') > MAX_PREPASS_FILE_BYTES)
+            continue;
+        if (!sawAxios && content.includes('axios'))
+            sawAxios = true;
+        eligible.push({ rel, language });
+    }
+    if (sawAxios) {
+        for (const { rel, language } of eligible) {
+            try {
+                const content = args.readFile(rel);
+                if (content === null)
+                    continue;
+                // `parseSource` belongs INSIDE the guard: `safe-parse.ts` throws
+                // `ParseTimeoutError` and makes catching it a per-caller obligation, and
+                // `prepareRepo` is contractually non-throwing. One escape here left the
+                // fact map unwritten for the WHOLE repo — and, because the orchestrator
+                // caches per plugin NAME, made all three JS/TS plugins re-walk it and
+                // fail the same way before falling back to literal-only scanning.
+                const tree = args.parseSource(parserFor(language), content);
+                if (!tree)
+                    continue;
+                byFile.set(normalizeRel(rel), extractJsModuleFacts(tree));
+            }
+            catch {
+                // One malformed file must never abort the pre-pass — it simply stays
+                // unresolved, exactly as it is without this pass at all.
+            }
+        }
+    }
+    const ctx = { facts: buildJsRepoFacts(byFile) };
+    REPO_CONTEXT_BY_FILE_LIST.set(args.files, ctx);
+    return ctx;
+}
+/** The repo facts to resolve against, or null when there was no pre-pass. */
+function resolveFactsFor(repoContext, fileRel) {
+    const ctx = repoContext;
+    if (!ctx || fileRel === undefined)
+        return null;
+    return ctx.facts;
+}
+/**
+ * Whether a folded first argument is plausibly a URL path.
+ *
+ * The query now captures ANY first argument, and "it folded to a string" is not
+ * "it is a path" — `normalizeConsumerPath` is a canonicalizer, not a validator,
+ * and it happily turns non-paths into contracts that exact-match real provider
+ * routes:
+ *
+ *   api.get(CONFIG.TIMEOUT)  // "5000"                     -> http::GET::/{param}
+ *   api.post(MSG.ERROR)      // "Could not reach the …"    -> http::POST::/could not reach the server
+ *
+ * `/{param}` matches every one-segment provider route in the group, and
+ * `matching.exclude_links_param_only_paths` defaults to `false`. A path whose
+ * leading term is an unresolved placeholder is refused for the same reason —
+ * nothing pins where it starts. (`resolveJsPathExpression` already refuses those
+ * it folded itself; this also covers the literal fallback below.)
+ */
+function looksLikeHttpPath(path) {
+    if (path === '')
+        return false;
+    if (/^https?:\/\//i.test(path))
+        return true;
+    // A `${…}` term is a runtime value that `normalizeConsumerPath` rewrites to
+    // `{param}`; its SOURCE text can be any expression (`${draft ? 'a' : 'b'}`,
+    // `${id ?? ''}`), so the checks below have to run against the normalized
+    // shape. Testing the raw source dropped every partially folded path whose
+    // unresolved term happened to contain a space.
+    const shape = path.replace(/\$\{[^}]+\}/g, '{param}');
+    if (/\s/.test(shape))
+        return false;
+    if (shape.startsWith('{param}'))
+        return false;
+    // An all-digit string is a path only when it is written as one. A leading
+    // slash is that evidence: `client.get('/123')` is a route whose segment the
+    // consumer normalizer reads as `{param}`, while a bare `"5000"` folded out of
+    // `CONFIG.TIMEOUT` is a timeout that would match every one-segment provider.
+    if (!shape.startsWith('/'))
+        return !/^\d+$/.test(shape);
+    return true;
 }
-function scanBundle(bundle, tree) {
+/**
+ * The path a consumer call's first argument denotes.
+ *
+ * Prefers full resolution against the repo facts; falls back to the raw
+ * literal for a string/template node so a repo with no pre-pass (or an
+ * unresolvable reference) behaves exactly as it did before.
+ *
+ * `fileKey` is already `normalizeRel`-ed by the caller — see `scanBundle`.
+ *
+ * `legacyShape` marks the exact combination this pattern matched BEFORE it was
+ * widened: the literal receiver `axios` with a string or template-string first
+ * argument. That combination keeps its old output verbatim, so this PR adds
+ * detections without removing any — `axios.get(`${API_BASE}/users`)` still
+ * yields `/{param}/users`. Everything the widened query NEWLY admits (any other
+ * receiver, or any non-literal argument) has to clear the gates.
+ */
+function resolveConsumerPath(pathNode, facts, fileKey, legacyShape) {
+    if (facts && fileKey !== undefined) {
+        const resolved = resolveJsPathExpression(fileKey, pathNode, facts);
+        if (resolved !== null && looksLikeHttpPath(resolved))
+            return resolved;
+    }
+    // The fallback is deliberately gated on node TYPE: `unquoteLiteral` returns
+    // unrecognized input unchanged, so handing it a `member_expression` would
+    // yield the literal text `API_ROUTE_PATH.LINKS` as if it were a URL path.
+    if (pathNode.type !== 'string' && pathNode.type !== 'template_string')
+        return null;
+    const literal = unquoteLiteral(pathNode.text);
+    // The fold bails past `MAX_FOLD_LENGTH`; the raw source it falls back to has
+    // no such bound and lands in `contractId` and `meta.path` all the same.
+    if (literal === null || literal.length > MAX_FOLD_LENGTH)
+        return null;
+    return legacyShape || looksLikeHttpPath(literal) ? literal : null;
+}
+function scanBundle(bundle, tree, repoContext, fileRel) {
     const out = [];
+    // Repo-wide constant / HTTP-client facts, when the orchestrator ran the
+    // `prepareRepo` pre-pass. Absent for a bare `scan(tree)` call, in which case
+    // every cross-file resolution below floors to the literal-only behavior.
+    const facts = resolveFactsFor(repoContext, fileRel);
+    // The fact map is keyed by `normalizeRel(rel)`. Normalizing at ONE place and
+    // using that value for every read keeps the two sides in step: the receiver
+    // gate used to read the raw `fileRel`, and `isHttpClientRef` cannot tell a key
+    // miss from "not a client", so any non-POSIX path (glob v13 has no
+    // `posix: true` and its walker joins with the platform separator; graph rows
+    // are a second unnormalized source) silently returned zero consumers.
+    const fileKey = fileRel === undefined ? undefined : normalizeRel(fileRel);
     // Local-binding → { declared export name, module } for the file's named
     // imports, so an express handler that is an imported (possibly aliased)
     // symbol resolves to the real definition rather than its local alias text.
@@ -450,24 +663,52 @@ function scanBundle(bundle, tree) {
             confidence: 0.7,
         });
     }
-    // Consumer: axios.<verb>(url)
-    for (const match of runCompiledPatterns(bundle.axios, tree)) {
+    // Consumer: <httpClient>.<verb>(url) — `axios` itself, or any receiver the
+    // repo pre-pass proves is an axios instance.
+    for (const match of runCompiledPatterns(bundle.httpClient, tree)) {
         const methodNode = match.captures.http_method;
         const pathNode = match.captures.path;
-        if (!methodNode || !pathNode)
-            continue;
-        const path = unquoteLiteral(pathNode.text);
-        if (path === null)
+        const objNode = match.captures.obj;
+        if (!methodNode || !pathNode || !objNode)
             continue;
-        out.push({
-            role: 'consumer',
-            framework: 'axios',
-            method: methodNode.text.toUpperCase(),
-            path,
-            name: null,
-            line: pathNode.startPosition.row + 1,
-            confidence: 0.7,
-        });
+        // Receiver gate. `axios.get(...)` needs no proof; anything else must be
+        // traced to an `axios.create(...)` binding, or it is not ours to claim.
+        const receiver = objNode.text;
+        // Cross-file resolution is the only work in this file that walks a
+        // repo-wide graph, and `HttpLanguagePlugin.scan` may not throw: a single
+        // hostile call site must cost its own detection, not the repo's whole
+        // contract set (`sync.ts` catches a throw here as an unexplained "missing
+        // repo", silently, for every contract type).
+        try {
+            // The receiver is admitted when it IS the axios module — the bare
+            // spelling this pattern trusted before it was widened, or a declared
+            // import/require of 'axios' under any name — or when it traces to an
+            // `axios.create(...)` instance. Nothing else.
+            const isModule = facts === null || fileKey === undefined
+                ? receiver === 'axios'
+                : isAxiosNamespace(fileKey, receiver, facts);
+            if (!isModule) {
+                if (!facts || fileKey === undefined)
+                    continue;
+                if (!isHttpClientRef(fileKey, receiver, facts))
+                    continue;
+            }
+            const path = resolveConsumerPath(pathNode, facts, fileKey, isModule && (pathNode.type === 'string' || pathNode.type === 'template_string'));
+            if (path === null)
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'axios',
+                method: methodNode.text.toUpperCase(),
+                path,
+                name: null,
+                line: pathNode.startPosition.row + 1,
+                confidence: 0.7,
+            });
+        }
+        catch {
+            // Unresolvable is the same outcome as unresolved — skip this call site.
+        }
     }
     // Consumer: jQuery shorthand $.get(url) / $.post(url, ...)
     for (const match of runCompiledPatterns(bundle.jqueryShorthand, tree)) {
@@ -554,15 +795,18 @@ function scanBundle(bundle, tree) {
 export const JAVASCRIPT_HTTP_PLUGIN = {
     name: 'javascript-http',
     language: JavaScript,
-    scan: (tree) => scanBundle(JAVASCRIPT_BUNDLE, tree),
+    prepareRepo: buildNodeRepoContext,
+    scan: (tree, repoContext, fileRel) => scanBundle(JAVASCRIPT_BUNDLE, tree, repoContext, fileRel),
 };
 export const TYPESCRIPT_HTTP_PLUGIN = {
     name: 'typescript-http',
     language: TypeScript.typescript,
-    scan: (tree) => scanBundle(TYPESCRIPT_BUNDLE, tree),
+    prepareRepo: buildNodeRepoContext,
+    scan: (tree, repoContext, fileRel) => scanBundle(TYPESCRIPT_BUNDLE, tree, repoContext, fileRel),
 };
 export const TSX_HTTP_PLUGIN = {
     name: 'tsx-http',
     language: TypeScript.tsx,
-    scan: (tree) => scanBundle(TSX_BUNDLE, tree),
+    prepareRepo: buildNodeRepoContext,
+    scan: (tree, repoContext, fileRel) => scanBundle(TSX_BUNDLE, tree, repoContext, fileRel),
 };

package/dist/core/ingestion/route-extractors/constant-resolver.d.ts

@@ -80,10 +80,10 @@ export type ImportResolver = (importingFileKey: string, moduleSpec: string, repo
  * value, folding `+` concatenation and following import chains via
  * `resolveImport`, or `null` when it cannot be fully folded.
  */
-export declare function resolveConstant(fileKey: string, name: string, repo: RepoConstants, resolveImport: ImportResolver): string | null;
+export declare function resolveConstant(fileKey: string, name: string, repo: RepoConstants, resolveImport: ImportResolver, repoKeys?: ReadonlySet<string>): string | null;
 /**
  * Resolve an inline operand list (an unnamed `+`-expression captured directly at
  * a decorator/annotation argument, e.g. `@router.get(API_V1 + "/widgets")`)
  * against `fileKey`.
  */
-export declare function resolveOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants, resolveImport: ImportResolver): string | null;
+export declare function resolveOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants, resolveImport: ImportResolver, repoKeys?: ReadonlySet<string>): string | null;

package/dist/core/ingestion/route-extractors/constant-resolver.js

@@ -104,10 +104,14 @@ function computeFold(fileKey, name, state, depth) {
     }
     return null;
 }
-function newState(repo, resolveImport) {
+function newState(repo, resolveImport, repoKeys) {
     return {
         repo,
-        repoKeys: new Set(repo.keys()),
+        // Materializing the key set here is O(files), and this runs once per fold —
+        // which is once per import hop, not once per scan. A binding that already
+        // holds the set (every one of them does; it is a projection of the same map
+        // it builds `repo` from) passes it in and skips the copy entirely.
+        repoKeys: repoKeys ?? new Set(repo.keys()),
         resolveImport,
         visited: new Set(),
         memo: new Map(),
@@ -118,14 +122,14 @@ function newState(repo, resolveImport) {
  * value, folding `+` concatenation and following import chains via
  * `resolveImport`, or `null` when it cannot be fully folded.
  */
-export function resolveConstant(fileKey, name, repo, resolveImport) {
-    return foldName(fileKey, name, newState(repo, resolveImport), 0);
+export function resolveConstant(fileKey, name, repo, resolveImport, repoKeys) {
+    return foldName(fileKey, name, newState(repo, resolveImport, repoKeys), 0);
 }
 /**
  * Resolve an inline operand list (an unnamed `+`-expression captured directly at
  * a decorator/annotation argument, e.g. `@router.get(API_V1 + "/widgets")`)
  * against `fileKey`.
  */
-export function resolveOperands(fileKey, operands, repo, resolveImport) {
-    return foldExpr(fileKey, operands, newState(repo, resolveImport), 0);
+export function resolveOperands(fileKey, operands, repo, resolveImport, repoKeys) {
+    return foldExpr(fileKey, operands, newState(repo, resolveImport, repoKeys), 0);
 }

package/dist/core/ingestion/route-extractors/js-const-resolver.d.ts

@@ -0,0 +1,192 @@
+/**
+ * JavaScript/TypeScript binding for the language-agnostic constant resolver.
+ *
+ * Supplies the two JS-specific pieces the shared fold in `constant-resolver.ts`
+ * needs — {@link resolveJsImport} (import specifier → file key, honoring
+ * relative paths, extensionless imports, directory `index` files and bare
+ * alias-style specifiers) and {@link extractJsModuleFacts} (tree →
+ * {@link ModuleConstants} plus the export/HTTP-client facts below) — mirroring
+ * how `python-const-resolver.ts` binds the same core for Python (#2391).
+ *
+ * Two JS-shaped facts the Python binding has no analogue for:
+ *
+ *  1. **Object-literal path tables.** Python route constants are module-level
+ *     scalars (`API_V1 = "/v1"`); the JS convention is one frozen table —
+ *     `export const API_ROUTE_PATH = { LINKS: "/links", … } as const` — read at
+ *     the call site as `API_ROUTE_PATH.LINKS`. The extractor flattens such a
+ *     table into DOTTED literal keys (`API_ROUTE_PATH.LINKS` → `/links`) so the
+ *     agnostic fold, which does a plain `literals.get(name)`, resolves a member
+ *     reference with no changes to the core.
+ *
+ *  2. **Export aliasing.** `export default routeApiClient` and
+ *     `export { a as b }` mean the name an importer writes is often not the
+ *     name the defining file bound. {@link JsModuleFacts.exports} maps the
+ *     EXPORTED name (including `default`) to the local one so a cross-file
+ *     chase lands on the right binding.
+ *
+ * Both stay in this binding — the shared core keeps knowing nothing about any
+ * language.
+ *
+ * Keying matches the Python binding: the repo map is keyed by unique POSIX file
+ * path, and an import that cannot be pinned to exactly one file resolves to
+ * `null` (skip) rather than an arbitrary winner. An unresolved path is a
+ * missing contract; a wrongly-resolved one is a false cross-repo link, which is
+ * strictly worse.
+ */
+import type Parser from 'tree-sitter';
+import { type ImportResolver, type ModuleConstants, type Operand, type RepoConstants } from './constant-resolver.js';
+export type { ImportBinding, ModuleConstants, Operand, RepoConstants, } from './constant-resolver.js';
+/**
+ * Per-file facts beyond the agnostic {@link ModuleConstants}: which exported
+ * name maps to which local binding, and which local bindings hold an HTTP
+ * client instance.
+ */
+export interface JsModuleFacts {
+    /** String constants, dotted table members, `+`-expressions and imports. */
+    readonly constants: ModuleConstants;
+    /** Exported name (incl. `default`) → local binding name in this file. */
+    readonly exports: Map<string, string>;
+    /**
+     * Module specifiers this file re-exports wholesale (`export * from './m'`).
+     * A directory barrel is built almost entirely out of these, and a barrel is
+     * what application code imports — so without following them, every name
+     * reached through one resolves to nothing.
+     */
+    readonly starExports: string[];
+    /**
+     * Local names proven to hold an HTTP client INSTANCE — bound directly to
+     * `axios.create(...)`, or to another local name that is one. Cross-file
+     * chains are followed at query time by {@link isHttpClientRef}, not here.
+     */
+    readonly clients: Set<string>;
+    /**
+     * True when this file declares its own top-level binding named `axios` that
+     * is NOT the axios module.
+     *
+     * The bare spelling `axios` is trusted without proof — it predates this
+     * binding and is what the original query matched on. That is right for
+     * `import axios from 'axios'` and for `const axios = require('axios')`, and
+     * wrong for `const axios = fakeFactory`, where the spelling is the only
+     * evidence and it is false. One flag, because the shortcut only ever applies
+     * to this one name.
+     */
+    readonly axiosShadowed: boolean;
+}
+/**
+ * Repo-wide facts, with everything the shared fold needs precomputed.
+ *
+ * `constants`, `keys` and `resolveImport` are derived from `byFile` and built
+ * ONCE by {@link buildJsRepoFacts}, never per lookup: materializing a key set
+ * at each call site makes every resolution O(files) and the whole scan
+ * quadratic in a repo's file count. That was only half true before —
+ * `resolveConstant` rebuilt its own key set on every fold regardless, so the
+ * mitigation this comment describes was not in force for any resolution that
+ * went through the shared core. It now takes `keys` as an argument.
+ */
+export interface JsRepoFacts {
+    readonly byFile: ReadonlyMap<string, JsModuleFacts>;
+    readonly constants: RepoConstants;
+    readonly keys: ReadonlySet<string>;
+    /**
+     * {@link resolveJsImport} bound to a prebuilt basename index and memoized for
+     * the lifetime of the facts. Every resolution inside this module goes through
+     * it rather than the bare export: the widened consumer query matches every
+     * `<identifier>.<verb>(…)` call in the repo, so an unindexed lookup ran once
+     * per call site over every repo key.
+     */
+    readonly resolveImport: ImportResolver;
+}
+/** Build the {@link JsRepoFacts} projections from per-file facts. */
+export declare function buildJsRepoFacts(byFile: ReadonlyMap<string, JsModuleFacts>): JsRepoFacts;
+/**
+ * Standalone {@link ImportResolver} — the same rules as {@link resolveImportWith}
+ * with the basename index built on the spot.
+ *
+ * Production goes through `JsRepoFacts.resolveImport`, which holds one index
+ * for the whole repo and memoizes; this export exists so the resolution rules
+ * can be exercised directly against a key set.
+ */
+export declare const resolveJsImport: ImportResolver;
+/**
+ * Parse a `+`-concatenation / template string into an operand list the shared
+ * fold can resolve, or `null` when a term is not a string literal or a
+ * resolvable name reference.
+ *
+ * Handles the two shapes a JS route path is built with:
+ *   `BASE + "/users"`            → [ref BASE, literal /users]
+ *   `` `${BASE}/users/${id}` ``  → [ref BASE, literal /users/, ref id]
+ *
+ * A member reference inside either (`${API_ROUTE_PATH.LISTS}`) becomes a
+ * dotted `ref`, which the flattened table above resolves directly.
+ */
+export declare function parseJsConstOperands(node: Parser.SyntaxNode, depth?: number): Operand[] | null;
+/**
+ * The dotted name a member expression denotes (`A.B.C`), or `null` for a
+ * computed / non-identifier chain (`A[key]`, `fn().B`) that has no stable
+ * textual key.
+ */
+export declare function dottedNameOf(node: Parser.SyntaxNode): string | null;
+/**
+ * Extract one file's {@link JsModuleFacts} from its parsed tree.
+ *
+ * Only TOP-LEVEL declarations are collected. A route table or an API client
+ * defined inside a function body is not a module constant, and treating it as
+ * one would let an unrelated same-named local shadow the real export.
+ */
+export declare function extractJsModuleFacts(tree: Parser.Tree): JsModuleFacts;
+/**
+ * Resolve a path reference at a call site to its literal string, or `null`.
+ *
+ * `ref` is the dotted name as written (`API_ROUTE_PATH.LINKS`, or a bare
+ * `BASE_PATH`). Resolution order:
+ *
+ *   1. The dotted name as a constant of the CURRENT file — hits when the table
+ *      is declared in the same file (flattened to dotted literal keys).
+ *   2. The base name as an IMPORT of the current file — hop to the defining
+ *      file and look the dotted name up there, re-hopping through barrels that
+ *      re-export it, bounded by {@link MAX_REEXPORT_HOPS}.
+ *
+ * Returns `null` on anything it cannot fully fold, which leaves the call site
+ * exactly as unmatched as it is today — never a guessed path.
+ */
+export declare function resolveJsMemberPath(fileKey: string, ref: string, facts: JsRepoFacts): string | null;
+/**
+ * Resolve the first argument of an HTTP call to a path string, or `null` when
+ * the expression is not a path shape this binding understands.
+ *
+ * Accepts a plain literal, a constant reference (`BASE_PATH`), a table member
+ * (`API_ROUTE_PATH.LINKS`), a template string, and a `+`-concatenation of any
+ * of those. Template and concat forms fold PARTIALLY — see
+ * {@link foldTermOrPlaceholder}.
+ *
+ * A reference that resolves to nothing returns `null` (skip), and so does a
+ * mixed expression whose leading term is unresolved — see {@link FoldedPath}.
+ */
+export declare function resolveJsPathExpression(fileKey: string, node: Parser.SyntaxNode, facts: JsRepoFacts): string | null;
+/**
+ * Whether `name`, as referenced in `fileKey`, holds an HTTP client instance.
+ *
+ * Chases local aliases and import/export hops so the common app shape —
+ * `axios.create()` in `lib/axios.config.ts`, `export default apiClient`,
+ * `import apiClient from '@/lib/axios.config'` at the call site — is proven
+ * rather than pattern-matched on the receiver's spelling.
+ *
+ * Deliberately conservative: an unproven receiver returns `false`, which keeps
+ * today's behavior for it. The alternative — trusting any identifier with an
+ * HTTP-verb method — would classify every Express `router.get('/x', handler)`
+ * provider as a consumer of itself.
+ */
+/**
+ * Whether `name`, as a receiver in `fileKey`, IS the axios module — as opposed
+ * to an instance built from it, which is {@link isHttpClientRef}'s question.
+ *
+ * Two ways to be it. The bare spelling `axios` predates the widened query — it
+ * is what the original `(#eq? @obj "axios")` pattern matched — so it stays
+ * trusted by default, and a file with no facts keeps exactly that behavior; it
+ * is withdrawn only where the file itself binds that name to something else.
+ * The other way is a declared import or `require` of `'axios'` under any local
+ * name, which is proof rather than convention and covers the aliased form the
+ * spelling rule cannot see.
+ */
+export declare function isAxiosNamespace(fileKey: string, name: string, facts: JsRepoFacts): boolean;
+export declare function isHttpClientRef(fileKey: string, name: string, facts: JsRepoFacts): boolean;