@wrongstack/tools 1.0.1 → 1.0.3

package/dist/codebase-index/project-server.js

@@ -10,8 +10,9 @@ import {
   projectIndexServerBuildId,
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath
-} from "../chunk-GDDXX27P.js";
+} from "../chunk-6ZLRRC74.js";
 import {
+  contextService,
   fileGraphService,
   incomingCallsService,
   indexService,
@@ -21,17 +22,20 @@ import {
   resolveIndexDir,
   searchService,
   statsService,
-  symbolGraphService
-} from "../chunk-N3K2SFEI.js";
-import "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+  symbolGraphService,
+  vectorSearchService
+} from "../chunk-3JVSOBHU.js";
+import "../chunk-6LCKF5KH.js";
+import "../chunk-REWOZIA4.js";
 import "../chunk-6IEBD27U.js";
-import "../chunk-UCYQTZ7F.js";
+import {
+  recordWriteQueueWait
+} from "../chunk-ZKC5UNGD.js";
 import {
   isIndexablePath
 } from "../chunk-YOHO4DVT.js";
 import "../chunk-2CTZW6JQ.js";
-import "../chunk-KE7A76VC.js";
+import "../chunk-5U5ULQX2.js";
 
 // src/codebase-index/project-server.ts
 import { randomBytes } from "node:crypto";
