gitnexus 1.6.10-rc.99 → 1.6.10

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;