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/cypher.ts
* Gleicher Urheber (Bernhard Jackiewicz). Semantisch unveraendert uebernommen:
* jede Spalte, jeder Deckel und jede Escape-Regel ist hier dieselbe, weil eine
* abgewandelte Frage eine andere Antwort ergibt und der Unterschied genau die
* Sorte Abweichung waere, die erst in einer Zahl auf dem Bildschirm auffaellt.
* Aenderungen gegenueber dem Original: keine. Die Datei hat keine Importe, der
* Transport steht woanders.
*/
/**
* Every graph query CodeAtlas sends, in one file.
*
* The frozen acceptance test asserts that no other source file contains a
* query. That is not tidiness for its own sake: it is what makes the engine
* replaceable. A second provider reimplements this file and nothing else in
* the intelligence extension has to change shape.
*
* Three properties of the 0.9.0 query subset shape what can be written here:
*
* - Supported clauses are MATCH, WHERE, RETURN, ORDER BY and LIMIT. There is
* no WITH, no COLLECT, no OPTIONAL MATCH and no labels() function, so a
* node's label cannot be returned as a value.
* - A pattern carries at most one label, so a query that needs several labels
* runs several times. That is why resolution issues one query per label.
* - An unknown property returns the empty string rather than failing, so a
* typo in a property name reads as "no data" instead of as an error. The
* property names below are therefore constants, never inline literals.
*/
/** Node properties read by the queries in this file. */
export const NODE_PROPS = {
name: 'name',
qualifiedName: 'qualified_name',
filePath: 'file_path',
startLine: 'start_line',
endLine: 'end_line',
isTest: 'is_test',
isExported: 'is_exported',
envKey: 'env_key',
complexity: 'complexity',
cognitive: 'cognitive',
loopDepth: 'loop_depth',
allocInLoop: 'alloc_in_loop',
linearScanInLoop: 'linear_scan_in_loop',
unguardedRecursion: 'unguarded_recursion'
} as const;
/** Relation properties read by the queries in this file. */
export const REL_PROPS = {
/** Last recorded site of a relation, 1-based. Relations are deduplicated per pair. */
line: 'line',
strategy: 'strategy'
} as const;
/**
* Relation names. Kept here so no other file has to spell them.
*
* There are two error relations rather than one because the engine records two.
* `RAISES` is what the TypeScript and JavaScript analyses write for a `throw`;
* `THROWS` is what the Java analysis writes for a declared `throws` clause. A
* product that read only the first would tell a Java reader that a method
* declaring `throws NoAuthorizationException` raises nothing, which is a
* finding CodeAtlas never made. Both are read and the results are merged.
*/
export const RELATIONS = {
invocation: 'CALLS',
raise: 'RAISES',
throwDeclaration: 'THROWS',
environment: 'CONFIGURES',
typeReference: 'USAGE',
/**
* One file importing another.
*
* Written by the 0.9.0 analysis for every language whose modules declare
* their dependencies, and confirmed by the schema canary. The source of an
* edge is the importing module and the target is the imported file; both
* ends carry `file_path`, which is what makes a file-level dependency graph
* readable without a second lookup per node.
*/
moduleImport: 'IMPORTS'
} as const;
/**
* Labels tried when resolving a caret position, ordered narrowest first. The
* order is also the tie-break when two candidates span the same number of
* lines: a method body wins over the function that shares its extent, which
* wins over the class that contains it.
*/
export const ENCLOSING_LABELS = ['Method', 'Function', 'Class'] as const;
export type EnclosingLabel = typeof ENCLOSING_LABELS[number];
/** Label of the nodes that stand for indexed files. */
export const FILE_LABEL = 'File';
/** Label of the nodes that stand for environment values. */
export const ENV_LABEL = 'EnvVar';
/** Label whose call targets are constructions rather than plain invocations. */
export const CLASS_LABEL = 'Class';
/** Default row ceiling. Fact lists longer than this are truncated by the UI anyway. */
export const DEFAULT_LIMIT = 200;
/**
* Make a value safe to embed in a double-quoted literal. Backslashes first,
* then quotes, then the control characters that would end the statement early.
*/
export function escapeLiteral(value: string): string {
let out = '';
for (const char of value) {
const code = char.codePointAt(0) ?? 0;
if (code < 0x20 || code === 0x7f) {
// Control characters have no meaning in a symbol name or a path and
// would end the statement early, so they are dropped.
continue;
}
if (char === '\\' || char === '"') {
out += `\\${char}`;
continue;
}
out += char;
}
return out;
}
/** Reject a line number that could not have come from an editor. */
function safeLine(oneBasedLine: number): number {
if (!Number.isFinite(oneBasedLine)) {
return 0;
}
return Math.max(0, Math.floor(oneBasedLine));
}
function safeLimit(limit: number): number {
if (!Number.isFinite(limit) || limit <= 0) {
return DEFAULT_LIMIT;
}
return Math.min(Math.floor(limit), 5000);
}
/** Columns each builder returns, in order. Consumers key rows by these. */
export const COLUMNS = {
enclosing: [
`n.${NODE_PROPS.name}`,
`n.${NODE_PROPS.qualifiedName}`,
`n.${NODE_PROPS.startLine}`,
`n.${NODE_PROPS.endLine}`
],
fileExists: [`n.${NODE_PROPS.name}`, `n.${NODE_PROPS.filePath}`],
files: [`n.${NODE_PROPS.filePath}`],
/**
* Der Modul-Knoten einer Datei: sein Name, und die Spanne, die er
* beansprucht. Die Spanne ist der Grund fuer diese Abfrage: sie ist die
* einzige Stelle, an der steht, wie lang die Datei wirklich ist, und ohne
* sie waere ein gekappter Schnipsel nicht von einer ganzen Datei zu
* unterscheiden.
*/
moduleForFile: [
`n.${NODE_PROPS.qualifiedName}`,
`n.${NODE_PROPS.startLine}`,
`n.${NODE_PROPS.endLine}`
],
/** Der qualifizierte Name des File-Knotens einer Datei. */
fileNode: [`n.${NODE_PROPS.qualifiedName}`],
callsOut: [
`b.${NODE_PROPS.name}`,
`b.${NODE_PROPS.qualifiedName}`,
`b.${NODE_PROPS.filePath}`,
`b.${NODE_PROPS.startLine}`,
`r.${REL_PROPS.line}`
],
classTargets: [`b.${NODE_PROPS.name}`, `b.${NODE_PROPS.qualifiedName}`],
callsIn: [
`a.${NODE_PROPS.name}`,
`a.${NODE_PROPS.qualifiedName}`,
`a.${NODE_PROPS.filePath}`,
`a.${NODE_PROPS.startLine}`,
`a.${NODE_PROPS.isTest}`,
`r.${REL_PROPS.line}`
],
raises: [
`b.${NODE_PROPS.name}`,
`b.${NODE_PROPS.filePath}`,
`b.${NODE_PROPS.startLine}`,
`r.${REL_PROPS.line}`
],
envReads: [
`b.${NODE_PROPS.name}`,
`b.${NODE_PROPS.envKey}`,
`b.${NODE_PROPS.filePath}`,
`r.${REL_PROPS.line}`,
`r.${REL_PROPS.strategy}`
],
typeRefs: [
`b.${NODE_PROPS.name}`,
`b.${NODE_PROPS.qualifiedName}`,
`b.${NODE_PROPS.filePath}`,
`b.${NODE_PROPS.startLine}`,
`r.${REL_PROPS.line}`
],
/** One import edge, as two workspace-relative paths: the importer and the imported. */
imports: [`a.${NODE_PROPS.filePath}`, `b.${NODE_PROPS.filePath}`],
hotspots: [
`n.${NODE_PROPS.name}`,
`n.${NODE_PROPS.qualifiedName}`,
`n.${NODE_PROPS.filePath}`,
`n.${NODE_PROPS.startLine}`,
`n.${NODE_PROPS.complexity}`,
`n.${NODE_PROPS.cognitive}`,
`n.${NODE_PROPS.loopDepth}`,
`n.${NODE_PROPS.allocInLoop}`,
`n.${NODE_PROPS.linearScanInLoop}`,
`n.${NODE_PROPS.unguardedRecursion}`
],
/**
* Declarations of one label inside a set of files. The same columns as the
* enclosing lookup plus the file, because the caller is asking about several
* files at once and has to be able to tell the rows apart.
*/
declarations: [
`n.${NODE_PROPS.name}`,
`n.${NODE_PROPS.qualifiedName}`,
`n.${NODE_PROPS.filePath}`,
`n.${NODE_PROPS.startLine}`,
`n.${NODE_PROPS.endLine}`,
`n.${NODE_PROPS.isTest}`
]
} as const;
const ret = (columns: readonly string[]): string => `RETURN ${columns.join(', ')}`;
/**
* A disjunction over one property, or undefined when there is nothing to ask.
*
* `IN [...]` parses at 0.9.0, but an OR chain is what every other query in this
* file is built from and it needs no assumption about list literal support in a
* subset that has neither WITH nor COLLECT. The values are escaped exactly as a
* single-valued predicate would escape them.
*/
function anyOf(alias: string, property: string, values: readonly string[]): string | undefined {
const unique = [...new Set(values.filter(value => value.length > 0))];
if (unique.length === 0) {
return undefined;
}
return unique.map(value => `${alias}.${property} = "${escapeLiteral(value)}"`).join(' OR ');
}
/**
* Symbols of one label whose declaration span covers `oneBasedLine` in
* `filePath`. Ordered so the innermost candidate of that label comes first.
*/
export function enclosingByLabel(label: string, filePath: string, oneBasedLine: number): string {
const line = safeLine(oneBasedLine);
return `MATCH (n:${label}) WHERE n.${NODE_PROPS.filePath} = "${escapeLiteral(filePath)}"`
+ ` AND n.${NODE_PROPS.startLine} <= ${line} AND n.${NODE_PROPS.endLine} >= ${line}`
+ ` ${ret(COLUMNS.enclosing)}`
+ ` ORDER BY n.${NODE_PROPS.startLine} DESC LIMIT 10`;
}
/** How many files one listing returns. A repository past this is read partially, not wrongly. */
export const FILE_LIST_LIMIT = 5000;
/**
* Every file the index holds, workspace-relative.
*
* The whole-project summary carries a file tree, but it is a shallow one: on a
* large repository it names the top of the tree and stops, so a caller that
* used it as a file list would silently read a fraction of the project. The
* file nodes are the complete answer.
*/
export function indexedFiles(limit = FILE_LIST_LIMIT): string {
return `MATCH (n:${FILE_LABEL}) ${ret(COLUMNS.files)} LIMIT ${safeLimit(limit)}`;
}
/**
* How many import edges one sweep returns.
*
* The same ceiling as the file listing, which is also the highest a query in
* this file may ask for. A repository past it is read partially rather than
* wrongly: the consumer records how many edges it was given, so a dependency
* order built from a truncated sweep says so instead of passing itself off as
* the whole graph.
*/
export const IMPORT_EDGE_LIMIT = FILE_LIST_LIMIT;
/**
* Every import edge in the project, as a pair of workspace-relative paths.
*
* One sweep rather than a reader per file, and that is the whole reason this is
* the only import query in the file. The consumer is the tour generator, which
* topologically sorts the entire dependency graph: it needs every edge before
* it can place the first file, so a per-file `importsOf` would be one round
* trip per file to assemble something a single query already returns. A
* neighbourhood reader would be dead weight until something asks a
* neighbourhood question.
*
* Unordered, and deliberately so. The 0.9.0 analysis writes one edge per import
* *statement*, so a file that imports three names from one module appears three
* times; the caller deduplicates on the pair and sorts, which makes the answer
* independent of the order the engine happens to return rows in.
*/
export function importEdges(limit = IMPORT_EDGE_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.moduleImport}]->(b) ${ret(COLUMNS.imports)} LIMIT ${safeLimit(limit)}`;
}
/**
* Das Label des Knotens, der eine ganze Datei umspannt.
*
* Zwei Labels beschreiben dieselbe Datei und sie sind nicht dasselbe: `File`
* ist der Eintrag im Datei-Inventar, `Module` ist die Datei als Symbol, mit
* Spanne und mit Quelltext hinter `get_code_snippet`. Der Reader braucht das
* zweite.
*/
export const MODULE_LABEL = 'Module';
/**
* Der Modul-Knoten einer Datei, mit seiner Zeilenspanne.
*
* Diese Abfrage ist der Gegenbeweis zur Ableitung in src/app/module-qn.ts: der
* Name laesst sich aus dem Pfad ausrechnen, aber ausgerechnet ist nicht
* nachgesehen. Der Reader rechnet, fragt und nimmt die Antwort, wenn beide
* auseinandergehen.
*/
export function moduleForFile(filePath: string): string {
return `MATCH (n:${MODULE_LABEL}) WHERE n.${NODE_PROPS.filePath} = "${escapeLiteral(filePath)}"`
+ ` ${ret(COLUMNS.moduleForFile)} LIMIT 1`;
}
/**
* Der File-Knoten einer Datei, nur sein qualifizierter Name.
*
* Der Rueckfallweg, wenn der Graph keinen Modul-Knoten fuehrt: sein Name ist
* der des Moduls plus Endung plus `.__file__`, und daraus laesst sich der
* Modul-Name zurueckrechnen (siehe moduleQnFromFileQn). Das ist eine schwaechere
* Auskunft als der Modul-Knoten selbst, denn eine Zeilenspanne kommt so nicht
* mit, und genau deshalb ist es der zweite Weg und nicht der erste.
*/
export function fileNodeForPath(filePath: string): string {
return `MATCH (n:${FILE_LABEL}) WHERE n.${NODE_PROPS.filePath} = "${escapeLiteral(filePath)}"`
+ ` ${ret(COLUMNS.fileNode)} LIMIT 1`;
}
/** Whether the engine has a file node for `filePath`. Distinguishes "nothing here" from "not indexed". */
export function fileExists(filePath: string): string {
return `MATCH (n:${FILE_LABEL}) WHERE n.${NODE_PROPS.filePath} = "${escapeLiteral(filePath)}"`
+ ` ${ret(COLUMNS.fileExists)} LIMIT 1`;
}
/** Outgoing invocations of a symbol, one row per distinct target. */
export function callsOut(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.invocation}]->(b)`
+ ` WHERE a.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.callsOut)}`
+ ` ORDER BY r.${REL_PROPS.line} LIMIT ${safeLimit(limit)}`;
}
/**
* Outgoing invocations whose target is a class. The engine records a
* construction as an invocation of the class, so this second query is what
* separates `new Foo()` from `foo()` without a labels() function.
*/
export function classCallTargets(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.invocation}]->(b:${CLASS_LABEL})`
+ ` WHERE a.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.classTargets)} LIMIT ${safeLimit(limit)}`;
}
/**
* Incoming invocations of a symbol. Returns the source's test flag so the
* tested-by inference can run without a second query.
*/
export function callsIn(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.invocation}]->(b)`
+ ` WHERE b.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.callsIn)}`
+ ` ORDER BY r.${REL_PROPS.line} LIMIT ${safeLimit(limit)}`;
}
/** Error types a symbol raises. */
export function raises(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.raise}]->(b)`
+ ` WHERE a.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.raises)} LIMIT ${safeLimit(limit)}`;
}
/**
* Error types a symbol declares it throws.
*
* The same columns as {@link raises}, on purpose: the two relations describe the
* same product fact in two languages and the caller merges the rows. A single
* query cannot cover both, because a pattern carries at most one relation type.
*/
export function throwsRelation(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.throwDeclaration}]->(b)`
+ ` WHERE a.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.raises)} LIMIT ${safeLimit(limit)}`;
}
/**
* Environment values a symbol reads. The engine models an environment read as
* a configuration relation to a dedicated node, not as a variable reference,
* which is why this is its own query rather than a filter on type references.
*/
export function envReads(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.environment}]->(b:${ENV_LABEL})`
+ ` WHERE a.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.envReads)} LIMIT ${safeLimit(limit)}`;
}
/** Labels whose nodes carry the per-symbol complexity readings. */
export const CALLABLE_LABELS = ['Function', 'Method'] as const;
/** How many callables one hotspot sweep reads. Ranking happens in the provider. */
export const HOTSPOT_SCAN_LIMIT = 1500;
/**
* Every callable of one label with the readings that make a symbol worth
* reading first.
*
* Unordered on purpose. The 0.9.0 answer is all strings, so `ORDER BY` on a
* numeric property sorts `"10"` before `"9"`; ranking is therefore done by the
* caller on coerced numbers. The limit is what keeps this a bounded sweep on a
* large repository rather than a download of the whole graph.
*/
export function hotspotCandidates(label: string, limit = HOTSPOT_SCAN_LIMIT): string {
return `MATCH (n:${label}) ${ret(COLUMNS.hotspots)} LIMIT ${safeLimit(limit)}`;
}
/** How many symbols one batched complexity read asks about. */
export const COMPLEXITY_BATCH_LIMIT = 200;
/**
* The complexity readings of a named set of symbols, one label at a time.
*
* The same columns as {@link hotspotCandidates}, because it is the same reading
* asked of a set rather than of a label. Returns undefined when the set is
* empty: a query with no predicate would match every callable in the project,
* which is the sweep this function exists to avoid.
*/
export function complexityOf(
label: string,
qualifiedNames: readonly string[],
limit = COMPLEXITY_BATCH_LIMIT
): string | undefined {
const predicate = anyOf('n', NODE_PROPS.qualifiedName, qualifiedNames);
if (predicate === undefined) {
return undefined;
}
return `MATCH (n:${label}) WHERE ${predicate} ${ret(COLUMNS.hotspots)} LIMIT ${safeLimit(limit)}`;
}
/** How many declarations one batched file read returns. */
export const DECLARATION_BATCH_LIMIT = 1000;
/**
* Symbols of one label declared in any of a set of files.
*
* This is the lookup that gives a change set its identities. The change tool
* names an affected symbol and the file it sits in and nothing else, so a
* product that wants to ask a follow-up question about that symbol, or to open
* it, has to recover the qualified name and the declaration line from the index
* itself. One query per label rather than one per symbol: a change set of forty
* files is two round trips this way and eighty the other.
*/
export function declarationsInFiles(
label: string,
filePaths: readonly string[],
limit = DECLARATION_BATCH_LIMIT
): string | undefined {
const predicate = anyOf('n', NODE_PROPS.filePath, filePaths);
if (predicate === undefined) {
return undefined;
}
return `MATCH (n:${label}) WHERE ${predicate} ${ret(COLUMNS.declarations)} LIMIT ${safeLimit(limit)}`;
}
/** How many callers one batched inbound read returns. */
export const CALLER_BATCH_LIMIT = 500;
/**
* Everything that calls any symbol in a set, in one query.
*
* The walk a change assessment needs is breadth first and unlabelled: what
* calls this set, then what calls that set. Asking per symbol would be one round
* trip per row of a list that grows with every step; asking per level is one
* round trip per step. What is given up is which member of the set each caller
* reached, and nothing above this needs it: the distance is a property of the
* level, not of the edge.
*/
export function callersOfAny(qualifiedNames: readonly string[], limit = CALLER_BATCH_LIMIT): string | undefined {
const predicate = anyOf('b', NODE_PROPS.qualifiedName, qualifiedNames);
if (predicate === undefined) {
return undefined;
}
return `MATCH (a)-[r:${RELATIONS.invocation}]->(b) WHERE ${predicate}`
+ ` ${ret(COLUMNS.callsIn)} LIMIT ${safeLimit(limit)}`;
}
/**
* Types a symbol references. This relation covers type positions only; local
* variable reads and writes are not recorded by the 0.9.0 engine at all, which
* is why the provider declares no read/write capability.
*/
export function typeRefs(qualifiedName: string, limit = DEFAULT_LIMIT): string {
return `MATCH (a)-[r:${RELATIONS.typeReference}]->(b)`
+ ` WHERE a.${NODE_PROPS.qualifiedName} = "${escapeLiteral(qualifiedName)}"`
+ ` ${ret(COLUMNS.typeRefs)} LIMIT ${safeLimit(limit)}`;
}