@@ -252,6 +256,9 @@ var ServerQueryCaches = class {
    */
   searchCache = new GenerationLruCache(128);
   statsCache = new GenerationLruCache(1);
+  // Retrieval answers are query-shaped like search, so they cache the same way.
+  contextCache = new GenerationLruCache(64);
+  vectorSearchCache = new GenerationLruCache(64);
   packageGraphCache = new GenerationLruCache(1);
   fileGraphCache = new GenerationLruCache(32);
   symbolGraphCache = new GenerationLruCache(64);
@@ -260,6 +267,8 @@ var ServerQueryCaches = class {
   clear() {
     this.searchCache.clear();
     this.statsCache.clear();
+    this.contextCache.clear();
+    this.vectorSearchCache.clear();
     this.packageGraphCache.clear();
     this.fileGraphCache.clear();
     this.symbolGraphCache.clear();
@@ -271,6 +280,8 @@ var ServerQueryCaches = class {
     return {
       searchCache: this.searchCache.size,
       statsCache: this.statsCache.size,
+      contextCache: this.contextCache.size,
+      vectorSearchCache: this.vectorSearchCache.size,
       packageGraphCache: this.packageGraphCache.size,
       fileGraphCache: this.fileGraphCache.size,
       symbolGraphCache: this.symbolGraphCache.size,
@@ -368,6 +379,24 @@ async function dispatchOperation(ctx, state, message) {
       );
       return stale ? { ...value, stale: true } : value;
     }
+    case "context": {
+      const { value, stale } = staleAwareRead(
+        ctx.queryCaches.contextCache,
+        JSON.stringify(message.args),
+        indexActivity2,
+        () => contextService(fixedArgs(ctx, message.args))
+      );
+      return stale ? { ...value, stale: true } : value;
+    }
+    case "vectorSearch": {
+      const { value, stale } = staleAwareRead(
+        ctx.queryCaches.vectorSearchCache,
+        JSON.stringify(message.args),
+        indexActivity2,
+        () => vectorSearchService(fixedArgs(ctx, message.args))
+      );
+      return stale ? { ...value, stale: true } : value;
+    }
     case "stats":
       if (indexActivity2.indexing) {
         throw indexRefreshInProgressError(indexActivity2.currentFile, indexActivity2.totalFiles);
@@ -660,6 +689,8 @@ var writeChain = Promise.resolve();
 var activeRequests = 0;
 var activeWrites = 0;
 var queuedWrites = 0;
+var maxQueuedWrites = 0;
+var writeQueueWaitMs = 0;
 var activeFullIndex = null;
 var queryCaches = new ServerQueryCaches();
 var indexActivity = {
@@ -708,16 +739,30 @@ function send(state, message) {
 }
 function withWriteMutex(job) {
   queuedWrites++;
+  maxQueuedWrites = Math.max(maxQueuedWrites, queuedWrites);
   const guarded = async () => {
     queuedWrites--;
     activeWrites++;
     try {
+      const holdMs = Number(process.env["WRONGSTACK_INDEX_BENCH_WRITE_HOLD_MS"] ?? 0);
+      if (Number.isFinite(holdMs) && holdMs > 0) {
+        await new Promise((resolve3) => setTimeout(resolve3, Math.min(holdMs, 5e3)));
+      }
       return await job();
     } finally {
       activeWrites--;
     }
   };
-  const run = writeChain.then(guarded, guarded);
+  const queuedAt = performance.now();
+  const wrapped = async () => {
+    const elapsedWaitMs = performance.now() - queuedAt;
+    const holdMs = Number(process.env["WRONGSTACK_INDEX_BENCH_WRITE_HOLD_MS"] ?? 0);
+    const waitMs = Number.isFinite(holdMs) && holdMs > 0 ? Math.max(elapsedWaitMs, holdMs) : elapsedWaitMs;
+    writeQueueWaitMs += waitMs;
+    recordWriteQueueWait(waitMs);
+    return guarded();
+  };
+  const run = writeChain.then(wrapped, wrapped);
   writeChain = run.then(
     () => void 0,
     () => void 0
@@ -766,6 +811,8 @@ function serverHealth() {
     activeRequests,
     activeWrites,
     queuedWrites,
+    maxQueuedWrites,
+    writeQueueWaitMs,
     pendingExternalFiles: watcherManager.pendingFileCount,
     watchingExternal: watcherManager.isWatching,
     watchingClients,

package/dist/codebase-index/repo-map-fallback.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Filesystem repo map — the path taken when the index has no ranks yet.
+ *
+ * This is the original heuristic map: walk the tree, score each file by
+ * entry-point name and depth, and pack skeletons until the budget runs out.
+ * It knows nothing about who references whom, so it is strictly a stand-in
+ * for {@link generateRepoMap}'s graph-ranked output on a fresh clone, during
+ * the first index run, or in a directory that was never indexed at all.
+ *
+ * Two defects of the original are fixed here, because a stand-in that lies is
+ * worse than no stand-in: it no longer stops after ~500 files (this repo has
+ * 8,412, so the old cap meant the "map" described whichever directories the
+ * walk happened to reach first), and it honours `.gitignore` instead of a
+ * hardcoded list of four directory names.
+ */
+import type { RepoMapOptions, RepoMapResult } from './repo-map-types.js';
+export declare function generateFallbackRepoMap(opts: RepoMapOptions): Promise<RepoMapResult>;
+//# sourceMappingURL=repo-map-fallback.d.ts.map

package/dist/codebase-index/repo-map-render.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Rendering half of the repo map: turning a ranked candidate list into
+ * budgeted skeleton sections. Shared by the graph-ranked generator and the
+ * filesystem fallback so the two produce the same section format.
+ */
+import { type SkeletonOptions } from './skeleton-extractor.js';
+export interface RepoMapCandidate {
+    /** Absolute path, for reading. */
+    absolute: string;
+    /** Project-relative POSIX path, for display. */
+    relative: string;
+}
+export interface RenderSectionsOptions {
+    skeleton?: SkeletonOptions | undefined;
+    /**
+     * Largest a single file's section may be. Without it one 9k-token type
+     * module consumes the entire budget and the "map" describes one file. The
+     * point of a map is breadth, so each file gets a slice and the rest of the
+     * budget goes to the next-most-central file.
+     */
+    maxSectionChars?: number | undefined;
+    /**
+     * Drop comment-only lines so the budget buys declarations, not prose.
+     * On for the map body; off for callers that want the skeleton verbatim.
+     */
+    signaturesOnly?: boolean | undefined;
+}
+export interface RenderedSections {
+    sections: string[];
+    /** Relative paths actually included, in order. */
+    files: string[];
+    /** Characters consumed by `sections`, including the blank-line separators. */
+    chars: number;
+}
+/**
+ * Extract skeletons for `candidates` in order until `charBudget` is exhausted.
+ *
+ * Unreadable and empty files are skipped rather than ending the walk, so one
+ * deleted-since-index path cannot truncate the whole map.
+ */
+export declare function renderSkeletonSections(candidates: readonly RepoMapCandidate[], charBudget: number, options?: RenderSectionsOptions): Promise<RenderedSections>;
+//# sourceMappingURL=repo-map-render.d.ts.map

package/dist/codebase-index/repo-map-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared shapes for the repo map. Split out so the graph-ranked generator and
+ * the filesystem fallback can import them without importing each other.
+ */
+import type { SkeletonOptions } from './skeleton-extractor.js';
+export interface RepoMapOptions {
+    projectRoot: string;
+    maxTokens?: number | undefined;
+    focusFiles?: string[] | undefined;
+    options?: SkeletonOptions | undefined;
+    /** Index directory override, for callers that do not use the default path. */
+    indexDir?: string | undefined;
+}
+export interface RepoMapResult {
+    map: string;
+    filesCount: number;
+    totalFilesScanned: number;
+    estimatedTokens: number;
+    rankedFiles: string[];
+}
+//# sourceMappingURL=repo-map-types.d.ts.map

package/dist/codebase-index/repo-map.d.ts

@@ -1,20 +1,32 @@
-import { type SkeletonOptions } from './skeleton-extractor.js';
-export interface RepoMapOptions {
-    projectRoot: string;
-    maxTokens?: number | undefined;
-    focusFiles?: string[] | undefined;
-    options?: SkeletonOptions | undefined;
-}
-export interface RepoMapResult {
-    map: string;
-    filesCount: number;
-    totalFilesScanned: number;
-    estimatedTokens: number;
-    rankedFiles: string[];
-}
 /**
- * Generate a reference-weighted, token-budgeted Repository Map.
- * Packs the most architecturally central symbols across the codebase into ~800-1500 tokens.
+ * Repository map — a token-budgeted orientation view of the codebase.
+ *
+ * The map is built from the index's graph centrality (`file_rank`), not from a
+ * filesystem walk. Two things follow from that:
+ *
+ *  - **It ranks by evidence.** The previous implementation never opened the
+ *    index at all: it walked the tree and scored files by whether their name
+ *    matched `index|main|app|server|…` plus a directory-depth bonus, stopping
+ *    after ~500 files. On a repo of 8,412 that produced a map of whichever
+ *    directories the walk reached first, ranked by filename. Centrality
+ *    instead answers the question the map is actually asked — what does the
+ *    rest of this codebase depend on?
+ *  - **It can group.** `files.package` gives every file an ecosystem-derived
+ *    cluster label, so the map opens with the shape of the repo (clusters and
+ *    their hubs, then global hotspots) before descending into signatures.
+ *
+ * When the index has no ranks — a fresh clone, the first index run, a
+ * directory that was never indexed — {@link generateFallbackRepoMap} takes
+ * over and the output degrades to the old heuristic rather than to nothing.
+ */
+import type { RepoMapOptions, RepoMapResult } from './repo-map-types.js';
+export { generateFallbackRepoMap } from './repo-map-fallback.js';
+export type { RepoMapOptions, RepoMapResult } from './repo-map-types.js';
+/**
+ * Generate a graph-ranked, token-budgeted repository map.
+ *
+ * Falls back to the filesystem heuristic whenever the index cannot answer —
+ * no ranks yet, or the store could not be opened at all.
  */
 export declare function generateRepoMap(opts: RepoMapOptions): Promise<RepoMapResult>;
 //# sourceMappingURL=repo-map.d.ts.map

package/dist/codebase-index/schema.d.ts

@@ -194,6 +194,26 @@ export interface GraphNode {
     scope?: string | undefined;
     /** True when this is a direct relation outside the current drill-down scope. */
     external?: boolean | undefined;
+    /**
+     * Global PageRank centrality, max-normalised to 1.0 across the whole index —
+     * so it is comparable between nodes of the same kind, not across kinds.
+     * Package nodes carry the sum of their files' ranks.
+     */
+    rank?: number | undefined;
+    /** Plain-language description of the node, from the concept layer. */
+    concept?: string | undefined;
+    /**
+     * The load-bearing source span the summary was drawn from, 1-based and
+     * inclusive. A summary can drift from the code; this cannot.
+     */
+    crux?: {
+        start: number;
+        end: number;
+    } | undefined;
+    /** Name of the subsystem this node's file belongs to, when one was derived. */
+    subsystem?: string | undefined;
+    /** `files.mtime_ms` — last modification, for recency shading. */
+    lastModifiedMs?: number | undefined;
 }
 /** A directed edge: source references / depends-on target. */
 export interface GraphEdge {

package/dist/codebase-index/worker-protocol.d.ts

@@ -4,8 +4,10 @@
  * Plain structured-cloneable shapes only — no class instances, no functions.
  * Errors cross the boundary as strings and are re-wrapped by the host.
  */
-import type { IncomingCallsResult, OutgoingCallsResult } from './worker-protocol/contracts.js';
+import type { ContextResult } from './context-retrieval.js';
 import type { CodeMapGraph, IndexResult, IndexStats, SearchResult } from './schema.js';
+import type { IncomingCallsResult, OutgoingCallsResult } from './worker-protocol/contracts.js';
+import type { VectorHit } from './writer-vectors.js';
 export interface IndexOpArgs {
     projectRoot: string;
     indexDir?: string | undefined;
@@ -61,6 +63,42 @@ export interface SearchOpResult {
      */
     stale?: boolean | undefined;
 }
+/**
+ * Personalised retrieval arguments.
+ *
+ * `vectorFiles` arrives already scored because the embedding model lives on
+ * the host: a function cannot cross this boundary, so the host embeds the
+ * query and only the resulting file scores travel as numbers.
+ */
+export interface ContextOpArgs extends StatsOpArgs {
+    query: string;
+    vectorFiles?: ReadonlyArray<{
+        file: string;
+        score: number;
+    }> | undefined;
+    limit?: number | undefined;
+    symbolsPerFile?: number | undefined;
+    pathPrefix?: string | undefined;
+}
+/**
+ * Nearest-vector search arguments.
+ *
+ * The vector is a plain number array rather than a `Float32Array` because
+ * only structured-cloneable plain shapes cross this protocol; the service
+ * re-wraps it before comparing.
+ */
+export interface VectorSearchOpArgs extends StatsOpArgs {
+    vector: number[];
+    limit: number;
+    minScore?: number | undefined;
+}
+export interface VectorSearchOpResult {
+    hits: VectorHit[];
+    /** Vectors currently stored — zero means the embedding pass has not run. */
+    total: number;
+    /** Set when the project server served a previous generation's cached answer. */
+    stale?: boolean | undefined;
+}
 /** Map of op name → { args, result } so host and worker stay in lockstep. */
 export interface OpShapes {
     index: {
@@ -95,6 +133,14 @@ export interface OpShapes {
         args: CallRefsOpArgs;
         result: OutgoingCallsResult;
     };
+    context: {
+        args: ContextOpArgs;
+        result: ContextResult;
+    };
+    vectorSearch: {
+        args: VectorSearchOpArgs;
+        result: VectorSearchOpResult;
+    };
 }
 export type OpName = keyof OpShapes;
 export type HostToWorker = {

package/dist/codebase-index/worker.js

@@ -1,4 +1,5 @@
 import {
+  contextService,
   fileGraphService,
   incomingCallsService,
   indexService,
@@ -6,15 +7,16 @@ import {
   packageGraphService,
   searchService,
   statsService,
-  symbolGraphService
-} from "../chunk-N3K2SFEI.js";
-import "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+  symbolGraphService,
+  vectorSearchService
+} from "../chunk-3JVSOBHU.js";
+import "../chunk-6LCKF5KH.js";
+import "../chunk-REWOZIA4.js";
 import "../chunk-6IEBD27U.js";
-import "../chunk-UCYQTZ7F.js";
+import "../chunk-ZKC5UNGD.js";
 import "../chunk-YOHO4DVT.js";
 import "../chunk-2CTZW6JQ.js";
-import "../chunk-KE7A76VC.js";
+import "../chunk-5U5ULQX2.js";
 
 // src/codebase-index/worker.ts
 import { parentPort } from "node:worker_threads";
@@ -50,6 +52,10 @@ async function dispatch(msg) {
     }
     case "search":
       return searchService(msg.args);
+    case "context":
+      return contextService(msg.args);
+    case "vectorSearch":
+      return vectorSearchService(msg.args);
     case "stats":
       return statsService(msg.args);
     case "packageGraph":

package/dist/codebase-index/writer-concepts.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Persistence for the concept layer (`file_concepts`, `subsystems`,
+ * `concept_edges`).
+ *
+ * Unlike the rank tables, these are written incrementally: a summary costs a
+ * model call, so the runner checkpoints as it goes and a cancelled or crashed
+ * pass must not throw away what it already paid for.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+type Statement = ReturnType<DatabaseSync['prepare']>;
+type PrepareStatement = (sql: string) => Statement;
+/**
+ * Whether a stored summary describes the file's current bytes.
+ *
+ * `stale` is kept rather than deleted: an outdated description of a file is
+ * still a better starting point than nothing, both for a reader and as a hint
+ * to the model on the next pass.
+ */
+export type ConceptState = 'ready' | 'stale' | 'pending';
+export interface FileConcept {
+    file: string;
+    contentHash: string;
+    summary: string;
+    /** 1-based inclusive line span of the file's load-bearing lines. */
+    cruxStart: number | null;
+    cruxEnd: number | null;
+    state: ConceptState;
+    model: string;
+    updatedAt: number;
+}
+export interface Subsystem {
+    id: string;
+    name: string;
+    summary: string;
+    memberFiles: string[];
+    model: string;
+    updatedAt: number;
+}
+/**
+ * Closed vocabulary for concept-to-concept relations.
+ *
+ * Closed on purpose. An open-ended verb list produces a graph where
+ * `configures`, `sets up` and `initialises` are three different edges between
+ * the same pair, which nothing downstream can group or filter on.
+ */
+export declare const CONCEPT_RELATIONS: readonly ['uses', 'configures', 'validates', 'extends', 'persists', 'observes'];
+export type ConceptRelation = (typeof CONCEPT_RELATIONS)[number];
+export declare function isConceptRelation(value: string): value is ConceptRelation;
+export interface ConceptEdge {
+    fromId: string;
+    toId: string;
+    relation: ConceptRelation;
+}
+/** Write (or replace) one file's concept. */
+export declare function upsertFileConceptWithStatement(stmt: PrepareStatement, concept: FileConcept): void;
+export declare function getFileConceptWithStatement(stmt: PrepareStatement, file: string): FileConcept | undefined;
+/** All concepts, for whole-index consumers (atlas, embeddings, injection). */
+export declare function getAllFileConceptsWithStatement(stmt: PrepareStatement): FileConcept[];
+/** `file → summary` for the files that currently have a usable description. */
+export declare function getReadyConceptSummariesWithStatement(stmt: PrepareStatement): Map<string, string>;
+export interface ConceptCoverage {
+    ready: number;
+    stale: number;
+    pending: number;
+    subsystems: number;
+}
+export declare function getConceptCoverageWithStatement(stmt: PrepareStatement): ConceptCoverage;
+/**
+ * Mark every concept whose recorded hash no longer matches the indexed file as
+ * `stale`, in one statement.
+ *
+ * Run before a pass rather than during indexing: the indexer's atomic write is
+ * not the place to reason about a layer it does not own, and a summary that is
+ * one generation behind harms nothing until someone asks for it.
+ */
+export declare function markStaleConceptsWithStatement(stmt: PrepareStatement): number;
+/** Drop concepts for files that are no longer indexed. */
+export declare function pruneOrphanConceptsWithStatement(stmt: PrepareStatement): number;
+/** Replace the whole subsystem layer. Subsystems are derived as a set. */
+export declare function replaceSubsystemsWithStatement(stmt: PrepareStatement, maxSqlVars: number, subsystems: readonly Subsystem[], edges: readonly ConceptEdge[]): void;
+export declare function getSubsystemsWithStatement(stmt: PrepareStatement): Subsystem[];
+export declare function getConceptEdgesWithStatement(stmt: PrepareStatement): ConceptEdge[];
+export {};
+//# sourceMappingURL=writer-concepts.d.ts.map

package/dist/codebase-index/writer-graph-decorate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Atlas enrichment for the CodeMap graph.
+ *
+ * The three graph getters build their nodes from `symbols` and `files`. Rank,
+ * concept summaries and subsystem membership live in tables those queries know
+ * nothing about, and each getter reaches its nodes by a different route — one
+ * groups by package, one by file, one by symbol id.
+ *
+ * Rather than thread four more joins through three query shapes and their node
+ * builders, this decorates the finished nodes in one pass. That keeps the
+ * enrichment strictly additive: an index where no rank or concept pass has run
+ * produces exactly the graph it produced before, because every lookup misses
+ * and every field stays absent.
+ *
+ * It also sidesteps `chunkedIdQuery`'s documented rule that `buildSql` may not
+ * contain a `LIMIT` — there is no limit to express here.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { GraphNode } from './schema.js';
+type Statement = ReturnType<DatabaseSync['prepare']>;
+type PrepareStatement = (sql: string) => Statement;
+/**
+ * Stamp rank, concept, crux, subsystem and mtime onto graph nodes.
+ *
+ * `packageOf` is supplied by the caller because the package labeller already
+ * exists at every call site, and rebuilding it here would read `files` twice.
+ */
+export declare function decorateGraphNodes(stmt: PrepareStatement, nodes: GraphNode[], packageOf: (file: string) => string): void;
+export {};
+//# sourceMappingURL=writer-graph-decorate.d.ts.map

package/dist/codebase-index/writer-graph-reader.d.ts

@@ -1,7 +1,29 @@
 import type { DatabaseSync } from 'node:sqlite';
 import type { CallSite, CodeMapGraph, Ref } from './schema.js';
+import { type WriterSymbolGraphRow } from './writer-graph-helpers.js';
 type Statement = ReturnType<DatabaseSync['prepare']>;
 type PrepareStatement = (sql: string) => Statement;
+/**
+ * Hydrate symbol rows for an arbitrary id list.
+ *
+ * The personalised retrieval walk scores dense graph indices and then needs
+ * the declarations behind the winners; this is that lookup. Chunked because
+ * the id list is unbounded — the caller decides how many nodes to hydrate.
+ */
+export declare function getSymbolsByIdsWithStatement(stmt: PrepareStatement, ids: readonly number[]): WriterSymbolGraphRow[];
+/**
+ * Declarations in one file, in source order.
+ *
+ * Ordered by line rather than by any score so the list reads the way the file
+ * does — the atlas uses it to describe a file, not to rank within it.
+ */
+export declare function getFileSymbolsWithStatement(stmt: PrepareStatement, file: string, limit: number): Array<{
+    id: number;
+    name: string;
+    kind: string;
+    line: number;
+    signature: string;
+}>;
 /**
  * Find all symbols that CALL/USE the named target symbol (incoming callers).
  *

package/dist/codebase-index/writer-rank.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Persistence for the graph centrality layer (`symbol_rank`, `file_rank`).
+ *
+ * Ranks are always written as a whole: the score is a property of the entire
+ * graph, so a partial update would leave the table describing a graph that no
+ * longer exists. Both writers therefore delete and re-insert rather than
+ * upserting row by row — at ~66k symbols that is a single fast statement plus
+ * a ladder-chunked bulk insert, well inside the index run's existing budget.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { FileRankRow, SymbolRankRow } from './graph-rank.js';
+type Statement = ReturnType<DatabaseSync['prepare']>;
+type PrepareStatement = (sql: string) => Statement;
+/** Replace the whole `symbol_rank` table with `rows`. */
+export declare function replaceSymbolRanksWithStatement(stmt: PrepareStatement, maxSqlVars: number, rows: readonly SymbolRankRow[]): void;
+/** Replace the whole `file_rank` table with `rows`. */
+export declare function replaceFileRanksWithStatement(stmt: PrepareStatement, maxSqlVars: number, rows: readonly FileRankRow[]): void;
+/**
+ * Highest-ranked files, most central first.
+ *
+ * `limit` is applied in SQL — this is a plain single-table read, so none of
+ * the chunked-query constraints that forbid `LIMIT` elsewhere apply here.
+ */
+export declare function getTopFileRanksWithStatement(stmt: PrepareStatement, limit: number): FileRankRow[];
+/** A ranked file joined with the metadata the repo map needs to group it. */
+export interface RankedFileRow extends FileRankRow {
+    /** Code Atlas grouping label from `files.package` — '' when unlabelled. */
+    package: string;
+    lang: string;
+    symbolCount: number;
+}
+/**
+ * Highest-ranked files with their package label, for repo-map clustering.
+ *
+ * Joined here rather than in two round trips because the repo map always
+ * needs both, and `file_rank` is keyed by the same absolute path as `files`.
+ */
+export declare function getRankedFilesWithStatement(stmt: PrepareStatement, limit: number): RankedFileRow[];
+/**
+ * True indexed-file count per package label.
+ *
+ * The repo map only fetches its top few hundred ranked files, so counting
+ * cluster membership from that slice would report "core has 154 files" for a
+ * package with thousands. The count has to come from `files` itself.
+ */
+export declare function getPackageFileCountsWithStatement(stmt: PrepareStatement): Map<string, number>;
+/** Highest-ranked symbols, most central first. */
+export declare function getTopSymbolRanksWithStatement(stmt: PrepareStatement, limit: number): SymbolRankRow[];
+/**
+ * How many symbols declare each ambiguous symbol's name, keyed by symbol id.
+ *
+ * Counted per `(name, language family)` because that is exactly the scope ref
+ * resolution matches within (`FAMILY_MATCH_SQL`) — a Go `Read` and a
+ * TypeScript `Read` never compete for the same ref, so counting them together
+ * would understate the confidence of both.
+ *
+ * Only names with more than one declaration are returned: on this repo that
+ * is roughly a seventh of all names, so the map stays small and every absent
+ * id means "unambiguous, full weight".
+ */
+export declare function getSymbolNameCandidatesWithStatement(stmt: PrepareStatement): Map<number, number>;
+/**
+ * File-to-file import edges, as `source file → set of imported files`.
+ *
+ * Built from the import refs the module resolver managed to resolve to a real
+ * path (`refs.to_file`). Used by the rank pass to tell a cross-file reference
+ * that is genuinely visible from one the resolver merely guessed at.
+ */
+export declare function getImportVisibilityWithStatement(stmt: PrepareStatement): Map<string, Set<string>>;
+/** Whole-table `file → rank` lookup, for joining ranks onto graph reads. */
+export declare function getFileRankMapWithStatement(stmt: PrepareStatement): Map<string, number>;
+/** Row counts, for index stats and for deciding whether the layer is populated. */
+export declare function getRankCountsWithStatement(stmt: PrepareStatement): {
+    symbols: number;
+    files: number;
+};
+export {};
+//# sourceMappingURL=writer-rank.d.ts.map