@huanlin/dsh-plugin-codegraph-sqlite 0.1.8

package/lib/queries.js

@@ -0,0 +1,302 @@
+/**
+ * The eight seam operations against one open graph database. Every function here is synchronous:
+ * `node:sqlite` is a synchronous binding, so a query either completes within one turn or throws,
+ * and the store's async surface exists for the seam's contract rather than for I/O interleaving.
+ * @module @huanlin/dsh-plugin-codegraph-sqlite/queries
+ */
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CodegraphError } from '@huanlin/dsh-plugin-codegraph-service';
+import { toEdge, toFile, toNode } from "./rows.js";
+import { NODE_COLUMNS, SEARCH_ORDER, SYMBOL_ORDER, ftsPhrase, likeAnywhere, } from "./sql.js";
+/** Run a statement and return its rows already typed as raw records. */
+function rows(db, sql, ...params) {
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Read a single-column aggregate as a number. Every caller passes an aggregate, which always yields
+ * exactly one row and one column; `MAX` over an empty table yields SQL NULL, which reads as 0.
+ */
+function scalar(db, sql, ...params) {
+    const [value] = Object.values(db.prepare(sql).get(...params));
+    return typeof value === 'number' ? value : 0;
+}
+/**
+ * Candidate declarations for a symbol name, most relevant first.
+ * @param db - the open graph connection.
+ * @param symbol - the simple or qualified name to resolve.
+ * @param limit - largest number of candidates to read.
+ * @returns the matching nodes in relevance order; empty when the name matches nothing.
+ */
+function resolveSymbol(db, symbol, limit) {
+    return rows(db, `SELECT ${NODE_COLUMNS} FROM nodes n
+      WHERE n.qualified_name = ? OR n.name = ? OR lower(n.name) = lower(?)
+      ORDER BY ${SYMBOL_ORDER}
+      LIMIT ?`, symbol, symbol, symbol, symbol, symbol, symbol, limit).map(toNode);
+}
+/**
+ * Find declarations matching a free-text query.
+ * @param db - the open graph connection.
+ * @param request - the search query with its resolved bounds.
+ * @returns the matching declarations, most relevant first, with the pre-limit total.
+ */
+export function search(db, request) {
+    const like = likeAnywhere(request.query);
+    const kind = request.kind ?? null;
+    const language = request.language ?? null;
+    const candidates = `
+    FROM nodes n
+    JOIN (
+      SELECT rowid AS rid FROM nodes WHERE lower(name) LIKE ? ESCAPE '\\' OR lower(qualified_name) LIKE ? ESCAPE '\\'
+      UNION
+      SELECT rowid FROM nodes_fts WHERE nodes_fts MATCH ?
+    ) m ON m.rid = n.rowid
+    WHERE (? IS NULL OR n.kind = ?) AND (? IS NULL OR n.language = ?)`;
+    const filters = [like, like, ftsPhrase(request.query), kind, kind, language, language];
+    const total = scalar(db, `SELECT count(*) AS total ${candidates}`, ...filters);
+    const matches = rows(db, `SELECT ${NODE_COLUMNS} ${candidates} ORDER BY ${SEARCH_ORDER} LIMIT ?`, ...filters, request.query, request.query, request.query, request.query, request.limit).map(toNode);
+    return { kind: 'search', nodes: matches, total, truncated: total > matches.length };
+}
+/** Read every edge on one side of a node, with the node at the far end. */
+function relationsOf(db, id, direction, edgeKind, limit) {
+    const anchor = direction === 'incoming' ? 'target' : 'source';
+    const far = direction === 'incoming' ? 'source' : 'target';
+    const where = `WHERE e.${anchor} = ? AND (? IS NULL OR e.kind = ?)`;
+    // Grouping by the far node AND the edge kind is what makes a relation distinct: five calls from
+    // one function collapse to one relation, while a node that both calls and contains another stays
+    // two, because those are different facts about the pair.
+    const grouping = `GROUP BY e.${far}, e.kind`;
+    const total = scalar(db, `SELECT count(*) AS total FROM (SELECT 1 FROM edges e ${where} ${grouping})`, id, edgeKind, edgeKind);
+    const relations = rows(db, 
+    // MIN(e.line) both picks the earliest site and, per SQLite's bare-column rule for a query with a
+    // single MIN aggregate, makes every other `e.` column come from that same earliest row.
+    `SELECT ${NODE_COLUMNS}, e.source AS edge_source, e.target AS edge_target, e.kind AS edge_kind,
+            MIN(e.line) AS edge_line, e.col AS edge_col, e.provenance AS edge_provenance,
+            count(*) AS site_count
+       FROM edges e
+       JOIN nodes n ON n.id = e.${far}
+       ${where}
+       ${grouping}
+       ORDER BY n.file_path, MIN(e.line), n.start_line
+       LIMIT ?`, id, edgeKind, edgeKind, limit).map(row => ({
+        node: toNode(row),
+        edge: toEdge(row),
+        siteCount: Number(row['site_count']),
+    }));
+    return { relations, total };
+}
+/**
+ * Resolve one symbol and read its immediate neighbourhood.
+ * @param db - the open graph connection.
+ * @param request - the node query with its resolved bounds.
+ * @returns the resolved declaration with its one-hop relations, or a null subject when the name
+ * matches nothing.
+ */
+export function node(db, request) {
+    // One extra candidate beyond the reported alternatives distinguishes "exactly this many" from
+    // "at least this many" without a second count query.
+    const candidates = resolveSymbol(db, request.symbol, request.limit + 1);
+    const best = candidates[0];
+    if (best === undefined) {
+        return { kind: 'node', node: null, incoming: [], outgoing: [], alternatives: [] };
+    }
+    return {
+        kind: 'node',
+        node: best,
+        incoming: relationsOf(db, best.id, 'incoming', null, request.limit).relations,
+        outgoing: relationsOf(db, best.id, 'outgoing', null, request.limit).relations,
+        alternatives: candidates.slice(1),
+    };
+}
+/**
+ * Find the declarations that call, or are called by, one symbol.
+ * @param db - the open graph connection.
+ * @param request - the callers or callees query; its operation picks the direction walked.
+ * @returns the distinct related declarations with their earliest call sites and repeat counts.
+ */
+export function relations(db, request) {
+    const kind = request.operation === 'callers' ? 'callers' : 'callees';
+    const subject = resolveSymbol(db, request.symbol, 1)[0];
+    if (subject === undefined) {
+        return { kind, subject: null, relations: [], total: 0, truncated: false };
+    }
+    const direction = request.operation === 'callers' ? 'incoming' : 'outgoing';
+    const found = relationsOf(db, subject.id, direction, 'calls', request.limit);
+    return {
+        kind,
+        subject,
+        relations: found.relations,
+        total: found.total,
+        truncated: found.total > found.relations.length,
+    };
+}
+/** Read many nodes by id, preserving the caller's order. */
+function nodesByIds(db, ids) {
+    if (ids.length === 0)
+        return new Map();
+    const found = rows(db, `SELECT ${NODE_COLUMNS} FROM nodes n WHERE n.id IN (${new Array(ids.length).fill('?').join(', ')})`, ...ids).map(toNode);
+    return new Map(found.map(entry => [entry.id, entry]));
+}
+/**
+ * Walk dependents transitively.
+ * @param db - the open graph connection.
+ * @param request - the impact query.
+ * @param walk - the reverse-reachability walk, injected so the traversal budget stays with the
+ * plugin that configures it.
+ * @returns the affected declarations, nearest first.
+ */
+export function impact(db, request, walk) {
+    const subject = resolveSymbol(db, request.symbol, 1)[0];
+    if (subject === undefined) {
+        return { kind: 'impact', subject: null, entries: [], total: 0, truncated: false };
+    }
+    const { hits, exhausted } = walk(subject.id, request.depth);
+    const kept = hits.slice(0, request.limit);
+    const byId = nodesByIds(db, kept.map(hit => hit.node));
+    const entries = [];
+    for (const hit of kept) {
+        const affected = byId.get(hit.node);
+        // An edge whose endpoint row is gone is a dangling reference in someone else's index, not a
+        // reason to fail the whole query; the counts below still report what the walk reached.
+        if (affected === undefined)
+            continue;
+        entries.push({ node: affected, distance: hit.distance, via: hit.via });
+    }
+    return {
+        kind: 'impact',
+        subject,
+        entries,
+        total: hits.length,
+        truncated: exhausted || hits.length > entries.length,
+    };
+}
+/**
+ * Find shortest directed paths between two symbols.
+ * @param db - the open graph connection.
+ * @param request - the trace query.
+ * @param walk - the shortest-path sweep, injected so the traversal budget stays with the plugin that
+ * configures it.
+ * @returns the paths, each as ordered hops from origin to destination.
+ */
+export function trace(db, request, walk) {
+    const from = resolveSymbol(db, request.from, 1)[0];
+    const to = resolveSymbol(db, request.to, 1)[0];
+    if (from === undefined || to === undefined) {
+        return { kind: 'trace', from: from ?? null, to: to ?? null, paths: [] };
+    }
+    const walked = walk(from.id, to.id, request.maxDepth, request.maxPaths);
+    const reached = [...new Set(walked.flatMap(path => path.map(step => step.node)))];
+    const byId = nodesByIds(db, reached);
+    const paths = [];
+    for (const path of walked) {
+        const hops = [{ node: from }];
+        let complete = true;
+        for (const step of path) {
+            const reachedNode = byId.get(step.node);
+            if (reachedNode === undefined) {
+                complete = false;
+                break;
+            }
+            hops.push({ node: reachedNode, edge: { ...step.edge } });
+        }
+        // A path through a dangling endpoint cannot be rendered honestly, so it is dropped rather than
+        // reported with a hole in it; other paths in the same answer remain valid.
+        if (complete)
+            paths.push(hops);
+    }
+    return { kind: 'trace', from, to, paths };
+}
+/**
+ * List indexed files under an optional subtree and glob.
+ * @param db - the open graph connection.
+ * @param request - the files query with its resolved bounds.
+ * @returns the matching files ordered by path, with the pre-limit total.
+ */
+export function files(db, request) {
+    const prefix = request.path === undefined ? null : `${request.path.replace(/\/+$/, '')}/%`;
+    const pattern = request.pattern ?? null;
+    const where = 'WHERE (? IS NULL OR path LIKE ?) AND (? IS NULL OR path GLOB ?)';
+    const filters = [prefix, prefix, pattern, pattern];
+    const total = scalar(db, `SELECT count(*) AS total FROM files ${where}`, ...filters);
+    const found = rows(db, `SELECT path, language, size, node_count, modified_at, indexed_at FROM files ${where} ORDER BY path LIMIT ?`, ...filters, request.limit).map(toFile);
+    return { kind: 'files', files: found, total, truncated: total > found.length };
+}
+/**
+ * Whether one indexed file's on-disk state no longer matches what the index recorded for it.
+ * Missing entirely counts as stale — it is the most unambiguous case there is, and treating a
+ * deleted file as merely "unchanged" would hide the one drift a caller most needs to know about.
+ */
+function isStale(projectRoot, relativePath, indexedModifiedAt) {
+    try {
+        return statSync(join(projectRoot, relativePath)).mtimeMs > indexedModifiedAt;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Count indexed files a direct filesystem check finds stale, capped for cost.
+ * @param db - the open graph connection.
+ * @param projectRoot - the project root the indexed paths are relative to.
+ * @param maxChecks - largest number of indexed files to stat before reporting a lower bound.
+ * @returns the stale count among the checked files, and whether checking stopped short of every
+ * indexed file.
+ */
+function staleness(db, projectRoot, maxChecks) {
+    // One extra row beyond the cap distinguishes "exactly this many files" from "more than this many"
+    // without a second count query, mirroring the same trick `node`'s alternatives use.
+    const candidates = rows(db, 'SELECT path, modified_at FROM files ORDER BY path LIMIT ?', maxChecks + 1);
+    const truncated = candidates.length > maxChecks;
+    const checked = truncated ? candidates.slice(0, maxChecks) : candidates;
+    let count = 0;
+    for (const row of checked) {
+        const path = row['path'];
+        const modifiedAt = row['modified_at'];
+        if (typeof path !== 'string') {
+            throw new CodegraphError('the code graph has a malformed file path', 'CODEGRAPH_MALFORMED_INDEX');
+        }
+        if (typeof modifiedAt !== 'number') {
+            throw new CodegraphError('the code graph has a malformed file timestamp', 'CODEGRAPH_MALFORMED_INDEX');
+        }
+        if (isStale(projectRoot, path, modifiedAt))
+            count += 1;
+    }
+    return { count, truncated };
+}
+/**
+ * Report index size, language coverage, and freshness.
+ * @param db - the open graph connection.
+ * @param projectRoot - the project root the result echoes back, since the graph does not record it.
+ * @param maxStalenessChecks - largest number of indexed files to stat on the host filesystem when
+ * looking for drift, so a call against a very large index stays cheap.
+ * @returns the index summary.
+ */
+export function status(db, projectRoot, maxStalenessChecks) {
+    const languages = rows(db, 'SELECT language, count(*) AS file_count FROM files GROUP BY language ORDER BY file_count DESC, language').map((row) => {
+        // Only `language` is durable data worth checking; the count beside it is computed by SQLite
+        // in this very statement, so it is numeric by construction.
+        const language = row['language'];
+        if (typeof language !== 'string') {
+            throw new CodegraphError('the code graph has a malformed language summary', 'CODEGRAPH_MALFORMED_INDEX');
+        }
+        return { language, fileCount: Number(row['file_count']) };
+    });
+    const indexedAt = scalar(db, 'SELECT MAX(indexed_at) AS indexed_at FROM files');
+    const { count: staleFileCount, truncated: staleFileCountTruncated } = staleness(db, projectRoot, maxStalenessChecks);
+    return {
+        kind: 'status',
+        projectRoot,
+        fileCount: scalar(db, 'SELECT count(*) AS c FROM files'),
+        nodeCount: scalar(db, 'SELECT count(*) AS c FROM nodes'),
+        edgeCount: scalar(db, 'SELECT count(*) AS c FROM edges'),
+        languages,
+        // The version actually recorded on disk, not the store's support ceiling: two writers stamp
+        // different supported versions (tree-sitter writes v4, the CLI writes v8), so echoing the
+        // database's own row is the honest answer.
+        formatVersion: scalar(db, 'SELECT MAX(version) AS version FROM schema_versions'),
+        indexedAt: indexedAt === 0 ? null : indexedAt,
+        staleFileCount,
+        staleFileCountTruncated,
+    };
+}
+//# sourceMappingURL=queries.js.map

package/lib/rows.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Durable-boundary mapping from SQLite rows to seam records. Every value crossing this module comes
+ * from a file an independently versioned indexer wrote, so each field is checked before it becomes a
+ * typed record; a row that violates the format fails loud as `CODEGRAPH_MALFORMED_INDEX` rather than
+ * reaching a consumer as a plausible-looking wrong value.
+ * @module @huanlin/dsh-plugin-codegraph-sqlite/rows
+ */
+import type { CodegraphEdge, CodegraphFile, CodegraphNode } from '@huanlin/dsh-plugin-codegraph-service';
+/** One `nodes` row as `node:sqlite` returns it, before validation. */
+export type NodeRow = Record<string, unknown>;
+/**
+ * Build a {@link CodegraphNode} from a `nodes` row.
+ * @param row - the raw row, selected with every `nodes` column present.
+ * @returns the validated node record.
+ */
+export declare function toNode(row: NodeRow): CodegraphNode;
+/**
+ * Build a {@link CodegraphEdge} from an `edges` row selected with the `edge_` column prefix that
+ * {@link toNode} joins avoid colliding with.
+ * @param row - the raw row carrying `edge_source`, `edge_target`, `edge_kind`, `edge_line`,
+ * `edge_col`, and `edge_provenance`.
+ * @returns the validated edge record.
+ */
+export declare function toEdge(row: NodeRow): CodegraphEdge;
+/**
+ * Build a {@link CodegraphFile} from a `files` row.
+ * @param row - the raw row, selected with every `files` column present.
+ * @returns the validated file record.
+ */
+export declare function toFile(row: NodeRow): CodegraphFile;
+//# sourceMappingURL=rows.d.ts.map

package/lib/rows.js

@@ -0,0 +1,174 @@
+/**
+ * Durable-boundary mapping from SQLite rows to seam records. Every value crossing this module comes
+ * from a file an independently versioned indexer wrote, so each field is checked before it becomes a
+ * typed record; a row that violates the format fails loud as `CODEGRAPH_MALFORMED_INDEX` rather than
+ * reaching a consumer as a plausible-looking wrong value.
+ * @module @huanlin/dsh-plugin-codegraph-sqlite/rows
+ */
+import { CodegraphError, CodegraphNodeId } from '@huanlin/dsh-plugin-codegraph-service';
+/**
+ * Read a required text column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's string value.
+ */
+function text(row, column, what) {
+    const value = row[column];
+    if (typeof value !== 'string') {
+        throw new CodegraphError(`${what} has a non-text "${column}"`, 'CODEGRAPH_MALFORMED_INDEX');
+    }
+    return value;
+}
+/**
+ * Read a required integer column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's numeric value.
+ */
+function integer(row, column, what) {
+    const value = row[column];
+    if (typeof value === 'number')
+        return value;
+    // A stored INTEGER outside the safe range never reaches here: `node:sqlite` raises a RangeError
+    // while reading the row, because this store opens connections without bigint reads.
+    throw new CodegraphError(`${what} has a non-integer "${column}"`, 'CODEGRAPH_MALFORMED_INDEX');
+}
+/**
+ * Read an optional text column, treating SQL NULL and the empty string alike as absent.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's string value, or undefined when absent.
+ */
+function optionalText(row, column, what) {
+    const value = row[column];
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new CodegraphError(`${what} has a non-text "${column}"`, 'CODEGRAPH_MALFORMED_INDEX');
+    }
+    return value;
+}
+/**
+ * Read an optional integer column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the column's numeric value, or undefined when NULL.
+ */
+function optionalInteger(row, column, what) {
+    const value = row[column];
+    if (value === null || value === undefined)
+        return undefined;
+    return integer(row, column, what);
+}
+/**
+ * Read a boolean stored as INTEGER 0/1, treating NULL as false.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @returns whether the flag is set.
+ */
+function flag(row, column) {
+    return row[column] === 1;
+}
+/**
+ * Read a JSON-array text column.
+ * @param row - the raw row.
+ * @param column - the column name.
+ * @param what - the record being built, for the failure message.
+ * @returns the parsed strings, or an empty array when the column is NULL or empty.
+ */
+function stringArray(row, column, what) {
+    const raw = optionalText(row, column, what);
+    if (raw === undefined)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Only JSON.parse runs in the try; any throw here is a syntax error in the stored text, which
+        // is exactly the malformed-index case reported below.
+        throw new CodegraphError(`${what} has an unparseable "${column}"`, 'CODEGRAPH_MALFORMED_INDEX');
+    }
+    if (!Array.isArray(parsed) || parsed.some(entry => typeof entry !== 'string')) {
+        throw new CodegraphError(`${what} has a non-string-array "${column}"`, 'CODEGRAPH_MALFORMED_INDEX');
+    }
+    return parsed;
+}
+/**
+ * Build a {@link CodegraphNode} from a `nodes` row.
+ * @param row - the raw row, selected with every `nodes` column present.
+ * @returns the validated node record.
+ */
+export function toNode(row) {
+    const what = 'a graph node';
+    const id = text(row, 'id', what);
+    const named = `graph node "${id}"`;
+    const docstring = optionalText(row, 'docstring', named);
+    const signature = optionalText(row, 'signature', named);
+    const visibility = optionalText(row, 'visibility', named);
+    return {
+        id: CodegraphNodeId(id),
+        kind: text(row, 'kind', named),
+        name: text(row, 'name', named),
+        qualifiedName: text(row, 'qualified_name', named),
+        filePath: text(row, 'file_path', named),
+        language: text(row, 'language', named),
+        startLine: integer(row, 'start_line', named),
+        endLine: integer(row, 'end_line', named),
+        startColumn: integer(row, 'start_column', named),
+        endColumn: integer(row, 'end_column', named),
+        ...docstring === undefined ? {} : { docstring },
+        ...signature === undefined ? {} : { signature },
+        ...visibility === undefined ? {} : { visibility },
+        isExported: flag(row, 'is_exported'),
+        isAsync: flag(row, 'is_async'),
+        isStatic: flag(row, 'is_static'),
+        isAbstract: flag(row, 'is_abstract'),
+        decorators: stringArray(row, 'decorators', named),
+        typeParameters: stringArray(row, 'type_parameters', named),
+        updatedAt: integer(row, 'updated_at', named),
+    };
+}
+/**
+ * Build a {@link CodegraphEdge} from an `edges` row selected with the `edge_` column prefix that
+ * {@link toNode} joins avoid colliding with.
+ * @param row - the raw row carrying `edge_source`, `edge_target`, `edge_kind`, `edge_line`,
+ * `edge_col`, and `edge_provenance`.
+ * @returns the validated edge record.
+ */
+export function toEdge(row) {
+    const what = 'a graph edge';
+    const line = optionalInteger(row, 'edge_line', what);
+    const column = optionalInteger(row, 'edge_col', what);
+    const provenance = optionalText(row, 'edge_provenance', what);
+    return {
+        source: CodegraphNodeId(text(row, 'edge_source', what)),
+        target: CodegraphNodeId(text(row, 'edge_target', what)),
+        kind: text(row, 'edge_kind', what),
+        ...line === undefined ? {} : { line },
+        ...column === undefined ? {} : { column },
+        ...provenance === undefined ? {} : { provenance },
+    };
+}
+/**
+ * Build a {@link CodegraphFile} from a `files` row.
+ * @param row - the raw row, selected with every `files` column present.
+ * @returns the validated file record.
+ */
+export function toFile(row) {
+    const path = text(row, 'path', 'an indexed file');
+    const named = `indexed file "${path}"`;
+    return {
+        path,
+        language: text(row, 'language', named),
+        size: integer(row, 'size', named),
+        nodeCount: integer(row, 'node_count', named),
+        modifiedAt: integer(row, 'modified_at', named),
+        indexedAt: integer(row, 'indexed_at', named),
+    };
+}
+//# sourceMappingURL=rows.js.map

package/lib/sql.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SQL fragments shared by the store's queries: the column projections the row mappers expect, the
+ * ranking expressions that decide which declaration a bare symbol name means, and the escaping that
+ * makes an arbitrary model-supplied string a safe FTS5 query.
+ *
+ * Ranking is expressed in SQL rather than in TypeScript so ordering and truncation happen in the
+ * same statement: a `LIMIT` must keep the most relevant matches, which it can only do if the
+ * database already knows the order.
+ * @module @huanlin/dsh-plugin-codegraph-sqlite/sql
+ */
+/** Every `nodes` column {@link toNode} reads, aliased `n`. */
+export declare const NODE_COLUMNS: string;
+/**
+ * Order candidates for a symbol lookup: match exactness first, then declaration relevance, then
+ * exported over internal, then file and line so equally ranked results never reorder between runs.
+ * Binds the symbol three times, ahead of any other parameter in the statement.
+ */
+export declare const SYMBOL_ORDER = "CASE\n  WHEN n.qualified_name = ? THEN 0\n  WHEN n.name = ? THEN 1\n  WHEN lower(n.name) = lower(?) THEN 2\n  ELSE 3\nEND, CASE n.kind\n  WHEN 'function' THEN 0\n  WHEN 'method' THEN 0\n  WHEN 'class' THEN 1\n  WHEN 'component' THEN 1\n  WHEN 'struct' THEN 1\n  WHEN 'interface' THEN 2\n  WHEN 'trait' THEN 2\n  WHEN 'protocol' THEN 2\n  WHEN 'type_alias' THEN 3\n  WHEN 'enum' THEN 3\n  WHEN 'route' THEN 3\n  WHEN 'constant' THEN 4\n  WHEN 'variable' THEN 4\n  WHEN 'property' THEN 5\n  WHEN 'field' THEN 5\n  WHEN 'enum_member' THEN 5\n  WHEN 'parameter' THEN 6\n  WHEN 'namespace' THEN 6\n  WHEN 'module' THEN 6\n  WHEN 'import' THEN 7\n  WHEN 'export' THEN 7\n  WHEN 'file' THEN 8\n  ELSE 6\nEND, n.is_exported DESC, n.file_path, n.start_line";
+/** Order candidates for a free-text search. Binds the query four times. */
+export declare const SEARCH_ORDER = "CASE\n  WHEN n.name = ? THEN 0\n  WHEN lower(n.name) = lower(?) THEN 1\n  WHEN lower(n.name) LIKE lower(?) || '%' THEN 2\n  WHEN lower(n.qualified_name) LIKE '%' || lower(?) || '%' THEN 3\n  ELSE 4\nEND, CASE n.kind\n  WHEN 'function' THEN 0\n  WHEN 'method' THEN 0\n  WHEN 'class' THEN 1\n  WHEN 'component' THEN 1\n  WHEN 'struct' THEN 1\n  WHEN 'interface' THEN 2\n  WHEN 'trait' THEN 2\n  WHEN 'protocol' THEN 2\n  WHEN 'type_alias' THEN 3\n  WHEN 'enum' THEN 3\n  WHEN 'route' THEN 3\n  WHEN 'constant' THEN 4\n  WHEN 'variable' THEN 4\n  WHEN 'property' THEN 5\n  WHEN 'field' THEN 5\n  WHEN 'enum_member' THEN 5\n  WHEN 'parameter' THEN 6\n  WHEN 'namespace' THEN 6\n  WHEN 'module' THEN 6\n  WHEN 'import' THEN 7\n  WHEN 'export' THEN 7\n  WHEN 'file' THEN 8\n  ELSE 6\nEND, n.is_exported DESC, n.file_path, n.start_line";
+/**
+ * Turn a model-supplied string into an FTS5 prefix query that cannot be misread as FTS syntax.
+ * Doubling the quote characters and wrapping the whole value in quotes makes it one literal phrase,
+ * so `AND`, `*`, `:` and parentheses in a symbol name search for themselves instead of changing the
+ * query's meaning.
+ * @param query - the raw search text.
+ * @returns an FTS5 MATCH expression matching the text as a prefix phrase.
+ */
+export declare function ftsPhrase(query: string): string;
+/**
+ * Wrap a raw string as a SQL `LIKE` pattern matching it anywhere, escaping the wildcard characters
+ * so a symbol containing `%` or `_` matches literally.
+ * @param query - the raw search text.
+ * @returns the escaped pattern, for use with `LIKE ? ESCAPE '\\'`.
+ */
+export declare function likeAnywhere(query: string): string;
+//# sourceMappingURL=sql.d.ts.map

package/lib/sql.js

@@ -0,0 +1,116 @@
+/**
+ * SQL fragments shared by the store's queries: the column projections the row mappers expect, the
+ * ranking expressions that decide which declaration a bare symbol name means, and the escaping that
+ * makes an arbitrary model-supplied string a safe FTS5 query.
+ *
+ * Ranking is expressed in SQL rather than in TypeScript so ordering and truncation happen in the
+ * same statement: a `LIMIT` must keep the most relevant matches, which it can only do if the
+ * database already knows the order.
+ * @module @huanlin/dsh-plugin-codegraph-sqlite/sql
+ */
+/** Every `nodes` column {@link toNode} reads, aliased `n`. */
+export const NODE_COLUMNS = [
+    'n.id',
+    'n.kind',
+    'n.name',
+    'n.qualified_name',
+    'n.file_path',
+    'n.language',
+    'n.start_line',
+    'n.end_line',
+    'n.start_column',
+    'n.end_column',
+    'n.docstring',
+    'n.signature',
+    'n.visibility',
+    'n.is_exported',
+    'n.is_async',
+    'n.is_static',
+    'n.is_abstract',
+    'n.decorators',
+    'n.type_parameters',
+    'n.updated_at',
+].join(', ');
+/**
+ * Relevance among declarations that share a name. A bare name in a query means the thing that
+ * declares behaviour, so callable and type declarations outrank the values and re-exports that
+ * merely mention the same identifier: an `import { parse }` node must never win over the `parse`
+ * function it imports, and a `file` node never wins at all.
+ */
+const KIND_RANK_CASE = `CASE n.kind
+  WHEN 'function' THEN 0
+  WHEN 'method' THEN 0
+  WHEN 'class' THEN 1
+  WHEN 'component' THEN 1
+  WHEN 'struct' THEN 1
+  WHEN 'interface' THEN 2
+  WHEN 'trait' THEN 2
+  WHEN 'protocol' THEN 2
+  WHEN 'type_alias' THEN 3
+  WHEN 'enum' THEN 3
+  WHEN 'route' THEN 3
+  WHEN 'constant' THEN 4
+  WHEN 'variable' THEN 4
+  WHEN 'property' THEN 5
+  WHEN 'field' THEN 5
+  WHEN 'enum_member' THEN 5
+  WHEN 'parameter' THEN 6
+  WHEN 'namespace' THEN 6
+  WHEN 'module' THEN 6
+  WHEN 'import' THEN 7
+  WHEN 'export' THEN 7
+  WHEN 'file' THEN 8
+  ELSE 6
+END`;
+/**
+ * How exactly a candidate matched the requested symbol: a fully qualified name beats a
+ * case-sensitive simple name, which beats a case-insensitive one. Binds the symbol three times.
+ */
+const SYMBOL_TIER_CASE = `CASE
+  WHEN n.qualified_name = ? THEN 0
+  WHEN n.name = ? THEN 1
+  WHEN lower(n.name) = lower(?) THEN 2
+  ELSE 3
+END`;
+/**
+ * How a candidate matched a free-text search: an exact name beats a case-insensitive one, which
+ * beats a prefix, which beats any other match (a substring, or a documentation or signature hit).
+ * Binds the query four times.
+ */
+const SEARCH_TIER_CASE = `CASE
+  WHEN n.name = ? THEN 0
+  WHEN lower(n.name) = lower(?) THEN 1
+  WHEN lower(n.name) LIKE lower(?) || '%' THEN 2
+  WHEN lower(n.qualified_name) LIKE '%' || lower(?) || '%' THEN 3
+  ELSE 4
+END`;
+/**
+ * Order candidates for a symbol lookup: match exactness first, then declaration relevance, then
+ * exported over internal, then file and line so equally ranked results never reorder between runs.
+ * Binds the symbol three times, ahead of any other parameter in the statement.
+ */
+export const SYMBOL_ORDER = `${SYMBOL_TIER_CASE}, ${KIND_RANK_CASE}, n.is_exported DESC, n.file_path, n.start_line`;
+/** Order candidates for a free-text search. Binds the query four times. */
+export const SEARCH_ORDER = `${SEARCH_TIER_CASE}, ${KIND_RANK_CASE}, n.is_exported DESC, n.file_path, n.start_line`;
+/**
+ * Turn a model-supplied string into an FTS5 prefix query that cannot be misread as FTS syntax.
+ * Doubling the quote characters and wrapping the whole value in quotes makes it one literal phrase,
+ * so `AND`, `*`, `:` and parentheses in a symbol name search for themselves instead of changing the
+ * query's meaning.
+ * @param query - the raw search text.
+ * @returns an FTS5 MATCH expression matching the text as a prefix phrase.
+ */
+export function ftsPhrase(query) {
+    return `"${query.replaceAll('"', '""')}"*`;
+}
+/**
+ * Wrap a raw string as a SQL `LIKE` pattern matching it anywhere, escaping the wildcard characters
+ * so a symbol containing `%` or `_` matches literally.
+ * @param query - the raw search text.
+ * @returns the escaped pattern, for use with `LIKE ? ESCAPE '\\'`.
+ */
+export function likeAnywhere(query) {
+    const escaped = query.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_');
+    return `%${escaped.toLowerCase()}%`;
+}
+//# sourceMappingURL=sql.js.map