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-29 aus CodeAtlasIDE,
* /Users/bernhard/Desktop/CodeAtlasIDE/theia-extensions/codeatlas-views/src/browser/pseudocode/imports-group.ts
* (380 Zeilen). Gleicher Urheber (Bernhard Jackiewicz). Semantisch unveraendert
* uebernommen: die drei Antworten used/unused/unknown samt ihrer Begruendung,
* IMPORTS_GROUP_CAP, buildImportsGroup mit der Zaehlung ueber die ganze Liste
* statt ueber die gekappte, entryOf mit den drei namenlosen Formen, matchOf mit
* der Familien-Reihenfolge calls/typeRefs/throws/reads, fullyAnswered und
* citationOf.
*
* Aenderungen gegenueber dem Original: die Importpfade (Evidence, Fact,
* KnowledgeState und SemanticIR aus src/core/, der Wortlaut aus
* ./pseudocode-strings), UND die beiden DTOs stehen hier statt in der
* Provider-Schnittstelle. Grund: im Referenzprojekt beantwortet der Backend-
* Provider `fileImports(root, filePath)`; der C-Server dieses Projekts bietet
* kein solches Werkzeug an (INVENTAR Abschnitt 3), also wird die Antwort in
* ./imports-source.ts aus zwei vorhandenen Lesungen zusammengesetzt. Die DTOs
* gehoeren damit zu dieser Schicht und nicht zur Provider-Grenze.
*/
/**
* What a file pulls in, and which names the complete file reading reaches.
*
* No React, no DOM, no services, no fetching. Two things in, one group out: the
* import list the backend read for a file, and the semantic IR of every callable
* declaration in that file. Both surfaces that draw this (the pseudocode block
* and the twin's data chips) call this one function, so the block and the panel
* can never disagree about whether the file reaches `query`.
*
* The feature exists because of one sentence of user feedback: the imports are
* not explained. They are the first thing anybody reads in an unfamiliar file
* and the last thing this product had anything to say about.
*
* Four rules make that safe to put on screen.
*
* **Three answers, not two.** The tempting design has a boolean, and the boolean
* is a lie in one direction. A linter says "unused import" after parsing the
* file; CodeAtlas has a list of names and recorded facts for every callable in
* the file. The absence of a match means one of two very different things
* depending on whether the family that would have carried the match was
* answered at all. So a name a fact mentions is `used`, a name no fact mentions
* *in families the index answered* is `unused`, and a name whose file-wide
* check could not be run is `unknown`.
* The third one is the whole point: claiming `unused` when `typeRefs` came back
* `notIndexed` would be inventing a finding out of a gap.
*
* **`unused` is about the complete file, never the focused symbol.** `query`
* is imported at the top of `userService.ts` and `createUser` never touches it;
* `listUsers`, four lines up, does. A focused symbol alone therefore cannot
* establish a negative file claim. If the complete callable reading is absent
* or partial, every named import remains `unknown`.
*
* **A positive match wins outright.** If any family names the import, the entry
* is `used`, whatever state the other families are in. A missing family can only
* ever weaken a negative answer; it cannot weaken a match that was found.
*
* **The two readings stay apart.** The dependency between two files is the
* analysis speaking. The statement, its line and the name it binds are CodeAtlas
* reading the file. Every entry carries a citation for each of the two it has,
* so a reader who opens the evidence on a chip sees exactly which half of the
* claim came from where; an entry whose only citation is the import is an entry
* that proves the import and nothing about its use, and it says so.
*/
import type { Evidence, Fact, KnowledgeState, SemanticIR } from '../core/semantic-ir';
import {
IMPORTS_NOTE_INDEX_ONLY,
IMPORTS_NOTE_NAMESPACE,
IMPORTS_NOTE_SIDE_EFFECT,
IMPORTS_NOTE_UNKNOWN,
IMPORTS_NOTE_UNUSED,
IMPORTS_NOTE_USED,
IMPORT_MARK_UNKNOWN,
IMPORT_MARK_UNUSED,
IMPORT_MARK_USED,
importsCappedNote,
importsFindingHeading,
importsIndexOnlyLine,
importsNamespaceLine,
importsSideEffectLine,
importsTally,
importsUnknownLine,
importsUnusedLine,
importsUsedLine,
} from './pseudocode-strings';
import type { PseudocodeSourceRef } from './pseudocode-builder';
/**
* One name one file pulls in, and where that claim comes from.
*
* Assembled from two readings, because neither one answers the question on its
* own. The index records that a file imports another file and nothing else: no
* imported name, no statement line, and no edge at all for a module that
* resolves outside the workspace. The file's own text carries all three and is
* not a finding of the analysis. So both are read, every entry says which
* reading produced it, and a surface can show the difference instead of
* flattening it.
*/
export interface FileImportRef {
/**
* The name as the exporting module spells it.
*
* Absent for a side-effect import, for a namespace import and for an entry
* recovered from an index edge alone, and those three absences mean the same
* thing to a consumer: this entry names no symbol, so nothing about it can
* be checked against the file's callable facts.
*/
name?: string;
/** The local binding, when the statement renamed what it imported. */
alias?: string;
/** The module specifier as written, or the imported file's path for an index-only entry. */
module: string;
/** 1-based graph line of the import statement, when the text was readable. */
line?: number;
/** Workspace-relative path of the imported file, when the index recorded an edge to one. */
targetPath?: string;
/**
* True when the statement binds a whole module under one name.
*
* A namespace binding cannot be checked against callable facts: the index
* records `db.query()` as a call to `query`, so the binding `db` appears
* nowhere and would read as unused while the file leans on it.
*/
namespace?: boolean;
/** `index` means the analysis reported it; `source` means it was read off the text. */
origin: 'index' | 'source';
/** Citations backing this entry, in the same grammar every other fact uses. */
evidence: Evidence[];
}
/**
* What one file pulls in, plus everything a consumer needs in order not to
* overstate it.
*
* The three fields beside `entries` exist because an empty list has four
* different meanings here and a surface must be able to tell them apart: the
* file imports nothing, the analysis records no import relation for this
* language, the file could not be read, or a bound cut the reading short.
*/
export interface FileImportsDto {
/** One entry per imported name, in the order the statements appear. */
entries: FileImportRef[];
/** True when the read stopped at its bound, so `entries` is a floor. */
truncated: boolean;
/**
* Workspace-relative paths of the files the index records this one
* importing, deduplicated and sorted.
*
* Kept beside the entries rather than folded into them, because it is the
* one half of the answer the analysis itself stands behind.
*/
indexedTargets: string[];
/**
* True when the file's own text was read.
*
* False means every entry below came from an index edge, so none of them
* names a symbol or a line. That is a statement about this reading and not
* about the file.
*/
sourceRead: boolean;
/** Facts for every callable declaration in the file, only when the read completed. */
fileIrs?: SemanticIR[];
}
/**
* What CodeAtlas is willing to say about one import and its containing file.
*
* Ordered by strength on purpose: a reader scanning a list of these should be
* able to treat the first as a finding, the second as a finding about an
* absence, and the third as an admission.
*/
export type ImportUsage =
/** A fact recorded for a callable in this file names this import. */
| 'used'
/** No fact recorded for the complete file names it, in families the index answered. */
| 'unused'
/** The check could not be run, so nothing is claimed either way. */
| 'unknown';
/** One name a file pulls in, as this group presents it. */
export interface ImportEntry {
/** Stable within one group, used as a React key and as an evidence anchor. */
id: string;
/** Address of this entry's citations, in the `fact[row]` grammar the popover parses. */
factPath: string;
/** What the entry is called on screen: the imported name, the binding, or the module. */
label: string;
/** The module specifier exactly as the statement wrote it. */
module: string;
usage: ImportUsage;
/** The short word beside the label. Never the only carrier of the status. */
marker: string;
/** The whole sentence the pseudocode block draws for this entry. */
text: string;
/** One sentence saying why this entry carries the status it does. */
note: string;
/** The import statement, when the file's text was read. */
sourceRef?: PseudocodeSourceRef;
/** Workspace-relative path of the imported file, when the index named one. */
targetPath?: string;
/**
* True when this entry is the finding of the group rather than a line in
* it (W8c).
*
* `used` is the expected case and reads as background; the other two are
* the reason the group is worth a reader's time, and until W8c they sat in
* the same typography as everything else, under a heading that sounded like
* a footnote. The flag does not change what is said: the entry keeps its
* own sentence, its marker and its limit.
*/
finding: boolean;
/** Which IR family produced the match, for a `used` entry. */
usedBy?: ImportUsageFamily;
/** `index` means the analysis reported it; `source` means it was read off the text. */
origin: 'index' | 'source';
/** The import's own citations, plus the one that proves the use when there is one. */
evidence: Evidence[];
}
/** Which family of recorded facts named an import. */
export type ImportUsageFamily = 'calls' | 'typeRefs' | 'throws' | 'reads';
/** One file's imports, judged against its complete callable reading, ready to render. */
export interface ImportsGroup {
heading: string;
/** The entries the surface draws, already capped. */
entries: ImportEntry[];
/** How many entries the cap left out. Zero when nothing was left out. */
hidden: number;
/** The honest sentence about the cap, present exactly when `hidden` is not zero. */
cappedNote?: string;
/** The tally under the entries. Counted over the whole list, not over the capped one. */
tally: string;
used: number;
unused: number;
unknown: number;
/** True when the file's own text was read; false means no entry names a symbol. */
sourceRead: boolean;
}
/** What the group is built from. */
export interface ImportsGroupInput {
/** The backend's answer for the file the anchor symbol lives in. */
imports: FileImportsDto;
/**
* Kept for callers that already hold the focused IR. It is deliberately not
* used to decide a file-level import claim: only `imports.fileIrs` can do
* that, because another declaration in the same file may use the name.
*/
irs: readonly SemanticIR[];
/** Absolute URI of that file, so an entry can point at its own statement. */
uri: string;
/** How many entries the group may draw. Defaults to {@link IMPORTS_GROUP_CAP}. */
cap?: number;
}
/**
* How many entries one group draws.
*
* Twelve is about where a list of names stops being scannable and starts being
* a wall, and it is comfortably above what an ordinary source file imports. A
* file past it is read partially and says so, exactly as a bounded walk does.
*/
export const IMPORTS_GROUP_CAP = 12;
/**
* Judge one file's imports against the complete callable reading of that file.
*
* Total: a file with no imports, a file whose text could not be read and a
* symbol whose families are all missing each produce a group rather than
* nothing, because every one of those is an answer a reader needs to be able to
* tell from the others.
*/
export function buildImportsGroup(input: ImportsGroupInput): ImportsGroup {
const cap = Math.max(1, input.cap ?? IMPORTS_GROUP_CAP);
// `fileIrs` is present only after every declaration was resolved and built.
// The focused IR is intentionally never a fallback: a positive match in it
// proves one use, but its absence cannot prove that the whole file is quiet.
const scopedInput = { ...input, irs: input.imports.fileIrs ?? [] };
// `finding` is set here and not in the six branches of `entryOf`: it is one
// rule over the answer they produce ("anything but `used` is why this group
// exists"), and six copies of one rule is how two of them end up disagreeing.
const judged: ImportEntry[] = input.imports.entries.map((entry, index) => {
const built = entryOf(entry, index, scopedInput);
return { ...built, finding: built.usage !== 'used' };
});
const counts = { used: 0, unused: 0, unknown: 0 };
for (const entry of judged) {
counts[entry.usage] += 1;
}
const hidden = Math.max(0, judged.length - cap);
return {
heading: importsFindingHeading(counts.unused, counts.unknown, judged.length),
entries: judged.slice(0, cap),
hidden,
cappedNote: hidden > 0 ? importsCappedNote(hidden, Math.min(cap, judged.length)) : undefined,
tally: importsTally(counts.used, counts.unused, counts.unknown),
used: counts.used,
unused: counts.unused,
unknown: counts.unknown,
sourceRead: input.imports.sourceRead,
};
}
// ---------------------------------------------------------------------------
/** One import, with everything decided about it except which of them is the finding. */
function entryOf(ref: FileImportRef, index: number, input: ImportsGroupInput): Omit<ImportEntry, 'finding'> {
const base = {
id: `import-${index}`,
factPath: `imports[${index}]`,
module: ref.module,
origin: ref.origin,
sourceRef: ref.line === undefined ? undefined : { uri: input.uri, line: ref.line },
targetPath: ref.targetPath,
evidence: [...ref.evidence],
};
// The three shapes that name no symbol. None of them can be checked against
// the file's callable facts, and each says why in its own words rather than sharing
// one sentence that would have to be vague enough to cover all three.
if (ref.namespace === true) {
const binding = ref.alias ?? ref.name ?? ref.module;
return {
...base,
label: binding,
usage: 'unknown',
marker: IMPORT_MARK_UNKNOWN,
text: importsNamespaceLine(binding, ref.module),
note: IMPORTS_NOTE_NAMESPACE,
};
}
if (ref.origin === 'index') {
return {
...base,
label: ref.targetPath ?? ref.module,
usage: 'unknown',
marker: IMPORT_MARK_UNKNOWN,
text: importsIndexOnlyLine(ref.targetPath ?? ref.module),
note: IMPORTS_NOTE_INDEX_ONLY,
};
}
if (ref.name === undefined) {
return {
...base,
label: ref.module,
usage: 'unknown',
marker: IMPORT_MARK_UNKNOWN,
text: importsSideEffectLine(ref.module),
note: IMPORTS_NOTE_SIDE_EFFECT,
};
}
const label = ref.alias === undefined ? ref.name : `${ref.name} as ${ref.alias}`;
const match = matchOf(ref, input.irs);
if (match !== undefined) {
return {
...base,
label,
usage: 'used',
marker: IMPORT_MARK_USED,
text: importsUsedLine(label, ref.module),
note: IMPORTS_NOTE_USED,
usedBy: match.family,
evidence: [...base.evidence, ...match.evidence],
};
}
if (!fullyAnswered(input.irs)) {
return {
...base,
label,
usage: 'unknown',
marker: IMPORT_MARK_UNKNOWN,
text: importsUnknownLine(label, ref.module),
note: IMPORTS_NOTE_UNKNOWN,
};
}
return {
...base,
label,
usage: 'unused',
marker: IMPORT_MARK_UNUSED,
text: importsUnusedLine(label, ref.module),
note: IMPORTS_NOTE_UNUSED,
};
}
/** The names one import statement could be matched under: what it exports, and what it binds. */
function namesOf(ref: FileImportRef): string[] {
return [ref.name, ref.alias].filter((name): name is string => name !== undefined && name.length > 0);
}
/**
* The first family of the file's callable facts that names the import, with the
* citation that backs it.
*
* The order is the order of strength. A recorded call is the strongest thing the
* index can say about a symbol reaching a name; a type reference is the next,
* because a signature naming a type is a real use of the import that brought it
* in; a raised type and an environment read come last because both are usually
* already visible as one of the first two and are here so that a symbol whose
* only mention of `ValidationError` is the raise site still counts.
*/
function matchOf(
ref: FileImportRef,
irs: readonly SemanticIR[],
): { family: ImportUsageFamily; evidence: Evidence[] } | undefined {
const names = namesOf(ref);
if (names.length === 0) {
return undefined;
}
// Family before symbol: a call recorded for the second method of a class
// outranks a type reference recorded for the first, because the ordering is
// about how strong the finding is and not about whose facts it came from.
for (const family of ['calls', 'typeRefs', 'throws', 'reads'] as const) {
for (const ir of irs) {
const found = matchIn(family, names, ir);
if (found !== undefined) {
return { family, evidence: found };
}
}
}
return undefined;
}
/** One family of one callable declaration, searched for any import binding. */
function matchIn(family: ImportUsageFamily, names: readonly string[], ir: SemanticIR): Evidence[] | undefined {
switch (family) {
case 'calls': {
const index = ir.calls.value.findIndex((call) => names.includes(call.targetName));
return index < 0 ? undefined : citationOf(ir.calls, index);
}
case 'typeRefs': {
const index = (ir.typeRefs?.value ?? []).findIndex((entry) => names.includes(entry.name));
return index < 0 ? undefined : citationOf(ir.typeRefs, index);
}
case 'throws': {
const index = ir.throws.value.findIndex((entry) => names.includes(entry.type));
return index < 0 ? undefined : citationOf(ir.throws, index);
}
default: {
const index = ir.reads.value.findIndex((entry) => names.includes(entry.name));
return index < 0 ? undefined : citationOf(ir.reads, index);
}
}
}
/**
* True when every family the match would have come from was actually answered,
* for every callable declaration in the file.
*
* This is what separates `unused` from `unknown`, and it is deliberately strict:
* one family the index could not answer is enough to stop the product claiming
* an import is untouched. `typeRefs` is the one that matters most in practice,
* because a provider that cannot recover type positions omits the field
* altogether, and a type-only import would otherwise be reported as unused in
* every file of the project.
*
* A scope with no facts at all answers false. Nothing was checked, so nothing
* may be denied.
*/
function fullyAnswered(irs: readonly SemanticIR[]): boolean {
if (irs.length === 0) {
return false;
}
return irs.every((ir) =>
[ir.calls.state, ir.typeRefs?.state, ir.throws.state, ir.reads.state].every(answered));
}
/** True when a family's state is a reading rather than a gap. */
function answered(state: KnowledgeState | undefined): boolean {
return state === 'known' || state === 'inferred';
}
/**
* The citation backing one row of one fact, or none.
*
* The same lockstep rule the twin's popover follows: providers build the
* evidence array in step with the value array, and where that does not hold the
* honest answer is no citation rather than the wrong line.
*/
function citationOf<T>(fact: Fact<T[]> | undefined, index: number): Evidence[] {
if (fact === undefined || fact.value.length !== fact.evidence.length) {
return [];
}
const entry = fact.evidence[index];
return entry === undefined ? [] : [entry];
}