@wrongstack/tools 1.0.1 → 1.0.3

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

@@ -0,0 +1,198 @@
+/**
+ * Graph centrality over the symbol wiring graph.
+ *
+ * Two modes share one implementation:
+ *
+ *  - **Global** — computed once per index run with a uniform restart
+ *    distribution, persisted to `symbol_rank` / `file_rank`. Answers "what is
+ *    architecturally central in this repo", and drives the repo map, the
+ *    CodeMap node sizing and the atlas projection.
+ *  - **Personalised** — computed per query with the lexical (BM25) hit scores
+ *    as the restart distribution. Answers "what is central *to this query*".
+ *    Lexical search proposes the seeds; the graph decides the ordering.
+ *
+ * The walk runs over an **undirected** view of the graph: a caller and its
+ * callee are mutually relevant when you are trying to understand either one,
+ * and a directed walk starves leaf utilities that everything depends on.
+ * Directed in/out degrees are still reported separately, because they are
+ * what a human reads as "blast radius" vs "coupling".
+ *
+ * Only refs that resolved to a real symbol id participate. At the time of
+ * writing roughly a third of this repo's refs stay unresolved (stdlib and
+ * third-party targets that were never indexed); including them would mean
+ * walking to nodes that carry no code.
+ *
+ * Edge multiplicity is deliberately preserved. Five calls from A to B produce
+ * five edges, so B receives five shares of A's mass: repeated coupling is
+ * stronger coupling. Self-references are dropped — recursion should not make
+ * a symbol important on its own account.
+ *
+ * ## Why edges carry a confidence weight
+ *
+ * The index resolves a ref by matching `to_name` to the lowest symbol id in
+ * the same language family — it is not file- or import-aware, which
+ * `findIncomingCallsByName` already documents as an ambiguity source. For a
+ * per-query answer that is a caveat; for a global ranking it is fatal. On this
+ * repo roughly half of all resolved refs point at a name that several symbols
+ * declare, and the worst offenders are test globals and single-letter locals:
+ * every `it(...)` in the suite lands on whichever `it` happens to hold the
+ * lowest id, handing that one symbol thousands of incoming edges it never had.
+ *
+ * So an edge into a name that `n` symbols declare carries weight `1 / n`: the
+ * resolver guessed one of `n` equally plausible targets, and the walk spreads
+ * exactly that much belief. Unique names — the half we can actually trust —
+ * keep full weight.
+ *
+ * Homonym counting alone is not enough, because the worst misresolutions are
+ * to names that really are unique. Every `it(...)` in the test suite resolves
+ * to the one `const it: Catalog` in the desktop app's i18n file — the Italian
+ * locale — handing a translation table 5,500 incoming edges. Nothing declares
+ * a competing `it`, so no homonym penalty applies.
+ *
+ * The second weight is therefore visibility, in three tiers. An edge is fully
+ * trusted when the two symbols share a file, or when the source file actually
+ * imports the target's file — the module resolver already recorded those pairs
+ * in `refs.to_file`. Otherwise the question is whether we can believe the
+ * absence of that import:
+ *
+ *  - The source file has resolved imports, and the target's file is not among
+ *    them. The resolver worked here and still did not connect these two files,
+ *    so the reference almost certainly is not to this symbol
+ *    ({@link CONTRADICTED_VISIBILITY_WEIGHT}).
+ *  - The source file has no resolved imports at all. Resolution failed
+ *    wholesale for it, so its silence is not evidence either way, and the edge
+ *    keeps a reduced but meaningful weight
+ *    ({@link UNVERIFIED_VISIBILITY_WEIGHT}).
+ *
+ * These stay penalties rather than filters: module resolution only resolves
+ * about three fifths of this repo's import specifiers, and dropping the rest
+ * outright would gut the graph.
+ *
+ * Both of these are ranking-quality fixes, not resolver fixes; making ref
+ * resolution import-aware would remove the need for either.
+ */
+/** Ref shape as returned by `IndexStore.getAllResolvedRefs()`. */
+export interface ResolvedRefEdge {
+    fromId: number;
+    toId: number;
+    callType: string;
+}
+/**
+ * Compressed sparse row adjacency over a dense node numbering.
+ *
+ * `neighbours[offsets[u] .. offsets[u + 1]]` are the dense indices adjacent to
+ * dense node `u`. `ids[u]` maps back to the original symbol id.
+ */
+export interface WiringGraph {
+    /** Number of nodes. */
+    size: number;
+    /** Original symbol id for each dense index. */
+    ids: Int32Array;
+    /** Dense index for each original symbol id. */
+    index: Map<number, number>;
+    /** CSR row offsets, length `size + 1`. */
+    offsets: Int32Array;
+    /** CSR adjacency entries, length `offsets[size]`. */
+    neighbours: Int32Array;
+    /**
+     * Confidence per adjacency entry, parallel to `neighbours`, in `(0, 1]`.
+     *
+     * This attenuates rather than redistributes: an edge with confidence `c`
+     * carries `c` of the mass it would otherwise carry, and the remaining
+     * `1 - c` returns to the restart distribution as belief the walk declined
+     * to place. Normalising these away — dividing each node's split by the sum
+     * of its weights — would make them inert, because a node with a single
+     * low-confidence edge would still hand over all of its mass.
+     */
+    weights: Float64Array;
+    /** Directed in-degree per dense node (how many symbols reference it). */
+    inDegree: Int32Array;
+    /** Directed out-degree per dense node (how many symbols it references). */
+    outDegree: Int32Array;
+}
+export interface PageRankOptions {
+    /**
+     * Restart (teleport) probability — the share of mass that returns to the
+     * restart distribution each iteration. Higher keeps the walk closer to its
+     * seeds. 0.25 is the value Graft settled on for code graphs; the classic
+     * web-PageRank 0.15 wanders too far for personalised queries.
+     */
+    restart?: number;
+    /** Power iterations. 25 converges comfortably at this graph size. */
+    iterations?: number;
+    /**
+     * Seed weights by **dense index**, for a personalised walk. Weights need not
+     * be normalised. Omitted (or empty) means a uniform restart distribution.
+     */
+    seeds?: ReadonlyMap<number, number> | undefined;
+}
+export declare const DEFAULT_RESTART = 0.25;
+export declare const DEFAULT_ITERATIONS = 25;
+/**
+ * Weight for a cross-file edge from a file whose imports never resolved. We
+ * cannot corroborate the edge, but we cannot contradict it either.
+ */
+export declare const UNVERIFIED_VISIBILITY_WEIGHT = 0.25;
+/**
+ * Weight for a cross-file edge from a file whose imports DID resolve, to a
+ * file it does not import. Near-zero rather than zero so a single resolver
+ * miss degrades one edge instead of erasing it.
+ */
+export declare const CONTRADICTED_VISIBILITY_WEIGHT = 0.02;
+/**
+ * Build the undirected CSR wiring graph from the resolved ref list.
+ *
+ * Two passes over the edge list (count, then fill) so the adjacency lands in
+ * flat typed arrays with no intermediate per-node arrays — at 180k edges the
+ * array-of-arrays shape costs more in allocation than the walk itself.
+ */
+export interface WiringGraphOptions {
+    /**
+     * How many symbols declare the name each target symbol carries, keyed by
+     * target symbol id. Absent ids are treated as unambiguous (weight 1).
+     */
+    candidates?: ReadonlyMap<number, number> | undefined;
+    /** Declaring file per symbol id, used for the visibility check. */
+    fileOf?: ReadonlyMap<number, string> | undefined;
+    /** Files each source file imports, as resolved by the module resolver. */
+    importsOf?: ReadonlyMap<string, ReadonlySet<string>> | undefined;
+}
+export declare function buildWiringGraph(refs: readonly ResolvedRefEdge[], options?: WiringGraphOptions): WiringGraph;
+/**
+ * Power-iterate PageRank over `graph`, returning scores normalised so the
+ * highest is exactly 1.0. Nodes the walk never reaches score 0.
+ *
+ * Mass is conserved exactly: every node hands `restart` of its mass back to
+ * the restart distribution, spreads the rest over its neighbours, and a node
+ * with no neighbours hands everything back. Low-confidence edges return their
+ * unspent share to the same pool. Without it the total would leak downwards
+ * and the final normalisation would hide the leak.
+ */
+export declare function pageRank(graph: WiringGraph, options?: PageRankOptions): Float64Array;
+/** One persisted `symbol_rank` row. */
+export interface SymbolRankRow {
+    symbolId: number;
+    rank: number;
+    inDeg: number;
+    outDeg: number;
+}
+/** One persisted `file_rank` row. */
+export interface FileRankRow {
+    file: string;
+    rank: number;
+    inDeg: number;
+    outDeg: number;
+}
+/** Materialise the score vector as persistable symbol rows. */
+export declare function toSymbolRankRows(graph: WiringGraph, scores: Float64Array): SymbolRankRow[];
+/**
+ * Roll symbol scores up to files.
+ *
+ * A file's rank is the **sum** of its symbols' ranks, not the mean: a module
+ * that exports twenty things everyone uses is more central than one that
+ * exports a single equally-used thing, and averaging erases exactly that.
+ * Degrees roll up the same way. The result is re-normalised to max 1.0 so
+ * file and symbol ranks share a scale.
+ */
+export declare function aggregateFileRank(rows: readonly SymbolRankRow[], fileOf: ReadonlyMap<number, string>): FileRankRow[];
+//# sourceMappingURL=graph-rank.d.ts.map

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

