@ltm-alpha/alpha-cs 1.6.0

package/dist/ui-server/api/search.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `GET /api/search?q=` — the search palette's one round-trip.
+ *
+ * Three lookups feed it, because no single one covers what a person types into
+ * a palette:
+ *
+ * - `getNodesByNameSubstring` — case-insensitive, catches the exact, prefix and
+ *   mid-name matches (`profileInfo` inside `getProfileInfoV2`) that FTS tokens
+ *   cannot.
+ * - `searchNodes` — FTS5, plus the engine's own LIKE and fuzzy fallbacks, and
+ *   the `kind:` / `lang:` / `path:` / `name:` filter grammar for free.
+ * - `getNodesByName` — every symbol with exactly that name, uncapped, so a
+ *   heavily-overloaded name never loses its definitions below a search cut.
+ *
+ * They are then merged and ranked by HOW the name matched — exact, prefix,
+ * substring, qualified name, file path — rather than by any single engine's
+ * score, because those scores are not comparable with each other. Results are
+ * grouped by kind: "did I mean the class or the method" is the question a
+ * palette actually has to answer.
+ */
+import type AlphaCodeSense from '../../index';
+import { type WireNodeRef } from './wire';
+/** How a result's text matched the query. Also the primary sort key. */
+export type MatchKind = 'exact' | 'prefix' | 'substring' | 'qualified' | 'file' | 'related';
+export interface WireSearchResult extends WireNodeRef {
+    matchKind: MatchKind;
+}
+export declare function buildSearch(cg: AlphaCodeSense, query: URLSearchParams): unknown;
+//# sourceMappingURL=search.d.ts.map

package/dist/ui-server/api/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,cAAc,MAAM,aAAa,CAAC;AAI9C,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE/D,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;AAgB5F,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,SAAS,EAAE,SAAS,CAAC;CACtB;AA+CD,wBAAgB,WAAW,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAgG/E"}

