Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* Herkunft: portiert am 2026-08-28 aus CodeAtlasIDE,
* /Users/bernhard/Desktop/CodeAtlasIDE/theia-extensions/codeatlas-intelligence/src/node/provider/cbm-provider.ts
* Gleicher Urheber (Bernhard Jackiewicz). Die Logik ist semantisch
* unveraendert: die Zustandstabelle, die Zusammenfuehrung der beiden
* Fehlerrelationen, die immer nur inferierte Test-Heuristik, der
* Projektnamen-Cache mit Toleranz fuer den Schraegstrich am Ende, die Deckel
* und die Zeilen-Rueckfaelle stehen hier so, wie sie dort stehen. Die
* Provider-Id bleibt 'cbm', damit jede Evidenz weiter derselben Quelle
* zugeschrieben wird.
*
* Aenderungen gegenueber dem Original, alle im Transport und alle unten am Ort
* begruendet:
*
* - Der Client ist RpcIntelligenceClient auf POST /rpc statt der CLI ueber
* einen Kindprozess. Nichts unter src/** darf einen Prozess starten.
* - engineInfo fragt den Server statt ein Binaerprogramm.
* - indexWorkspace und deleteProject sind auf /rpc gesperrt und lehnen ab,
* statt eine Antwort zu erfinden.
* - Der Route-Scan hat keinen Vorgabe-Leser mehr: ohne Dateisystem gibt es
* nichts zu lesen, und Routen kommen dann nur aus dem Index.
* - Der Klassenname heisst CbmRpcProvider, weil im selben Projekt spaeter ein
* zweiter Transport denkbar ist und zwei Klassen namens CbmProvider dann
* nicht unterscheidbar waeren.
*/
/**
* The first `IntelligenceProvider` implementation.
*
* Its whole job is translation: product questions in, engine queries out,
* evidence-carrying facts back. Two rules make the translation honest.
*
* Rule one: an empty answer is not a fact until we know why it is empty. Every
* fact family therefore carries the state that explains its emptiness, and the
* decision is made by one pure function (`knowledgeStateFor`) so it can be
* tested as a table rather than as a pile of branches.
*
* Rule two: never dress a heuristic as a reading. The 0.9.0 engine records no
* test relation for TypeScript, so `testedBy` is derived from callers that the
* engine flagged as test code. That derivation is real and useful, and it is
* reported as `inferred` with the strategy named in the evidence, forever.
* An empty `testedBy` never becomes `known`, because "no test caller found"
* and "not tested" are different claims.
*/
import type {
ArchitectureHotspot,
ArchitectureOverviewDto,
ChangeImpactDto,
ChangeImpactSymbol,
EngineInfo,
FactKind,
IndexOptions,
IndexProgress,
IndexState,
IntelligenceProvider,
ModuleDependency,
ModuleDependencyGraph,
ProviderCapabilities,
ProviderQueryOptions,
ResolveResult,
RouteRef,
SymbolComplexity,
SymbolFacts,
SymbolSearchHit,
TraceDirection,
TraceNode,
TraceOptions,
TraceResult
} from '../core/intelligence-provider';
import type { CodeAtlasSymbolKind, Range, SymbolRef } from '../core/focus-protocol';
import type {
CallerRef,
CallSite,
DataRef,
Evidence,
Fact,
KnowledgeState,
TestRef,
ThrowRef
} from '../core/semantic-ir';
import { EngineError, EngineUnavailableError } from './engine-errors';
import { RpcIntelligenceClient } from './rpc-client';
import { isAmbiguousPath, toBoolean, toOptionalNumber } from './rpc-schemas';
import type { DetectedSymbol, PathHop, PathWalk } from './rpc-schemas';
import type { EnclosingLabel } from './cypher';
import {
CALLABLE_LABELS,
COLUMNS,
COMPLEXITY_BATCH_LIMIT,
ENCLOSING_LABELS,
callersOfAny,
callsIn,
callsOut,
classCallTargets,
complexityOf,
declarationsInFiles,
enclosingByLabel,
envReads,
fileExists,
hotspotCandidates,
IMPORT_EDGE_LIMIT,
importEdges,
indexedFiles,
raises,
throwsRelation,
typeRefs
} from './cypher';
import { isRouteSource, readRoutes } from './route-reader';
/**
* Identifier stamped on every piece of evidence this provider emits.
*
* The reference declares the string here and the class field reads it; this
* port does it the other way round. The field is what actually lands on every
* `Evidence.providerId`, so that is where the string belongs, and typing the
* constant from the field means the two cannot drift: change the field and
* this line stops compiling.
*/
export const CBM_PROVIDER_ID: CbmRpcProvider['id'] = 'cbm';
/** How many hotspots the overview carries. More than a reader looks at in one sitting. */
export const MAX_HOTSPOTS = 20;
/** How many routes the overview carries. */
export const MAX_ROUTES = 200;
/**
* How many invocation steps a change assessment walks outwards.
*
* Two, and the number is a reading decision rather than a performance one. One
* step answers "who calls what I touched", which is the question; two answers
* "and who calls them", which is where an endpoint usually turns up. Three
* steps out of a service function is most of a codebase, and a list nobody
* finishes reading is the same as no list.
*/
export const IMPACT_WALK_DISTANCE = 2;
/** How many symbols one change assessment carries before it says it stopped early. */
export const MAX_IMPACT_SYMBOLS = 200;
/** How many changed files are looked up in the index to recover identities. */
export const MAX_CHANGED_FILES_READ = 60;
/**
* CodeAtlas's own state directory inside the workspace.
*
* Indexing writes a project pin here, so a workspace that has been opened once
* has a file in it that git reports as changed and that the reader did not
* touch. Listing it in an impact assessment would be reporting our bookkeeping
* back to them as their own work, and worse, it would inflate the changed-file
* count that the narrative and the risk rules both read. It is dropped from the
* change set, and this constant is the one place that decision lives.
*/
export const CODEATLAS_STATE_PREFIX = '.codeatlas/';
/** True when a path is CodeAtlas's own state rather than the reader's code. */
export function isCodeAtlasState(path: string): boolean {
return path === '.codeatlas' || path.startsWith(CODEATLAS_STATE_PREFIX);
}
/** How many files the route scan opens. A bound on cost, not on correctness. */
export const MAX_ROUTE_SCAN_FILES = 800;
/** Files above this size are generated or vendored, and are not read. */
export const MAX_ROUTE_SCAN_BYTES = 512 * 1024;
/** Relation labels written into evidence. Product wording, not engine wording. */
export const EVIDENCE_RELATIONS = {
invocation: 'invocation',
raise: 'raise',
/**
* A declared error, as opposed to a raised one. Kept apart from `raise` so a
* reader looking at the evidence can tell "this code throws it" from "this
* signature declares it", which is the difference between the two relations
* the engine records.
*/
throwDeclaration: 'throw-declaration',
environmentRead: 'environment-read',
typeReference: 'type-reference'
} as const;
/** Named heuristics. A strategy string in evidence must always match one of these. */
export const STRATEGIES = {
/** A caller the engine flagged as test code is treated as a test of the callee. */
testCaller: 'is-test-caller',
/** The target of the invocation is a class, so the site constructs rather than calls. */
construction: 'construction',
/** An ordinary resolved invocation. */
directCall: 'direct-call'
} as const;
/** Inputs to the state decision. Kept as data so the table can be tested directly. */
export interface FactStateContext {
/** False when no engine answered at all. */
engineAvailable: boolean;
/** False when the symbol's project or file is not in the index. */
indexed: boolean;
/** False when this provider cannot answer this family for this language. */
supported: boolean;
/** True when the value came from a heuristic rather than from a reading. */
derived: boolean;
}
/**
* The one place that decides how much trust a fact carries.
*
* Order matters: an unavailable engine outranks everything, because we do not
* know whether the family is supported for a workspace we could not open.
* Support outranks indexing, because an unsupported family stays unsupported
* however complete the index becomes.
*/
export function knowledgeStateFor(ctx: FactStateContext): KnowledgeState {
if (!ctx.engineAvailable) {
return 'unknown';
}
if (!ctx.supported) {
return 'unsupported';
}
if (!ctx.indexed) {
return 'notIndexed';
}
return ctx.derived ? 'inferred' : 'known';
}
/** Map an engine label to the narrower product symbol kind. */
export function symbolKindOf(label: string | undefined): CodeAtlasSymbolKind {
switch ((label ?? '').toLowerCase()) {
case 'function': return 'function';
case 'method': return 'method';
case 'class': return 'class';
case 'interface': return 'interface';
case 'module':
case 'file': return 'module';
case 'variable': return 'variable';
case 'type': return 'type';
case 'route': return 'route';
default: return 'unknown';
}
}
/** Map an engine label to the caller kinds the semantic IR models. */
export function sourceKindOf(label: string | undefined): 'function' | 'method' | 'module' | undefined {
const kind = symbolKindOf(label);
return kind === 'function' || kind === 'method' || kind === 'module' ? kind : undefined;
}
/**
* The stable identity of an indexed symbol, as this provider can supply one.
*
* `SymbolRef.nodeId` is documented as "stable engine graph node id, absent when
* the symbol is not indexed", and the whole product reads its presence as "the
* index knows this thing": `EditorSyncService.revealSymbol` publishes
* `indexed: Boolean(symbol.nodeId)`, so a reveal of a symbol without one tells
* every panel on the bus that a perfectly well indexed symbol is not indexed.
* That is exactly the demotion the guided review had to work around in C16.
*
* The engine's own numeric node ids are not reachable: the 0.9.0 query subset
* has no `id()` function and no property holding one, so there is nothing to
* return. The qualified name is what is available and it is a genuine stable
* identity rather than a stand-in for one: it is the key the engine itself
* accepts for every symbol-addressed call this provider makes (`callsIn`,
* `callsOut`, `raises`, `getCodeSnippet`, `tracePath`), and it is already what
* the IR cache, the understanding store and the frontend's own caches key on.
*
* A symbol with no qualified name gets no node id, which is correct: that is
* precisely the case where the index cannot name the thing.
*/
export function stableNodeId(qualifiedName: string | undefined): string | undefined {
return qualifiedName && qualifiedName.length > 0 ? qualifiedName : undefined;
}
function fileUri(workspaceRoot: string, relativePath: string): string {
const root = workspaceRoot.replace(/\/+$/, '');
const rest = relativePath.replace(/^\/+/, '');
return `file://${root}/${rest}`;
}
/** Turn 1-based inclusive graph lines into a 0-based editor range. */
function graphRange(startLine: number | undefined, endLine: number | undefined): Range {
const start = Math.max(0, (startLine ?? 1) - 1);
const end = Math.max(start, (endLine ?? startLine ?? 1) - 1);
return {
start: { line: start, character: 0 },
end: { line: end, character: 0 }
};
}
/**
* What the first-hop enrichment of a path walk recovers about one reached
* symbol. Every field is optional because each one comes from a different
* column and a column the engine did not fill arrives empty rather than absent.
*/
interface HopFacts {
/** Display name, needed when the reading contributes a row the walk omitted. */
name?: string;
/** Workspace-relative path of the declaring file. */
file?: string;
/** 1-based graph line of the declaration. */
line?: number;
isTest?: boolean;
construction?: boolean;
}
/** What the index knows about one declaration, recovered by file and name. */
interface DeclarationRow {
qualifiedName?: string;
/** 1-based declaration line. */
line?: number;
isTest?: boolean;
}
/** Key of a declaration lookup: a name is only unique inside its own file. */
function declarationKey(filePath: string | undefined, name: string): string {
return `${filePath ?? ''}|${name}`;
}
/**
* The change tool's symbol list with its repeats removed.
*
* It reports the whole list once per repeated changed file, so a change to one
* file that the diff mentions twice arrives as six rows describing three
* symbols. Deduplicated on what identifies a row at 0.9.0, which is the file,
* the name and the label, because that is all a row carries.
*/
export function dedupeDetected(entries: readonly DetectedSymbol[]): DetectedSymbol[] {
const seen = new Set<string>();
const out: DetectedSymbol[] = [];
for (const entry of entries) {
const key = [
entry.file ?? entry.file_path ?? '',
entry.name ?? '',
entry.label ?? '',
entry.qualified_name ?? ''
].join('|');
if (seen.has(key)) {
continue;
}
seen.add(key);
out.push(entry);
}
return out;
}
/**
* Every symbol the index places inside a set of files, as change rows.
*
* Used only where the analysis names a count of changed declarations and not
* their names. Sorted by file and then by line, so two runs against one index
* produce the same list, and every row carries the identity a surface needs to
* open it.
*/
export function declarationsIn(
filePaths: readonly string[],
declarations: Map<string, DeclarationRow>
): ChangeImpactSymbol[] {
const wanted = new Set(filePaths);
const rows: ChangeImpactSymbol[] = [];
for (const [key, row] of declarations) {
const separator = key.indexOf('|');
const filePath = key.slice(0, separator);
const name = key.slice(separator + 1);
if (!wanted.has(filePath) || name.length === 0) {
continue;
}
rows.push({
name,
qualifiedName: row.qualifiedName,
filePath,
line: row.line,
kind: 'unknown',
changeKind: 'declared',
distance: 0,
...(row.isTest === undefined ? {} : { isTest: row.isTest })
});
}
// Ordinal, never localeCompare: two machines with two collations would
// otherwise order one change set two ways. Dieselbe Regel wie im
// Tour-Generator und im Closure-Walk.
return rows.sort((a, b) => {
const left = a.filePath ?? '';
const right = b.filePath ?? '';
if (left !== right) {
return left < right ? -1 : 1;
}
return (a.line ?? 0) - (b.line ?? 0);
});
}
export interface EnclosingCandidate {
label: EnclosingLabel;
name: string;
qualifiedName: string;
startLine: number;
endLine: number;
}
/**
* Innermost candidate wins, measured by declaration span. A tie means two
* labels describe the same extent, and then the narrower label wins.
*/
export function pickInnermost(candidates: EnclosingCandidate[]): EnclosingCandidate | undefined {
const rank = (label: EnclosingLabel): number => ENCLOSING_LABELS.indexOf(label);
return [...candidates].sort((a, b) => {
const spanA = a.endLine - a.startLine;
const spanB = b.endLine - b.startLine;
if (spanA !== spanB) {
return spanA - spanB;
}
return rank(a.label) - rank(b.label);
})[0];
}
export interface CbmRpcProviderOptions {
/**
* Index generation stamped on evidence. Bumped by the index service on each
* rebuild; evidence from an older generation is discarded, never patched.
*/
generation?: number;
/**
* Reads one workspace file as text, or answers undefined when it cannot.
*
* Injected so the route scan can be driven without a file system, and so a
* provider that reads a workspace over a connection rather than off a disk
* has somewhere to say so. In the browser there is nothing to inject and
* the field stays absent, which is why the scan reports nothing there and
* routes come from the index alone. A Node caller that injects a reader is
* expected to honour {@link MAX_ROUTE_SCAN_BYTES} itself; the ceiling moved
* to the reader along with the file system.
*/
readSource?: (absolutePath: string) => string | undefined;
}
export class CbmRpcProvider implements IntelligenceProvider {
readonly id = 'cbm';
/** Cache of workspace root to engine project name, filled from the project list. */
private readonly projectNames = new Map<string, string>();
constructor(
protected readonly client: RpcIntelligenceClient,
protected readonly options: CbmRpcProviderOptions = {}
) { }
capabilities(): ProviderCapabilities {
return {
callers: true,
callees: true,
throws: true,
envReads: true,
typeRefs: true,
// No first class test relation is recorded for TypeScript at 0.9.0.
tests: 'heuristic',
routes: true,
architecture: true,
changeImpact: true,
// Measured against this server rather than assumed, and false for
// a second reason here. In the reference the tool accepted events
// and wrote nothing, so reporting `true` because the call succeeded
// would have been the exact dishonesty this flag exists to prevent.
// On /rpc the tool is not offered at all: the read-only allowlist
// answers `ingest_traces` with 403 and -32601. Either way there is
// no runtime relation to query, and the product's own trace store
// is what a surface reads.
runtimeTraces: false,
semanticSearch: true,
// Invocations are deduplicated per target, so a reported line is the
// last recorded site and not the only one.
callSiteGranularity: 'per-target'
};
}
/**
* Whether the backend answers, asked by asking it something.
*
* The original probed the engine binary and read its version out of
* `--version`. There is no binary on this side of the wire and no version
* on /rpc, so the question is put to the server instead: the cheapest read
* it offers is the project list, and a surface that answers it is a surface
* that can be asked the rest. `version` stays absent rather than being
* filled with the UI's own build number, which would answer a question
* about the analysis backend with a fact about the frontend.
*/
async engineInfo(): Promise<EngineInfo> {
try {
await this.client.listProjects();
return { available: true, providerId: this.id };
} catch (error) {
return {
available: false,
providerId: this.id,
detail: error instanceof Error ? error.message : String(error)
};
}
}
/**
* Build or refresh the index. Not something this surface can do.
*
* The server's read-only allowlist does not offer `index_repository` on
* /rpc, so this rejects with the engine-unavailable error the client
* raises. It rejects rather than answering `{ state: 'failed' }`, because
* `failed` means "the last build failed" and would tell a reader something
* about their workspace. Nothing was attempted, and the caller has to be
* able to tell those apart.
*/
async indexWorkspace(_root: string, _opts: IndexOptions = {}): Promise<IndexProgress> {
return this.client.indexRepository();
}
async indexState(root: string, opts?: ProviderQueryOptions): Promise<IndexProgress> {
const project = await this.projectFor(root, opts);
if (!project) {
return { state: 'absent', generation: this.generation() };
}
try {
const status = await this.client.indexStatus(project);
return {
state: indexStateOf(status.status),
symbolCount: status.nodes,
relationCount: status.edges,
generation: this.generation(),
message: status.status
};
} catch (error) {
if (error instanceof EngineUnavailableError) {
return { state: 'absent', generation: this.generation(), message: error.message };
}
if (error instanceof EngineError) {
return { state: 'absent', generation: this.generation(), message: error.message };
}
throw error;
}
}
async resolveSymbolAt(
workspaceRoot: string,
filePath: string,
oneBasedLine: number,
opts?: ProviderQueryOptions
): Promise<ResolveResult> {
let project: string | undefined;
try {
project = await this.projectFor(workspaceRoot, opts);
} catch (error) {
if (error instanceof EngineUnavailableError) {
return { kind: 'engine-unavailable', reason: error.message };
}
throw error;
}
if (!project) {
return { kind: 'file-not-indexed', filePath };
}
try {
const candidates: EnclosingCandidate[] = [];
for (const label of ENCLOSING_LABELS) {
const rows = await this.client.queryRows(project, enclosingByLabel(label, filePath, oneBasedLine));
for (const row of rows) {
const qualifiedName = row[COLUMNS.enclosing[1]];
const startLine = toOptionalNumber(row[COLUMNS.enclosing[2]]);
const endLine = toOptionalNumber(row[COLUMNS.enclosing[3]]);
if (!qualifiedName || startLine === undefined || endLine === undefined) {
continue;
}
candidates.push({
label,
name: row[COLUMNS.enclosing[0]] ?? qualifiedName,
qualifiedName,
startLine,
endLine
});
}
}
if (candidates.length === 0) {
const fileRows = await this.client.queryRows(project, fileExists(filePath));
return fileRows.length > 0
? { kind: 'no-symbol-at-line', filePath }
: { kind: 'file-not-indexed', filePath };
}
const innermost = pickInnermost(candidates)!;
const toRef = (candidate: EnclosingCandidate): SymbolRef => ({
nodeId: stableNodeId(candidate.qualifiedName),
name: candidate.name,
qualifiedName: candidate.qualifiedName,
kind: symbolKindOf(candidate.label),
uri: fileUri(workspaceRoot, filePath),
range: graphRange(candidate.startLine, candidate.endLine),
projectName: project
});
const enclosing = candidates
.filter(candidate => candidate !== innermost)
.sort((a, b) => (a.endLine - a.startLine) - (b.endLine - b.startLine))
.map(toRef);
return { kind: 'ok', symbol: toRef(innermost), enclosing };
} catch (error) {
if (error instanceof EngineUnavailableError) {
return { kind: 'engine-unavailable', reason: error.message };
}
if (error instanceof EngineError) {
// A refused query on a known project means the project no longer
// holds this file: not indexed, rather than nothing at the line.
return { kind: 'file-not-indexed', filePath };
}
throw error;
}
}
async getFacts(
workspaceRoot: string,
symbol: SymbolRef,
kinds: FactKind[],
opts?: ProviderQueryOptions
): Promise<SymbolFacts> {
const facts: SymbolFacts = {};
const qualifiedName = symbol.qualifiedName;
let project: string | undefined;
let engineAvailable = true;
try {
project = symbol.projectName ?? await this.projectFor(workspaceRoot, opts);
} catch (error) {
if (!(error instanceof EngineUnavailableError)) {
throw error;
}
engineAvailable = false;
}
const indexed = engineAvailable && !!project && !!qualifiedName;
// testedBy rides on the caller rows, so callers are fetched whenever
// either family was requested.
const wantCallers = kinds.includes('callers');
const wantTested = kinds.includes('testedBy');
let callerRows: Record<string, string>[] = [];
let callersFailed = false;
if ((wantCallers || wantTested) && indexed) {
try {
callerRows = await this.client.queryRows(project!, callsIn(qualifiedName!));
} catch (error) {
callersFailed = true;
engineAvailable = engineAvailable && !(error instanceof EngineUnavailableError);
if (!(error instanceof EngineError) && !(error instanceof EngineUnavailableError)) {
throw error;
}
}
}
const callersUsable = indexed && !callersFailed;
for (const kind of kinds) {
switch (kind) {
case 'callees':
facts.callees = await this.calleesFact(project, qualifiedName, engineAvailable, indexed);
break;
case 'callers':
facts.callers = this.callersFact(callerRows, engineAvailable, callersUsable);
break;
case 'testedBy':
facts.testedBy = this.testedByFact(callerRows, engineAvailable, callersUsable);
break;
case 'throws':
facts.throws = await this.throwsFact(project, qualifiedName, engineAvailable, indexed, symbol);
break;
case 'envReads':
facts.envReads = await this.envReadsFact(project, qualifiedName, engineAvailable, indexed, symbol);
break;
case 'typeRefs':
facts.typeRefs = await this.typeRefsFact(project, qualifiedName, engineAvailable, indexed);
break;
}
}
// The generation belongs to the caller's read, not to the provider's
// lifetime: the provider is built once and the index is rebuilt many
// times. Stamping here, at the one boundary where the caller's pinned
// generation is known, keeps every fact builder free of it.
return opts?.generation === undefined ? facts : stampGeneration(facts, opts.generation);
}
/**
* Walk invocation paths away from a symbol.
*
* Two of the three knobs in the product's contract are honoured here rather
* than by the engine, because the 0.9.0 engine accepts them and ignores
* them. Measured against the frozen fixture:
*
* - `direction` only produces an answer when it is `both` or absent.
* Asking for `callees` or `callers` returns a walk with neither list on
* it, which a caller cannot tell apart from a symbol that reaches
* nothing. So the call is made without a direction and the answer is
* filtered here.
* - `max_depth` does not bound the walk. Asking for one hop still returns
* hop two and hop three, so the bound is applied to the answer.
*
* Both are translations rather than workarounds: the product asks for a
* directed, bounded walk, and this is what that means against this backend.
* Filtering after the fact costs the engine the work of the other direction,
* which for a call graph walk is the same traversal it was doing anyway.
*/
async tracePaths(
workspaceRoot: string,
symbol: SymbolRef,
direction: TraceDirection,
opts?: TraceOptions
): Promise<TraceResult> {
const project = symbol.projectName ?? await this.projectFor(workspaceRoot, opts);
const target = symbol.qualifiedName ?? symbol.name;
if (!project) {
return { status: 'ok', direction, root: symbol, layers: [] };
}
// No direction and no depth on the wire: see the note above.
const result = await this.client.tracePath(project, target, {});
if (isAmbiguousPath(result)) {
return {
status: 'ambiguous',
candidates: result.suggestions.map(suggestion => ({
nodeId: stableNodeId(suggestion.qualified_name),
name: suggestion.name,
qualifiedName: suggestion.qualified_name,
kind: symbolKindOf(suggestion.label),
uri: suggestion.file_path ? fileUri(workspaceRoot, suggestion.file_path) : '',
range: graphRange(undefined, undefined),
projectName: project
}))
};
}
const maxDepth = opts?.maxDepth;
const layers: TraceNode[][] = [];
const push = (hops: PathHop[] | undefined, via: 'callers' | 'callees'): void => {
if (direction !== 'both' && direction !== via) {
return;
}
for (const hop of hops ?? []) {
const depth = Math.max(1, hop.hop ?? 1);
if (maxDepth !== undefined && depth > maxDepth) {
continue;
}
const index = depth - 1;
while (layers.length <= index) {
layers.push([]);
}
layers[index].push({
symbol: {
nodeId: stableNodeId(hop.qualified_name),
name: hop.name,
qualifiedName: hop.qualified_name,
kind: 'unknown',
uri: '',
range: graphRange(undefined, undefined),
projectName: project
},
hop: depth,
via
});
}
};
const walk = result as PathWalk;
push(walk.callees, 'callees');
push(walk.callers, 'callers');
if (maxDepth === undefined || maxDepth >= 1) {
await this.enrichFirstHop(workspaceRoot, project, symbol, direction, layers);
}
return { status: 'ok', direction, root: symbol, layers };
}
/**
* Make the first hop complete, and say what it knows.
*
* The walk carries a name, a qualified name and a distance per hop and
* nothing more: no file, no test flag, and no way to tell a construction
* from a call. Those come from the invocation relations of one symbol,
* which is one query per direction, and this is where they are read.
*
* The reading also completes the layer, which is the less obvious half. The
* 0.9.0 walk only steps through symbols it treats as callable, so a caller
* that is file-level code is missing from it even though the invocation
* relation records it: `listUsers` is called by its own test file, the
* relation says so, and the walk does not mention it. Adding those rows is
* not an invention. The relation this reads is the same relation the walk is
* built from, read directly and one hop out, so a symbol it names is a
* direct neighbour by the engine's own account. Leaving them out would tell
* a reader that nothing tests a symbol that a test calls, which is the one
* claim this product exists not to make.
*
* The enrichment stops at hop 1, deliberately and visibly. Asking the same
* questions for the whole walk would be one query per reached symbol per
* layer, which on a real repository is hundreds of round trips for a panel
* that has to feel like a tree control. Every node it touches is stamped
* `enriched` and the deeper layers are left without it, which is what lets a
* surface draw a badge only where a badge was looked up. Expanding a deeper
* node issues a walk rooted at that node, whose own first hop is enriched in
* turn, so a reader following the tree down never meets a row that could
* have carried a badge and does not.
*
* Failure is not propagated. The walk has already succeeded here, and an
* enrichment query that cannot run is a reason to show the tree without
* badges rather than to show no tree at all. Each direction is guarded on
* its own so one refusal does not cost the other its answer.
*/
protected async enrichFirstHop(
workspaceRoot: string,
project: string,
root: SymbolRef,
direction: TraceDirection,
layers: TraceNode[][]
): Promise<void> {
const qualifiedName = root.qualifiedName;
if (!qualifiedName) {
return;
}
// Driven by what the caller asked for rather than by what the walk
// returned: a direction whose walk came back empty is exactly the case
// where the relation reading has something to add.
const outgoing = direction === 'callees' || direction === 'both'
? await this.outgoingHopFacts(project, qualifiedName)
: undefined;
const incoming = direction === 'callers' || direction === 'both'
? await this.incomingHopFacts(project, qualifiedName)
: undefined;
if (outgoing === undefined && incoming === undefined) {
return;
}
const layer = layers[0] ?? [];
const seen = { callees: new Set<string>(), callers: new Set<string>() };
for (const node of layer) {
const facts = node.via === 'callees' ? outgoing : incoming;
if (facts === undefined) {
continue;
}
node.enriched = true;
const target = node.symbol.qualifiedName;
if (target === undefined) {
continue;
}
seen[node.via].add(target);
const match = facts.get(target);
if (match === undefined) {
continue;
}
if (match.isTest !== undefined) {
node.isTest = match.isTest;
}
if (match.construction !== undefined) {
node.construction = match.construction;
}
// A walk hop names no file, so the first thing that does wins. The
// guard keeps a later enrichment from overwriting a location the
// engine reported directly.
if (match.file && node.symbol.uri.length === 0) {
node.symbol.uri = fileUri(workspaceRoot, match.file);
node.symbol.range = graphRange(match.line, match.line);
}
}
const added: TraceNode[] = [
...this.missingNeighbours(workspaceRoot, project, outgoing, seen.callees, 'callees'),
...this.missingNeighbours(workspaceRoot, project, incoming, seen.callers, 'callers')
];
if (added.length === 0) {
return;
}
if (layers.length === 0) {
layers.push([]);
}
layers[0].push(...added);
}
/**
* Direct neighbours the relation records and the walk did not mention.
*
* Stamped `enriched` like every other first-hop node, because they come from
* the reading that does the stamping.
*/
protected missingNeighbours(
workspaceRoot: string,
project: string,
facts: Map<string, HopFacts> | undefined,
seen: ReadonlySet<string>,
via: 'callers' | 'callees'
): TraceNode[] {
if (facts === undefined) {
return [];
}
const out: TraceNode[] = [];
for (const [qualifiedName, entry] of facts) {
if (seen.has(qualifiedName)) {
continue;
}
out.push({
symbol: {
nodeId: stableNodeId(qualifiedName),
name: entry.name ?? qualifiedName,
qualifiedName,
kind: 'unknown',
uri: entry.file ? fileUri(workspaceRoot, entry.file) : '',
range: graphRange(entry.line, entry.line),
projectName: project
},
hop: 1,
via,
...(entry.isTest === undefined ? {} : { isTest: entry.isTest }),
...(entry.construction === undefined ? {} : { construction: entry.construction }),
enriched: true
});
}
return out;
}
/** Files and construction flags for what the root calls, or undefined when nobody could look. */
protected async outgoingHopFacts(
project: string,
qualifiedName: string
): Promise<Map<string, HopFacts> | undefined> {
try {
const rows = await this.client.queryRows(project, callsOut(qualifiedName));
const classRows = await this.client.queryRows(project, classCallTargets(qualifiedName));
const constructed = new Set(classRows.map(row => row[COLUMNS.classTargets[1]]).filter(Boolean));
const facts = new Map<string, HopFacts>();
for (const row of rows) {
const target = row[COLUMNS.callsOut[1]];
if (!target) {
continue;
}
facts.set(target, {
name: row[COLUMNS.callsOut[0]] || undefined,
file: row[COLUMNS.callsOut[2]] || undefined,
line: toOptionalNumber(row[COLUMNS.callsOut[3]]),
construction: constructed.has(target)
});
}
return facts;
} catch {
return undefined;
}
}
/** Files and test flags for what calls the root, or undefined when nobody could look. */
protected async incomingHopFacts(
project: string,
qualifiedName: string
): Promise<Map<string, HopFacts> | undefined> {
try {
const rows = await this.client.queryRows(project, callsIn(qualifiedName));
const facts = new Map<string, HopFacts>();
for (const row of rows) {
const source = row[COLUMNS.callsIn[1]];
if (!source) {
continue;
}
facts.set(source, {
name: row[COLUMNS.callsIn[0]] || undefined,
file: row[COLUMNS.callsIn[2]] || undefined,
line: toOptionalNumber(row[COLUMNS.callsIn[3]]),
isTest: toBoolean(row[COLUMNS.callsIn[4]])
});
}
return facts;
} catch {
return undefined;
}
}
/**
* The whole project, in one answer.
*
* Three readings rather than one, because the engine's summary alone would
* be a map with two blanks on it.
*
* - The summary itself: packages, layers, boundaries, clusters, the
* entry points it flagged, and the routes it recovered for the languages
* where it recovers any.
* - The hotspot sweep. The summary ranks hotspots by fan-in alone, which
* puts a trivial helper that everything calls above the one function
* with three nested loops in it. The complexity readings live on the
* nodes, so they are swept once here and ranked in a pure function.
* - The route scan, for the languages whose analysis writes no routes at
* all. See route-reader.ts for why that is a gap worth filling and for
* the rules that keep filling it honest.
*/
async architectureOverview(root: string, opts?: ProviderQueryOptions): Promise<ArchitectureOverviewDto> {
const project = await this.projectFor(root, opts);
if (!project) {
return emptyOverview();
}
const result = await this.client.getArchitecture(project);
const files = await this.indexedFilesOf(project, result);
const sweep = await this.sweepCallables(project);
return {
projectName: result.project,
totalSymbols: result.total_nodes ?? 0,
totalRelations: result.total_edges ?? 0,
symbolKinds: result.node_labels.map(entry => ({ kind: entry.label, count: entry.count ?? 0 })),
relationKinds: result.edge_types.map(entry => ({ kind: entry.type, count: entry.count ?? 0 })),
languages: result.languages.map(entry => ({ language: entry.language, fileCount: entry.file_count ?? 0 })),
groups: result.packages.map(entry => ({
name: entry.name,
symbolCount: entry.node_count ?? 0,
fanIn: entry.fan_in ?? 0,
fanOut: entry.fan_out ?? 0
})),
// The summary names an entry point and the file it lives in, and
// stops there. Without a line the product can open the file but not
// the symbol, so the declaration line is taken from the sweep that
// has already been paid for.
entryPoints: result.entry_points.map(entry => ({
name: entry.name,
qualifiedName: entry.qualified_name,
kind: 'unknown' as CodeAtlasSymbolKind,
filePath: entry.file ?? sweep.get(entry.qualified_name ?? '')?.filePath,
line: sweep.get(entry.qualified_name ?? '')?.line
})),
routes: this.routesOf(result, root, files),
clusters: result.clusters.map((entry, index) => ({
id: String(entry.id ?? index),
label: entry.label ?? '',
memberCount: entry.members ?? entry.top_nodes.length,
cohesion: entry.cohesion,
topMembers: entry.top_nodes
})),
layers: result.layers
.filter(entry => (entry.layer ?? '').length > 0)
.map(entry => ({
group: entry.name ?? '',
layer: entry.layer ?? '',
reason: entry.reason
})),
boundaries: result.boundaries
.filter(entry => (entry.from ?? '').length > 0 && (entry.to ?? '').length > 0)
.map(entry => ({ from: entry.from!, to: entry.to!, callCount: entry.call_count ?? 0 })),
hotspots: this.hotspotsOf(result, sweep),
files
};
}
/**
* Which file depends on which, in one sweep.
*
* The engine writes an import edge from the importing module to the imported
* file, and both ends carry `file_path`, so a file-level dependency graph is
* one query and no per-node lookups. Rows that name a file at either end the
* index has no path for are dropped rather than carried as an empty string:
* an edge to nowhere would make a file look like it depends on the project
* root.
*
* A refused query answers with an empty graph rather than throwing, for the
* same reason the route scan swallows an unreadable file: the caller is
* building an onboarding artefact, and a language whose analysis records no
* imports must produce a shorter answer rather than an error page. The
* emptiness is not a claim, and {@link ModuleDependencyGraph} says so.
*/
async moduleDependencies(root: string, opts?: ProviderQueryOptions): Promise<ModuleDependencyGraph> {
const project = await this.projectFor(root, opts);
if (!project) {
return { edges: [], truncated: false };
}
let rows: Record<string, string>[];
try {
rows = await this.client.queryRows(project, importEdges());
} catch (error) {
if (error instanceof EngineError || error instanceof EngineUnavailableError) {
return { edges: [], truncated: false };
}
throw error;
}
const edges: ModuleDependency[] = [];
for (const row of rows) {
const from = row[COLUMNS.imports[0]];
const to = row[COLUMNS.imports[1]];
if (!from || !to) {
continue;
}
edges.push({ from, to });
}
return { edges, truncated: rows.length >= IMPORT_EDGE_LIMIT };
}
/**
* The files the index holds, workspace-relative and in a stable order.
*
* Read from the file nodes rather than from the summary's file tree. The
* tree is shallow: on the Java project it names six configuration files and
* none of the hundred and thirty sources, so a route scan driven by it
* would report "no routes found" after opening nothing. The tree is still
* the fallback for an engine that answers the listing with a refusal.
*/
protected async indexedFilesOf(
project: string,
result: { file_tree: { path: string; type?: string }[] }
): Promise<string[]> {
try {
const rows = await this.client.queryRows(project, indexedFiles());
const paths = rows
.map(row => row[COLUMNS.files[0]])
.filter(path => typeof path === 'string' && path.length > 0);
if (paths.length > 0) {
return [...new Set(paths)].sort();
}
} catch (error) {
if (!(error instanceof EngineError)) {
throw error;
}
}
return result.file_tree
.filter(entry => entry.type !== 'dir' && entry.path.length > 0)
.map(entry => entry.path)
.sort();
}
/**
* Routes the index reported, plus the ones only the source knows about.
*
* Merged rather than chosen between: a Java project gets paths from the
* index that carry no file, and a TypeScript project gets nothing at all
* from the index. Deduplication is on method and path, and the source scan
* wins a tie because it is the reading that knows where the registration is
* written, which is what a reader clicks on.
*/
protected routesOf(
result: { routes: { method?: string; path?: string; handler?: string; file?: string; file_path?: string; line?: number }[] },
root: string,
files: string[]
): RouteRef[] {
const scanned = this.scanRoutes(root, files);
const seen = new Set(scanned.map(route => `${route.method ?? ''} ${route.path}`));
const fromIndex: RouteRef[] = [];
for (const entry of result.routes) {
const path = entry.path ?? '';
if (path.length === 0 || seen.has(`${entry.method ?? ''} ${path}`)) {
continue;
}
seen.add(`${entry.method ?? ''} ${path}`);
fromIndex.push({
method: entry.method || undefined,
path,
filePath: entry.file_path || entry.file || undefined,
line: entry.line,
handler: entry.handler || undefined,
origin: 'index'
});
}
return [...scanned, ...fromIndex].slice(0, MAX_ROUTES);
}
/**
* Read the workspace's own files looking for route registrations.
*
* Bounded by the number of files, because this runs on the caret's path for
* a workspace of any size and a generated bundle is not a file anybody
* registers a route in. A file that cannot be read is skipped in silence:
* the index listed it, so its absence is a race with the user's editor and
* not a finding.
*
* With no reader injected there is no scan, and that is the browser's
* ordinary state: nothing there can open a workspace file. The result is an
* honest shortfall rather than a wrong answer, and `ProviderCapabilities`
* is where a surface reads that a route list can be incomplete.
*/
protected scanRoutes(root: string, files: string[]): RouteRef[] {
const read = this.options.readSource;
if (read === undefined) {
return [];
}
const out: RouteRef[] = [];
let scanned = 0;
for (const filePath of files) {
if (scanned >= MAX_ROUTE_SCAN_FILES || out.length >= MAX_ROUTES) {
break;
}
if (!isRouteSource(filePath)) {
continue;
}
scanned += 1;
const source = read(joinPath(root, filePath));
if (source === undefined) {
continue;
}
for (const route of readRoutes(source, filePath)) {
out.push({ ...route, filePath, origin: 'source' });
}
}
return out;
}
/**
* The symbols worth reading first, with the readings that say so.
*
* The engine's own hotspot list carries one signal, fan-in, and it is a
* real one: a function twenty other symbols reach is worth knowing about.
* It is not the only one, and on a small project it is the weakest: the
* fixture's most expensive function is called by nothing and would never
* appear. So both are read, the complexity signals decide the order, and
* fan-in is folded in as one more signal on the symbols that have it.
*/
/**
* Every callable the index holds, with its declaration line and its
* complexity readings, keyed by qualified name.
*
* One sweep serving two answers. The readings are what makes the hotspot
* list something other than a fan-in ranking, and the declaration lines are
* what lets an entry point be opened at the symbol rather than at the top
* of its file. Both are on the same rows, so asking twice would be paying
* twice for one traversal.
*/
protected async sweepCallables(project: string): Promise<Map<string, ArchitectureHotspot>> {
const readings = new Map<string, ArchitectureHotspot>();
for (const label of CALLABLE_LABELS) {
let rows: Record<string, string>[];
try {
rows = await this.client.queryRows(project, hotspotCandidates(label));
} catch (error) {
if (!(error instanceof EngineError)) {
throw error;
}
// A label the index does not hold is not a reason to lose the
// other: a project with no methods at all is ordinary.
continue;
}
for (const row of rows) {
const qualifiedName = row[COLUMNS.hotspots[1]] || undefined;
const key = qualifiedName ?? row[COLUMNS.hotspots[0]];
if (key.length === 0 || readings.has(key)) {
continue;
}
readings.set(key, {
name: row[COLUMNS.hotspots[0]] ?? '',
qualifiedName,
filePath: row[COLUMNS.hotspots[2]] || undefined,
line: toOptionalNumber(row[COLUMNS.hotspots[3]]),
complexity: toOptionalNumber(row[COLUMNS.hotspots[4]]),
cognitive: toOptionalNumber(row[COLUMNS.hotspots[5]]),
loopDepth: toOptionalNumber(row[COLUMNS.hotspots[6]]),
// Counts, not flags: the index writes how many allocations
// and scans sit inside a loop, and one is already a finding.
allocationInLoop: (toOptionalNumber(row[COLUMNS.hotspots[7]]) ?? 0) > 0,
scanInLoop: (toOptionalNumber(row[COLUMNS.hotspots[8]]) ?? 0) > 0,
unguardedRecursion: toBoolean(row[COLUMNS.hotspots[9]])
});
}
}
return readings;
}
protected hotspotsOf(
result: { hotspots: { name: string; qualified_name?: string; file_path?: string; fan_in?: number }[] },
sweep: Map<string, ArchitectureHotspot>
): ArchitectureHotspot[] {
const candidates = new Map<string, ArchitectureHotspot>(sweep);
for (const entry of result.hotspots) {
const key = entry.qualified_name ?? entry.name;
const known = candidates.get(key);
candidates.set(key, {
// Whatever the summary ranked and the sweep did not reach still
// belongs on the map: dropping it would lose a finding to a row
// limit rather than to a reading.
...(known ?? {
name: entry.name,
qualifiedName: entry.qualified_name,
filePath: entry.file_path
}),
fanIn: entry.fan_in
});
}
return rankHotspots([...candidates.values()]).slice(0, MAX_HOTSPOTS);
}
/**
* What a change reaches, in three readings rather than one.
*
* The change tool alone is not an impact assessment, and pretending it is
* was the single largest gap between what this method used to return and
* what a reader needs. Measured against the real 0.9.0 answer:
*
* - It names the symbols that sit **inside** the changed files and nothing
* further out. Asking for `depth: 3` returns the same rows as asking for
* nothing, so the "downstream" half of the question is not answered at
* all. That walk is done here, one query per step, against the same
* invocation relation the twin and the navigator read.
* - It names those symbols by display name and file only: no qualified
* name, no line. So they cannot be opened, cannot be asked a follow-up
* question about, and cannot be told apart from a same-named symbol in
* another file. The identities are recovered from the index.
* - It repeats both lists once per repeated changed file.
*
* The server of PR 1860 answers the other way round, and the difference is
* decided per row by the `hop` column: `impacted` holds the transitive
* CALLERS of the changed declarations, each with its distance, and the
* changed declarations themselves are reported only as a number
* (`seed_symbols`), scoped to the changed hunks. So a row with a step is
* read as a caller at that step and the walk below is left to the server,
* and the changed symbols are recovered from the index. Which of the two
* answers arrived is never assumed; it is read off the row.
*
* That recovery is the one thing the 0.9.0 reading deliberately refused,
* and it is refused here too wherever the tool did name declarations: an
* empty symbol list from a non-empty file list is a finding, and it means
* the index does not hold those files. It is only done when the tool names
* a *count* and no names, because then the index is the only place those
* names exist and answering "no changed symbol" would report a gap in the
* answer as a fact about the change. What comes back is then exactly "every
* symbol the index places inside a changed file", which is what
* `changeKind: 'declared'` has always meant, and never "every symbol that
* changed": the seed count travels with it so a surface can say both.
*/
async changeImpact(root: string, sinceRef?: string, opts?: ProviderQueryOptions): Promise<ChangeImpactDto> {
const project = await this.projectFor(root, opts);
if (!project) {
return { baselineRef: sinceRef, changedFiles: [], impacted: [], symbols: [] };
}
const result = await this.client.detectChanges(project, sinceRef, { depth: IMPACT_WALK_DISTANCE });
const changedFiles = [...new Set(result.changed_files.filter(path => path.length > 0 && !isCodeAtlasState(path)))]
.sort();
const reported = dedupeDetected(result.impacted_symbols)
.filter(entry => !isCodeAtlasState(entry.file ?? entry.file_path ?? ''));
/*
* Two readings of `impacted`, decided by the `hop` column.
*
* Measured against the built server of PR 1860: `impacted` holds the
* transitive CALLERS of the changed declarations, each with the step at
* which it was reached, and the changed declarations themselves are not
* in the list at all (only their number, as `seed_symbols`). The 0.9.0
* tool this provider was written against reported the other thing: the
* symbols inside the changed files, with no distance. Both answers
* arrive under one key, and the column is what tells them apart.
*
* So a row that names a step is a caller at that step, and a row that
* names none is read the way 0.9.0 meant it. Reading the new answer the
* old way would print a route handler under the heading "changed
* symbols", which is a claim about somebody's diff that their diff does
* not make.
*/
const callerRows = reported.filter(entry => (entry.hop ?? 0) >= 1);
const declaredRows = reported.filter(entry => (entry.hop ?? 0) < 1);
// The files to look declarations up in. Every changed file when the
// tool named no declaration of its own, because then the index is the
// only place their names are; otherwise the files it did name, which is
// the reading 0.9.0 needed to recover identities.
const reportedFiles = [...new Set([
...declaredRows.map(entry => entry.file ?? entry.file_path ?? ''),
...callerRows.map(entry => entry.file ?? entry.file_path ?? ''),
...(declaredRows.length === 0 ? changedFiles : []),
])]
.filter(path => path.length > 0)
.slice(0, MAX_CHANGED_FILES_READ);
const declarations = await this.declarationsOf(project, reportedFiles);
/*
* The changed symbols, when the tool named none.
*
* This is the sweep the 0.9.0 reading deliberately refused, and the
* refusal's reason no longer holds: there it meant "the index does not
* hold those files", because the tool would have named the symbols if
* it could. Here the tool names their number and never their names, so
* the index is the only place they exist, and answering "no changed
* symbol" would be reporting a gap in the answer as a fact about the
* change.
*
* What this list is, exactly: every symbol the index places inside a
* changed file. It is NOT "every symbol that changed" and nothing in
* the product says it is; the tool scoped its own seeds to the changed
* hunks and reports how many, which is why {@link ChangeImpactDto.seedSymbols}
* is carried alongside for a surface to say so.
*/
const declared: ChangeImpactSymbol[] = declaredRows.length > 0
? declaredRows.map(entry => this.directSymbol(entry, declarations))
: declarationsIn(changedFiles, declarations);
const symbols: ChangeImpactSymbol[] = [...declared];
const seen = new Set(symbols.map(symbol => symbol.qualifiedName ?? '').filter(name => name.length > 0));
let reportedDistance = 0;
for (const entry of callerRows) {
const symbol = this.callerSymbol(entry, declarations);
if (symbol.qualifiedName !== undefined && seen.has(symbol.qualifiedName)) {
continue;
}
if (symbol.qualifiedName !== undefined) {
seen.add(symbol.qualifiedName);
}
reportedDistance = Math.max(reportedDistance, symbol.distance);
symbols.push(symbol);
}
/*
* The provider's own caller walk runs only when the tool did none.
*
* With the hop column present the server has already walked, and
* walking again from a frontier that holds symbols at step two would
* label their callers "one step out". One walk or the other, never
* both halves of two.
*/
const walk = callerRows.length > 0
? { symbols: [] as ChangeImpactSymbol[], distance: reportedDistance, truncated: result.truncated === true }
: await this.walkCallers(project, symbols);
symbols.push(...walk.symbols);
return {
baselineRef: sinceRef,
changedFiles,
depth: result.depth,
symbols,
seedSymbols: result.seed_symbols,
walkedDistance: Math.max(reportedDistance, walk.distance),
truncated: walk.truncated,
impacted: symbols.map(symbol => ({
name: symbol.name,
qualifiedName: symbol.qualifiedName,
kind: symbol.kind,
filePath: symbol.filePath,
line: symbol.line,
isTest: symbol.isTest
})),
raw: result as unknown as Record<string, unknown>
};
}
/**
* One reported symbol, with whatever identity the index can give it back.
*
* A row the index cannot match is kept rather than dropped. The engine
* looked at the diff and said this symbol is in it; that is a finding, and
* losing it because a follow-up lookup came back empty would report fewer
* changes than were found. What such a row loses is everything that needs a
* qualified name: it cannot be walked from and it cannot be measured, and
* both of those absences are visible to the caller.
*/
/**
* One reported caller, at the step the tool reached it.
*
* The same identity recovery as {@link directSymbol} and one different
* claim: this symbol was not changed, it calls something that was. The
* distance is the tool's own, never recomputed, because the tool is the one
* that walked.
*/
protected callerSymbol(entry: DetectedSymbol, declarations: Map<string, DeclarationRow>): ChangeImpactSymbol {
const direct = this.directSymbol(entry, declarations);
return { ...direct, changeKind: 'caller', distance: Math.max(1, entry.hop ?? 1) };
}
protected directSymbol(entry: DetectedSymbol, declarations: Map<string, DeclarationRow>): ChangeImpactSymbol {
const filePath = entry.file || entry.file_path || undefined;
const name = entry.name ?? entry.qualified_name ?? '';
const isModule = (entry.label ?? '').toLowerCase() === 'module' || name === filePath;
const match = isModule ? undefined : declarations.get(declarationKey(filePath, name));
return {
name,
qualifiedName: entry.qualified_name || match?.qualifiedName,
filePath,
line: match?.line,
kind: symbolKindOf(entry.label),
changeKind: isModule ? 'module' : 'declared',
distance: 0,
...(match?.isTest === undefined ? {} : { isTest: match.isTest })
};
}
/**
* Every symbol declared in one of a set of files, keyed by file and name.
*
* Two queries for any number of files: one per callable label, each with a
* disjunction over the paths. A label the index does not hold is skipped in
* silence, exactly as the hotspot sweep skips it, because a project with no
* methods is ordinary rather than broken.
*/
protected async declarationsOf(project: string, filePaths: string[]): Promise<Map<string, DeclarationRow>> {
const rows = new Map<string, DeclarationRow>();
if (filePaths.length === 0) {
return rows;
}
for (const label of CALLABLE_LABELS) {
const query = declarationsInFiles(label, filePaths);
if (query === undefined) {
continue;
}
let answered: Record<string, string>[];
try {
answered = await this.client.queryRows(project, query);
} catch (error) {
if (!(error instanceof EngineError)) {
throw error;
}
continue;
}
for (const row of answered) {
const name = row[COLUMNS.declarations[0]] ?? '';
const filePath = row[COLUMNS.declarations[2]] || undefined;
const key = declarationKey(filePath, name);
if (name.length === 0 || rows.has(key)) {
continue;
}
rows.set(key, {
qualifiedName: row[COLUMNS.declarations[1]] || undefined,
line: toOptionalNumber(row[COLUMNS.declarations[3]]),
isTest: toBoolean(row[COLUMNS.declarations[5]])
});
}
}
return rows;
}
/**
* The callers of a change set, level by level.
*
* Breadth first and one query per level, never one per symbol: the set at
* step two is the set at step one's neighbours, and asking the relation for
* a whole level at once is the same traversal the engine would do anyway.
* The walk stops at {@link IMPACT_WALK_DISTANCE}, at
* {@link MAX_IMPACT_SYMBOLS}, or when a level reaches nothing new, and it
* says which of the first two happened so a surface can tell a complete
* answer from a bounded one.
*
* A refused query ends the walk without ending the call. The direct half of
* the answer is already correct at that point, and a panel that showed
* nothing because the second reading failed would be hiding the first.
*/
protected async walkCallers(
project: string,
direct: ChangeImpactSymbol[]
): Promise<{ symbols: ChangeImpactSymbol[]; distance: number; truncated: boolean }> {
const seen = new Set<string>();
for (const symbol of direct) {
if (symbol.qualifiedName) {
seen.add(symbol.qualifiedName);
}
}
const symbols: ChangeImpactSymbol[] = [];
let frontier = [...seen];
let distance = 0;
let truncated = false;
for (let step = 1; step <= IMPACT_WALK_DISTANCE && frontier.length > 0 && !truncated; step++) {
const query = callersOfAny(frontier);
if (query === undefined) {
break;
}
let rows: Record<string, string>[];
try {
rows = await this.client.queryRows(project, query);
} catch (error) {
if (!(error instanceof EngineError) && !(error instanceof EngineUnavailableError)) {
throw error;
}
break;
}
const next: string[] = [];
for (const row of rows) {
const qualifiedName = row[COLUMNS.callsIn[1]];
if (!qualifiedName || seen.has(qualifiedName)) {
continue;
}
if (symbols.length >= MAX_IMPACT_SYMBOLS) {
truncated = true;
break;
}
seen.add(qualifiedName);
next.push(qualifiedName);
symbols.push({
name: row[COLUMNS.callsIn[0]] || qualifiedName,
qualifiedName,
filePath: row[COLUMNS.callsIn[2]] || undefined,
line: toOptionalNumber(row[COLUMNS.callsIn[3]]),
kind: symbolKindOf(inferLabelFromRow(row)),
changeKind: 'caller',
distance: step,
isTest: toBoolean(row[COLUMNS.callsIn[4]])
});
}
distance = step;
// A level that reached nothing new is the end of the graph, not a
// bound, so the truncation flag stays where it is.
frontier = next;
}
return { symbols, distance, truncated: truncated || frontier.length > 0 };
}
/**
* The complexity readings of a named set of symbols.
*
* One query per label per batch, over the same columns the hotspot sweep
* reads. Reusing those columns is the point: the map's "read these first"
* list and an impact assessment's risk chips must never disagree about the
* same function, and the only way to guarantee that is for both to be the
* same reading of the same properties.
*/
async getComplexity(
root: string,
qualifiedNames: string[],
opts?: ProviderQueryOptions
): Promise<SymbolComplexity[]> {
const wanted = [...new Set(qualifiedNames.filter(name => name.length > 0))];
if (wanted.length === 0) {
return [];
}
const project = await this.projectFor(root, opts);
if (!project) {
return [];
}
const readings = new Map<string, SymbolComplexity>();
for (let at = 0; at < wanted.length; at += COMPLEXITY_BATCH_LIMIT) {
const batch = wanted.slice(at, at + COMPLEXITY_BATCH_LIMIT);
for (const label of CALLABLE_LABELS) {
const query = complexityOf(label, batch);
if (query === undefined) {
continue;
}
let rows: Record<string, string>[];
try {
rows = await this.client.queryRows(project, query);
} catch (error) {
if (!(error instanceof EngineError)) {
throw error;
}
continue;
}
for (const row of rows) {
const qualifiedName = row[COLUMNS.hotspots[1]] || undefined;
if (!qualifiedName || readings.has(qualifiedName)) {
continue;
}
readings.set(qualifiedName, {
name: row[COLUMNS.hotspots[0]] ?? '',
qualifiedName,
filePath: row[COLUMNS.hotspots[2]] || undefined,
line: toOptionalNumber(row[COLUMNS.hotspots[3]]),
complexity: toOptionalNumber(row[COLUMNS.hotspots[4]]),
cognitive: toOptionalNumber(row[COLUMNS.hotspots[5]]),
loopDepth: toOptionalNumber(row[COLUMNS.hotspots[6]]),
allocationInLoop: (toOptionalNumber(row[COLUMNS.hotspots[7]]) ?? 0) > 0,
scanInLoop: (toOptionalNumber(row[COLUMNS.hotspots[8]]) ?? 0) > 0,
unguardedRecursion: toBoolean(row[COLUMNS.hotspots[9]])
});
}
}
}
// Answered in the order asked, so a caller zipping the answer against
// its request does not have to sort first.
return wanted.map(name => readings.get(name)).filter((entry): entry is SymbolComplexity => entry !== undefined);
}
/**
* Symbole suchen.
*
* `signal` ist die eine Zutat, die seit W7b ueber den Protokolltyp
* hinausgeht, und sie steht hier statt in ProviderQueryOptions, weil sie
* nur diese eine Methode betrifft: die Suche ist der einzige Aufruf, den
* ein Tastendruck ueberholt, bevor er beantwortet ist. Wer sie nicht
* mitgibt, bekommt das Verhalten von vorher.
*/
async searchFile(root: string, path: string, opts?: ProviderQueryOptions & { signal?: AbortSignal }): Promise<SymbolSearchHit | undefined> {
if (opts?.signal?.aborted) return undefined;
const project = await this.projectFor(root, opts);
if (!project || opts?.signal?.aborted) return undefined;
const rows = await this.client.queryRows(project, fileExists(path));
if (opts?.signal?.aborted) return undefined;
const row = rows.find(row => row[COLUMNS.fileExists[1]] === path);
return row ? { name: path.split('/').at(-1) ?? path, kind: 'unknown', filePath: path } : undefined;
}
async searchSymbols(
root: string,
pattern: string,
limit?: number,
opts?: ProviderQueryOptions & { signal?: AbortSignal }
): Promise<SymbolSearchHit[]> {
const project = await this.projectFor(root, opts);
if (!project) {
return [];
}
const result = await this.client.searchGraph(project, {
namePattern: pattern,
limit,
...(opts?.signal === undefined ? {} : { signal: opts.signal })
});
return result.results.map(hit => ({
name: hit.name,
qualifiedName: hit.qualified_name,
kind: symbolKindOf(hit.label),
filePath: hit.file_path,
line: hit.start_line,
isTest: hit.is_test,
isExported: hit.is_exported
}));
}
/**
* Where the index says one named symbol is declared.
*
* Reuses the declaration read the change assessment already makes, over a
* single file: one query per callable label, both of them a lookup on
* `file_path`. Nothing is cached, for the reason nothing else here is
* either: the answer moves when the index moves, and the caller asking it is
* about to open the file.
*/
async declarationLineOf(
root: string,
filePath: string,
name: string,
opts?: ProviderQueryOptions
): Promise<number | undefined> {
const project = await this.projectFor(root, opts);
if (!project || filePath.length === 0 || name.length === 0) {
return undefined;
}
const rows = await this.declarationsOf(project, [filePath]);
return rows.get(declarationKey(filePath, name))?.line;
}
async getSnippet(root: string, qualifiedName: string, opts?: ProviderQueryOptions): Promise<string> {
const project = await this.projectFor(root, opts);
if (!project) {
return '';
}
const result = await this.client.getCodeSnippet(project, qualifiedName);
return result.source;
}
/**
* Hand observed calls to the analysis backend, and say what it did.
*
* Deliberately not on the `IntelligenceProvider` interface. That interface
* is the anti lock-in boundary and every optional ability on it is declared
* in `capabilities()`; this one is declared false there, because the 0.9.0
* engine builds nothing from what it accepts. Putting the handoff on the
* interface anyway would invite a second provider to implement a method
* whose result no surface may read.
*
* On this surface the handoff cannot be made at all: `ingest_traces` is one
* of the three tools the read-only allowlist refuses. The attempt is still
* made rather than skipped, so the sentence the reader gets names what the
* server said instead of a guess this method made about it, and so the day
* the allowlist grows the tool nothing here has to change.
*/
async ingestRuntimeTraces(
root: string,
_events: readonly unknown[],
opts?: ProviderQueryOptions
): Promise<string> {
const project = await this.projectFor(root, opts).catch(() => undefined);
if (!project) {
return 'the analysis backend has no project for this workspace yet, so the events were kept locally only.';
}
try {
await this.client.ingestTraces();
return 'the analysis backend accepted the events.';
} catch (error) {
return `the analysis backend did not take the events: ${String(error)}`;
}
}
/** Drop everything the provider holds about a workspace. Also not on /rpc. */
async deleteProject(_root: string, _opts?: ProviderQueryOptions): Promise<void> {
return this.client.deleteProject();
}
// Fact builders -------------------------------------------------------
protected async calleesFact(
project: string | undefined,
qualifiedName: string | undefined,
engineAvailable: boolean,
indexed: boolean
): Promise<Fact<CallSite[]>> {
if (!engineAvailable || !indexed) {
return emptyFact<CallSite>(knowledgeStateFor({ engineAvailable, indexed, supported: true, derived: false }));
}
const rows = await this.client.queryRows(project!, callsOut(qualifiedName!));
const classRows = await this.client.queryRows(project!, classCallTargets(qualifiedName!));
const constructed = new Set(classRows.map(row => row[COLUMNS.classTargets[1]]).filter(Boolean));
const value: CallSite[] = [];
const evidence: Evidence[] = [];
for (const row of rows) {
const targetQualifiedName = row[COLUMNS.callsOut[1]] || undefined;
const targetFile = row[COLUMNS.callsOut[2]] || undefined;
const line = toOptionalNumber(row[COLUMNS.callsOut[4]]);
value.push({
targetName: row[COLUMNS.callsOut[0]] ?? '',
targetQualifiedName,
targetFile,
line,
// Where the target is declared, which is where following this
// call leads. The call site line above is in the caller's file
// and means nothing inside `targetFile`.
targetLine: toOptionalNumber(row[COLUMNS.callsOut[3]]),
strategy: targetQualifiedName && constructed.has(targetQualifiedName)
? STRATEGIES.construction
: STRATEGIES.directCall
});
evidence.push(this.evidence(EVIDENCE_RELATIONS.invocation, targetFile, line));
}
return { value, state: 'known', evidence };
}
protected callersFact(
rows: Record<string, string>[],
engineAvailable: boolean,
usable: boolean
): Fact<CallerRef[]> {
if (!engineAvailable || !usable) {
return emptyFact<CallerRef>(knowledgeStateFor({ engineAvailable, indexed: usable, supported: true, derived: false }));
}
const value: CallerRef[] = [];
const evidence: Evidence[] = [];
for (const row of rows) {
const file = row[COLUMNS.callsIn[2]] || undefined;
const line = toOptionalNumber(row[COLUMNS.callsIn[5]]);
value.push({
name: row[COLUMNS.callsIn[0]] ?? '',
qualifiedName: row[COLUMNS.callsIn[1]] || undefined,
file,
line,
isTest: toBoolean(row[COLUMNS.callsIn[4]]),
sourceKind: sourceKindOf(inferLabelFromRow(row))
});
evidence.push(this.evidence(EVIDENCE_RELATIONS.invocation, file, line));
}
return { value, state: 'known', evidence };
}
/**
* Tests are inferred, never read. The engine flags nodes that live in test
* files; an invocation from such a node is the best available signal that
* the callee is exercised by a test. The state stays `inferred` even when
* the list is empty, because a heuristic that finds nothing has not proved
* an absence.
*/
protected testedByFact(
rows: Record<string, string>[],
engineAvailable: boolean,
usable: boolean
): Fact<TestRef[]> {
const state = knowledgeStateFor({ engineAvailable, indexed: usable, supported: true, derived: true });
if (!engineAvailable || !usable) {
return emptyFact<TestRef>(state);
}
const value: TestRef[] = [];
const evidence: Evidence[] = [];
for (const row of rows) {
if (!toBoolean(row[COLUMNS.callsIn[4]])) {
continue;
}
const file = row[COLUMNS.callsIn[2]] || undefined;
const line = toOptionalNumber(row[COLUMNS.callsIn[5]]);
value.push({
name: row[COLUMNS.callsIn[0]] ?? '',
file,
line,
kind: 'unit'
});
evidence.push({
...this.evidence(EVIDENCE_RELATIONS.invocation, file, line),
source: 'test',
strategy: STRATEGIES.testCaller
});
}
return { value, state, evidence };
}
/**
* The error types one symbol can produce, read from both error relations.
*
* Two queries and one answer. The engine names the same product fact twice:
* `RAISES` for a `throw` statement in TypeScript, JavaScript and Python,
* `THROWS` for a Java `throws` clause. Reading only the first made every
* Java method answer "I looked and found nothing" next to a signature that
* names the exception, which is the worst failure this product has: a
* confident empty list.
*
* The two result sets are merged and deduplicated on the type, file and
* line, because a symbol that both declares and raises the same exception
* produces one fact, not two. The evidence keeps them apart: the reader can
* still see which relation carried the finding.
*/
protected async throwsFact(
project: string | undefined,
qualifiedName: string | undefined,
engineAvailable: boolean,
indexed: boolean,
symbol: SymbolRef
): Promise<Fact<ThrowRef[]>> {
if (!engineAvailable || !indexed) {
return emptyFact<ThrowRef>(knowledgeStateFor({ engineAvailable, indexed, supported: true, derived: false }));
}
const sources: [string, string][] = [
[EVIDENCE_RELATIONS.raise, raises(qualifiedName!)],
[EVIDENCE_RELATIONS.throwDeclaration, throwsRelation(qualifiedName!)]
];
const value: ThrowRef[] = [];
const evidence: Evidence[] = [];
const seen = new Set<string>();
for (const [relation, query] of sources) {
const rows = await this.client.queryRows(project!, query);
for (const row of rows) {
// Neither relation records the site line at 0.9.0, so the
// declaration line of the symbol is the honest fallback.
const file = row[COLUMNS.raises[1]] || undefined;
const line = toOptionalNumber(row[COLUMNS.raises[3]]) ?? symbol.range.start.line + 1;
const type = row[COLUMNS.raises[0]] ?? '';
const key = `${type}|${file ?? ''}|${line}`;
if (seen.has(key)) {
continue;
}
seen.add(key);
value.push({ type, file, line });
evidence.push(this.evidence(relation, file, toOptionalNumber(row[COLUMNS.raises[2]])));
}
}
return { value, state: 'known', evidence };
}
protected async envReadsFact(
project: string | undefined,
qualifiedName: string | undefined,
engineAvailable: boolean,
indexed: boolean,
symbol: SymbolRef
): Promise<Fact<DataRef[]>> {
if (!engineAvailable || !indexed) {
return emptyFact<DataRef>(knowledgeStateFor({ engineAvailable, indexed, supported: true, derived: false }));
}
const rows = await this.client.queryRows(project!, envReads(qualifiedName!));
const value: DataRef[] = [];
const evidence: Evidence[] = [];
for (const row of rows) {
const name = row[COLUMNS.envReads[1]] || row[COLUMNS.envReads[0]] || '';
const file = row[COLUMNS.envReads[2]] || fileFromUri(symbol.uri);
const line = toOptionalNumber(row[COLUMNS.envReads[3]]);
value.push({ name, kind: 'global', file, line });
evidence.push(this.evidence(EVIDENCE_RELATIONS.environmentRead, file, line));
}
return { value, state: 'known', evidence };
}
protected async typeRefsFact(
project: string | undefined,
qualifiedName: string | undefined,
engineAvailable: boolean,
indexed: boolean
): Promise<Fact<DataRef[]>> {
if (!engineAvailable || !indexed) {
return emptyFact<DataRef>(knowledgeStateFor({ engineAvailable, indexed, supported: true, derived: false }));
}
const rows = await this.client.queryRows(project!, typeRefs(qualifiedName!));
const value: DataRef[] = [];
const evidence: Evidence[] = [];
for (const row of rows) {
const file = row[COLUMNS.typeRefs[2]] || undefined;
const line = toOptionalNumber(row[COLUMNS.typeRefs[4]]) ?? toOptionalNumber(row[COLUMNS.typeRefs[3]]);
value.push({
name: row[COLUMNS.typeRefs[0]] ?? '',
kind: 'unknown',
qualifiedName: row[COLUMNS.typeRefs[1]] || undefined,
file,
line
});
evidence.push(this.evidence(EVIDENCE_RELATIONS.typeReference, file, line));
}
return { value, state: 'known', evidence };
}
// Plumbing ------------------------------------------------------------
protected evidence(relation: string, file: string | undefined, line: number | undefined): Evidence {
return {
source: 'graph-edge',
relation,
file,
range: line !== undefined ? { startLine: line, endLine: line } : undefined,
engineGeneration: this.generation(),
providerId: this.id
};
}
protected generation(): number {
return this.options.generation ?? 0;
}
/**
* Engine project name for a workspace root.
*
* Until the pinning file lands, an explicit name wins and otherwise the
* project list is matched on root path. A workspace the engine has never
* seen resolves to undefined, which every caller reads as "not indexed".
*/
protected async projectFor(root: string, opts?: ProviderQueryOptions): Promise<string | undefined> {
if (opts?.projectName) {
return opts.projectName;
}
const key = normalizeRoot(root);
const cached = this.projectNames.get(key);
if (cached) {
return cached;
}
let listed;
try {
listed = await this.client.listProjects();
} catch (error) {
if (error instanceof EngineError) {
return undefined;
}
throw error;
}
const match = listed.projects.find(entry => entry.root_path && normalizeRoot(entry.root_path) === key);
if (match) {
this.projectNames.set(key, match.name);
return match.name;
}
return undefined;
}
}
function normalizeRoot(root: string): string {
return root.replace(/\/+$/, '');
}
/**
* Workspace root and a workspace-relative path, joined.
*
* `node:path` would be one import away and is the one import this file may not
* have: everything here runs in a browser. The join is the whole of what was
* used, and a POSIX-shaped one is correct for what it joins, since the paths
* come from the index and the index writes them with forward slashes.
*/
function joinPath(root: string, relativePath: string): string {
return `${normalizeRoot(root)}/${relativePath.replace(/^\/+/, '')}`;
}
function fileFromUri(uri: string): string | undefined {
return uri.length > 0 ? uri : undefined;
}
/**
* The engine returns rows, not labels, for incoming invocations. A source
* whose qualified name ends in the file marker is module level code, which is
* where test runners register their cases; anything else is left unclassified
* rather than guessed.
*/
function inferLabelFromRow(row: Record<string, string>): string | undefined {
const qualifiedName = row[COLUMNS.callsIn[1]] ?? '';
const name = row[COLUMNS.callsIn[0]] ?? '';
if (qualifiedName.endsWith('.__file__') || name.includes('/')) {
return 'module';
}
return undefined;
}
function emptyFact<T>(state: KnowledgeState): Fact<T[]> {
return { value: [], state, evidence: [] };
}
/**
* Rewrite the generation on every piece of evidence in a fact bundle.
*
* Exported because it is the whole of the per-call generation contract and a
* table test is a better proof of it than a mock provider would be. Pure: the
* input bundle is never mutated, so a cached bundle cannot be re-stamped by
* accident.
*/
export function stampGeneration(facts: SymbolFacts, generation: number): SymbolFacts {
const stampFact = <T>(fact: Fact<T> | undefined): Fact<T> | undefined => fact === undefined
? undefined
: { ...fact, evidence: fact.evidence.map(entry => ({ ...entry, engineGeneration: generation })) };
const stamped: SymbolFacts = {};
for (const key of Object.keys(facts) as (keyof SymbolFacts)[]) {
const fact = stampFact(facts[key] as Fact<unknown> | undefined);
if (fact !== undefined) {
// The index signature of SymbolFacts is per-family typed; the cast
// is safe because stampFact only replaces the evidence array.
(stamped as Record<string, unknown>)[key] = fact;
}
}
return stamped;
}
function indexStateOf(status: string | undefined): IndexState {
switch (status) {
case 'indexed':
case 'ready':
return 'ready';
case 'indexing':
return 'indexing';
case 'stale':
return 'stale';
case 'failed':
case 'error':
return 'failed';
default:
return 'absent';
}
}
function emptyOverview(): ArchitectureOverviewDto {
return {
totalSymbols: 0,
totalRelations: 0,
symbolKinds: [],
relationKinds: [],
languages: [],
groups: [],
entryPoints: [],
routes: [],
clusters: [],
layers: [],
boundaries: [],
hotspots: [],
files: []
};
}
/**
* How urgently one symbol asks to be read first.
*
* The weights are a reading order and never a verdict. Nesting counts for more
* than raw complexity because depth is what turns a loop into a cost that
* follows the data size; recursion with no visible base case counts for most
* because it is the one signal here that describes a defect rather than an
* expense. Fan-in is folded in last and lightly: something everything calls is
* worth knowing about, but a two-line helper reached forty times is not the
* function anyone needs to read first.
*
* Exported so the weights can be read and argued with in one place instead of
* being inferred from a rendered list.
*/
export function hotspotScore(hotspot: ArchitectureHotspot): number {
return (hotspot.cognitive ?? 0)
+ (hotspot.complexity ?? 0)
+ 3 * (hotspot.loopDepth ?? 0)
+ 2 * (hotspot.allocationInLoop ? 1 : 0)
+ 2 * (hotspot.scanInLoop ? 1 : 0)
+ 8 * (hotspot.unguardedRecursion ? 1 : 0)
+ 0.25 * (hotspot.fanIn ?? 0);
}
/**
* Rank hotspots, keeping only the ones that carry a signal at all.
*
* A symbol with every reading at zero is not a quiet hotspot, it is not a
* hotspot; listing it would fill the section with the alphabetical head of the
* codebase. Ties break on the name so two runs of the same index produce the
* same list.
*/
export function rankHotspots(candidates: ArchitectureHotspot[]): ArchitectureHotspot[] {
return candidates
.filter(candidate => hotspotScore(candidate) > 0)
.sort((left, right) => {
const delta = hotspotScore(right) - hotspotScore(left);
return delta !== 0 ? delta : (left.qualifiedName ?? left.name).localeCompare(right.qualifiedName ?? right.name);
});
}