@aroman22/codegraph-vba 1.3.3

package/dist/resolution/path-aliases.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Project-level import-path alias loading.
+ *
+ * Reads `compilerOptions.paths` from `tsconfig.json` / `jsconfig.json`
+ * at the project root and converts the patterns into a form the
+ * import-resolver can consult.
+ *
+ * This is the single biggest blocker to accurate resolution on modern
+ * JS/TS codebases: aliases like `@/components/Foo` (Next, Nuxt, Nest,
+ * Vite scaffolds) point into a `paths` map the resolver previously
+ * ignored — every import through an alias was treated as unresolvable
+ * unless it happened to match the small hard-coded fallback list.
+ *
+ * Scope deliberately small for v1:
+ *   - reads tsconfig.json, then jsconfig.json
+ *   - honours top-level `compilerOptions.baseUrl` and `compilerOptions.paths`
+ *   - supports `*` wildcard (the only TS-supported wildcard)
+ *   - does NOT follow `extends` chains yet (most projects don't need it)
+ *   - does NOT read Vite/webpack/Rollup configs (separate follow-up)
+ *
+ * The file is parsed as JSON-with-comments-tolerant — tsconfigs in the
+ * wild routinely contain `//` and `/* *\/` comments and trailing
+ * commas, which JSON.parse rejects. We strip those before parsing.
+ */
+/** A single alias pattern from `compilerOptions.paths`. */
+export interface AliasPattern {
+    /** The literal prefix before `*` (or the whole pattern if no `*`). */
+    prefix: string;
+    /** The literal suffix after `*` (almost always empty). */
+    suffix: string;
+    /** Whether the pattern contains a `*` wildcard. */
+    hasWildcard: boolean;
+    /**
+     * Replacement templates. When `hasWildcard` is true, `*` in the
+     * replacement is filled with the captured wildcard portion of the
+     * import path. Stored relative to {@link AliasMap.baseUrl}.
+     * tsconfig allows multiple targets per alias (priority order).
+     */
+    replacements: string[];
+}
+export interface AliasMap {
+    /** Absolute path. The directory `compilerOptions.paths` is rooted at. */
+    baseUrl: string;
+    /**
+     * Patterns ordered by specificity: longer prefix first, then literal-
+     * before-wildcard, so the resolver tries the most-specific match.
+     */
+    patterns: AliasPattern[];
+}
+/**
+ * Load aliases for `projectRoot`. Returns `null` when no tsconfig /
+ * jsconfig is present or when the file has no usable `paths`.
+ *
+ * Cheap to call repeatedly — caching is the caller's job (the
+ * resolver does it via {@link aliasCache}).
+ */
+export declare function loadProjectAliases(projectRoot: string): AliasMap | null;
+/**
+ * Resolve an import path through an {@link AliasMap}. Returns the list
+ * of candidate filesystem paths (relative to `projectRoot`), in the
+ * priority order defined by tsconfig (multiple replacements per alias
+ * are tried in order). Returns `[]` when no alias matches.
+ *
+ * Callers still need to try each candidate with the language's
+ * extension list — this function only does the alias rewrite.
+ */
+export declare function applyAliases(importPath: string, aliases: AliasMap, projectRoot: string): string[];
+//# sourceMappingURL=path-aliases.d.ts.map

package/dist/resolution/strip-comments.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-language comment stripper for framework route extractors.
+ *
+ * Replaces comment characters and string-literal contents that hide
+ * routing-shaped text with spaces (NOT removal) so that source offsets
+ * are preserved. This means `match.index` from a regex run on the
+ * stripped output still maps to the same line in the original source.
+ *
+ * Example:
+ *   Input:  "x = 1  # path('/fake/', V)\n real = 2"
+ *   Output: "x = 1                       \n real = 2"
+ *
+ * Why strip strings/docstrings as well as comments? Python module/class
+ * docstrings are a common source of false positives — they often contain
+ * `path('/example/', View)` examples in usage docs. We treat triple-quoted
+ * strings the same as comments. Single-line strings stay intact (a `#`
+ * inside a Python string is NOT a comment).
+ *
+ * Scope: this is a pragmatic, regex-supporting helper, not a full parser.
+ * It does NOT try to detect JS regex literals, Python f-string expressions,
+ * or shell-style heredocs. Those edge cases are not load-bearing for the
+ * `path(...)`, `Route::get(...)`, `app.get(...)` style patterns that
+ * framework extractors scan for.
+ */
+export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust' | 'c' | 'cpp';
+export declare function stripCommentsForRegex(content: string, lang: CommentLang): string;
+//# sourceMappingURL=strip-comments.d.ts.map

package/dist/resolution/swift-objc-bridge.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Swift ↔ Objective-C bridging rules.
+ *
+ * Apple's auto-bridging mechanism exposes Swift declarations to the ObjC
+ * runtime under a deterministic selector name. The full rule set:
+ * https://developer.apple.com/documentation/swift/importing-swift-into-objective-c
+ *
+ * This module is **pure name math** — given a Swift declaration's base name
+ * + parameter external labels (or the raw signature text), produce the
+ * bridged ObjC selector(s); given an ObjC selector, produce the
+ * candidate Swift base names. No graph/DB access here.
+ *
+ * Used by `frameworks/swift-objc.ts` (the framework resolver that wires
+ * the rules into the resolution pipeline) and by its tests.
+ *
+ * ─── Bridging cheat sheet ───────────────────────────────────────────────
+ *
+ *   Swift declaration                             ObjC selector
+ *   ─────────────────────────────────────────     ─────────────────────────
+ *   func play()                                    play
+ *   func play(_ song: String)                      play:
+ *   func play(song: String)                        playWithSong:
+ *   func play(_ song: String, by artist: String)   play:by:
+ *   func play(song: String, by artist: String)     playWithSong:by:
+ *   init(name: String)                             initWithName:
+ *   init(name: String, age: Int)                   initWithName:age:
+ *   var name: String  (getter / setter)            name  /  setName:
+ *   @objc(custom:) func f(_ x: Int)                custom:        (literal override)
+ *
+ * The reverse direction (ObjC → Swift) collapses the bridge: a Swift call
+ * site for `play(song:)` reaches us as the bare base name `play` (Swift's
+ * tree-sitter call_expression strips parameter labels from the callee
+ * name). So `swiftBaseNamesForObjcSelector('playWithSong:')` returns
+ * `['play']` — the resolver looks up Swift methods named `play`.
+ */
+/**
+ * Compute the auto-bridged ObjC selector for a Swift method declaration.
+ *
+ * @param baseName  The Swift method's base name (e.g. `play`).
+ * @param externalLabels  Parameter EXTERNAL labels in declaration order;
+ *                        `null` for a `_` (unlabeled) parameter.
+ *                        `[]` for a no-parameter method.
+ * @param explicitObjcName  If `@objc(customSel:)` was specified, the
+ *                          literal selector — short-circuits the rule
+ *                          and is returned as-is.
+ * @returns The ObjC selector (e.g. `playWithSong:by:`), or `null` if it
+ *          can't be determined.
+ *
+ * **Method rules:**
+ * - No params → base name (no colons)
+ * - Single param, `_` label → `baseName:`
+ * - Single param, explicit label `L` → `baseNameWithL:`
+ * - Multi-param, `_` first label → `baseName:label2:label3:`
+ * - Multi-param, explicit first label `L1` → `baseNameWithL1:label2:label3:`
+ *
+ * Initializer rules are handled by `objcSelectorForSwiftInit`.
+ */
+export declare function objcSelectorForSwiftMethod(baseName: string, externalLabels: (string | null)[], explicitObjcName?: string | null): string | null;
+/**
+ * Compute the bridged ObjC selector for a Swift `init(...)` declaration.
+ *
+ * **Init rules** (different from regular methods — Apple always uses
+ * `initWith` regardless of whether the first label is `_`):
+ * - `init()`                       → `init`
+ * - `init(_ name: String)`         → `initWithName:`  (uses the INTERNAL
+ *                                    name when external is `_`, per Apple's
+ *                                    bridging conventions)
+ * - `init(name: String)`           → `initWithName:`
+ * - `init(name: String, age: Int)` → `initWithName:age:`
+ *
+ * For the `_` case we need the internal (second identifier) name —
+ * passed via `internalNames`.
+ */
+export declare function objcSelectorForSwiftInit(externalLabels: (string | null)[], internalNames: string[], explicitObjcName?: string | null): string | null;
+/**
+ * Compute the bridged ObjC getter + setter for a Swift `@objc` property.
+ *
+ * - `var name: String`        → getter `name`, setter `setName:`
+ * - `var isReady: Bool`       → getter `isReady`, setter `setIsReady:`
+ *   (no special `is` handling — Swift's `isReady` stays as `isReady` in ObjC;
+ *   `@objc(name:)` overrides if a Cocoa-style getter `isReady` / setter
+ *   `setReady:` pairing is needed — that's the responsibility of the
+ *   declaration's `@objc(customGetter)` annotation, which we surface via
+ *   `explicitObjcName`.)
+ */
+export declare function objcAccessorsForSwiftProperty(swiftName: string, explicitObjcName?: string | null): {
+    getter: string;
+    setter: string;
+} | null;
+/**
+ * Reverse: from an ObjC selector, return the candidate Swift base names
+ * the resolver should try when looking for the bridged Swift declaration.
+ *
+ * Examples:
+ *   `play`                 → ['play']
+ *   `play:`                → ['play']
+ *   `playWithSong:`        → ['play', 'playWithSong']
+ *   `play:by:`             → ['play']
+ *   `playWithSong:by:`     → ['play', 'playWithSong']
+ *   `initWithName:`        → ['init']                      (init is its own base name)
+ *   `initWithName:age:`    → ['init']
+ *   `setName:`             → ['name', 'setName']           (could be a setter OR a regular func)
+ *   `tableView:didSel…:`   → ['tableView']
+ *
+ * Returns multiple candidates because the bare base name is ambiguous —
+ * `playWithSong:` could correspond to either `func play(song:)` or
+ * `func playWithSong(_ x:)` (a Swift method literally named that with a
+ * `_` first label). The resolver tries each.
+ */
+export declare function swiftBaseNamesForObjcSelector(selector: string): string[];
+/**
+ * Detect whether a Swift method `@objc` declaration uses the `@objc(custom:)`
+ * override form, returning the literal selector when present.
+ *
+ * Regex-based scan over the small chunk of source preceding the declaration —
+ * tree-sitter would be more precise but this is only consulted as a fallback
+ * when the structured AST isn't available (e.g. resolver-time lookups
+ * via `context.readFile`).
+ *
+ * Returns `null` when the declaration is plain `@objc` (no override) or has
+ * no `@objc` attribute at all.
+ */
+export declare function detectExplicitObjcName(sourceSlice: string): string | null;
+/**
+ * Detect whether a Swift declaration is `@objc`-exposed by scanning the
+ * source slice that precedes it. Returns true for explicit `@objc`,
+ * `@objc(custom:)`, or membership in a `@objcMembers` class (caller's
+ * responsibility to pass class-level context if relevant).
+ *
+ * `@nonobjc` returns false even if `@objc` also appears (per Swift's rule
+ * that `@nonobjc` opts out of class-level `@objcMembers`).
+ */
+export declare function isObjcExposed(sourceSlice: string): boolean;
+//# sourceMappingURL=swift-objc-bridge.d.ts.map

package/dist/resolution/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Reference Resolution Types
+ *
+ * Types for the reference resolution system.
+ */
+import { Language, Node, ReferenceKind } from '../types';
+/**
+ * An unresolved reference from extraction
+ */
+export interface UnresolvedRef {
+    /** ID of the source node containing the reference */
+    fromNodeId: string;
+    /** The name being referenced */
+    referenceName: string;
+    /** Type of reference */
+    referenceKind: ReferenceKind;
+    /** Line where reference occurs */
+    line: number;
+    /** Column where reference occurs */
+    column: number;
+    /** File path where reference occurs */
+    filePath: string;
+    /** Language of the source file */
+    language: Language;
+    /** Possible qualified names it might resolve to */
+    candidates?: string[];
+}
+/**
+ * A resolved reference
+ */
+export interface ResolvedRef {
+    /** Original unresolved reference */
+    original: UnresolvedRef;
+    /** ID of the target node */
+    targetNodeId: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** How it was resolved */
+    resolvedBy: 'exact-match' | 'import' | 'qualified-name' | 'framework' | 'fuzzy' | 'instance-method' | 'file-path' | 'function-ref';
+}
+/**
+ * Result of resolution attempt
+ */
+export interface ResolutionResult {
+    /** Successfully resolved references */
+    resolved: ResolvedRef[];
+    /** References that couldn't be resolved */
+    unresolved: UnresolvedRef[];
+    /** Statistics */
+    stats: {
+        total: number;
+        resolved: number;
+        unresolved: number;
+        byMethod: Record<string, number>;
+    };
+}
+/**
+ * Context for resolution - provides access to the graph
+ */
+export interface ResolutionContext {
+    /** Get all nodes in a file */
+    getNodesInFile(filePath: string): Node[];
+    /** Get all nodes by name */
+    getNodesByName(name: string): Node[];
+    /** Get all nodes by qualified name */
+    getNodesByQualifiedName(qualifiedName: string): Node[];
+    /** Get all nodes of a kind */
+    getNodesByKind(kind: Node['kind']): Node[];
+    /** Check if a file exists */
+    fileExists(filePath: string): boolean;
+    /** Read file content */
+    readFile(filePath: string): string | null;
+    /** Get project root */
+    getProjectRoot(): string;
+    /** Get all files */
+    getAllFiles(): string[];
+    /** Get nodes by lowercase name (O(1) lookup for fuzzy matching) */
+    getNodesByLowerName(lowerName: string): Node[];
+    /**
+     * Direct supertypes of the type named `typeName` (same language): the classes
+     * it extends and the interfaces / protocols / traits it implements/conforms to,
+     * by simple name. Backed by the resolved `implements`/`extends` edges, so it is
+     * EMPTY during the first resolution pass (edges aren't built yet) and populated
+     * afterward — the conformance pass uses it to resolve a chained method defined
+     * on a supertype the receiver type conforms to (e.g. a protocol-extension
+     * method). Optional so external/test contexts compile without it.
+     */
+    getSupertypes?(typeName: string, language: Language): string[];
+    /**
+     * Look up a node by its id. Lets matchers derive the FROM-symbol's
+     * enclosing-class scope (Swift implicit-self method scoping, `this.X`
+     * member resolution). Optional so external/test contexts compile
+     * without it.
+     */
+    getNodeById?(id: string): Node | null;
+    /** Get cached import mappings for a file */
+    getImportMappings(filePath: string, language: Language): ImportMapping[];
+    /**
+     * Project import-path aliases (tsconfig/jsconfig `paths`). Returns
+     * `null` when the project doesn't define any. Cached per resolver
+     * instance — safe to call from any resolver code path. Optional so
+     * existing test fixtures and external context implementations
+     * compile without modification; production resolver implements it.
+     */
+    getProjectAliases?(): import('./path-aliases').AliasMap | null;
+    /**
+     * Go module info from `go.mod` at the project root. Returns `null`
+     * when the project has no `go.mod` (non-Go projects, pre-modules
+     * Go code, or projects whose modules live in subdirectories). Used
+     * by the Go branch of import resolution to distinguish in-module
+     * cross-package imports from third-party packages.
+     */
+    getGoModule?(): import('./go-module').GoModule | null;
+    /**
+     * Monorepo workspace member packages, keyed by declared package name.
+     * Returns `null` for single-package repos (no `workspaces` field).
+     * Lets the resolver treat `@scope/ui/sub` as a local import into the
+     * member's directory instead of an external npm package (#629).
+     */
+    getWorkspacePackages?(): import('./workspace-packages').WorkspacePackages | null;
+    /**
+     * Re-exports declared by a file (`export { x } from './other'`,
+     * `export * from './other'`). Empty array when the file has none.
+     * Optional so older callers compile; the import resolver follows
+     * re-export chains when this is provided.
+     */
+    getReExports?(filePath: string, language: Language): ReExport[];
+    /**
+     * List immediate subdirectories of `relativePath` (relative to the
+     * project root). Returns an empty array when the path doesn't exist
+     * or isn't a directory. Used by framework resolvers that need to
+     * walk build-system metadata (e.g. Cargo workspace globs). Optional
+     * so external context implementations and test fixtures compile
+     * without modification.
+     */
+    listDirectories?(relativePath: string): string[];
+    /**
+     * C/C++ include search directories (relative to project root),
+     * extracted from compile_commands.json or discovered by heuristic.
+     * Used by resolveCppIncludePath to search -I directories when
+     * relative resolution fails. Optional so existing callers compile.
+     */
+    getCppIncludeDirs?(): string[];
+}
+/**
+ * Result of framework-specific file extraction.
+ */
+export interface FrameworkExtractionResult {
+    /** Framework-specific nodes (e.g. routes) */
+    nodes: Node[];
+    /** Framework-specific unresolved references (e.g. route -> handler) */
+    references: UnresolvedRef[];
+}
+/**
+ * Framework-specific resolver
+ */
+export interface FrameworkResolver {
+    /** Framework name */
+    name: string;
+    /** Languages this framework applies to. If omitted, applies to all languages. */
+    languages?: Language[];
+    /** Detect if project uses this framework (project-level, called once at startup) */
+    detect(context: ResolutionContext): boolean;
+    /** Resolve a reference using framework-specific patterns */
+    resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+    /**
+     * Opt a reference NAME through the resolver's name-exists pre-filter, even when
+     * no node is named that. Needed for dynamic dispatch where the call target is
+     * an attribute/descriptor, not a declared symbol (e.g. Django's
+     * `self._iterable_class(...)`, React effect callbacks). Returning true lets the
+     * ref reach `resolve()` instead of being dropped for having no name match.
+     */
+    claimsReference?(name: string): boolean;
+    /**
+     * Extract framework-specific nodes and references from a file.
+     *
+     * Returns route nodes, middleware nodes, etc., plus unresolved references
+     * that link those nodes to handlers (view classes, controller methods,
+     * included modules). Unresolved references flow into the normal resolution
+     * pipeline; the framework's own `resolve()` is one of the strategies tried.
+     */
+    extract?(filePath: string, content: string): FrameworkExtractionResult;
+    /**
+     * Cross-file finalization pass, called once after all per-file extraction
+     * completes (and again on every incremental sync). Used by frameworks where
+     * a symbol's final representation depends on a sibling file the per-file
+     * `extract()` never saw — e.g. NestJS's `RouterModule.register([...])`
+     * sets route prefixes for controllers declared elsewhere.
+     *
+     * Implementations return route/etc. nodes with mutated fields (typically
+     * `name`); the orchestrator persists each via `updateNode`. The node `id`
+     * MUST be preserved so existing edges (route → handler, etc.) stay intact;
+     * `qualifiedName` SHOULD be preserved so the pass stays idempotent — a
+     * second run can recover the original in-file form from `qualifiedName`.
+     */
+    postExtract?(context: ResolutionContext): Node[];
+}
+/**
+ * Import mapping from a file
+ */
+export interface ImportMapping {
+    /** Local name used in the file */
+    localName: string;
+    /** Original exported name (may differ due to aliasing) */
+    exportedName: string;
+    /** Source module/path */
+    source: string;
+    /** Whether it's a default import */
+    isDefault: boolean;
+    /** Whether it's a namespace import (import * as X) */
+    isNamespace: boolean;
+    /** Resolved file path (if local) */
+    resolvedPath?: string;
+}
+/**
+ * Re-export from a file: `export { x } from './other'` or
+ * `export * from './other'`. Used by the resolver to chase
+ * symbols through barrel files.
+ */
+export type ReExport = {
+    kind: 'named';
+    /** Name as exported by THIS file. */
+    exportedName: string;
+    /** Name in the upstream module (differs when renamed: `as`). */
+    originalName: string;
+    /** Module specifier of the upstream module. */
+    source: string;
+} | {
+    kind: 'wildcard';
+    /** Module specifier of the upstream module. */
+    source: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/resolution/workspace-packages.d.ts

@@ -0,0 +1,48 @@
+/**
+ * JS/TS workspace (monorepo) package resolution.
+ *
+ * npm / yarn / bun read member packages from the root `package.json`
+ * `workspaces` field; pnpm from `pnpm-workspace.yaml`. A cross-package
+ * import like `@scope/ui/widgets` is LOCAL to the monorepo, but to a
+ * single-package resolver it looks exactly like a third-party npm
+ * specifier — so `isExternalImport` flags it external and the
+ * consumer↔definition edge is never created. For component barrels
+ * (`export { default as X } from './x.svelte'`) that surfaces as a false
+ * `0 callers` on a live component (issue #629).
+ *
+ * This module maps each member package's declared `name` to its
+ * directory so the resolver can rewrite `@scope/ui/widgets` →
+ * `packages/ui/widgets` and then run normal extension/index resolution.
+ *
+ * Scope deliberately small for v1 (mirrors path-aliases.ts):
+ *   - reads `workspaces` (array OR `{ packages: [...] }`) from package.json,
+ *     plus a minimal `pnpm-workspace.yaml` `packages:` list
+ *   - expands one level of `*` / `**` globs (`packages/*`, `apps/*`)
+ *   - subpath resolution is directory-based (`@scope/ui/sub` → `<ui>/sub`);
+ *     it does NOT yet honour a member's `exports` map or `main` field
+ *   - returns null when the project declares no workspaces, so single-
+ *     package repos pay nothing and see no behaviour change.
+ */
+export interface WorkspacePackages {
+    /** Member package `name` → directory relative to projectRoot (posix). */
+    byName: Map<string, string>;
+}
+/**
+ * Load workspace member packages for `projectRoot`. Returns `null` when
+ * the project declares no workspaces (the common single-package case) —
+ * callers then skip all workspace logic.
+ *
+ * Cheap to call repeatedly only via the resolver's per-instance cache;
+ * this function itself touches the filesystem, so the resolver memoises it
+ * the same way it does {@link loadProjectAliases} / {@link loadGoModule}.
+ */
+export declare function loadWorkspacePackages(projectRoot: string): WorkspacePackages | null;
+/**
+ * Rewrite a bare workspace import to a path relative to projectRoot,
+ * WITHOUT an extension — the caller applies the language's extension/index
+ * resolution. `@scope/ui/widgets` → `packages/ui/widgets`; the bare package
+ * name `@scope/ui` → its directory. Returns `null` when no member package
+ * name matches.
+ */
+export declare function resolveWorkspaceImport(importPath: string, ws: WorkspacePackages): string | null;
+//# sourceMappingURL=workspace-packages.d.ts.map

package/dist/search/query-parser.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Field-qualified search query parser.
+ *
+ * Splits a raw query like
+ *
+ *     kind:function name:auth path:src/api authenticate
+ *
+ * into structured filters (kind=function, name="auth", path prefix
+ * "src/api") plus the free-text portion ("authenticate") that goes
+ * to FTS. Free-text and filters compose: filters narrow the result
+ * set, FTS scores within the narrowed set.
+ *
+ * Recognised fields (case-insensitive, value is the rest until
+ * whitespace):
+ *
+ *   kind:    one of function|method|class|interface|struct|...
+ *   lang:    one of typescript|python|go|...   (alias: language:)
+ *   path:    case-insensitive substring of file_path
+ *   name:    case-insensitive substring of the symbol's name
+ *
+ * Unknown field prefixes (e.g. `foo:bar`) are passed through to FTS
+ * as plain text — that's how someone searching for `TODO:` gets a
+ * result instead of a parse error.
+ *
+ * Quoting:
+ *   kind:function path:"src/some path/with spaces" → handled by stripping
+ *   the surrounding double quotes from the value (single token only,
+ *   no nested escapes).
+ */
+import type { NodeKind, Language } from '../types';
+export interface ParsedQuery {
+    /** Free-text portion to feed to FTS / LIKE. May be empty. */
+    text: string;
+    /** kind: filters (OR'd). Empty when none specified. */
+    kinds: NodeKind[];
+    /** lang:/language: filters (OR'd). Empty when none specified. */
+    languages: Language[];
+    /** path: filters (OR'd, case-insensitive substring of file_path). Empty when none. */
+    pathFilters: string[];
+    /** name: filters (OR'd, case-insensitive substring of node.name). */
+    nameFilters: string[];
+}
+/**
+ * Parse a raw query into structured filters + remaining text.
+ * Always returns a value; never throws.
+ */
+export declare function parseQuery(raw: string): ParsedQuery;
+/**
+ * Damerau-Levenshtein-ish bounded edit distance. Returns `maxDist + 1`
+ * as soon as the distance is known to exceed `maxDist`; that early-exit
+ * makes the fuzzy fallback cheap even over tens of thousands of names.
+ *
+ * Pure DP, O(min(len(a), len(b))) memory. Compares case-folded inputs;
+ * callers should pass `lowercase(name)` strings.
+ */
+export declare function boundedEditDistance(a: string, b: string, maxDist: number): number;
+//# sourceMappingURL=query-parser.d.ts.map

package/dist/search/query-utils.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Search Query Utilities
+ *
+ * Shared module for search term extraction and scoring.
+ */
+import { Node } from '../types';
+/** Normalize a name to a comparable token: lowercase, alphanumerics only. */
+export declare function normalizeNameToken(raw: string): string;
+/**
+ * Tokens that name the PROJECT as a whole — its `go.mod` module, `package.json`
+ * name, or repo root directory — rather than any specific symbol. A user
+ * naturally puts the project name in a query as context ("MyApp backend
+ * routes"), but it carries no discriminative signal: when it's also a substring
+ * of a symbol or path on one stack (a `MyAppFrontend/` dir, a `MyAppApp` class)
+ * it lexically inflates that stack and buries the rest (#720).
+ *
+ * Returned normalized (lowercase, alphanumerics only) so a query word can be
+ * compared by its normalized form. Only names ≥5 chars are kept — short ones
+ * (`api`, `app`, `core`, `web`) collide with real query terms too often to
+ * safely down-weight.
+ */
+export declare function deriveProjectNameTokens(projectRoot: string): Set<string>;
+/**
+ * Common stop words to filter from search queries.
+ * Includes generic English + code-specific noise words.
+ */
+export declare const STOP_WORDS: Set<string>;
+/**
+ * Generate stem variants of a search term by removing common English suffixes.
+ * Used for FTS query expansion so "caching" also finds "cache", "eviction" finds "evict", etc.
+ * Stems are used as PREFIX matches in FTS, so they don't need to be perfect English words.
+ */
+export declare function getStemVariants(term: string): string[];
+/**
+ * Extract meaningful search terms from a natural language query.
+ * Splits camelCase, PascalCase, snake_case, SCREAMING_SNAKE, and dot.notation
+ * into individual tokens before filtering.
+ *
+ * Preserves original compound identifiers (e.g., "scrapeLoop") alongside
+ * their split parts so that FTS can match both the full symbol name and
+ * individual words within it.
+ *
+ * Also generates stem variants (e.g., "caching"→"cache", "eviction"→"evict")
+ * so FTS prefix matching can find related code symbols.
+ */
+export declare function extractSearchTerms(query: string, options?: {
+    stems?: boolean;
+}): string[];
+/**
+ * Score path relevance to a query
+ * Higher score = more relevant path
+ */
+export declare function scorePathRelevance(filePath: string, query: string, projectNameTokens?: Set<string>): number;
+/**
+ * Check if a file path looks like a test file
+ */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Bonus when a node's name matches the search query.
+ * Exact matches get the largest boost; prefix matches get smaller boosts.
+ * Multi-word queries also check individual term matches against the name.
+ */
+export declare function nameMatchBonus(nodeName: string, query: string): number;
+/**
+ * Kind-based bonus for search ranking
+ * Functions and classes are typically more relevant than variables/imports
+ */
+export declare function kindBonus(kind: Node['kind']): number;
+/**
+ * Whether a query token looks like a code identifier the user deliberately typed
+ * (camelCase / PascalCase-with-internal-caps / snake_case / has a digit) rather
+ * than a plain dictionary word ("flat", "object", "screen").
+ *
+ * Used to decide whether an EXACT name match earns the "the user named this
+ * symbol" exemption from single-term dampening. A common English word that
+ * happens to exact-match an unrelated symbol — the query "flat object" matching
+ * a constant named `FLAT` — must NOT get that exemption, or the +exact-name
+ * bonus floats it to the top of a prose query on its own.
+ *
+ * Classifies the token AS THE USER TYPED IT, not the matched symbol's name:
+ * "flat" (lowercase, descriptive) is non-distinctive even though it matches
+ * `FLAT`. A leading-capital-only word ("Screen", "Zustand") is also treated as
+ * a plain word — sentence-start capitalization and proper nouns aren't reliable
+ * identifier signals.
+ */
+export declare function isDistinctiveIdentifier(token: string): boolean;
+//# sourceMappingURL=query-utils.d.ts.map