package/dist/ui-server/api/search.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * `GET /api/search?q=` — the search palette's one round-trip.
+ *
+ * Three lookups feed it, because no single one covers what a person types into
+ * a palette:
+ *
+ * - `getNodesByNameSubstring` — case-insensitive, catches the exact, prefix and
+ *   mid-name matches (`profileInfo` inside `getProfileInfoV2`) that FTS tokens
+ *   cannot.
+ * - `searchNodes` — FTS5, plus the engine's own LIKE and fuzzy fallbacks, and
+ *   the `kind:` / `lang:` / `path:` / `name:` filter grammar for free.
+ * - `getNodesByName` — every symbol with exactly that name, uncapped, so a
+ *   heavily-overloaded name never loses its definitions below a search cut.
+ *
+ * They are then merged and ranked by HOW the name matched — exact, prefix,
+ * substring, qualified name, file path — rather than by any single engine's
+ * score, because those scores are not comparable with each other. Results are
+ * grouped by kind: "did I mean the class or the method" is the question a
+ * palette actually has to answer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSearch = buildSearch;
+const query_parser_1 = require("../../search/query-parser");
+const respond_1 = require("./respond");
+const wire_1 = require("./wire");
+const MATCH_RANK = {
+    exact: 0,
+    prefix: 1,
+    substring: 2,
+    qualified: 3,
+    file: 4,
+    // Matched by FTS through a signature, docstring or fuzzy neighbour — real,
+    // but never what someone typing a name is looking for first.
+    related: 5,
+};
+/** Candidates pulled from each source before ranking trims to `limit`. */
+const CANDIDATE_POOL = 400;
+/**
+ * Tie-break inside a match tier: the kinds someone navigates to, before the
+ * kinds that merely mention a name.
+ */
+function kindRank(kind) {
+    switch (kind) {
+        case 'function':
+        case 'method':
+        case 'class':
+        case 'component':
+        case 'interface':
+        case 'struct':
+        case 'trait':
+        case 'protocol':
+        case 'enum':
+        case 'union':
+        case 'type_alias':
+        case 'route':
+            return 0;
+        case 'constant':
+        case 'property':
+        case 'field':
+        case 'variable':
+        case 'enum_member':
+            return 1;
+        case 'file':
+        case 'module':
+        case 'namespace':
+            return 2;
+        default:
+            // import / export / parameter — a mention, not a definition.
+            return 3;
+    }
+}
+function classify(node, needle) {
+    const name = node.name.toLowerCase();
+    if (name === needle)
+        return 'exact';
+    if (name.startsWith(needle))
+        return 'prefix';
+    if (name.includes(needle))
+        return 'substring';
+    if (node.qualifiedName.toLowerCase().includes(needle))
+        return 'qualified';
+    if (node.filePath.toLowerCase().replace(/\\/g, '/').includes(needle))
+        return 'file';
+    return null;
+}
+function buildSearch(cg, query) {
+    const raw = (0, respond_1.optionalTextParam)(query, 'q');
+    const limit = (0, respond_1.intParam)(query, 'limit', { min: 1, max: 200, default: 60 });
+    // An empty search box is the palette's resting state, not a mistake — it
+    // answers with nothing rather than with an error the viewer has to special-
+    // case. A MISSING `q` is still a 400: that is a caller bug.
+    if (raw.trim() === '')
+        return emptySearch(raw);
+    // The filter grammar (`kind:function auth`) belongs to `searchNodes`; the
+    // name lookups only ever want the free-text part of what was typed.
+    const parsed = (0, query_parser_1.parseQuery)(raw);
+    const text = parsed.text.trim();
+    const needle = text.toLowerCase();
+    const candidates = new Map();
+    const remember = (node) => {
+        if (!candidates.has(node.id))
+            candidates.set(node.id, node);
+    };
+    if (text.length > 0) {
+        for (const node of cg.getNodesByName(text))
+            remember(node);
+        for (const node of cg.getNodesByNameSubstring(text, { limit: CANDIDATE_POOL }))
+            remember(node);
+    }
+    for (const result of cg.searchNodes(raw, { limit: CANDIDATE_POOL }))
+        remember(result.node);
+    const scored = [];
+    for (const node of candidates.values()) {
+        // `searchNodes` applies the filter grammar to its own results, but the two
+        // direct name lookups above know nothing about it — so `kind:class Cache`
+        // would otherwise pull in `CacheKey` and every `Cache` method through the
+        // substring lookup. The gate belongs to the merged candidate set.
+        if (!matchesFilters(node, parsed))
+            continue;
+        // An empty text portion means the query was pure filters (`kind:route`);
+        // everything `searchNodes` returned already satisfies them, so there is no
+        // name match to grade and every row is equally "related".
+        const match = needle.length === 0 ? 'related' : classify(node, needle) ?? 'related';
+        scored.push({ node, match });
+    }
+    scored.sort((a, b) => {
+        const byMatch = MATCH_RANK[a.match] - MATCH_RANK[b.match];
+        if (byMatch !== 0)
+            return byMatch;
+        const byKind = kindRank(a.node.kind) - kindRank(b.node.kind);
+        if (byKind !== 0)
+            return byKind;
+        // Production code before tests and fixtures: both are real answers, but one
+        // of them is the one someone searching for a symbol usually means.
+        const aTest = isTestPath(a.node.filePath);
+        const bTest = isTestPath(b.node.filePath);
+        if (aTest !== bTest)
+            return aTest ? 1 : -1;
+        // Shorter names are closer to what was typed (`get` before `getOrCreate`).
+        const byLength = a.node.name.length - b.node.name.length;
+        if (byLength !== 0)
+            return byLength;
+        return (a.node.filePath.localeCompare(b.node.filePath) || a.node.startLine - b.node.startLine);
+    });
+    const top = scored.slice(0, limit);
+    // One bounded lookup for the whole page of results, so a generated stub
+    // reads as one at a glance instead of after a click.
+    const isGenerated = cg.generatedFilePredicate(top.map(({ node }) => node.filePath));
+    const results = top.map(({ node, match }) => {
+        const result = { ...(0, wire_1.toNodeRef)(node), matchKind: match };
+        if (isGenerated(node.filePath))
+            result.generated = true;
+        return result;
+    });
+    // Groups keep the ranked order: a group appears where its best result did, so
+    // flattening the groups reproduces the flat ranking for keyboard navigation.
+    const groups = [];
+    const byKind = new Map();
+    for (const result of results) {
+        const bucket = byKind.get(result.kind);
+        if (bucket) {
+            bucket.push(result);
+        }
+        else {
+            const created = [result];
+            byKind.set(result.kind, created);
+            groups.push({ kind: result.kind, count: 0, items: created });
+        }
+    }
+    for (const group of groups)
+        group.count = group.items.length;
+    return {
+        query: raw,
+        text,
+        filters: {
+            kinds: parsed.kinds,
+            languages: parsed.languages,
+            paths: parsed.pathFilters,
+            names: parsed.nameFilters,
+        },
+        results: (0, wire_1.wireList)(results, scored.length),
+        groups,
+    };
+}
+/**
+ * Deliberately a plain path check rather than the engine's `isTestFile`: this
+ * is a ranking nudge inside one tier, and `isTestFile` also treats `examples/`,
+ * `benchmarks/` and `fixtures/` as tests — pushing a legitimately-searched
+ * example below an unrelated production symbol.
+ */
+function isTestPath(filePath) {
+    const lower = filePath.toLowerCase().replace(/\\/g, '/');
+    return (/(^|\/)(tests?|specs?|__tests__)\//.test(lower) ||
+        /[._-](test|tests|spec|specs)\.[a-z0-9]+$/.test(lower));
+}
+/**
+ * The hard gate the `kind:` / `lang:` / `path:` / `name:` grammar asks for.
+ *
+ * Deliberately the same predicates `searchNodes` uses internally — kinds and
+ * languages exact, paths and names case-insensitive substrings, each list OR'd
+ * within itself and AND'd across lists — so a filtered search means the same
+ * thing whichever lookup a result came from.
+ */
+function matchesFilters(node, parsed) {
+    if (parsed.kinds.length > 0 && !parsed.kinds.includes(node.kind))
+        return false;
+    if (parsed.languages.length > 0 && !parsed.languages.includes(node.language))
+        return false;
+    if (parsed.pathFilters.length > 0) {
+        const file = node.filePath.toLowerCase();
+        if (!parsed.pathFilters.some((p) => file.includes(p.toLowerCase())))
+            return false;
+    }
+    if (parsed.nameFilters.length > 0) {
+        const name = node.name.toLowerCase();
+        if (!parsed.nameFilters.some((n) => name.includes(n.toLowerCase())))
+            return false;
+    }
+    return true;
+}
+/** The resting state of the palette: the shape of a real answer, with nothing in it. */
+function emptySearch(raw) {
+    return {
+        query: raw,
+        text: '',
+        filters: { kinds: [], languages: [], paths: [], names: [] },
+        results: (0, wire_1.wireList)([], 0),
+        groups: [],
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/ui-server/api/search.js.map

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

package/dist/ui-server/api/session.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one open handle on the project's index.
+ *
+ * `AlphaCodeSense.openSync` costs tens of milliseconds and runs pending migrations,
+ * so it happens once for the life of the server rather than once per request.
+ * That leaves two things this module has to get right:
+ *
+ * - **A missing index is guidance, not a stack trace.** `codegraph ui` refuses
+ *   to start without one, but a user can delete `.alpha-cs/` while the viewer
+ *   is open, so every endpoint has to be able to say so in the same words the
+ *   CLI does.
+ * - **A re-index must not be served from a phantom database.** `codegraph init`
+ *   on an already-indexed project *replaces the database file* (see
+ *   `AlphaCodeSense.recreate`). On POSIX our handle would keep reading the unlinked
+ *   inode and happily serve a graph that no longer exists on disk. So the file
+ *   identity is re-checked on acquisition — one `stat` — and a swapped file
+ *   reopens the connection.
+ * - **A sync by ANOTHER process must not be served from memory.** The same
+ *   `stat` also notices the database growing, and when it has, the read caches
+ *   go (`dropReadCaches`). The query layer holds an LRU of nodes by id which
+ *   only a write through *this* instance invalidates, so without it
+ *   `/api/node/<id>` keeps answering with a symbol an agent's sync deleted
+ *   while `/api/search` — which never caches — correctly says it is gone. That
+ *   is not a stale screen, it is two screens contradicting each other; and
+ *   because a node's id contains its start line, ANY edit above a symbol
+ *   renames it, so this is the common case rather than the corner one.
+ */
+import AlphaCodeSense from '../../index';
+/**
+ * Holds the project's `AlphaCodeSense` open for the life of the server.
+ *
+ * Not thread-safe and does not need to be: `node:http` dispatches on one
+ * thread, and every read below is synchronous.
+ */
+export declare class GraphSession {
+    readonly projectRoot: string;
+    private readonly dbPath;
+    private cg;
+    private identity;
+    constructor(projectRoot: string);
+    /**
+     * The open graph, opening (or reopening) it if needed.
+     *
+     * @throws {ApiError} `no-index` when the project has no index,
+     *   `index-unusable` when it has one that will not open.
+     */
+    acquire(): AlphaCodeSense;
+    /** Release the handle. Idempotent — the CLI calls it on Ctrl-C. */
+    close(): void;
+    private closeQuietly;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/ui-server/api/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,cAAc,MAAM,aAAa,CAAC;AAiFzC;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,EAAE,CAA+B;IACzC,OAAO,CAAC,QAAQ,CAA6B;gBAEjC,WAAW,EAAE,MAAM;IAK/B;;;;;OAKG;IACH,OAAO,IAAI,cAAc;IAuCzB,mEAAmE;IACnE,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,YAAY;CAYrB"}

package/dist/ui-server/api/session.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * The one open handle on the project's index.
+ *
+ * `AlphaCodeSense.openSync` costs tens of milliseconds and runs pending migrations,
+ * so it happens once for the life of the server rather than once per request.
+ * That leaves two things this module has to get right:
+ *
+ * - **A missing index is guidance, not a stack trace.** `codegraph ui` refuses
+ *   to start without one, but a user can delete `.alpha-cs/` while the viewer
+ *   is open, so every endpoint has to be able to say so in the same words the
+ *   CLI does.
+ * - **A re-index must not be served from a phantom database.** `codegraph init`
+ *   on an already-indexed project *replaces the database file* (see
+ *   `AlphaCodeSense.recreate`). On POSIX our handle would keep reading the unlinked
+ *   inode and happily serve a graph that no longer exists on disk. So the file
+ *   identity is re-checked on acquisition — one `stat` — and a swapped file
+ *   reopens the connection.
+ * - **A sync by ANOTHER process must not be served from memory.** The same
+ *   `stat` also notices the database growing, and when it has, the read caches
+ *   go (`dropReadCaches`). The query layer holds an LRU of nodes by id which
+ *   only a write through *this* instance invalidates, so without it
+ *   `/api/node/<id>` keeps answering with a symbol an agent's sync deleted
+ *   while `/api/search` — which never caches — correctly says it is gone. That
+ *   is not a stale screen, it is two screens contradicting each other; and
+ *   because a node's id contains its start line, ANY edit above a symbol
+ *   renames it, so this is the common case rather than the corner one.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphSession = void 0;
+const fs = __importStar(require("fs"));
+const index_1 = __importDefault(require("../../index"));
+const db_1 = require("../../db");
+const directory_1 = require("../../directory");
+const respond_1 = require("./respond");
+function identify(dbPath) {
+    try {
+        const st = fs.statSync(dbPath);
+        let walSize = 0;
+        let walMtimeMs = 0;
+        try {
+            const wal = fs.statSync(`${dbPath}-wal`);
+            walSize = wal.size;
+            walMtimeMs = wal.mtimeMs;
+        }
+        catch {
+            // No WAL sidecar: either not in WAL mode, or fully checkpointed. Both are
+            // "nothing pending", which is what zeroes mean here.
+        }
+        return {
+            ino: st.ino,
+            birthtimeMs: st.birthtimeMs,
+            size: st.size,
+            mtimeMs: st.mtimeMs,
+            walSize,
+            walMtimeMs,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function sameFile(a, b) {
+    if (a === null || b === null)
+        return false;
+    // `ino` is 0 on a few Windows filesystems; birthtime alone still catches a
+    // recreate there, and a false "changed" only costs one reopen.
+    return a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+}
+/** Same file, but written to since we last looked. */
+function sameContent(a, b) {
+    if (a === null || b === null)
+        return false;
+    return (a.size === b.size &&
+        a.mtimeMs === b.mtimeMs &&
+        a.walSize === b.walSize &&
+        a.walMtimeMs === b.walMtimeMs);
+}
+/**
+ * Guidance shown when there is no index to read. Deliberately the same three
+ * facts the CLI prints: the viewer never creates an index, `codegraph init`
+ * does, and you can point the viewer somewhere already indexed.
+ */
+function noIndexError(projectRoot) {
+    return new respond_1.ApiError('no-index', `No Alpha Code Sense index found for ${projectRoot}.`, 'The viewer reads an index that already exists — it never creates one. ' +
+        'Run "codegraph init" in that project, or start the viewer against a project ' +
+        'that has one: codegraph ui /path/to/indexed/project');
+}
+/**
+ * Holds the project's `AlphaCodeSense` open for the life of the server.
+ *
+ * Not thread-safe and does not need to be: `node:http` dispatches on one
+ * thread, and every read below is synchronous.
+ */
+class GraphSession {
+    projectRoot;
+    dbPath;
+    cg = null;
+    identity = null;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.dbPath = (0, db_1.getDatabasePath)(projectRoot);
+    }
+    /**
+     * The open graph, opening (or reopening) it if needed.
+     *
+     * @throws {ApiError} `no-index` when the project has no index,
+     *   `index-unusable` when it has one that will not open.
+     */
+    acquire() {
+        const current = identify(this.dbPath);
+        if (this.cg !== null) {
+            if (sameFile(this.identity, current)) {
+                // Same file, but somebody wrote to it. SQLite itself is fine — a WAL
+                // reader sees the new commits — but our in-memory node cache is not,
+                // so it goes. One `stat` already paid for; clearing a bounded Map is
+                // the whole cost.
+                if (!sameContent(this.identity, current)) {
+                    this.identity = current;
+                    this.cg.dropReadCaches();
+                }
+                return this.cg;
+            }
+            // The database was replaced (a re-index) or removed. Drop the stale
+            // handle; falling through re-opens against whatever is there now.
+            this.closeQuietly();
+        }
+        if (!(0, directory_1.isInitialized)(this.projectRoot))
+            throw noIndexError(this.projectRoot);
+        try {
+            this.cg = index_1.default.openSync(this.projectRoot);
+        }
+        catch (err) {
+            this.cg = null;
+            this.identity = null;
+            throw new respond_1.ApiError('index-unusable', `The Alpha Code Sense index for ${this.projectRoot} could not be opened: ` +
+                (err instanceof Error ? err.message : String(err)), 'If another Alpha Code Sense process is rebuilding it, wait for that to finish. ' +
+                'If the index is damaged, rebuild it with "codegraph init".');
+        }
+        this.identity = current ?? identify(this.dbPath);
+        return this.cg;
+    }
+    /** Release the handle. Idempotent — the CLI calls it on Ctrl-C. */
+    close() {
+        this.closeQuietly();
+    }
+    closeQuietly() {
+        const cg = this.cg;
+        this.cg = null;
+        this.identity = null;
+        if (!cg)
+            return;
+        try {
+            cg.close();
+        }
+        catch {
+            // A close that fails has nothing left to release — the process is either
+            // exiting or the file is already gone. Never let it fail a request.
+        }
+    }
+}
+exports.GraphSession = GraphSession;
+//# sourceMappingURL=session.js.map

package/dist/ui-server/api/session.js.map

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