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-views/src/browser/twin/render-model.ts
* Gleicher Urheber (Bernhard Jackiewicz). Semantisch unveraendert uebernommen:
* buildTwinViewModel mit allen vier Tiefen, visibleSections, MAX_PROSE_CHIPS,
* MAX_GUIDED_FACTS, die Facetten-Zuordnung SECTION_FACETS, die beiden
* Platzhalter-Sektionen und visibleTextOf.
*
* Aenderungen gegenueber dem Original: die Importpfade auf die ebenfalls
* portierten Dateien dieses Projekts.
*
* Die in W2b deklarierte Auslassung ist beglichen: die Imports-Gruppe ("What it
* pulls in", Original Z. 302-330, withImportsSection) ist reaktiviert am
* 2026-08-29 mit dem Pseudocode-Port, W4c. Der Data-Block traegt die
* Import-Antwort wieder, aus src/pseudocode/imports-group.ts.
*/
/**
* One semantic IR, five readers looking at it. No DOM, no services, no JSX.
*
* The slider is the product's central claim, and since W13 it asks a different
* question. It used to ask how much to say. It now asks who is reading, and the
* five answers are the reader's own words: vibe coder, junior, medior, senior,
* architect. The claim is the same and stronger: the same recorded facts,
* *chosen* for the reader in front of them, with nothing invented on the way
* down and nothing hidden on the way up. That only survives if the five
* presentations are one function of the IR rather than five panels that happen
* to be pointed at the same symbol, which is why this module exists and why it
* is pure.
*
* The five, and the question each of them answers:
*
* - **0 vibe coder**: what happens here, and why does it matter to you? One
* paragraph, clickable names, no list and no jargon it can avoid.
* - **1 junior**: in what order does it happen, and why? The calls in the
* order the body reaches them, with the connective between them, and a word
* explained the first time it is used.
* - **2 medior**: what is actually written here? The recorded facts with
* their jump targets and no groundwork. This one is the old technical depth,
* unchanged, down to the section order.
* - **3 senior**: what does this cost me? The failure paths, what is
* unchecked, who depends on it, and what a change here drags with it.
* - **4 architect**: what does this sit on, and where does our knowledge end?
* The ground under it, what carries it, what it owes, and the limits of the
* index as a first-class part of the answer rather than a footnote.
*
* Five rules run through everything below.
*
* **One reading of the IR, five shapes of it.** The medior level is
* `buildSections` unchanged; the other four are derived from the same sections,
* or from the same facts, and never from a second interpretation. A row that
* says `validate.ts:19` for the medior cannot say `validate.ts:21` for the
* architect, because there is only one place that decided.
*
* **The level changes what is said, never what is true.** The vibe coder's
* level spends counts and consequences where the architect's spends names, line
* numbers and confidences; neither is allowed to state something the other
* would contradict. In particular the vibe coder's level carries no qualified
* name and no confidence figure anywhere a reader can see one: a reader who has
* asked for prose has not asked to be told that a resolution scored 0.55, and
* showing it anyway is how a "simple" mode becomes a lying one.
*
* **No level is allowed to be empty, and no level is allowed to be silent.** A
* block with nothing in it says so in that reader's own words. "No error path
* was recorded here" is an answer to the senior's question; a blank space is
* not, and it is indistinguishable from a level that does not work.
*
* **Facets subtract, they never add.** A facet that is off removes its section.
* A facet that is on and has no answer yet renders the heading with the
* sentence saying so. Both are honest; silently rendering nothing for a lens
* the reader explicitly asked for is not.
*
* **Nothing here knows which preset is active.** The input is a
* {@link ResolvedPresentation}: depth, facets, terminology, callouts. That is
* deliberate. The moment a renderer can ask "am I in Learning" it starts
* growing behaviour that no slider position can reproduce, and the slider stops
* being the truth about what is on screen.
*/
import type { SymbolRef } from '../core/focus-protocol';
import type { CallSite, KnowledgeState, SemanticIR } from '../core/semantic-ir';
import {
Facet
} from './presentation-profile';
import type {
DepthLevel,
ResolvedPresentation,
TerminologyLevel
} from './presentation-profile';
import type { ReaderLine } from './reader-rewrite';
import { readerLines } from './reader-rewrite';
import {
CHANGES_NOT_IN_TWIN,
CONFIDENCE_EXACT,
CONFIDENCE_EXACT_TOOLTIP,
CONFIDENCE_SCORED_TOOLTIP,
CONFIDENCE_UNSCORED,
CONFIDENCE_UNSCORED_TOOLTIP,
LENS_ANSWERED_ELSEWHERE_NOTE,
PLAIN_SUBJECT_ERRORS,
PLAIN_SUBJECT_TESTS,
PROSE_CHIPS_LEAD,
PROSE_GENERATED_NOTE,
PROSE_TESTS_NONE,
RUNTIME_NOT_IN_TWIN,
SECTION_ICONS,
SECTION_LABELS_PLAIN,
SECTION_LABELS_TECHNICAL,
SUBJECT_CALLERS,
SUBJECT_CHANGES,
SUBJECT_EFFECTS,
SUBJECT_ERRORS,
SUBJECT_PURPOSE,
SUBJECT_RUNTIME,
SUBJECT_STATE,
SUBJECT_STEPS,
SUBJECT_TESTS,
citationCount,
confidenceLabel,
plainAbsence,
plainKind,
proseCalls,
joinNames,
proseLead,
proseMoreParts,
proseReads,
proseTestsSome,
proseThrows,
rowCountLabel,
strategyLabel,
// --- W13: the five readers -------------------------------------------
COST_EMPTY_DEPENDS,
COST_EMPTY_FAILS,
COST_EMPTY_MOVES,
COST_EMPTY_UNTESTED,
COST_LEAD_DEPENDS,
COST_LEAD_FAILS,
COST_LEAD_MOVES,
COST_LEAD_UNTESTED,
COST_TITLE_DEPENDS,
COST_TITLE_FAILS,
COST_TITLE_MOVES,
COST_TITLE_UNTESTED,
DEBT_ALLOC_IN_LOOP,
DEBT_RECURSIVE,
DEBT_SCAN_IN_LOOP,
DEBT_UNGUARDED_RECURSION,
GROUND_EMPTY_CARRIED,
GROUND_EMPTY_DEBTS,
GROUND_EMPTY_SITS_ON,
GROUND_ENTRY_POINT,
GROUND_EXPORTED,
GROUND_LEAD_CARRIED,
GROUND_LEAD_DEBTS,
GROUND_LEAD_LIMITS,
GROUND_LEAD_SITS_ON,
GROUND_NOT_EXPORTED,
GROUND_TITLE_CARRIED,
GROUND_TITLE_DEBTS,
GROUND_TITLE_SITS_ON,
JUNIOR_NO_STEPS,
JUNIOR_ORDER_LEAD,
LEVEL_QUESTIONS,
LIMIT_CALLS_DEDUPLICATED,
LIMIT_NO_HANDLER_SITES,
LIMIT_NO_ROUTES,
LIMIT_NO_TEST_RELATION,
STEP_CONNECTIVES,
STEP_CONNECTIVE_LAST,
TERM_EXPLANATIONS,
absenceSentence,
costWeight,
debtBranches,
debtLoopDepth,
groundReach,
juniorStep,
juniorStepAt,
limitGeneration,
limitOfFamily
} from './strings';
import type { ImportsGroup } from '../pseudocode/imports-group';
import {
buildSections,
displayFile,
evidenceFor,
importsSection,
locationLabel,
refAt,
runtimeSection,
stepTarget
} from './twin-view-model';
import type { TwinRow, TwinSection } from './twin-view-model';
/**
* How the twin's body is laid out for one reader.
*
* Five modes rather than a level number, because a widget rendering JSX should
* not be doing arithmetic on a scale whose meaning lives here. The names are
* about shape and not about the reader: `cost` is what the senior's level looks
* like, and a second reader who wanted that shape would get the same word.
*/
export type TwinRenderMode = 'prose' | 'guided' | 'sections' | 'cost' | 'ground';
/** A clickable name in the narrative depth. Plain name only, never qualified. */
export interface TwinChip {
label: string;
target?: SymbolRef;
}
/** One line of the guided depth's short list. */
export interface TwinFactRow {
id: string;
/** Which family this came from, in the active terminology. */
label: string;
/** The plain name of the thing, exactly as the code spells it. */
name: string;
target?: SymbolRef;
/** Address of this row's citation inside the IR. */
factPath: string;
}
/** One call, in the order the body reaches it, with the word that joins it on. */
export interface TwinStepLine {
id: string;
/** 1-based position in the reading order. */
order: number;
/** The whole sentence, connective included. */
text: string;
target?: SymbolRef;
factPath: string;
}
/** A word this level used, explained once. */
export interface TwinTerm {
term: string;
explanation: string;
}
/**
* One question inside a level, with what the index answers to it.
*
* The same shape carries the senior's four costs and the architect's three
* grounds, and that is deliberate: they are the same idea (a question, the
* sentence that frames it, the rows that answer it, and what to say when there
* are none) asked by two different people, and two near-identical types would
* be two places to forget the empty sentence.
*/
export interface TwinReaderBlock {
name: string;
title: string;
/** What this block is, in this reader's voice. Never blank. */
lead: string;
rows: TwinRow[];
/** What it says when there are no rows. Never blank. */
emptyText: string;
/** How much work this block implies, worded. Absent when there is none. */
weight?: string;
}
/** One thing this page cannot tell the architect, and why. */
export interface TwinLimit {
id: string;
text: string;
/**
* Where the limit comes from.
*
* - `state`: a fact family this index did not answer for this symbol.
* - `engine`: something this engine does not record for anybody.
* - `generation`: the age of the build everything above was read from.
*/
kind: 'state' | 'engine' | 'generation';
}
/** Everything the twin's body needs, already shaped for one reader. */
export interface TwinViewModel {
mode: TwinRenderMode;
depth: DepthLevel;
terminology: TerminologyLevel;
/**
* The question this level answers, said out loud before it answers it.
*
* Present on every level, and it is the one element every level has: a
* reader who moves the slider sees the question change before they have
* read a word of the body.
*/
question: string;
/** The exact symbol and source span every level is answering about. */
subject: string;
/** Short cross-cutting facts that remain visible in every level shape. */
context: string[];
/** Lead prose. Empty where the body leads with rows instead. */
paragraphs: string[];
/** Clickable names, vibe coder only. Empty everywhere else. */
chips: TwinChip[];
/** Honest sentences about what is absent, in this level's own vocabulary. */
notes: string[];
/** The ordered calls with their connectives, junior only. */
steps: TwinStepLine[];
/** The words the junior level used, explained once each. Junior only. */
terms: TwinTerm[];
/** The short list the guided level used to lead with. Empty everywhere now. */
facts: TwinFactRow[];
/** The full sections, medior only. Empty everywhere else. */
sections: TwinSection[];
/** The senior's costs, or the architect's grounds. Empty on the other three. */
blocks: TwinReaderBlock[];
/** Where this index stops, architect only. */
limits: TwinLimit[];
/**
* Every assembled sentence on this level, addressable by id.
*
* This is what the local model is allowed to reword and nothing else. Rows
* are not in it on purpose: a row is a name, a file and a line as the index
* spells them, and there is no rewording of `validate.ts:19` that is worth
* the risk of one.
*/
rewritable: ReaderLine[];
}
/**
* How many callees the narrative depth names.
*
* Five is where a sentence stops being a sentence. Past that the list is
* summarised, and the summary says how many were left out rather than trailing
* off, because "and more" is the kind of vagueness this panel exists to remove.
*/
export const MAX_PROSE_CHIPS = 5;
/** How many rows the guided depth leads with, for the same reason. */
export const MAX_GUIDED_FACTS = 5;
/**
* Which lenses can bring a section on screen.
*
* A section appears when any one of its facets is on. `steps` belongs to two of
* them on purpose: it is both the narrative of what the symbol does, which is
* Logic, and the list of what it calls, which is Calls. Making it belong to
* only one would mean a reader who asked for Calls and got no list of calls.
*/
const SECTION_FACETS: Readonly<Record<string, readonly Facet[]>> = {
purpose: [Facet.Logic],
steps: [Facet.Logic, Facet.Calls],
callers: [Facet.Calls],
state: [Facet.Data],
errors: [Facet.Errors],
// What a symbol writes, exposes and reaches is data crossing a boundary, so
// it follows the same lens as the data it holds. Giving effects a lens of
// their own would mean a reader who asked for Data and got told what the
// symbol reads but not what it writes.
effects: [Facet.Data],
tests: [Facet.Tests],
// A risk is a rule over calls and failure modes, so it follows whichever of
// the two the reader is looking through.
risks: [Facet.Logic, Facet.Errors]
};
/**
* The two lenses whose section is a heading and a sentence rather than facts.
*
* Runtime is only half a placeholder. When a recording has been imported the IR
* carries a `runtime` fact and the section is real; when it has not, the sentence
* below is what the reader gets, and it names the surface that does hold observed
* calls and the command that puts them in the index. Keeping both cases in one
* list is deliberate: the facet decides whether the section appears at all, and
* that decision must not depend on whether anybody has imported anything.
*/
const PLACEHOLDER_SECTIONS: readonly { name: string; facet: Facet; subject: string; sentence: string }[] = [
{ name: 'runtime', facet: Facet.Runtime, subject: SUBJECT_RUNTIME, sentence: RUNTIME_NOT_IN_TWIN },
{ name: 'changes', facet: Facet.Changes, subject: SUBJECT_CHANGES, sentence: CHANGES_NOT_IN_TWIN }
];
/**
* The whole body of the twin for one reader.
*
* Never throws and never returns nothing: an IR with every family empty still
* produces a mode, a question, a paragraph or a set of headings, and the
* sentences that explain the emptiness.
*/
export function buildTwinViewModel(ir: SemanticIR, presentation: ResolvedPresentation): TwinViewModel {
switch (presentation.depth) {
case 0:
return narrative(ir, presentation);
case 1:
return junior(ir, presentation);
case 3:
return senior(ir, presentation);
case 4:
return architect(ir, presentation);
default:
return technical(ir, presentation);
}
}
/**
* The fields every level shares, so a new level cannot forget one.
*
* A builder that returned an object literal of its own would be one `terms: []`
* away from an undefined array in a renderer, and the renderer would find out
* about it in a browser rather than in a type error.
*/
function emptyModel(
ir: SemanticIR,
presentation: ResolvedPresentation,
mode: TwinRenderMode,
): TwinViewModel {
return {
mode,
depth: presentation.depth,
terminology: presentation.terminology,
question: LEVEL_QUESTIONS[presentation.depth] ?? '',
subject: subjectLine(ir),
context: contextLines(ir, presentation.facets),
paragraphs: [],
chips: [],
notes: [],
steps: [],
terms: [],
facts: [],
sections: [],
blocks: [],
limits: [],
rewritable: []
};
}
// ---------------------------------------------------------------------------
// section selection, shared by every depth
// ---------------------------------------------------------------------------
/** True when the reader has asked for at least one of the lenses this section answers. */
function sectionVisible(name: string, facets: ReadonlySet<Facet>): boolean {
const owners = SECTION_FACETS[name];
// A section nobody claimed is shown: a new family should be visible by
// default rather than invisible until somebody remembers to map it.
return owners === undefined || owners.some(facet => facets.has(facet));
}
function labelsFor(terminology: TerminologyLevel): Readonly<Record<string, string>> {
return terminology === 'plain' ? SECTION_LABELS_PLAIN : SECTION_LABELS_TECHNICAL;
}
/**
* One placeholder section: a heading, and the sentence saying that this panel
* does not answer the lens behind it and which surface does.
*
* The row carries an empty fact path, which is how the renderer knows there is
* no citation to offer. An evidence button over a claim CodeAtlas has not made
* would be an affordance that leads nowhere.
*/
function placeholderSection(
spec: { name: string; subject: string; sentence: string },
labels: Readonly<Record<string, string>>
): TwinSection {
return {
name: spec.name,
title: labels[spec.name] ?? spec.name,
subject: spec.subject,
icon: SECTION_ICONS[spec.name],
state: 'unsupported',
stateNote: LENS_ANSWERED_ELSEWHERE_NOTE,
factPath: '',
rows: [{ id: `${spec.name}-placeholder`, label: spec.sentence, factPath: '' }],
emptyText: spec.sentence,
populated: false
};
}
/**
* The sections this presentation shows, titled in its terminology.
*
* A section with no rows and no sentence is dropped here rather than in the
* widget: a heading over nothing is exactly the shape this panel avoids, and
* deciding it in one place keeps the depths from disagreeing about it.
*/
export function visibleSections(ir: SemanticIR, presentation: ResolvedPresentation): TwinSection[] {
const labels = labelsFor(presentation.terminology);
const sections: TwinSection[] = buildSections(ir)
.filter(section => sectionVisible(section.name, presentation.facets))
.filter(section => section.populated || section.emptyText.length > 0)
.map(section => ({
...section,
title: labels[section.name] ?? section.title,
icon: SECTION_ICONS[section.name]
}));
for (const spec of PLACEHOLDER_SECTIONS) {
if (!presentation.facets.has(spec.facet)) {
continue;
}
// A lens with something behind it renders what is behind it. The
// placeholder is the fallback and not the default: a reader who has
// imported a recording must not be told the lens is unbuilt.
const answered = spec.name === 'runtime' ? runtimeSection(ir) : undefined;
sections.push(answered === undefined
? placeholderSection(spec, labels)
: { ...answered, title: labels[answered.name] ?? answered.title, icon: SECTION_ICONS[answered.name] });
}
return sections;
}
/**
* The same body, with the file's imports folded into the DATA block.
*
* A second pass rather than an argument to {@link buildTwinViewModel}, and the
* reason is that the imports are not in the IR. They are a file-level answer
* that arrives on its own round trip, later than the document the rest of this
* file is a function of, and threading an optional late arrival through four
* depth builders would make every one of them a function of two things instead
* of one. This way the depths stay pure functions of the IR and the panel adds
* what it has when it has it.
*
* Three rules, all of them the same rules the sections above follow.
*
* **The lens decides.** The group answers "what has this code been handed from
* outside itself", which is the Data lens, so a reader who turned Data off does
* not get it. Same rule as `state` and `effects`.
*
* **Only where a list of names is an answer.** The vibe coder and the junior
* spend their words on counts, order and consequences; a list of import names
* for the vibe coder would be exactly the identifier dump that level exists to
* remove. The other three each fold it into the block whose question it
* answers, which is why this function has three arms rather than one.
*
* **Beside the state section, never instead of it.** What a symbol reads and
* what its file pulls in are two answers to one question and are read together.
*/
export function withImportsSection(
model: TwinViewModel,
group: ImportsGroup | undefined,
presentation: ResolvedPresentation
): TwinViewModel {
if (group === undefined || !presentation.facets.has(Facet.Data)) {
return model;
}
const labels = labelsFor(presentation.terminology);
const built = importsSection(group);
if (model.mode === 'ground') {
/*
* For the architect the imports are not a section beside the others.
* They are half the answer to "what does this sit on": a name the file
* pulls in is a dependency the index cannot see a call to, and putting
* it in a list of its own would leave the ground block claiming a
* shorter foundation than the file really has.
*/
const at = model.blocks.findIndex((block) => block.name === 'sits-on');
if (at < 0) {
return model;
}
const rows = [
...model.blocks[at].rows,
...built.rows.map((row) => ({ ...row, id: `import-${row.id}`, group: built.title }))
];
const blocks = [...model.blocks];
blocks[at] = {
...blocks[at],
rows,
...(rows.length > 0 ? { weight: rowCountLabel(rows.length) } : {})
};
return { ...model, blocks };
}
if (model.mode === 'cost') {
/*
* For the senior they belong to what a change drags with it, for the
* same reason: a name the file pulls in moves when the file moves, and
* the senior is the reader counting the places they have to look.
*/
const at = model.blocks.findIndex((block) => block.name === 'moves');
if (at < 0) {
return model;
}
const rows = [
...model.blocks[at].rows,
...built.rows.map((row) => ({ ...row, id: `import-${row.id}`, group: built.title }))
];
const blocks = [...model.blocks];
blocks[at] = {
...blocks[at],
rows,
...(rows.length > 0 ? { weight: costWeight(rows.length) } : {})
};
return { ...model, blocks };
}
if (model.mode !== 'sections') {
return model;
}
const section: TwinSection = {
...built,
title: labels[built.name] ?? built.title,
icon: SECTION_ICONS[built.name]
};
const at = model.sections.findIndex(entry => entry.name === 'state');
const sections = [...model.sections];
sections.splice(at < 0 ? sections.length : at + 1, 0, section);
return { ...model, sections, rewritable: sectionLines(sections) };
}
// ---------------------------------------------------------------------------
// level 2, medior: the recorded facts, as they are
// ---------------------------------------------------------------------------
/**
* The assembled sentences of a set of sections, in reading order.
*
* A section's own paragraph and its empty sentence are the only two things on
* this level that CodeAtlas wrote rather than read, so they are the only two a
* rewrite may touch. The rows are the index's own spelling and stay out of it.
*/
function sectionLines(sections: readonly TwinSection[]): ReaderLine[] {
return readerLines(sections.flatMap((section) => [
{ id: `section-${section.name}-text`, text: section.text ?? '' },
{ id: `section-${section.name}-empty`, text: section.rows.length === 0 ? section.emptyText : '' },
{ id: `section-${section.name}-note`, text: section.note ?? '' }
]));
}
function technical(ir: SemanticIR, presentation: ResolvedPresentation): TwinViewModel {
const sections = visibleSections(ir, presentation);
return {
...emptyModel(ir, presentation, 'sections'),
sections,
rewritable: sectionLines(sections)
};
}
// ---------------------------------------------------------------------------
// what a reviewer wants appended to a row, wherever a row is shown to one
// ---------------------------------------------------------------------------
/**
* The call site a row came from, when it came from one.
*
* Steps are the only family whose records carry a resolution confidence and a
* strategy of their own; everything else has to fall back to its citation.
*/
function callFor(ir: SemanticIR, factPath: string): CallSite | undefined {
const match = /^steps\[(\d+)\]$/.exec(factPath);
return match ? ir.steps.value[Number(match[1])] : undefined;
}
/**
* How certain one row is, worded, whether or not anyone put a number on it.
*
* The 0.9.0 engine scores nothing: it reads its call, caller and raise
* relations straight off the graph, so a recorded confidence is absent because
* there was never anything to score rather than because a field went missing.
* Rendering a blank there would leave a reviewer unable to tell that apart from
* a derived claim nobody scored, so both say which one they are.
*/
function certaintyOf(confidence: number | undefined, state: KnowledgeState): { label: string; note: string } {
if (confidence !== undefined) {
return { label: confidenceLabel(confidence), note: CONFIDENCE_SCORED_TOOLTIP };
}
return state === 'known'
? { label: CONFIDENCE_EXACT, note: CONFIDENCE_EXACT_TOOLTIP }
: { label: CONFIDENCE_UNSCORED, note: CONFIDENCE_UNSCORED_TOOLTIP };
}
/**
* One row, with what a reviewer needs appended to it.
*
* Confidence stays a number on the row as well as a label: the renderer puts it
* in its own element so it can be found, checked and styled as the qualified
* claim it is, and a consumer that wants to threshold on it does not have to
* parse a sentence.
*/
function densifyRow(ir: SemanticIR, row: TwinRow, state: KnowledgeState): TwinRow {
// A row with no fact path makes no claim about the code, so it has no
// certainty to report and no citations to count.
if (row.factPath.length === 0) {
return row;
}
const citations = evidenceFor(ir, row.factPath);
const call = callFor(ir, row.factPath);
const confidence = call?.confidence ?? citations[0]?.confidence;
const strategy = call?.strategy ?? citations[0]?.strategy;
const certainty = certaintyOf(confidence, state);
const extras: string[] = [];
if (strategy !== undefined) {
extras.push(strategyLabel(strategy));
}
if (citations.length > 0) {
extras.push(citationCount(citations.length));
}
return {
...row,
confidence,
confidenceLabel: certainty.label,
confidenceNote: certainty.note,
extras: extras.length > 0 ? extras : undefined
};
}
// ---------------------------------------------------------------------------
// level 1, junior: the order, the connective between the steps, and the words
// ---------------------------------------------------------------------------
/**
* The lead paragraph, assembled from the clauses the active lenses allow.
*
* Each clause is gated by the facet that owns its fact, so a reader who turned
* Data off is not told how many environment values there are. The alternative,
* one fixed sentence over all three counts, would quietly reintroduce the facts
* the facets were asked to remove.
*/
function overviewClauses(ir: SemanticIR, facets: ReadonlySet<Facet>): string[] {
const clauses = [proseLead(ir.symbol.name, ir.symbol.kind)];
const absent: string[] = [];
if (facets.has(Facet.Logic) || facets.has(Facet.Calls)) {
const callees = ir.steps.value.map((call) => call.targetName).filter((name) => name.length > 0);
if (callees.length > 0) {
clauses.push(proseCalls(ir.symbol.name, callees));
} else {
absent.push('outgoing call');
}
}
if (facets.has(Facet.Data)) {
const reads = ir.reads.value.map((entry) => entry.name).filter((name) => name.length > 0);
if (reads.length > 0) {
clauses.push(proseReads(ir.symbol.name, reads));
} else if (sharedNames(ir).length === 0) {
absent.push('environment read');
}
}
if (facets.has(Facet.Errors)) {
const errors = ir.throws.value.map((entry) => entry.type).filter((name) => name.length > 0);
if (errors.length > 0) {
clauses.push(proseThrows(ir.symbol.name, errors));
} else {
absent.push('stopping error');
}
}
if (absent.length > 0) {
clauses.push(`The index records no ${joinNames(absent)} for ${ir.symbol.name}.`);
}
return clauses;
}
/** The first factual sentence on every level, including the positive leaf case. */
function subjectLine(ir: SemanticIR): string {
const lines = Math.max(1, ir.symbol.range.end.line - ir.symbol.range.start.line);
const file = displayFile(ir.symbol.uri) ?? ir.symbol.uri;
if (ir.steps.value.length === 0) {
return `${ir.symbol.name} is a ${plainKind(ir.symbol.kind)} spanning ${lines} lines in ${file}. `
+ 'The index resolves no outgoing calls from this symbol.';
}
const start = ir.symbol.range.start.line + 1;
const end = ir.symbol.range.end.line;
return `${ir.symbol.name} is a ${plainKind(ir.symbol.kind)} spanning ${lines} lines in ${file}, `
+ `from line ${start} through line ${end}.`;
}
/** Type references whose declaration lies outside the focused symbol. */
function sharedNames(ir: SemanticIR): string[] {
const start = ir.symbol.range.start.line + 1;
const end = ir.symbol.range.end.line;
const names = (ir.typeRefs?.value ?? [])
.filter((entry) => entry.file !== ir.symbol.uri
|| entry.line === undefined
|| entry.line < start
|| entry.line > end)
.map((entry) => entry.name)
.filter((name) => name.length > 0);
return [...new Set(names)];
}
/** Facts whose impact is useful before any level-specific shape begins. */
function contextLines(ir: SemanticIR, facets: ReadonlySet<Facet>): string[] {
const lines: string[] = [];
if (facets.has(Facet.Data)) {
const names = sharedNames(ir);
if (names.length > 0) {
lines.push(`${ir.symbol.name} leans on shared names declared outside its own lines: ${joinNames(names)}.`);
}
}
if (facets.has(Facet.Calls) && ir.calledBy.value.length > 0) {
const callers = ir.calledBy.value.map((caller) => callerLabel(caller.name)).filter((name) => name.length > 0);
lines.push(`${callers.length} callers reach ${ir.symbol.name}: ${joinNames(callers)}.`);
}
return lines;
}
/** Module callers are shown as plain labels, never as path-shaped jargon. */
function callerLabel(name: string): string {
if (!name.includes('/') && !/\.(?:[cm]?[jt]sx?)$/.test(name)) {
return name;
}
const base = name.split('/').filter((part) => part.length > 0).at(-1) ?? name;
return base.replace(/\.(?:[cm]?[jt]sx?)$/, '').replace(/[._-]+/g, ' ');
}
/**
* The breadth-first short list the guided level used to lead with.
*
* One row from each visible family before a second row from any of them. Not
* built for any level since W13: the junior's question is about order, and a
* breadth-first sample of five families is the one shape that answers every
* question except that one. It is kept, exported and tested because it is the
* right answer to "show me a little of everything", which is a question a
* future surface will ask, and rebuilding it from the same three rules later
* would be rebuilding a thing that already worked.
*/
export function topFacts(sections: TwinSection[], limit: number): TwinFactRow[] {
const queues = sections.filter(section => section.rows.length > 0);
const facts: TwinFactRow[] = [];
for (let round = 0; facts.length < limit; round++) {
let took = false;
for (const section of queues) {
const row = section.rows[round];
if (row === undefined) {
continue;
}
took = true;
facts.push({
id: `${section.name}-${row.id}`,
label: section.title,
name: row.label,
target: row.target,
factPath: row.factPath
});
if (facts.length === limit) {
return facts;
}
}
if (!took) {
return facts;
}
}
return facts;
}
/**
* The sentences a family's emptiness deserves.
*
* A level that shows no sections shows no empty sentence either, and without
* this "no test caller was found" would be visible for the medior and invisible
* for the junior, which would make the slider hide a finding rather than choose
* one.
*/
function emptyNotes(sections: TwinSection[]): string[] {
return sections
.filter(section => section.rows.length === 0 && section.emptyText.length > 0)
.map(section => section.emptyText);
}
/**
* The calls in the order the body reaches them, joined by a word.
*
* The connective is the whole point of this level and it is also the place
* where a builder is most tempted to lie. "First", "then", "after that" are
* claims about order, and order is exactly what the index records: the call
* sites arrive in source order. "Because" and "so that" would be claims about
* intent, and nothing in the index knows the intent, so no word here implies
* one.
*
* Duplicate targets are kept. The vibe coder's chips drop them because a
* sentence naming the same function twice reads badly; a numbered order that
* dropped one would be a different order from the one the code runs.
*/
function juniorSteps(ir: SemanticIR): TwinStepLine[] {
const calls = ir.steps.value;
return calls.map((call, index) => {
const last = index === calls.length - 1 && calls.length > 1;
const connective = index === 0
? STEP_CONNECTIVES[0]
: (last ? STEP_CONNECTIVE_LAST : STEP_CONNECTIVES[1 + ((index - 1) % (STEP_CONNECTIVES.length - 1))]);
const where = locationLabel(call.targetFile, call.targetLine ?? call.line);
return {
id: `s${index}`,
order: index + 1,
text: `${juniorStep(connective, call.targetName)}${where === undefined ? '' : juniorStepAt(where)}.`,
target: stepTarget(call),
factPath: `steps[${index}]`
};
});
}
/**
* The words this level used, explained once each, and only the ones it used.
*
* Tied to what is on screen rather than to a fixed vocabulary list: a glossary
* that explains "entry point" on a symbol that is not one is a page of reading
* in front of the answer, and it teaches the junior that the panel talks past
* them.
*/
function juniorTerms(ir: SemanticIR, facets: ReadonlySet<Facet>): TwinTerm[] {
const wanted: string[] = [];
const add = (term: string): void => {
if (TERM_EXPLANATIONS[term] !== undefined && !wanted.includes(term)) {
wanted.push(term);
}
};
if (ir.steps.value.length > 0 && (facets.has(Facet.Logic) || facets.has(Facet.Calls))) {
add('call site');
}
if (facets.has(Facet.Calls) && ir.calledBy.value.length > 0) {
add('caller');
}
if (facets.has(Facet.Errors) && ir.throws.value.length > 0) {
add('raise');
}
if (facets.has(Facet.Data) && ir.reads.value.length > 0) {
add('environment read');
}
if (facets.has(Facet.Tests) && ir.tests.value.length > 0) {
add('test caller');
}
if (ir.complexity.state === 'known' && ir.complexity.value.isEntryPoint) {
add('entry point');
}
return wanted.map((term) => ({ term, explanation: TERM_EXPLANATIONS[term] }));
}
function junior(ir: SemanticIR, presentation: ResolvedPresentation): TwinViewModel {
const facets = presentation.facets;
const sections = visibleSections(ir, presentation);
const showSteps = facets.has(Facet.Logic) || facets.has(Facet.Calls);
const steps = showSteps ? juniorSteps(ir) : [];
const paragraphs = [overviewClauses(ir, facets).join(' ')];
if (showSteps) {
// The lead is only honest when there is an order to lead into, and the
// sentence about there being none is honest only when the reader asked
// for the lens that would have shown one.
paragraphs.push(steps.length > 0 ? JUNIOR_ORDER_LEAD : JUNIOR_NO_STEPS);
}
const notes = emptyNotes(sections);
return {
...emptyModel(ir, presentation, 'guided'),
paragraphs,
notes,
steps,
terms: juniorTerms(ir, facets),
rewritable: readerLines([
...paragraphs.map((text, index) => ({ id: `p${index}`, text })),
...steps.map((step) => ({ id: step.id, text: step.text })),
...notes.map((text, index) => ({ id: `n${index}`, text }))
])
};
}
// ---------------------------------------------------------------------------
// level 3, senior: what it costs
// ---------------------------------------------------------------------------
/**
* One cost block, built from sections that are already there.
*
* `undefined` when the lens behind it is off, which is how a facet keeps
* subtracting on this level too. An empty block is not the same thing: a lens
* that is on and found nothing renders its heading and the sentence saying so.
*/
function costBlock(
sections: readonly TwinSection[],
name: string,
title: string,
lead: string,
emptyText: string,
from: readonly string[]
): TwinReaderBlock | undefined {
const used = from
.map((sectionName) => sections.find((section) => section.name === sectionName))
.filter((section): section is TwinSection => section !== undefined);
if (used.length === 0) {
return undefined;
}
// Rows from more than one family keep the family name as their group, so a
// reader can see that "what moves" is three questions answered together.
const rows: TwinRow[] = used.flatMap((section) => section.rows.map((row) => ({
...row,
id: `${section.name}-${row.id}`,
group: used.length > 1 ? section.title : row.group
})));
return {
name,
title,
lead,
rows,
emptyText,
...(rows.length > 0 ? { weight: costWeight(rows.length) } : {})
};
}
function senior(ir: SemanticIR, presentation: ResolvedPresentation): TwinViewModel {
const sections = visibleSections(ir, presentation);
const blocks = [
costBlock(sections, 'fails', COST_TITLE_FAILS, COST_LEAD_FAILS, COST_EMPTY_FAILS, ['errors']),
costBlock(sections, 'unchecked', COST_TITLE_UNTESTED, COST_LEAD_UNTESTED, COST_EMPTY_UNTESTED, ['tests']),
costBlock(sections, 'depends', COST_TITLE_DEPENDS, COST_LEAD_DEPENDS, COST_EMPTY_DEPENDS, ['callers']),
costBlock(sections, 'moves', COST_TITLE_MOVES, COST_LEAD_MOVES, COST_EMPTY_MOVES,
['steps', 'state', 'imports', 'effects'])
].filter((block): block is TwinReaderBlock => block !== undefined);
// The risks the medior sees as a section are consequences, so they are said
// here as sentences beside the blocks rather than as a fourth list.
const notes = sections
.filter((section) => section.name === 'risks')
.flatMap((section) => section.rows.map((row) => row.label));
return {
...emptyModel(ir, presentation, 'cost'),
notes,
blocks,
rewritable: readerLines([
...blocks.flatMap((block) => [
{ id: `block-${block.name}-lead`, text: block.lead },
{ id: `block-${block.name}-empty`, text: block.rows.length === 0 ? block.emptyText : '' }
]),
...notes.map((text, index) => ({ id: `n${index}`, text }))
])
};
}
// ---------------------------------------------------------------------------
// level 4, architect: the ground, the carriers, the debts, and the edge
// ---------------------------------------------------------------------------
/**
* The module a call lands in, as a reader would name it.
*
* The last two segments of the recorded path, which is enough to tell
* `util/validate.ts` from `repo/validate.ts` and short enough to read in a
* column. The whole recorded path is on the row's detail, so nothing is hidden,
* only folded.
*/
function moduleLabel(uri: string): string {
const path = uri.split('?')[0].split('#')[0];
const segments = path.split('/').filter((part) => part.length > 0);
return segments.slice(-2).join('/') || (displayFile(uri) ?? uri);
}
/**
* What this symbol sits on: one row per module, with how many call sites reach
* into it.
*
* A module reached from six places and a module reached once are two different
* relationships, and a flat list of twenty call sites hides which is which.
* That is the whole difference between this and the medior's step list: same
* facts, grouped by the thing the architect is asking about.
*/
function groundRows(ir: SemanticIR): TwinRow[] {
const byModule = new Map<string, { calls: CallSite[]; firstIndex: number }>();
ir.steps.value.forEach((call, index) => {
const key = call.targetFile;
if (key === undefined || key.length === 0) {
return;
}
const entry = byModule.get(key);
if (entry === undefined) {
byModule.set(key, { calls: [call], firstIndex: index });
} else {
entry.calls.push(call);
}
});
return [...byModule.entries()].map(([uri, entry]) => {
const certainty = certaintyOf(
entry.calls.find((call) => call.confidence !== undefined)?.confidence,
ir.steps.state
);
const strategy = entry.calls.find((call) => call.strategy !== undefined)?.strategy;
return {
id: `ground-${entry.firstIndex}`,
label: moduleLabel(uri),
detail: entry.calls.map((call) => call.targetName).join(', '),
target: refAt(uri, entry.calls[0].targetLine ?? entry.calls[0].line, moduleLabel(uri)),
factPath: `steps[${entry.firstIndex}]`,
confidenceLabel: certainty.label,
confidenceNote: certainty.note,
extras: [
groundReach(entry.calls.length),
...(strategy === undefined ? [] : [strategyLabel(strategy)])
]
};
});
}
/** What holds this symbol up: its callers, plus what the outside world can reach. */
function carrierRows(ir: SemanticIR, sections: readonly TwinSection[]): TwinRow[] {
const callers = sections.find((section) => section.name === 'callers');
const rows: TwinRow[] = (callers?.rows ?? []).map((row) => densifyRow(ir, row, callers?.state ?? 'unknown'));
if (ir.complexity.state === 'known') {
const flags = ir.complexity.value;
rows.push({
id: 'carrier-reach',
label: flags.isEntryPoint
? GROUND_ENTRY_POINT
: (flags.isExported ? GROUND_EXPORTED : GROUND_NOT_EXPORTED),
factPath: 'complexity'
});
}
return rows;
}
/** What this symbol owes: the rules that fired, and the shapes that cost. */
function debtRows(ir: SemanticIR, sections: readonly TwinSection[]): TwinRow[] {
const risks = sections.find((section) => section.name === 'risks');
const rows: TwinRow[] = (risks?.rows ?? []).map((row) => ({ ...row, id: `debt-${row.id}` }));
// Structural flags are only said when somebody measured them. This engine
// reports `complexity` as unsupported for TypeScript, and a zero read off an
// unsupported family is not a zero, it is a blank.
if (ir.complexity.state === 'known') {
const flags = ir.complexity.value;
const said: string[] = [];
if (flags.unguardedRecursion) {
said.push(DEBT_UNGUARDED_RECURSION);
} else if (flags.recursive) {
said.push(DEBT_RECURSIVE);
}
if (flags.linearScanInLoop) {
said.push(DEBT_SCAN_IN_LOOP);
}
if (flags.allocInLoop) {
said.push(DEBT_ALLOC_IN_LOOP);
}
if (flags.loopDepth > 1) {
said.push(debtLoopDepth(flags.loopDepth));
}
if (flags.cyclomatic > 1) {
said.push(debtBranches(flags.cyclomatic));
}
rows.push(...said.map((label, index) => ({
id: `debt-flag-${index}`,
label,
factPath: 'complexity'
})));
}
return rows;
}
/**
* Where this index stops, as a list a reader can count.
*
* Three kinds, and the difference between them is the whole value of the block:
* a family this build did not answer for this symbol is a gap somebody could
* close by indexing again; something the engine does not record for anybody is a
* gap nobody can close from here; and the generation is the age of every
* sentence above it.
*/
function indexLimits(ir: SemanticIR, facets: ReadonlySet<Facet>): TwinLimit[] {
const limits: TwinLimit[] = [];
const families: { key: string; subject: string; state: KnowledgeState }[] = [
{ key: 'purpose', subject: SUBJECT_PURPOSE, state: ir.purpose.state },
{ key: 'steps', subject: SUBJECT_STEPS, state: ir.steps.state },
{ key: 'callers', subject: SUBJECT_CALLERS, state: ir.calledBy.state },
{ key: 'state', subject: SUBJECT_STATE, state: ir.reads.state },
{ key: 'errors', subject: SUBJECT_ERRORS, state: ir.throws.state },
{ key: 'effects', subject: SUBJECT_EFFECTS, state: ir.externalEffects.state },
{ key: 'tests', subject: SUBJECT_TESTS, state: ir.tests.state }
];
for (const family of families) {
const sentence = absenceSentence(family.state, family.subject);
if (sentence.length > 0) {
limits.push({ id: `limit-${family.key}`, kind: 'state', text: limitOfFamily(family.subject, sentence) });
}
}
for (const [index, sentence] of [
LIMIT_NO_TEST_RELATION,
LIMIT_NO_HANDLER_SITES,
LIMIT_NO_ROUTES,
LIMIT_CALLS_DEDUPLICATED
].entries()) {
limits.push({ id: `limit-engine-${index}`, kind: 'engine', text: sentence });
}
for (const spec of PLACEHOLDER_SECTIONS) {
if (facets.has(spec.facet)) {
limits.push({ id: `limit-lens-${spec.name}`, kind: 'engine', text: spec.sentence });
}
}
limits.push({ id: 'limit-generation', kind: 'generation', text: limitGeneration(ir.generation) });
return limits;
}
function architect(ir: SemanticIR, presentation: ResolvedPresentation): TwinViewModel {
const facets = presentation.facets;
const sections = visibleSections(ir, presentation);
const blocks: TwinReaderBlock[] = [];
if (facets.has(Facet.Logic) || facets.has(Facet.Calls)) {
const rows = groundRows(ir);
blocks.push({
name: 'sits-on',
title: GROUND_TITLE_SITS_ON,
lead: GROUND_LEAD_SITS_ON,
rows,
emptyText: GROUND_EMPTY_SITS_ON,
...(rows.length > 0 ? { weight: rowCountLabel(rows.length) } : {})
});
}
if (facets.has(Facet.Calls)) {
const rows = carrierRows(ir, sections);
blocks.push({
name: 'carried-by',
title: GROUND_TITLE_CARRIED,
lead: GROUND_LEAD_CARRIED,
rows,
emptyText: GROUND_EMPTY_CARRIED,
...(rows.length > 0 ? { weight: rowCountLabel(rows.length) } : {})
});
}
if (facets.has(Facet.Logic) || facets.has(Facet.Errors)) {
const rows = debtRows(ir, sections);
blocks.push({
name: 'debts',
title: GROUND_TITLE_DEBTS,
lead: GROUND_LEAD_DEBTS,
rows,
emptyText: GROUND_EMPTY_DEBTS,
...(rows.length > 0 ? { weight: rowCountLabel(rows.length) } : {})
});
}
const limits = indexLimits(ir, facets);
return {
...emptyModel(ir, presentation, 'ground'),
blocks,
limits,
rewritable: readerLines([
...blocks.flatMap((block) => [
{ id: `block-${block.name}-lead`, text: block.lead },
{ id: `block-${block.name}-empty`, text: block.rows.length === 0 ? block.emptyText : '' }
]),
{ id: 'limits-lead', text: GROUND_LEAD_LIMITS },
...limits.map((limit) => ({ id: limit.id, text: limit.text }))
])
};
}
// ---------------------------------------------------------------------------
// level 0, vibe coder: prose, counts, and the handful of names worth clicking
// ---------------------------------------------------------------------------
/** Distinct callees in the order the body reaches them, capped. */
function proseChips(ir: SemanticIR, limit: number): { chips: TwinChip[]; hidden: number } {
const seen = new Set<string>();
const distinct: CallSite[] = [];
for (const call of ir.steps.value) {
const key = call.targetQualifiedName ?? call.targetName;
if (key.length === 0 || seen.has(key)) {
continue;
}
seen.add(key);
distinct.push(call);
}
return {
chips: distinct.slice(0, limit).map(call => ({ label: call.targetName, target: stepTarget(call) })),
hidden: Math.max(0, distinct.length - limit)
};
}
/**
* One honest sentence about whether anything tests this, in plain words.
*
* Never "not tested". The engine records no test relation for TypeScript, so
* this is a search through callers that found none, and the sentence says which
* of the two it is.
*/
function testsNote(ir: SemanticIR): string {
if (ir.tests.value.length > 0) {
return proseTestsSome(ir.tests.value.length);
}
const absence = plainAbsence(ir.tests.state, PLAIN_SUBJECT_TESTS);
return ir.tests.state === 'known' || ir.tests.state === 'inferred'
? PROSE_TESTS_NONE
: absence;
}
/** The same, for failure: an empty list is only a finding once someone looked. */
function errorsNote(ir: SemanticIR): string {
if (ir.throws.value.length > 0) {
return '';
}
return plainAbsence(ir.throws.state, PLAIN_SUBJECT_ERRORS);
}
function narrative(ir: SemanticIR, presentation: ResolvedPresentation): TwinViewModel {
const facets = presentation.facets;
const paragraphs = [overviewClauses(ir, facets).join(' ')];
const notes: string[] = [];
// The paragraph above was assembled from counts, and a reader who cannot
// see the sections cannot see that for themselves.
if (facets.has(Facet.Logic)) {
notes.push(PROSE_GENERATED_NOTE);
}
const showCallees = facets.has(Facet.Logic) || facets.has(Facet.Calls);
const { chips, hidden } = showCallees ? proseChips(ir, MAX_PROSE_CHIPS) : { chips: [], hidden: 0 };
if (chips.length > 0) {
paragraphs.push(PROSE_CHIPS_LEAD);
}
if (hidden > 0) {
notes.push(proseMoreParts(hidden));
}
if (facets.has(Facet.Errors)) {
const note = errorsNote(ir);
if (note.length > 0) {
notes.push(note);
}
}
if (facets.has(Facet.Tests)) {
const note = testsNote(ir);
if (note.length > 0) {
notes.push(note);
}
}
for (const spec of PLACEHOLDER_SECTIONS) {
if (!facets.has(spec.facet)) {
continue;
}
// The same rule the section list follows: a lens with an answer says its
// answer, and only a lens with none says it has none. At this depth the
// answer is a count and never a list of identifiers, which is what the
// narrative depth is for.
const answered = spec.name === 'runtime' ? runtimeSection(ir) : undefined;
notes.push(answered === undefined
? spec.sentence
: (answered.text ?? answered.emptyText));
}
return {
...emptyModel(ir, presentation, 'prose'),
paragraphs,
chips,
notes,
rewritable: readerLines([
...paragraphs.map((text, index) => ({ id: `p${index}`, text })),
...notes.map((text, index) => ({ id: `n${index}`, text }))
])
};
}
/**
* Everything this model puts in front of a reader, as one string.
*
* Used by the depth tests to assert what the narrative depth may not say. It is
* deliberately the visible text and not a serialisation of the whole object: a
* chip carries a navigation target whose qualified name is how the twin follows
* it, and that name is metadata the reader never sees. Asserting over the
* object would either fail on data that is never rendered or force the chips to
* drop the identity that makes them clickable.
*/
export function visibleTextOf(model: TwinViewModel): string {
const parts = [
model.question,
model.subject,
...model.context,
...model.paragraphs,
...model.notes,
...model.chips.map(chip => chip.label),
...model.steps.map(step => step.text),
...model.terms.flatMap(term => [term.term, term.explanation]),
...model.facts.flatMap(fact => [fact.label, fact.name]),
...model.limits.map(limit => limit.text)
];
for (const block of model.blocks) {
parts.push(block.title, block.lead, block.weight ?? '');
if (block.rows.length === 0) {
parts.push(block.emptyText);
}
for (const row of block.rows) {
parts.push(
row.group ?? '',
row.label,
row.detail ?? '',
row.badge?.text ?? '',
row.confidenceLabel ?? '',
...(row.extras ?? [])
);
}
}
for (const section of model.sections) {
parts.push(
section.title,
section.text ?? '',
section.stateNote ?? '',
section.countLabel ?? '',
// The sentence about the half of a section the index cannot see is
// on screen beside the rows, so it is part of what the reader is
// being told and belongs in what the depth tests assert over.
section.note ?? ''
);
// Same rule the renderer follows: the absence sentence is on screen
// only when there is nothing else in the section.
if (section.rows.length === 0) {
parts.push(section.emptyText);
}
for (const row of section.rows) {
parts.push(row.label, row.detail ?? '', row.badge?.text ?? '', row.confidenceLabel ?? '', ...(row.extras ?? []));
}
}
return parts.filter(part => part.length > 0).join('\n');
}