@@ -11,8 +11,9 @@
  * run on one event loop, so a pooled connection is both safe and substantially
  * cheaper than re-running schema/FTS drift checks for every edited file.
  */
+import type { ContextResult } from './context-retrieval.js';
 import type { CodeMapGraph, IndexResult, IndexStats } from './schema.js';
-import type { CallRefsOpArgs, IndexOpArgs, SearchOpArgs, SearchOpResult, StatsOpArgs } from './worker-protocol.js';
+import type { CallRefsOpArgs, ContextOpArgs, IndexOpArgs, SearchOpArgs, SearchOpResult, StatsOpArgs, VectorSearchOpArgs, VectorSearchOpResult } from './worker-protocol.js';
 interface ServiceHooks {
     signal?: AbortSignal | undefined;
     onProgress?: ((current: number, total: number) => void) | undefined;
@@ -21,6 +22,19 @@ interface ServiceHooks {
 export declare function indexService(args: IndexOpArgs, hooks?: ServiceHooks): Promise<IndexResult>;
 /** Ranked symbol search (FTS5 inside SQLite; BM25 fallback without FTS5). */
 export declare function searchService(args: SearchOpArgs): SearchOpResult;
+/**
+ * Personalised retrieval: lexical seeds walked through the wiring graph.
+ *
+ * Path relativisation happens here rather than in the retriever so the pure
+ * algorithm stays free of `node:path`, and so the daemon — which knows the
+ * project root it was started for — is the one that decides what "relative"
+ * means.
+ */
+export declare function contextService(args: ContextOpArgs): ContextResult;
+/**
+ * Nearest files to a query vector. The caller embeds; this only compares.
+ */
+export declare function vectorSearchService(args: VectorSearchOpArgs): VectorSearchOpResult;
 /** Index health and statistics. */
 export declare function statsService(args: StatsOpArgs): IndexStats;
 /** Package-level dependency graph. */

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

@@ -13,36 +13,51 @@
  *          fallback so every mapped language always enters the index
  * Ranking: Okapi BM25 / FTS5 (k1=1.5, b=0.75)
  */
-export { resolveProjectIndexDaemonAvailability, type ProjectIndexDaemonAvailability, } from './project-server-client.js';
+export { type InvariantEvaluationResult, type InvariantRuleId, type InvariantViolation, type ModuleContract, PolyglotInvariantEngine, polyglotInvariantEngine, } from './ast-invariant-engine.js';
+export { type MutateSymbolOptions, type MutateSymbolResult, replaceSymbolInFile, } from './ast-symbol-mutator.js';
 export { cancelPendingReindexes, checkCodebaseIndexServerHealth, codebaseIndexStats, enqueueReindex, ensureCodebaseIndexServer, fileGraphService, getIndexState, incomingCallsService, isIndexableFile, isIndexing, isIndexReady, onIndexStateChange, outgoingCallsService, packageGraphService, runStartupIndex, searchCodebaseIndex, shutdownCodebaseIndexHost, shutdownCodebaseIndexServer, symbolGraphService, } from './background-indexer.js';
 export { buildBm25Index, buildIndexableText, tokenise, } from './bm25.js';
+export { getCodebaseIndexPerfSnapshot, resetCodebaseIndexPerfMetrics, type CodebaseIndexPerfSnapshot, } from './perf-metrics.js';
 export type { CircuitSnapshot, CircuitState } from './circuit-breaker.js';
 export { CircuitOpenError, IndexCircuitBreaker, IndexTimeoutError, indexCircuitBreaker, resetIndexCircuitBreaker, } from './circuit-breaker.js';
-export { codebaseAstReplaceTool, type CodebaseAstReplaceInput, type CodebaseAstReplaceOutput, } from './codebase-ast-replace-tool.js';
-export { codebaseInvariantCheckTool, type CodebaseInvariantCheckInput, type CodebaseInvariantCheckOutput, } from './codebase-invariant-check-tool.js';
-export { replaceSymbolInFile, type MutateSymbolOptions, type MutateSymbolResult, } from './ast-symbol-mutator.js';
-export { codebaseImpactAnalysisTool, type CodebaseImpactAnalysisInput, type CodebaseImpactAnalysisOutput, type ImpactAnalysisInput, type ImpactAnalysisOutput, type ImpactCallSite, } from './codebase-impact-analysis-tool.js';
-export { codebaseIncomingCallsTool, type CodebaseIncomingCallsInput, type CodebaseIncomingCallsOutput, type IncomingCallsInput, type IncomingCallsOutput, } from './codebase-incoming-calls-tool.js';
-export { codebaseIndexTool, type CodebaseIndexInput, type CodebaseIndexOutput, } from './codebase-index-tool.js';
-export { codebaseOutgoingCallsTool, type CodebaseOutgoingCallsInput, type CodebaseOutgoingCallsOutput, type OutgoingCallsInput, type OutgoingCallsOutput, } from './codebase-outgoing-calls-tool.js';
-export { codebaseRepoMapTool, type CodebaseRepoMapInput, type CodebaseRepoMapOutput, } from './codebase-repo-map-tool.js';
-export { codebaseSearchTool, type CodebaseSearchInput, type CodebaseSearchOutput, } from './codebase-search-tool.js';
-export { codebaseSkeletonTool, type CodebaseSkeletonInput, type CodebaseSkeletonOutput, } from './codebase-skeleton-tool.js';
-export { codebaseStatsTool, type CodebaseStatsInput, type CodebaseStatsOutput, } from './codebase-stats-tool.js';
-export { codebaseTargetedTestTool, type CodebaseTargetedTestInput, type CodebaseTargetedTestOutput, type TargetedTestInput, type TargetedTestOutput, } from './codebase-targeted-test-tool.js';
-export { generateRepoMap, type RepoMapOptions, type RepoMapResult, } from './repo-map.js';
-export { extractDirectorySkeleton, extractFileSkeleton, type FileSkeletonResult, type SkeletonOptions, type SkeletonSymbolRange, } from './skeleton-extractor.js';
-export { deadCodeScanTool, runDeadCodeScan } from './dead-code-scan.js';
+export { type CodebaseAstReplaceInput, type CodebaseAstReplaceOutput, codebaseAstReplaceTool, } from './codebase-ast-replace-tool.js';
+export { type CodebaseImpactAnalysisInput, type CodebaseImpactAnalysisOutput, codebaseImpactAnalysisTool, type ImpactAnalysisInput, type ImpactAnalysisOutput, type ImpactCallSite, } from './codebase-impact-analysis-tool.js';
+export { type CodebaseIncomingCallsInput, type CodebaseIncomingCallsOutput, codebaseIncomingCallsTool, type IncomingCallsInput, type IncomingCallsOutput, } from './codebase-incoming-calls-tool.js';
+export { type CodebaseIndexInput, type CodebaseIndexOutput, codebaseIndexTool, } from './codebase-index-tool.js';
+export { type CodebaseInvariantCheckInput, type CodebaseInvariantCheckOutput, codebaseInvariantCheckTool, } from './codebase-invariant-check-tool.js';
+export { type CodebaseOutgoingCallsInput, type CodebaseOutgoingCallsOutput, codebaseOutgoingCallsTool, type OutgoingCallsInput, type OutgoingCallsOutput, } from './codebase-outgoing-calls-tool.js';
+export { type CodebaseRepoMapInput, type CodebaseRepoMapOutput, codebaseRepoMapTool, } from './codebase-repo-map-tool.js';
+export { type CodebaseSearchInput, type CodebaseSearchOutput, codebaseSearchTool, } from './codebase-search-tool.js';
+export { type CodebaseSkeletonInput, type CodebaseSkeletonOutput, codebaseSkeletonTool, } from './codebase-skeleton-tool.js';
+export { type CodebaseStatsInput, type CodebaseStatsOutput, codebaseStatsTool, } from './codebase-stats-tool.js';
+export { type CodebaseTargetedTestInput, type CodebaseTargetedTestOutput, codebaseTargetedTestTool, type TargetedTestInput, type TargetedTestOutput, } from './codebase-targeted-test-tool.js';
 export type { DeadCodeScanInput, DeadCodeScanOutput, DeadFile, DeadPackage, DeadSymbol, } from './dead-code-scan.js';
+export { deadCodeScanTool, runDeadCodeScan } from './dead-code-scan.js';
+export { compileGitignore, type IgnoreMatcher, loadGitignoreMatcher, } from './gitignore.js';
 export { runIndexer } from './indexer.js';
-export { compileGitignore, loadGitignoreMatcher, type IgnoreMatcher, } from './gitignore.js';
 export { detectLang, INDEXABLE_EXTENSIONS, isIndexablePath } from './languages.js';
 export { internalKindToLspKind, lspKindToInternalKind, } from './lsp-kind.js';
 export type { ProjectIndexServerClientHealth, ProjectIndexServerConnectionState, ProjectIndexServerConnectionStatus, } from './project-server-client.js';
+export { type ProjectIndexDaemonAvailability, resolveProjectIndexDaemonAvailability, } from './project-server-client.js';
+export { projectIndexServerEndpoint, projectIndexServerMetadataPath, } from './project-server-endpoint.js';
 export type { ProjectIndexServerActivity, ProjectIndexServerHealth, } from './project-server-protocol.js';
+export { generateRepoMap, type RepoMapOptions, type RepoMapResult, } from './repo-map.js';
 export type { CallSite, CodeMapGraph, FileMeta, FileSymbols, GraphEdge, GraphNode, IndexResult, IndexStats, SearchResult, Symbol, SymbolKind, SymbolLang, } from './schema.js';
-export { projectIndexServerEndpoint, projectIndexServerMetadataPath, } from './project-server-endpoint.js';
 export { SCHEMA_VERSION } from './schema.js';
+export { extractDirectorySkeleton, extractFileSkeleton, type FileSkeletonResult, type SkeletonOptions, type SkeletonSymbolRange, } from './skeleton-extractor.js';
 export { codebaseIndexDirOverride, IndexStore, resolveIndexDir } from './writer.js';
-export { PolyglotInvariantEngine, polyglotInvariantEngine, type InvariantEvaluationResult, type InvariantRuleId, type InvariantViolation, type ModuleContract, } from './ast-invariant-engine.js';
+export { type AtlasBrief, type AtlasBriefHub, type AtlasBriefIndexMissing, type AtlasBriefPackage, type AtlasBriefSubsystem, BRIEF_HUB_LIMIT, BRIEF_PACKAGE_LIMIT, BRIEF_SUBSYSTEM_LIMIT, buildAtlasBrief, buildProjectAtlasBrief, } from './atlas-brief.js';
+export { type AtlasExportOptions, EXPORT_FILE_LIMIT, EXPORT_PACKAGE_LIMIT, renderAtlasHtml, } from './atlas-export.js';
+export { ATLAS_DIR, ATLAS_FILE_LIMIT, ATLAS_JSON, ATLAS_MANIFEST, ATLAS_MARKDOWN, ATLAS_SCHEMA, type AtlasDocument, type AtlasEdge, type AtlasFile, type AtlasFreshness, type AtlasIndexMissing, type AtlasManifest, type AtlasPackage, type AtlasProjection, type AtlasSymbol, buildAtlas, checkAtlasFreshness, checkProjectAtlasFreshness, exportProjectAtlasHtml, MAX_REPORTED_DRIFT, type WrittenAtlas, writeAtlas, writeProjectAtlas, } from './atlas-projection.js';
+export { type CodebaseContextInput, type CodebaseContextOutput, codebaseContextTool, setContextQueryEmbedder, } from './codebase-context-tool.js';
+export { type ConceptIndexMissing, DEFAULT_CONCURRENCY, type EnrichOptions, type EnrichResult, enrichConcepts, enrichProjectConcepts, MAX_CRUX_LINES, MAX_SOURCE_CHARS, MAX_SUMMARY_CHARS, type SummarizeFileInput, type SummarizeFileResult, type SummarizerPort, type SummarizeSubsystemInput, type SummarizeSubsystemResult, } from './concept-enrichment.js';
+export { type ContextEntry, type ContextOptions, type ContextResult, type ContextSymbol, DEFAULT_LIMIT, DEFAULT_SYMBOLS_PER_FILE, retrieveContext, SEED_LIMIT, } from './context-retrieval.js';
+export { DEFAULT_BATCH_SIZE, type EmbeddingPort, type EmbedIndexMissing, type EmbedOptions, type EmbedResult, embedFiles, embedProjectFiles, MAX_EMBED_CHARS, } from './embedding-pass.js';
+export { clearWiringSnapshot, getWiringSnapshot, type WiringSnapshot, } from './graph-adjacency-cache.js';
+export { aggregateFileRank, buildWiringGraph, CONTRADICTED_VISIBILITY_WEIGHT, DEFAULT_ITERATIONS, DEFAULT_RESTART, type FileRankRow, type PageRankOptions, pageRank, type ResolvedRefEdge, type SymbolRankRow, toSymbolRankRows, UNVERIFIED_VISIBILITY_WEIGHT, type WiringGraph, type WiringGraphOptions, } from './graph-rank.js';
+export { RANK_REFRESH_FILE_THRESHOLD, RANK_VERSION, RANK_VERSION_KEY, type RankPassResult, runGraphRankPass, shouldRefreshRanks, } from './graph-rank-pass.js';
+export { CONCEPT_RELATIONS, type ConceptCoverage, type ConceptEdge, type ConceptRelation, type ConceptState, type FileConcept, isConceptRelation, type Subsystem, } from './writer-concepts.js';
+export { decorateGraphNodes } from './writer-graph-decorate.js';
+export type { RankedFileRow } from './writer-rank.js';
+export { FILE_VECTOR_PROVIDER_KEY, type FileVectorRow, type FileVectorState, type VectorHit, } from './writer-vectors.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/codebase-index/index.js

@@ -1,6 +1,30 @@
 import {
+  ATLAS_DIR,
+  ATLAS_FILE_LIMIT,
+  ATLAS_JSON,
+  ATLAS_MANIFEST,
+  ATLAS_MARKDOWN,
+  ATLAS_SCHEMA,
+  BRIEF_HUB_LIMIT,
+  BRIEF_PACKAGE_LIMIT,
+  BRIEF_SUBSYSTEM_LIMIT,
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_CONCURRENCY,
+  EXPORT_FILE_LIMIT,
+  EXPORT_PACKAGE_LIMIT,
+  MAX_CRUX_LINES,
+  MAX_EMBED_CHARS,
+  MAX_REPORTED_DRIFT,
+  MAX_SOURCE_CHARS,
+  MAX_SUMMARY_CHARS,
   PolyglotInvariantEngine,
+  buildAtlas,
+  buildAtlasBrief,
+  buildProjectAtlasBrief,
+  checkAtlasFreshness,
+  checkProjectAtlasFreshness,
   codebaseAstReplaceTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseIncomingCallsTool,
   codebaseIndexTool,
@@ -12,15 +36,24 @@ import {
   codebaseStatsTool,
   codebaseTargetedTestTool,
   deadCodeScanTool,
+  embedFiles,
+  embedProjectFiles,
+  enrichConcepts,
+  enrichProjectConcepts,
+  exportProjectAtlasHtml,
   extractDirectorySkeleton,
   extractFileSkeleton,
   generateRepoMap,
   polyglotInvariantEngine,
+  renderAtlasHtml,
   replaceSymbolInFile,
-  runDeadCodeScan
-} from "../chunk-YEISRT4S.js";
+  runDeadCodeScan,
+  setContextQueryEmbedder,
+  writeAtlas,
+  writeProjectAtlas
+} from "../chunk-PNLDTRC5.js";
 import "../chunk-XRNN44QY.js";
-import "../chunk-DRRY6SCM.js";
+import "../chunk-EMA2XENR.js";
 import "../chunk-SCMRM6NL.js";
 import "../chunk-HDYUBRMF.js";
 import "../chunk-7JJFC6CT.js";
@@ -45,32 +78,58 @@ import {
   shutdownCodebaseIndexHost,
   shutdownCodebaseIndexServer,
   symbolGraphService
-} from "../chunk-ZTCJCYLN.js";
+} from "../chunk-CVNCSMVU.js";
 import {
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath
-} from "../chunk-GDDXX27P.js";
+} from "../chunk-6ZLRRC74.js";
 import {
+  CONCEPT_RELATIONS,
+  CONTRADICTED_VISIBILITY_WEIGHT,
   CircuitOpenError,
+  DEFAULT_ITERATIONS,
+  DEFAULT_LIMIT,
+  DEFAULT_RESTART,
+  DEFAULT_SYMBOLS_PER_FILE,
+  FILE_VECTOR_PROVIDER_KEY,
   IndexCircuitBreaker,
   IndexStore,
   IndexTimeoutError,
+  RANK_REFRESH_FILE_THRESHOLD,
+  RANK_VERSION,
+  RANK_VERSION_KEY,
   SCHEMA_VERSION,
+  SEED_LIMIT,
+  UNVERIFIED_VISIBILITY_WEIGHT,
+  aggregateFileRank,
   buildBm25Index,
   buildIndexableText,
+  buildWiringGraph,
+  clearWiringSnapshot,
   codebaseIndexDirOverride,
+  decorateGraphNodes,
+  getWiringSnapshot,
   indexCircuitBreaker,
   internalKindToLspKind,
+  isConceptRelation,
   lspKindToInternalKind,
+  pageRank,
   resetIndexCircuitBreaker,
   resolveIndexDir,
+  retrieveContext,
+  runGraphRankPass,
   runIndexer,
+  shouldRefreshRanks,
+  toSymbolRankRows,
   tokenise
-} from "../chunk-N3K2SFEI.js";
-import "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+} from "../chunk-3JVSOBHU.js";
+import "../chunk-6LCKF5KH.js";
+import "../chunk-REWOZIA4.js";
 import "../chunk-6IEBD27U.js";
