@ltm-alpha/alpha-cs 1.6.0

package/dist/search/query-paths.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * File-path recognition for explore queries.
+ *
+ * Agents routinely name files by path in a `codegraph_explore` query —
+ * "the scroll logic in src/routes/m/projects/[id]/runs/[runId]/+page.svelte" —
+ * and until this module existed those spans were SHREDDED by the downstream
+ * tokenizers instead of being read as file references:
+ *
+ *   - the named-symbol seeder splits on `[\s,()[\]]+`, so SvelteKit/Next
+ *     bracketed segments (`[id]`, `[runId]`) and route groups (`(protected)`)
+ *     exploded the path into fragments; the identifier-shaped survivors
+ *     (`runId`, `scope`) then seeded as "symbols the agent named" and
+ *     headlined the blast radius;
+ *   - FTS saw the fragments (`page`, `chat`, `runs`) and admitted every
+ *     sibling `+page.svelte` in the repo, which ate the output envelope and
+ *     truncated the files the agent actually asked for.
+ *
+ * `extractQueryPaths` finds path-like spans — slashed paths, dotted basenames,
+ * and extension-less kebab basenames (`background-image-table`, the spelling
+ * import paths and prose actually use) — resolves them against the INDEXED
+ * file list (resolution IS the detector — `and/or`, `gen_server:call/2`,
+ * `non-blocking` and other path-shaped non-paths match nothing and are left
+ * alone), and returns the matches as pinned files plus the query with those
+ * spans removed.
+ * Callers treat pinned files as first-class: guaranteed admission, top rank,
+ * funded first. Pure string work — no DB, no fs — so it is trivially testable
+ * and safe inside the query-pool workers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryMightContainPaths = queryMightContainPaths;
+exports.extractQueryPaths = extractQueryPaths;
+/**
+ * Cheap pre-gate so callers only fetch the indexed file list when the query
+ * could possibly contain a path: a slash, a dot-extension-shaped tail
+ * (`chat-manager.ts`), or a hyphen-joined word (`background-image-table` —
+ * kebab files are named WITHOUT their extension more often than with, so the
+ * shape must open the gate on its own). Extensions cap at 8 chars, which
+ * keeps `Class.method` spans (`app.isPackaged`) from qualifying; the kebab
+ * alternative requires clean non-word boundaries, which keeps `--flags` and
+ * snake_case-with-a-dash hybrids from firing it.
+ */
+function queryMightContainPaths(query) {
+    return /[/\\]/.test(query)
+        || /\.[A-Za-z][A-Za-z0-9]{0,7}(?=[\s,;:)\]'"`]|$)/.test(query)
+        || /(?:^|[^-\w])[A-Za-z0-9]+(?:-[A-Za-z0-9]+)+(?=[^-\w]|$)/.test(query);
+}
+/**
+ * Longest span→suffix walk tried per span. 8 covers an absolute macOS path
+ * (`/Users/<user>/dev/<repo>/…`) over a deeply nested repo-relative file;
+ * deeper prefixes buy nothing.
+ */
+const MAX_SUFFIX_TRIES = 8;
+/** Spans examined per query — a prose sentence is not 50 paths. */
+const MAX_CANDIDATE_SPANS = 8;
+/** `name.ext` shape with a plausible source extension (no slash required). */
+const DOTTED_BASENAME = /^[^\s/\\]+\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+/**
+ * Extension-less kebab basename (`background-image-table`). Hyphens are
+ * illegal in identifiers, so consuming these tokens can never steal one from
+ * the named-symbol seeder; ≥2 segments keeps single words out.
+ */
+const KEBAB_BASENAME = /^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)+$/;
+/** A basename's last dot-extension, same shape DOTTED_BASENAME accepts. */
+const LAST_EXTENSION = /\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+/**
+ * Lowercased basename stems of the hyphen-named indexed files, stem → paths.
+ * A stem drops only the LAST extension (`a-b.module.scss` → `a-b.module`), so
+ * a bare kebab token can't accidentally pin a same-named stylesheet or
+ * `.d.ts` sibling of the source file it names; an extension-less basename
+ * (`pre-commit`) is its own stem. Hyphen-free basenames are skipped — a
+ * KEBAB_BASENAME token can never equal one, and the filter keeps the map
+ * near-empty in repos that don't name files this way.
+ */
+function buildBasenameStems(indexedPaths) {
+    const stems = new Map();
+    for (const p of indexedPaths) {
+        const basename = p.slice(Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\')) + 1);
+        if (!basename.includes('-'))
+            continue;
+        const stem = basename.replace(LAST_EXTENSION, '').toLowerCase();
+        if (!stem)
+            continue;
+        const existing = stems.get(stem);
+        if (existing)
+            existing.push(p);
+        else
+            stems.set(stem, [p]);
+    }
+    return stems;
+}
+/**
+ * Strip prose punctuation wrapped around a token without eating punctuation
+ * that is PART of the path: quotes/backticks always strip; a trailing `)`/`]`
+ * strips only when the token has no matching opener (so `(protected)` and
+ * `[id]` segments survive, while "…(see src/foo.ts)" loses its parenthesis);
+ * a leading `(`/`[` mirrors that. Trailing sentence punctuation strips last,
+ * so "src/foo.ts." resolves.
+ */
+function stripWrapping(token) {
+    let s = token;
+    for (;;) {
+        const first = s[0];
+        if (!first)
+            break;
+        if ('\'"`<'.includes(first)) {
+            s = s.slice(1);
+            continue;
+        }
+        if (first === '(' && !s.includes(')')) {
+            s = s.slice(1);
+            continue;
+        }
+        if (first === '[' && !s.includes(']')) {
+            s = s.slice(1);
+            continue;
+        }
+        if (first === '{' && !s.includes('}')) {
+            s = s.slice(1);
+            continue;
+        }
+        break;
+    }
+    for (;;) {
+        const last = s[s.length - 1];
+        if (!last)
+            break;
+        if ('\'"`>.,;!?'.includes(last)) {
+            s = s.slice(0, -1);
+            continue;
+        }
+        if (last === ')' && !s.includes('(')) {
+            s = s.slice(0, -1);
+            continue;
+        }
+        if (last === ']' && !s.includes('[')) {
+            s = s.slice(0, -1);
+            continue;
+        }
+        if (last === '}' && !s.includes('{')) {
+            s = s.slice(0, -1);
+            continue;
+        }
+        break;
+    }
+    // Line references ride along in agent-written paths: `foo.ts:123`,
+    // `foo.ts:12-40`, `foo.ts#L88`. The file is what gets pinned.
+    s = s.replace(/(?::\d+(?:-\d+)?|#L\d+(?:-L?\d+)?)$/, '');
+    return s;
+}
+/** Normalize a span into the repo-relative shape the files table stores. */
+function normalizeSpan(span) {
+    return span
+        .replace(/\\/g, '/')
+        .replace(/^(?:\.\/)+/, '')
+        .replace(/\/{2,}/g, '/')
+        .replace(/\/+$/, '');
+}
+/** Path-shaped beyond doubt: ≥2 segments and a dot-extension on the last. */
+function isClearlyPathShaped(normalized) {
+    const slash = normalized.lastIndexOf('/');
+    if (slash <= 0)
+        return false;
+    return DOTTED_BASENAME.test(normalized.slice(slash + 1));
+}
+/**
+ * Resolve one normalized span against the indexed paths: exact match first,
+ * then segment-aligned suffix matches, dropping leading segments one at a
+ * time (so an absolute path, or one prefixed with the repo directory name,
+ * still lands on the indexed repo-relative file). Suffixes only get shorter —
+ * and therefore only match MORE — so the walk stops at the first suffix that
+ * matches anything: within budget it resolves, over budget it is ambiguous.
+ */
+function resolveSpan(normalizedLower, lowerToOriginal, maxMatches) {
+    const exact = lowerToOriginal.get(normalizedLower);
+    if (exact)
+        return { matches: [exact], ambiguous: false };
+    const segments = normalizedLower.split('/').filter(Boolean);
+    const tries = Math.min(segments.length, MAX_SUFFIX_TRIES);
+    for (let drop = 0; drop < tries; drop++) {
+        const suffix = segments.slice(drop).join('/');
+        if (!suffix)
+            break;
+        const withSlash = '/' + suffix;
+        const matches = [];
+        for (const [lower, original] of lowerToOriginal) {
+            if (lower === suffix || lower.endsWith(withSlash)) {
+                matches.push(original);
+                if (matches.length > maxMatches)
+                    return { matches: [], ambiguous: true };
+            }
+        }
+        if (matches.length > 0)
+            return { matches, ambiguous: false };
+    }
+    return { matches: [], ambiguous: false };
+}
+function extractQueryPaths(query, indexedPaths, opts = {}) {
+    const maxPins = Math.max(1, opts.maxPins ?? 8);
+    const maxMatchesPerSpan = Math.max(1, opts.maxMatchesPerSpan ?? 3);
+    const passthrough = {
+        strippedQuery: query,
+        pinnedFiles: [],
+        unresolvedPathSpans: [],
+    };
+    if (!query.trim() || indexedPaths.length === 0)
+        return passthrough;
+    // Lowercase view of the index, built once per call. Last writer wins on a
+    // case-colliding pair, which is the existing file-view behavior too.
+    const lowerToOriginal = new Map();
+    for (const p of indexedPaths)
+        lowerToOriginal.set(p.toLowerCase(), p);
+    const tokens = query.split(/\s+/).filter(Boolean);
+    const consumed = new Set();
+    const pinned = [];
+    const pinnedSeen = new Set();
+    const unresolved = [];
+    let candidatesExamined = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        if (pinned.length >= maxPins)
+            break;
+        if (candidatesExamined >= MAX_CANDIDATE_SPANS)
+            break;
+        const stripped = stripWrapping(tokens[i]);
+        if (stripped.length < 4)
+            continue;
+        const hasSlash = /[/\\]/.test(stripped);
+        if (!hasSlash && !DOTTED_BASENAME.test(stripped))
+            continue;
+        const normalized = normalizeSpan(stripped);
+        if (!normalized)
+            continue;
+        candidatesExamined++;
+        const { matches, ambiguous } = resolveSpan(normalized.toLowerCase(), lowerToOriginal, maxMatchesPerSpan);
+        if (matches.length > 0) {
+            consumed.add(i);
+            for (const m of matches) {
+                if (pinnedSeen.has(m) || pinned.length >= maxPins)
+                    continue;
+                pinnedSeen.add(m);
+                pinned.push(m);
+            }
+        }
+        else if (ambiguous || isClearlyPathShaped(normalized)) {
+            // A real path that didn't resolve to a usable set. Keeping it in the
+            // query is strictly worse — its fragments are what minted the junk
+            // matches this module exists to stop — so strip it and say so.
+            consumed.add(i);
+            if (unresolved.length < 4)
+                unresolved.push(normalized);
+        }
+        // Anything else (`and/or`, `call/2`, `foo.Bar`) is not a path reference:
+        // leave the token for the normal matching pipeline.
+    }
+    // Second pass — extension-less kebab basenames. `background-image-table`
+    // opens no door above (no slash, no dotted tail), the hyphens disqualify it
+    // from the named-symbol seeder downstream, and FTS shreds it into the most
+    // common words in a kebab-cased repo (`background`, `image`, `table`) —
+    // which admit look-alike SIBLINGS that crowd out the named file. Resolution
+    // stays the detector: a token pins only when its whole lowercased form is
+    // the stem of an indexed basename. Two deliberate asymmetries vs the first
+    // pass: prose that resolves to nothing (`non-blocking`, `cross-call`) is
+    // LEFT IN the query — unlike a slashed span it may be legitimate wording,
+    // so it keeps feeding FTS and is not reported as an unresolved path — and a
+    // stem hotter than maxMatchesPerSpan is likewise left alone (pinning half a
+    // monorepo off one hot name trades precision the wrong way; a directory
+    // segment, which the first pass handles, disambiguates). Runs after the
+    // slashed/dotted pass so explicit paths win the shared maxPins budget, and
+    // examines every remaining token: lookups are O(1) map hits, so the
+    // scan-cost rationale behind MAX_CANDIDATE_SPANS doesn't apply.
+    let basenameStems = null;
+    for (let i = 0; i < tokens.length && pinned.length < maxPins; i++) {
+        if (consumed.has(i))
+            continue;
+        const stripped = stripWrapping(tokens[i]);
+        if (stripped.length < 4 || !KEBAB_BASENAME.test(stripped))
+            continue;
+        basenameStems ??= buildBasenameStems(indexedPaths);
+        const matches = basenameStems.get(stripped.toLowerCase());
+        if (!matches || matches.length > maxMatchesPerSpan)
+            continue;
+        consumed.add(i);
+        for (const m of matches) {
+            if (pinnedSeen.has(m) || pinned.length >= maxPins)
+                continue;
+            pinnedSeen.add(m);
+            pinned.push(m);
+        }
+    }
+    if (consumed.size === 0)
+        return passthrough;
+    return {
+        strippedQuery: tokens.filter((_, i) => !consumed.has(i)).join(' '),
+        pinnedFiles: pinned,
+        unresolvedPathSpans: unresolved,
+    };
+}
+//# sourceMappingURL=query-paths.js.map

package/dist/search/query-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-paths.js","sourceRoot":"","sources":["../../src/search/query-paths.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,102 @@
+/**
+ * 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>, isDeprioritized?: boolean): number;
+/**
+ * Check if a file path looks like a test file
+ *
+ * "Test" here is the wide reading: anything that is not production code,
+ * including examples, samples, benchmarks and fixtures. That is the right
+ * default for ranking — none of them are what a search is looking for — but it
+ * is the wrong set to put under a heading that says "Tests". A caller that
+ * means literally a test suite wants {@link isTestPath}.
+ */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Check if a file path names a TEST — a suite that exercises other code.
+ *
+ * The narrow half of {@link isTestFile}: the filename and directory
+ * conventions every ecosystem uses for its test suites, and nothing else. An
+ * example, a benchmark or a fixture is not a test, and a list headed "Tests"
+ * that contains them is telling the reader something untrue.
+ */
+export declare function isTestPath(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

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-utils.d.ts","sourceRoot":"","sources":["../../src/search/query-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAyBxE;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,aAkBrB,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyDtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CA2DzF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC/B,eAAe,CAAC,EAAE,OAAO,GACxB,MAAM,CA2DR;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKpD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAyCpD;AAwBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAuCtE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,MAAM,CA2BpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ9D"}