-import "../chunk-UCYQTZ7F.js";
+import {
+  getCodebaseIndexPerfSnapshot,
+  resetCodebaseIndexPerfMetrics
+} from "../chunk-ZKC5UNGD.js";
 import {
   INDEXABLE_EXTENSIONS,
   detectLang,
@@ -80,21 +139,60 @@ import {
   compileGitignore,
   loadGitignoreMatcher
 } from "../chunk-2CTZW6JQ.js";
-import "../chunk-KE7A76VC.js";
+import "../chunk-5U5ULQX2.js";
 import "../chunk-ZUFHAHTE.js";
 export {
+  ATLAS_DIR,
+  ATLAS_FILE_LIMIT,
+  ATLAS_JSON,
+  ATLAS_MANIFEST,
+  ATLAS_MARKDOWN,
+  ATLAS_SCHEMA,
+  BRIEF_HUB_LIMIT,
+  BRIEF_PACKAGE_LIMIT,
+  BRIEF_SUBSYSTEM_LIMIT,
+  CONCEPT_RELATIONS,
+  CONTRADICTED_VISIBILITY_WEIGHT,
   CircuitOpenError,
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_CONCURRENCY,
+  DEFAULT_ITERATIONS,
+  DEFAULT_LIMIT,
+  DEFAULT_RESTART,
+  DEFAULT_SYMBOLS_PER_FILE,
+  EXPORT_FILE_LIMIT,
+  EXPORT_PACKAGE_LIMIT,
+  FILE_VECTOR_PROVIDER_KEY,
   INDEXABLE_EXTENSIONS,
   IndexCircuitBreaker,
   IndexStore,
   IndexTimeoutError,
+  MAX_CRUX_LINES,
+  MAX_EMBED_CHARS,
+  MAX_REPORTED_DRIFT,
+  MAX_SOURCE_CHARS,
+  MAX_SUMMARY_CHARS,
   PolyglotInvariantEngine,
+  RANK_REFRESH_FILE_THRESHOLD,
+  RANK_VERSION,
+  RANK_VERSION_KEY,
   SCHEMA_VERSION,
+  SEED_LIMIT,
+  UNVERIFIED_VISIBILITY_WEIGHT,
+  aggregateFileRank,
+  buildAtlas,
+  buildAtlasBrief,
   buildBm25Index,
   buildIndexableText,
+  buildProjectAtlasBrief,
+  buildWiringGraph,
   cancelPendingReindexes,
+  checkAtlasFreshness,
   checkCodebaseIndexServerHealth,
+  checkProjectAtlasFreshness,
+  clearWiringSnapshot,
   codebaseAstReplaceTool,
+  codebaseContextTool,
   codebaseImpactAnalysisTool,
   codebaseIncomingCallsTool,
   codebaseIndexDirOverride,
@@ -109,17 +207,26 @@ export {
   codebaseTargetedTestTool,
   compileGitignore,
   deadCodeScanTool,
+  decorateGraphNodes,
   detectLang,
+  embedFiles,
+  embedProjectFiles,
   enqueueReindex,
+  enrichConcepts,
+  enrichProjectConcepts,
   ensureCodebaseIndexServer,
+  exportProjectAtlasHtml,
   extractDirectorySkeleton,
   extractFileSkeleton,
   fileGraphService,
   generateRepoMap,
+  getCodebaseIndexPerfSnapshot,
   getIndexState,
+  getWiringSnapshot,
   incomingCallsService,
   indexCircuitBreaker,
   internalKindToLspKind,
+  isConceptRelation,
   isIndexReady,
   isIndexableFile,
   isIndexablePath,
@@ -129,20 +236,30 @@ export {
   onIndexStateChange,
   outgoingCallsService,
   packageGraphService,
+  pageRank,
   polyglotInvariantEngine,
   projectIndexServerEndpoint,
   projectIndexServerMetadataPath,
+  renderAtlasHtml,
   replaceSymbolInFile,
+  resetCodebaseIndexPerfMetrics,
   resetIndexCircuitBreaker,
   resolveIndexDir,
   resolveProjectIndexDaemonAvailability,
+  retrieveContext,
   runDeadCodeScan,
+  runGraphRankPass,
   runIndexer,
   runStartupIndex,
   searchCodebaseIndex,
+  setContextQueryEmbedder,
+  shouldRefreshRanks,
   shutdownCodebaseIndexHost,
   shutdownCodebaseIndexServer,
   symbolGraphService,
-  tokenise
+  toSymbolRankRows,
+  tokenise,
+  writeAtlas,
+  writeProjectAtlas
 };
 //# sourceMappingURL=index.js.map

package/dist/codebase-index/parser-worker-script.js

@@ -1,11 +1,11 @@
 import {
   parseFilesContent
-} from "../chunk-NU2IZ72J.js";
-import "../chunk-VVZPQPTY.js";
+} from "../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-KE7A76VC.js";
+import "../chunk-5U5ULQX2.js";
 
 // src/codebase-index/parser-worker-script.ts
 import { parentPort, threadId } from "node:worker_threads";

package/dist/codebase-index/perf-metrics.d.ts

@@ -0,0 +1,19 @@
+/** Opt-in counters for controlled codebase-index performance measurements. */
+export interface CodebaseIndexPerfSnapshot {
+    filesystemBytesRead: number;
+    filesystemReadCount: number;
+    parserGateWaitMs: number;
+    parserGateCalls: number;
+    parserSubprocessCount: number;
+    ipcPendingPeak: number;
+    writeQueueWaitMs: number;
+    writeQueueCalls: number;
+}
+export declare function resetCodebaseIndexPerfMetrics(): void;
+export declare function getCodebaseIndexPerfSnapshot(): CodebaseIndexPerfSnapshot;
+export declare function recordFilesystemRead(bytes: number): void;
+export declare function recordParserGateWait(waitMs: number): void;
+export declare function recordParserSubprocess(): void;
+export declare function recordIpcPending(depth: number): void;
+export declare function recordWriteQueueWait(waitMs: number): void;
+//# sourceMappingURL=perf-metrics.d.ts.map

package/dist/codebase-index/project-server-protocol.d.ts

@@ -37,6 +37,8 @@ export interface ProjectIndexServerHealth {
     activeRequests: number;
     activeWrites: number;
     queuedWrites: number;
+    maxQueuedWrites?: number;
+    writeQueueWaitMs?: number;
     pendingExternalFiles: number;
     watchingExternal: boolean;
     /** Clients currently requesting ownership of the shared external watcher. */

package/dist/codebase-index/project-server-query-cache.d.ts

@@ -23,9 +23,11 @@
  *   transaction may have rolled back the visible generation) all caches are
  *   cleared.
  */
+import type { ContextResult } from './context-retrieval.js';
 import type { IncomingCallsResult, OutgoingCallsResult } from './index-service.js';
 import { GenerationLruCache } from './project-server-cache.js';
 import type { CodeMapGraph, IndexStats, SearchResult } from './schema.js';
+import type { VectorSearchOpResult } from './worker-protocol.js';
 /** The error the server answers a read it cannot serve with. */
 export declare function indexRefreshInProgressError(currentFile: number, totalFiles: number): Error;
 /**
@@ -76,6 +78,8 @@ export declare class ServerQueryCaches {
         total: number;
     }>;
     readonly statsCache: GenerationLruCache<IndexStats>;
+    readonly contextCache: GenerationLruCache<ContextResult>;
+    readonly vectorSearchCache: GenerationLruCache<VectorSearchOpResult>;
     readonly packageGraphCache: GenerationLruCache<CodeMapGraph>;
     readonly fileGraphCache: GenerationLruCache<CodeMapGraph>;
     readonly symbolGraphCache: GenerationLruCache<CodeMapGraph>;