Language Plugin Interface
Definition of the plugin interface for adding a new language to Aburi's extraction pipeline. One language plugin is responsible for one language id (e.g. ts / py / go) and produces Symbol candidates and AST metadata from source strings.
References:
ir-schema.md— the structure of the Symbols to producefingerprint.md§5 — the input contract for the syntax fingerprintextension-vocab.md— manifest and vocab registrationdrop-list.md— where drops are applied
1. Purpose
Keep the extraction pipeline language-agnostic while accommodating each language's AST shape, naming conventions, and syntactic sugar.
The core (@aburi/core) knows nothing about languages. It receives input normalized into the common Symbol shape and performs effect classification, decoration removal, fingerprint computation, and diff computation.
2. Plugin Responsibilities
2.1 In scope
- Declare the file extensions of its language
- Parse sources and hold an internal AST
- Extract all Symbol candidates from the AST (drop determination is the core's job, but the plugin must provide all the material for it)
- Extract each Symbol's Signature, Decorator, Visibility, SourceRange, qualified name, and derivedBy (language-level)
- Walk each Symbol body and extract Rules and call_expressions
- Produce a normalized AST string per Symbol (the syntax fingerprint input)
- Extract import statements and return them as
ImportEdge[] - Report language-specific file-level / symbol-level drop hints to the core
2.2 Out of scope
- Effect classification (= responsibility of effect plugins)
- Boundary determination for decorators (= responsibility of framework plugins)
- Computing
Symbol.fingerprint.api/.logic(= the core computes these from the normalized IR) - Hashing
Symbol.fingerprint.syntax(= the core hashes the plugin's string output) - Applying config.suppress / config.keep (= the core does this during drop-list evaluation)
- Call resolution (filling in
calls[].resolved) - Building cross-language Dependencies (the core builds them from import edges)
- Generating the Markdown projection
Keeping the responsibilities narrow lets a new language addition focus solely on AST extraction.
3. Lifecycle
1. The registry validates the manifest and loads the plugin
2. plugin.init() is called with ctx (registry/config)
3. For each file matching the language:
a. plugin.parseFile(file) → ParseResult { tree, errors, imports }
b. plugin.extractSymbols(tree, ctx) → SymbolCandidate[]
c. For each SymbolCandidate:
plugin.walkBody(symbol, ctx) → BodyExtraction { rules, calls, returns }
plugin.normalizeAst(symbol) → string (syntax fingerprint input)
d. plugin.releaseTree?(tree) — on every way out of a–c, including a throw
plugin.createImportResolver?() runs at most once, the first time the core
follows a decorator's import through a non-relative specifier (§4.8, §5.2.4)
4. After all files, plugin.cleanup?() is calledThe core then performs effect classification, drop-list application, and fingerprint computation.
4. Interface
The actual types are defined in the types package of @aburi/core. This document shows the signatures as a contract.
4.1 LanguagePlugin
interface LanguagePlugin {
manifest: LangManifest // type: "lang"; languageId: e.g. "ts"
// file matching (extensions only, not globs)
fileExtensions: string[] // e.g. [".ts", ".tsx", ".mts", ".cts"]
// capabilities (§6)
capabilities: LanguageCapabilities
// lifecycle
init(ctx: PluginContext): Promise<void>
cleanup?(): Promise<void>
// extraction
parseFile(file: SourceFile): Promise<ParseResult>
releaseTree?(tree: ParsedTree): void // free the handed-over tree (§8.1); the core
// calls it once, after the last reader below
extractSymbols(tree: ParsedTree, ctx: ExtractionContext): SymbolCandidate[]
walkBody(symbol: SymbolCandidate, ctx: WalkContext): BodyExtraction
normalizeAst(symbol: SymbolCandidate): string
// per-file / per-symbol drop hints (optional)
fileDropPatterns?: string[] // language-specific globs (e.g. ["**/*.d.ts"])
symbolDropHint?(symbol: SymbolCandidate, ctx: ExtractionContext): DropHint | null
// where a non-relative specifier points in the workspace (optional, §4.8)
createImportResolver?(ctx: ImportResolverContext): ImportResolver
}The LanguageId a plugin owns is its manifest's languageId (extension-vocab.md §3.1). It is the prefix on every Symbol id the plugin produces and what the core projects into IR.workspace.languages, and it matches ^[a-z][a-z0-9]*$, so it is not the manifest name: lang-typescript is a plugin ref, ts is its language. It is a manifest field and not a field of the plugin object so that the registry checks it with the rest of the manifest, whatever language the plugin is written in. The registry refuses a lang manifest that declares none, one outside that grammar, the reserved slice, and a token another loaded plugin declared (multi-language-id.md Rules L-1, L-3, L-11). The core then refuses a Symbol id that opens with any other language (scan-plugin-misconfigured, §7.2), so the token a plugin declares and the token it writes are the same. scan checks the token's type itself as well, before it parses any file: a caller that hands plugins to scan without registering their manifests would otherwise get a message about "undefined" from the first Symbol id, or, with no file of that language, a Document that lists undefined among workspace.languages. A manifest with no string languageId ends the run with scan-plugin-misconfigured, naming the plugin (ML2e).
4.2 SourceFile / ParseResult
interface SourceFile {
path: RelativePath // workspace-relative POSIX, NFC; branded (ir-schema.md §3.5)
content: string // UTF-8, LF line endings only (no CR)
}
interface ParseResult {
tree: ParsedTree | null // plugin-internal type (opaque); null → parse produced nothing
errors: ParseError[]
imports: Omit<ImportEdge, "origins">[] // an `origins` written here is dropped (§5.2.4)
}
interface ParseError {
message: string
line: number // 1-based
column: number // 1-based
recoverable: boolean // false → the core withdraws this file (§7.1)
}
interface ImportEdge {
source: string // verbatim string (e.g. "@billing/domain", "./util")
symbols: string[] | '*' // imported bindings ("X", "X as Y", "default as Y"), or "*"
line: number
dynamic: boolean // true for import()
namespaceBinding?: string // the local name bound to the whole module, when there is one
reexports?: Reexport[] // what the module exports through this edge
origins?: ReadonlyMap<string, string> // set by the scan alone (§5.2.4)
}
interface Reexport {
imported: string // the name taken from `source`, or "*" for the whole module
exported: string // the name the module exports it under
}reexports is the only part of an edge that says what the module exports. symbols lists what an edge takes from its source, which for export { A as B } from "m" is A, and an import the module only uses lists its names the same way as one it republishes. A re-export carries an entry for each value it exports — export { A as B } from "m" gives { imported: "A", exported: "B" }, export * as ns from "m" gives { imported: "*", exported: "ns" } — and so does an import that an export clause or export default in the same module republishes: import { A as L } from "m" with export { L as B } gives { imported: "A", exported: "B" }. A type-only clause or specifier exports nothing a decorator or call can name and adds no entry, and export * from names nothing, so it adds none either. A plugin for a language without re-exports leaves the field out.
tree is nullable so a plugin can report a parse that produced nothing without fabricating a tree its own type would refuse. It and recoverable: false are companion signals: a plugin that has no tree is expected to say why in errors[] too, and §7.1 reads the two as one condition, so a plugin that sets only one still gets the withdrawal it asked for.
4.3 SymbolCandidate
interface SymbolCandidate {
// precursor of an IR Symbol; the full set before drop determination
id: SymbolId // <language>:<file>#<qname>, from makeSymbolId
kind: SymbolKind // ir-schema §5.1 enum
extKind: string | null // §5.2 (chosen from what the plugin itself declared)
name: string // qualified name
visibility: Visibility
decorators: Decorator[]
signature: Signature | null
source: WrittenSourceRange // SourceRange with both columns required (see below)
derivedBy: string[] // language-level evidence (e.g. ["export-keyword"])
// internal handles passed to walkBody / normalizeAst
bodyNode: OpaqueAstNode | null
mergedDeclarations?: MergedDeclaration[] // §4.3.1, absent when one declaration wrote it
fullNode: OpaqueAstNode // signature + body
}id is a SymbolId, not a string: the type is nominal (ir-schema.md §3.5), so a plugin cannot hand core an id it assembled by concatenation. Build it with makeSymbolId from @aburi/core, which enforces the §3.1 grammar — a lowercase-ASCII language token that is not reserved, a POSIX workspace-relative path, and an identifier-like qualified name — and throws a coded CoreError otherwise. trySymbolId is the non-throwing variant, for a plugin that assembles speculative ids and expects some of them not to be buildable.
The path segment of id must be the path of the file being extracted — ctx.file.path, the same value the candidate's source.file carries. The grammar cannot enforce this: another file's path is a perfectly legal path, so makeSymbolId builds the id and the fault only shows as a Symbol filed under a file that never declared it. A plugin re-exporting or generating code names the declaring file in source.file and the declaring file alone, rather than the file it happened to read. The scan checks this per file and withdraws the file that broke it (§7.2). source.file is typed RelativePath, a brand (ir-schema.md §3.5): ctx.file.path already carries it and is the value to write; toDocumentPath from @aburi/core is the only other way to mint one, and refuses a spelling the Document has no room for.
A brand can be asserted rather than constructed, so the type is a contract, not a lock. Do not take that route: a plugin whose qualified names the §3.2 grammar cannot express — Ruby's save! and valid? are the standing example — must widen the grammar, not cast around it. The call-graph resolver and the LSP enrichment tier build candidate ids through trySymbolId and treat a refusal as "no such callee", so an id the constructor would have rejected resolves against nothing while looking like an ordinary miss. assertIRIntegrity catches it at the end of the scan (§14 invariant #17) and names the offending id, so it surfaces as a failure rather than as silently thinner output — but the diagnostic bucket in call-resolution.md §8.1 has no way to say "the grammar refused this candidate", so the reason will not appear in stats.callResolution.
source is a WrittenSourceRange, not the IR's SourceRange: startColumn and endColumn are required on the write side, carrying null when the plugin cannot determine a column. This is the Class A rule of ir-schema.md §1.1 expressed as a type. The narrowing matters because the canonical serializer drops properties whose value is undefined — a plugin that left the keys off would type-check against the wider SourceRange and then emit a document missing them, with nothing between the two to notice. The IR's own SourceRange stays optional so that a document written before the rule remains representable when it is read back off disk.
A plugin that has real column information may write it; nothing forbids that. The in-tree TypeScript plugin deliberately does not, so that every column in an Aburi IR comes from textDocument/documentSymbol (lsp-enrichment.md §4.2) and one convention about what a column counts. Be aware that a published column is not durable: the enrichment pass overwrites both keys on every Symbol it matches (§5), so a plugin-written column survives only where the LSP tier produced nothing — which is where it is least likely to be checked.
When the plugin chooses an extKind from its own declarations, the chosen value must fall under manifest.provides.extKinds or extKindPrefixes. The registry detects violations at startup.
4.3.1 One entity, several declarations
A Symbol id names an entity, not a declaration, and most languages let one entity be written more than once: a getter beside its setter, an overload beside its implementation, an interface reopened, a namespace augmenting the class above it, a partial class. A plugin emits one SymbolCandidate for all of them. Two candidates sharing an id costs the file they were written in: ir-schema.md §14 invariant #1 is decided per file, inside the boundary of §7.2, so the file is withdrawn and named and the rest of the workspace is scanned. It is still a file this plugin could have extracted, so folding is the plugin's job either way.
Which declaration leads is the plugin's to decide and to say in its own tests; what the interface fixes is where the rest goes. bodyNode / fullNode are the leading declaration's, and mergedDeclarations holds the others in source order, so that walkBody and normalizeAst describe the entity rather than whichever declaration was written first — a set password(v) that hashes the value has effects, and dropping it because a getter was written above it loses them with nothing to say so.
interface MergedDeclaration {
bodyNode: OpaqueAstNode | null
fullNode: OpaqueAstNode
}Each entry carries both nodes, for the reason the Symbol itself does: a declaration with no body — an enum, a type alias, a namespace whose statements are their own Symbols — is described by its fullNode, which is where normalizeAst already looks when a Symbol has no body. An entry holding only a body makes a reopened enum E {} fingerprint as though the second declaration had never been written, so adding, editing or deleting it changes nothing. Only the bodies belong in the body walk: a merged namespace walked here would be walked a second time through the member Symbols its statements already produce.
Everything list-shaped on the Symbol joins the same way — derivedBy and decorators both. Dropping a merged declaration's decorators is not cosmetic: an interface P {} written above an @Controller() class P {} is legal, so the leading declaration is the one carrying none, and a lost boundary decorator moves the Symbol back inside the drop list (drop-list.md §4.1).
The field is optional, absent and never empty, so a Symbol with one declaration — the ordinary case — does not carry the key at all. A consumer that reads only bodyNode is correct on those, and every path that predates the field still is; a consumer that describes the Symbol from its declarations reads both.
Nothing in the core checks that a plugin folded its declarations — the invariant catches the omission, at the file that wrote it. derivedBy is where a plugin says a fold happened; the in-tree TypeScript plugin writes declaration-merged.
4.4 BodyExtraction
interface BodyExtraction {
rules: Rule[] // ir-schema §8; strings per the rule-string contract below
calls: CallCandidate[] // raw calls before effect classification
}
interface CallCandidate {
target: string // string representation of the callee (before whitespace normalization)
line: number
argumentCount: number // arguments only — comments between them do not count
inAwait: boolean // true when under an await
inNew: boolean // true when a new expression
literalArgs: (string | null)[] // literal value of each argument (null if not a literal)
dynamicReceiver?: boolean // optional; true when the receiver was an expression
receiverType?: string // optional; the named type the receiver is declared with
thisBinding?: "class" | "instance" // optional; what `this` is where a call through this/super is written
}walkBody must not emit trivial returns as rules (drop-list §5.3-5.5). For call-only returns such as return foo(), the call goes into CallCandidate but not into a Rule.
Rule-string contract
A rule's condition, what and expr are written in the form ir-schema.md §8.2 gives them: comments taken out, every run of whitespace collapsed to one space, and cut to the first 120 code points plus .... They are the input of the logic fingerprint (fingerprint.md §4.1) and of the diff's rule delta, so anything left in them that is not the program moves logic and lists the rule under "rules modified".
Taking comments out falls to the plugin, because nothing after it can. Telling a comment from the code around it takes the language's grammar: /* … */ inside a string literal is string content, # opens a comment in Python and a private name in TypeScript, and @aburi/core holds no grammar. Nor can the core notice the omission. A Document whose rule strings still hold comments passes the schema and every integrity invariant, and the only symptom is a Symbol whose logic moves when someone edits a comment: it is reported as changed, with nothing to say why.
Replace each comment with a space rather than with nothing. A comment that is all that separates two tokens would otherwise join them: a-/**/-b is a - (-b), and a--b reads as a decrement. The space costs one case, which fingerprint.md §4.3 names: such a comment, with no whitespace on either side, leaves a space the comment-free spelling does not have, so a/**/||b gives a ||b where a||b gives a||b.
The whitespace collapse and the cut are applied again at the plugin boundary, so a plugin that skips them still writes a Document the schema accepts. Do not re-implement them: call normalizeRuleText from @aburi/core on the comment-free text. It counts code points, as the schema's maxLength does, so a cut never splits a surrogate pair, and it is idempotent, so the boundary pass leaves a string it produced unchanged. normalizeRuleStrings applies it to the three strings of one Rule. LP19b and LP19c (§9.4) are the criteria.
Argument-list contract
argumentCount is the number of arguments, and literalArgs[i] is the literal value of the i-th one. Comments are not arguments. Most grammars carry them as extras and hang them wherever they were written, including between the parentheses of a call, so a plugin that maps the argument node's children straight across reports f(\n x, // why\n) as a two-argument call and gives literalArgs a slot that belongs to no argument — shifting every later one, so literalArgs[0] may describe a comment rather than the first argument.
Effect plugins read both as a signature (effect-plugin.md §5.4), so the miscount lands as a call attributed to the wrong API, or as a real effect that never reaches the IR. Filter the comment nodes out; the count and the array are then the same length and the same order as the source's arguments.
Normalized-callee contract
target is non-empty, and every .-separated segment of it is non-empty. A leading, trailing, or adjacent dot (".create", "prisma.user.", "prisma..create") is a contract violation, not an input an effect plugin has to tolerate: "prisma..create" splits into three segments and would match a delegate-call shape that never existed in the source. The same holds for the ImportEdge of §4.2:
sourceis a normalized, non-empty module specifier.- Each
symbolsentry names something on both sides of itsas—"X as Y"bindsYto the exportX, and a bare"X"isXon both sides." as Y"bindsYto an export with no name and"X as "importsXunder no local name, so a consumer that resolves a decorator or receiver through the entry attributes it to a binding the source never wrote. namespaceBinding, when present, is non-empty, for the same reason: it is the local name a receiver is matched against.
Whitespace is not part of the rule: a segment, specifier or binding is rejected when it is empty, not when it is blank. "prisma. .create" satisfies the contract as written — plugins are free to be stricter, but the shared guards are not.
Consumers enforce this rather than work around it, through the shared guards in @aburi/plugin-registry/plugin-input. Each throws a PluginInputError naming the consuming plugin and the file, under the code of the clause it enforces:
| Guard | Refuses | code |
|---|---|---|
assertNonEmptySegments | an empty target, or one with an empty segment | unnormalized-callee |
assertImportEdgeSource | an empty source | unnormalized-import-source |
assertImportBinding | a symbols entry with an empty half | unnormalized-import-binding |
assertNamespaceBinding | an empty namespaceBinding | unnormalized-namespace-binding |
hasMatchingImport runs assertImportEdgeSource over every edge before it matches any, so whether it throws does not depend on import order. A violation propagates rather than degrading to an unclassified call (effect-plugin.md §10, EP3a), so an unnormalized callee surfaces as a failed scan instead of a silently miscategorized effect.
Because the guards throw, the producing side has to hold the line rather than pass the problem on. A source construct that would yield an empty specifier is legal to write — import x from "" parses, and tsc rejects it at resolution as TS2307 — so the plugin emits no edge for it and records a recoverable ParseError at the specifier's position. The file keeps its Symbols (a file is withdrawn when its parse returns no tree, which this is not), the diagnostic carries a line to fix, and the guard stays a signal that something upstream is genuinely broken.
A receiver that is not a name
A receiver the normalizer does not model never contributes its source text to target. Such a receiver — an array, object, string, number or template literal, new C(), an await, a binary expression, a function or arrow expression (an IIFE) — contributes the reserved segment <computed> (the same COMPUTED_TARGET_SEGMENT a bracket access uses, below) and the call carries dynamicReceiver: [...names].sort() is <computed>.sort, and an IIFE is <computed>. Its text would break the contract above ([...names] holds two empty segments, (.5) a leading dot) or put a function body, indentation included, into the IR.
A type assertion — x as Foo, x satisfies Foo, <Foo>x — states a type and leaves the value as it was, so it answers what the expression it wraps answers, and its type never reaches target: (emitter as Foo.Bar).update(x) is emitter.update, (this.repo as Repo).save() is this.repo.save, (f as Fn)() is f, and ([...a] as T).m() is <computed>.m. The parentheses the assertion needs hold a name in the first three, so none is dynamic, as (svc).save() is not. Kept, the type's text would add segments of its own (emitter as Foo.Bar.update has the three a Prisma delegate call has), or break the contract above when it spells a spread or spans lines.
A non-null assertion around a name answers that name's target with ! after its last segment: svc!.save() is svc!.save, (x as Foo)!.save() is x!.save, (x as Foo).m!() is x.m! and prisma["user"]!.create(d) is prisma.user!.create, none of them dynamic. It is built from the target, not from the source text, so a type, a comment or a line break between the name and the ! never reaches it: a target is read as a name, and reformatting must not change it. Around anything else the assertion answers what the wrapped expression does (getRepo()!.save() is the dynamic getRepo.save), and parentheses around it, a type assertion between or not, make the receiver dynamic: (svc!).save() and (svc! as Foo).save() are the dynamic svc!.save.
The keyword callee of a dynamic import("./m") is import, and import.meta and new.target are their own spellings.
A bracket access in a callee
prisma["user"].create(data) and prisma.user.create(data) are one call written two ways, and the target says so: a string-literal index whose value is a qualified-name segment (ir-schema.md §3.1) folds into the target as that segment, a private name aside (below). The literal is decoded rather than unquoted, so prisma["us\u0065r"] is prisma.user too, and it is refused when the parser guessed at any of it — a partial read (obj["a\u12b"]) and a whole literal standing beside an ERROR (prisma["user" "audit"], a missing operator) both name a property the source does not spell. That is the pair of guards a class member's written name already answers with (§9.1, LP8m).
Every other index names no segment: an identifier (prisma[model]), a number (items[0]), a substituting template, a string the grammar has no segment for (obj["a-b"], obj["a.b"], ""). A string that opens with # names no segment either, for the opposite reason: the grammar has the segment #v, but it names the #-private member (LP8o), and obj["#v"] is the public property with those characters. Core's isQnameSegment refuses #v unless asked for a private name, and a decoded string never asks. The bracket contributes the reserved segment <computed> instead — the exported COMPUTED_TARGET_SEGMENT, so both sides of the boundary spell it from one place — and the call carries dynamicReceiver, because a property nothing names is a property reached by evaluating an expression.
Where the brackets sit is not part of the question. The index of handlers["run"]() names the function being called exactly as the one in prisma["user"].create() names the receiver, so the terminal slot folds by the same rule and handlers[name]() answers handlers.<computed>. The flag then reports the callee rather than a receiver — which is what call-resolution.md §8.1's dynamic bucket wants either way: nothing in the target is a name a tier could look up.
Dropping the index is the one answer that is not available. prisma["user"].create() read as prisma.create is not a lossy spelling of the call, it is a different call: it never appears in the program, it is spelled exactly like an ordinary two-segment method call, and a consumer that counts segments — effects-prisma needs three for a delegate call — loses the db.write with nothing anywhere to say that it did. Recording no call at all would at least be honest, and it costs the call site its diagnostic, its arguments and any effect on it, which is the same loss paid twice.
A consumer reading a fixed position meets the sentinel where it expected a name. It names none, and a consumer that treats it as one is reading evidence out of a segment that carries none — queues[id].upsert(job) has a delegate call's three segments and is a queue. The rule is the plugin's own: effects-prisma requires the receiver to name a client binding before it credits a computed model, and effects-trpc caps a dynamicReceiver call at medium.
<computed> is unresolvable by construction: the segment grammar of ir-schema.md §3.1 admits no <, so every candidate id built through such a target is refused by trySymbolId, and no Symbol name a component-scope or workspace-scope lookup compares against can hold one (call-resolution.md §4.5, §4.6). (<default> is reserved ahead of that pattern rather than by it, so the safety is this segment's spelling, not the angle brackets.) An effect plugin claiming the call is the one path that leaves that bucket with nothing to say: a classified call never reaches calls[] (ir-schema.md §9.3) and is counted by no bucket, so what records the computed segment there is effects[].target and the tier the plugin chose.
This is ir-schema.md §3.2's computed-member row read from the other side, and the two do not disagree. A qualified name is a resolution target — inventing a segment there mints an id, and an id that names nothing is worse than no Symbol. A call target is a reading of what the source calls, which a missing segment falsifies, and which resolves against nothing either way.
dynamicReceiver
Set it to true when the callee's receiver was an expression rather than a name — getRepo().save(), items[0].save() (items.<computed>.save), (a ?? b).save() — and when the callee itself is one, which brackets are the way to write (handlers[name](), §4.4). Leave it absent otherwise; absent means false, so existing plugins stay valid without a change.
Normalization is lossy here in a way only the plugin can repair: getRepo().save() collapses to the target getRepo.save, which is spelled exactly like a genuine Class.method qname. Without the flag, call-resolution.md §8.1 would have to file every such call under no-match and send reviewers hunting for a typo that does not exist; with it, the call is correctly reported as dynamic.
Do not set it for this.save() / super.save() — §4.7 already keeps those unresolved through a separate rule, and the resolver buckets them itself. Be conservative: a receiver the plugin reads through to a name (a non-null assertion, a type assertion) is not evidence of dynamic dispatch, and over-reporting would make the bucket useless. The flag never affects which calls resolve — it only decides which diagnostic bucket an already-unresolved call lands in.
receiverType
Set it to the named type the receiver is declared with, type arguments aside, when the plugin can read that declaration off the tree without resolving a scope — EventEmitter2 for this.eventEmitter.emit(…) in a class whose constructor reads constructor(private readonly eventEmitter: EventEmitter2). Leave it absent otherwise, which includes every type that is not a name (a union, an object type, a function type): the field is evidence about whose method the call is, and a type an effect plugin would have to parse is not evidence it can compare. An effect plugin sees no AST (effect-plugin.md §6.1), and the callee string holds the binding's name, not what it was declared as, so a plugin that recognises a receiver by name alone recognises only the names its own vocabulary guesses (effect-plugin.md §5.4).
The in-tree TypeScript plugin reads it for a receiver that is this.<field>, one segment deep, in the class this is bound to there (LP20n). A plain name is left out: telling a parameter from what shadows it takes a scope resolver, which this plugin does not have. The field reaches no axis and no IR field — it is read by classify and dropped with the candidate — so the field itself moves no fingerprint; a plugin that classifies by it moves logic as any new effect does. The scan puts it in NFC with target before any classifier sees it, as it does an ImportEdge's symbols and namespaceBinding, so a type compares equal to the name an import binds whichever spelling either was written in.
thisBinding
Set it on a call through this or super to what this is where the call is written: "class" in a static block or a static member, its initializer included, and "instance" in an instance one. Leave it absent where the plugin cannot tell, and on a call through anything else. The LSP pass reads it to look up a this.m() hint's member on the side this is bound to (lsp-enrichment.md §4.2). Without it that side is the caller's own kind, which a method's id spells and the class Symbol's does not: the class holds the calls of its static blocks and of its field initializers of either kind, so seed = this.create() beside a static create() reads like the static block's this.create().
The in-tree TypeScript plugin finds the class this is bound to as LP20n does (LP20n1). Like receiverType, the field reaches no axis and no IR field. On the IR's Call it would repeat what the member's id already says for every call a member holds, but one in a class the member's body declares (LP20e), for the one reader that needs it on the class Symbol's calls.
4.5 ExtractionContext / WalkContext / FrameworkClassifyContext
interface ExtractionContext {
file: SourceFile
registry: VocabRegistry // ext-vocab §7
config: AburiConfig
}
interface WalkContext extends ExtractionContext {
symbol: SymbolCandidate
}
interface FrameworkClassifyContext extends ExtractionContext {
imports: readonly ImportEdge[] // the same edges parseFile produced for the file
}FrameworkClassifyContext is what a framework plugin's classifySymbol receives (§5.2). A plugin with no use for the edges may declare the parameter as the supertype ExtractionContext and still satisfy the interface.
The array is the live one, not a copy — the same instance the pipeline reports as the file's imports and hands to call resolution — hence readonly. A plugin may memoize per file on its identity; it must not mutate it.
4.6 DropHint
interface DropHint {
reason: string // goes directly into the IR Symbol.dropReason
category: 'B' | 'C' // category per drop-list §2
}Example: for TypeScript's export type X = Y, return { reason: "type alias", category: "B" }.
4.7 PluginContext
interface PluginContext {
registry: VocabRegistry
config: AburiConfig
workspaceRoot: string // absolute path (used by the plugin to initialize its parser)
log: Logger
}4.8 ImportResolver
interface ImportResolverContext {
workspaceRoot: string // absolute
log: Logger
}
interface ImportResolver {
// the workspace-relative POSIX paths `specifier`, written in `fromFile`, maps to,
// in the order the language tries them
resolve(specifier: string, fromFile: string): Promise<readonly string[]>
}A bare specifier can name a workspace file through build configuration the core does not read, such as TypeScript's compilerOptions.paths. The language plugin knows its build configuration and the core knows the file set, so the plugin maps the specifier and the core decides which path is a file: it probes each path, in the order given, the way it probes a relative specifier (call-resolution.md §4.4.1, steps 1 and 3), against the files discovery found. A path may therefore leave out its extension or name a directory, and one that names no file costs nothing. The core never asks about a relative specifier.
The core calls createImportResolver at most once per scan on each thread that extracts files — the main thread, or each parser worker (performance.md §7.2.1) — and only when that thread has a non-relative specifier to ask about. A resolver may cache what it reads for the length of that scan and no longer: the next scan creates a new one, which reads the configuration afresh. What resolvers say is counted over the scan, not over each of them: a line logged through ctx.log is said once per scan, at the first file whose extraction logged it, however many resolvers log it and however often; a failure on one specifier written in one file counts once; and a plugin's first resolver failure — createImportResolver throwing or returning something with no resolve method, or resolve throwing — is a warning, later ones are logged at debug, and a plugin whose resolver failed more than once is warned with the count at the end of the scan. A specifier the resolver failed on ends the chain it was part of without an origin (§5.2.4).
The TypeScript plugin reads the tsconfig.json nearest above the importing file, or a jsconfig.json where no tsconfig.json sits beside it, and looks no higher than the workspace root for it; an extends entry may still name a config outside the root. Comments, trailing commas, a leading byte order mark and an empty file (read as {}) are accepted, as tsc accepts them. It applies compilerOptions.paths and baseUrl the way tsc does:
- An exact key wins outright; otherwise the wildcard key with the longest prefix does, its match put in place of each substitution's
*. Every substitution is returned, in the order written, followed bybaseUrljoined with the specifier whenbaseUrlis set. - Substitutions resolve against
baseUrlwhen it is set, and otherwise against the directory of the config that declaredpaths. extends, a string or an array, is followed. A relative or absolute entry resolves against the extending config's directory, with.jsonadded when the entry has no such extension and names no file as written. A package entry is looked up asnode_modules/<entry>,node_modules/<entry>.jsonandnode_modules/<entry>/tsconfig.jsonin each directory upwards. A later entry overrides an earlier one and the extending config overrides them all, an option at a time, so its ownpathsreplaces the inherited ones whole. A config that extends itself, directly or through others, is read once.${configDir}at the start of a value is the directory of the config the file is compiled under, whichever config in the chain wrote it.
It does not read a package's package.json exports or tsconfig field when an extends entry names the package, project references, a config's files and include, or a package.json imports field. A path outside the workspace is dropped. What it cannot use, it warns about once and leaves out:
- A config that is not valid JSON, named with the line and column of the first error, or one that exists and cannot be read. It maps nothing, and the search for the nearest config stops at it rather than moving on to the one above, which the file is not compiled under. A name that is not there, or is a directory, is not a config, and the search moves on.
- An
extendsentry that names no config file. The rest of the chain still applies. - A value
tscrefuses: apathsthat is not an object, a key whose value is not a list, a key or substitution with more than one*, a substitution that is not a string, or abaseUrlthat is not a string. Only that key, substitution or option is left out.
A package entry in extends is found only where node_modules is installed. aburi diff <base>..<head> scans the base revision in a fresh worktree with no node_modules, so paths from a package's config apply to the head's scan and not to the base's, and a decorator reached through one of those aliases reads as moving from medium to high. The base's scan warns about the entry.
5. Cooperation with Other Plugins
5.1 Cooperation with effect plugins
The language plugin's job ends at returning CallCandidate[], in source order. The core queries the effect plugins in order for each call, and the result of the first plugin to return an EffectClassification is adopted. The core sorts effects[] and calls[] by line and keeps the plugin's order among the entries of one line (ir-schema.md §1), so that order reaches the IR and the logic fingerprint, which reads locally detected effects in it (fingerprint.md §4.7). @aburi/lang-typescript writes a call before the calls inside it: a(b()) gives a, then b.
The IR records a line and no column, so neither the integrity check nor the core can tell whether a plugin wrote the calls of one line in source order: the order is the plugin's to keep. That is deliberate. Ordering one line by anything the IR does hold, such as the target, would be checkable, but it would leave a swap of two calls on one line invisible to logic and let a renamed target reorder them.
- A call for which every effect plugin returned null → stays in
Symbol.calls[](target/line/resolved=null) - A call classified by some effect plugin → goes into
Symbol.effects[]and not intoSymbol.calls[](ir-schema §9.3)
See effect-plugin.md for the detailed interface.
5.2 Cooperation with framework plugins
The language plugin extracts each Decorator up to its raw string, arguments, name, and qualifier (the receiver it was written through, ir-schema.md §6). The boundary flag is filled in by the core querying the framework plugin.
5.2.1 First-match-wins among framework plugins
When multiple framework plugins are enabled in the config, first-match-wins in config order, just like effect plugins (same convention as effect-plugin.md §5.1):
- Each SymbolCandidate is passed to the framework plugins'
classifySymbolin config order - The result of the first plugin to return non-null is adopted (extKind / boundary adjustments, etc.)
- Subsequent plugins are skipped
This avoids ambiguous states such as "the same class is recognized as both a NestJS Controller and a Custom Framework Controller". If a project has conflicts, priority is controlled via config order. The ad-hoc plugins frameworkHints stands for come after every plugin in frameworks (config.md §8.3.2).
A framework plugin receives the following inputs:
- the
SymbolCandidate(including decorators) - the file's
ImportEdge[], onFrameworkClassifyContext(§4.5) - the framework declaration of the owning component
A const's fullNode is its whole declaration statement, shared by every name it declares; a plugin reads one name's initializer from the declarator that binds it. The <default> const a default export written as a call gives (LP7c1) has no declarator: its fullNode is the export_statement, and declaratorValue asked for <default> returns that statement's value. A plugin reads a value through @aburi/core's unwrapValue (a const's initializer through declaratorValue), the reader the language plugin names Symbols with (LP7a), so a role cannot depend on a wrapper the Symbol's name reads through. So framework-react reads export default memo(function Row() { … }) as it reads const Row = memo(…), and framework-next takes a default-exported const carrying call-argument-function as the component an App Router file's default export is.
Against these it may:
- override
decorator.boundary - fill in
Symbol.extKind(e.g.framework:nestjs:controller) - name the middleware a registration hands its handler to, in the order it runs (
middleware, §5.2.5), which the core writes toSymbol.middleware(ir-schema.md§5.8) - provide a Category B drop exclusion hint (e.g. a class carrying only
@Modulemust not be treated as a pure DTO) - drop the Symbol through
symbolDropHint(drop-list.md§6.3). UnlikeclassifySymbol, every framework plugin is asked, whichever of them won, and the first non-null answer is the drop
The detailed interface is deferred to a future framework-plugin.md (this document only reserves the contract surface).
5.2.2 Matching a decorator against the import edges
The language plugin reports a decorator under the identifier the source wrote. That identifier is not reliable evidence on its own, in either direction: import { Controller as Ctrl } writes a framework boundary under a name no table holds, and a @Controller from a competing library writes a foreign name that every table holds. A plugin that matches names against its vocabulary resolves the identifier through ctx.imports first:
| What the edges say about the name | Match against | Confidence |
|---|---|---|
| imported by name from a module the plugin owns, or from a workspace barrel the core traced to one (§5.2.4) | the imported name | high |
| imported by name from any other module | the imported name | medium |
bound by a default import (import Controller from './decorators', import { default as Controller } from …) | the written name | high from a module the plugin owns, medium from any other |
| no edge binds it | the written name | high |
The module a name is imported from is ImportEdge.origins under the imported name, where the core recorded one, and ImportEdge.source otherwise. Through a namespace import, the key is the member the receiver reads: its second segment, or the leaf when the receiver has one segment.
The second row downgrades rather than refuses. Re-exporting a framework's vocabulary through a project-local barrel is ordinary practice. The core traces the barrels it can read (§5.2.4), so a decorator re-exported through ../common or a path alias such as @app/common lands in the first row, but not every barrel can be read: one that re-exports through export * names no source for the name, and a workspace package reached through the package manager's links is a bare specifier no paths key maps. Those are still indistinguishable from a foreign package, so refusing would take the boundary off a whole project's worth of Symbols to close a narrower false positive. medium is the confidence criterion for an identifier match (ir-schema.md §5.4), which is exactly what is left when provenance is unknown.
The third row exists because a default import's imported name is default (LP24a), which no vocabulary lists. Matched on it, every default-imported decorator would classify as nothing, so the written name is the only evidence left of which decorator the file means; the module it came from still decides how far that is trusted, as in the first two rows.
Two consequences follow for the plugin's outputs. SymbolClassification.decoratorBoundaries is keyed on the decorator as the source wrote it, receiver included — Controller for @Controller(), nest.Controller for @nest.Controller() — because that is the key the core rebuilds from Decorator.qualifier and Decorator.name when it folds the result back in. The leaf alone is not a key: two decorators on one Symbol can share it and still resolve differently (@Ctrl() under import { Controller as Ctrl } classifies, while @x.Ctrl() canonicalises to Ctrl and matches nothing), and a shared key would flag both. derivedBy carries the imported name (the written one, for a default import), because it is a closed vocabulary that diffs and filters read, and renaming an import changes nothing about what the decorator does.
A qualified decorator (@nest.Controller()) is read the same way, one column over: Decorator.qualifier carries the receiver, and the lookup is on the receiver rather than on the leaf. Only the receiver's first dot-separated segment can name a binding — a.b in @a.b.C() reaches scope as a — so that segment is what the plugin looks up, and the name matched against the vocabulary is the leaf as written, because a namespace import renames nothing. The same confidence tiers then apply to the module the receiver names.
Which edges bind a receiver. Both kinds, and a plugin that reads only one leaves the table out of order. import * as nest from "m" arrives as symbols: "*" with namespaceBinding: "nest", and import nest from "m" arrives as symbols: ["default as nest"] with no namespaceBinding (LP24a) — two spellings of the same disclosure, one in each index. The last row of the table therefore means no edge binds the receiver, not no namespace edge binds it.
A qualified decorator must not fall back to the named-import index for its leaf. The leaf is a property of a module object, not an identifier in the file's scope, so a Controller imported by name from somewhere else says nothing about @nest.Controller(), and reading it would attribute the decorator to a module it was never written through. The receiver is the opposite case, which is why it is looked up in both indexes: nest really is an identifier in scope.
Both halves are necessary for the table to be ordered by how much the file disclosed. A plugin that drops the qualifier sees only the leaf, and a namespace import from a competing library then lands in the last row — trusted further than the named import of the very same decorator. A plugin that keeps the qualifier but indexes only one of the two binding forms gets the same result one spelling over.
Two shapes reach the edge list without binding anything in local scope, and a plugin matching names should know both. A re-export (export { X } from './y') names a symbol the file republishes rather than uses — and its aliased form arrives in symbols as the source-side name alone, since the language plugin composes " as " on imports but not on re-exports; the name it is exported under is on reexports (§4.2). Because re-exports do not bind, a name can appear on two edges in a file that compiles, so a plugin needs a duplicate rule and should say which of its outcomes are order-independent.
5.2.3 Naming a call in derivedBy
A framework plugin that names a call in derivedBy — the registration it classified, or the factory or wrapper call a const holds in its own declarator (§5.2) — reads the name off the tree, not off the callee's text (ir-schema.md §5.5). The text carries the call's formatting: a chain a formatter wrapped over several lines put its line breaks and indentation into the entry, a comment inside the chain was copied in, and a ; in that comment split the entry in two, because the core splits a classification's derivedBy on ;. A filter matching framework:express:route:router.delete then missed the wrapped spelling of the same call, and a whitespace-only edit changed the entry.
The name is <receiver>.<method>. The method is the callee's property. The receiver is the name the receiver chain starts from, read through LP7a's wrappers and through every call, member access and index on the way; for every registration the TypeScript plugin extracts, that is the receiver its call-statement: entry carries, which LP20i1 slugs into its name. So app.get(p, h), (app as Express).get(p, h), app!.get(p, h), the same call wrapped over two lines or with a comment before the .get, and app.route(p).get(h) are all app.get, and express.Router().get(p, h) is express.get. A chain that starts from something that is not a name, new Registry().memo(Inner), starts from <computed>, the segment a call target uses for such a receiver (§4.4): its text would carry the formatting back in. A callee that is a bare name is that name, Router() being Router; one that is neither a name nor a member access, (memo)(Inner), names nothing, and a plugin matching the name's leaf against its vocabulary matches nothing either. @aburi/core exports this reading as calleeName, the wrappers it reads through as unwrapValue, and the walk down the chain as walkReceiverChain, so every framework plugin reads a callee one way. The TypeScript plugin reads its call-statement: receiver, and whether the chain passes a call (chained-call), off that same walk, so a change to the walk moves both and they cannot name one registration apart. The TypeScript plugin takes only a chain that starts from an identifier and passes no index, so routers["admin"].get(p, h) and this.app.get(p, h) are no call Symbol. The name would drop what an index picks, and the statements it reads are at module scope, where this is undefined in an ES module, module.exports in CommonJS and the global object in a script, never an app or a router. The calls a registration chains, the ones LP20i1 looks for a path on and @aburi/framework-express names middleware from, are the calls that walk passes, exported as chainCalls. LP7c reads a const's functions off the same calls, and an index on the way stops neither reading: (() => { … })()["run"]() runs its function as (() => { … })().run() does.
5.2.4 Following a decorator's name through re-exports
Before framework classification, the core traces each name a decorator in the file binds through the workspace's re-exports, and records the result on ImportEdge.origins: keyed by the name the edge's module exports, the specifier of the module outside the workspace that the chain ends at.
- Which names. A decorator's leaf, through the named-import edge that binds it, and a qualified decorator's receiver head, through the named-import edge that binds it (keyed by its imported name) or the namespace edge that binds it (keyed by the member the receiver reads, as in §5.2.2). No other name is followed: an origin for every import would parse most of the workspace twice, and a decorator is the only name a framework plugin matches by its imported name. A plugin that grades on which modules a file imports reads
ImportEdge.sourceand gets no origin. A scan with no framework plugin follows nothing. - One hop. The specifier resolves against the importing file: a relative one as call resolution resolves it (call-resolution.md §4.4.1), a bare one through the language plugin's
ImportResolver(§4.8). In the module it resolves to, the next hop is the edge whosereexportsexports the name (§4.2), and the chain carries on from that edge's source with the name the entry takes from it. Nothing else on an edge is read, so an import the module only uses, and a re-export of the name under another one, lead nowhere, whichever order the edges are in. - Where it ends. A bare specifier that resolves to no workspace file ends the chain outside the workspace, and that specifier is the origin. It is the first such specifier, so a workspace package the package manager links in, which no
pathskey maps, is an origin too. A whole module exported under the name (export * as ns from) ends the chain there: outside the workspace its specifier is the origin, and inside it there is none, because which member the decorator reads is not carried past it. A module with no edge exporting the name, because it declares the name itself or reaches it throughexport *, ends the chain inside the workspace, and so do a relative specifier that names no file, a module the chain already visited for the name, and a specifier the resolver failed on (§4.8). Those leave no origin. An origin equal to the edge's own specifier is not recorded, sooriginsholds only what the core learned. - Cost. A module the chain reaches is parsed once for its edges, unless its own turn in the scan came first, and that tree is released at once (§8.1). The chain does not count against the importing file's
parseTimeoutMs(§7.1.2): which file reaches a barrel first depends on discovery order, and a file's outcome should not.
export * is not followed because the module it names may be outside the workspace, where nothing says whether it exports the name, and a guess would put a module in origins that the source does not name.
origins is the scan's alone. An origins a language plugin returns is dropped before any plugin sees the edge, so a language plugin cannot vouch for its own edges. Effect plugins see the same edges through FileSummary.imports, and there as here a missing key says nothing about where a name is declared.
5.2.5 Naming a registration's middleware
SymbolClassification.middleware lists what a registration hands its framework before the handler, by name, in the order it runs. The core takes it from the classification that won (§5.2.1), brings each name to the form the fingerprint reads text in (NFC, ir-schema.md §1.2, with each run of whitespace collapsed to one space and the ends trimmed), drops a name left empty, and writes the rest to Symbol.middleware, leaving the key out when nothing is left and on a dropped Symbol. Normalizing once, where the names enter the IR, means the fingerprint and the diff's middleware delta read the same strings: a name that differs only in its whitespace is one name to both. The logic fingerprint reads it (fingerprint.md §4.1). LP20i keeps the arguments on the syntax axis, which saw app.get(p, authenticate, h) → app.get(p, h) and filed it as a reformat, the one reading a reviewer most needs to be wrong.
A name is composed from the tree, as a derivedBy entry is (§5.2.3), never copied from the argument's text: the text carries the line breaks and comments it was written with into the fingerprint, so a reformat would read as a changed gate. An identifier is its name (requireAdmin). A member access is its object's name and its property joined by . (auth.required); a bracketed property written as a number, a string or a backtick with no substitution is that value (handlers["auth"] and handlers[`auth`] → handlers.auth), and any other is <computed>, the segment a call target uses (§4.4). A call is its callee's name and its arguments, each a literal, a name, or … for anything else (requireRole("admin"); rateLimit(…) for rateLimit({ max: 10 })): a factory's arguments decide what its middleware lets through, and swapping "admin" for "user" is a change to review. A string, or a backtick with no substitution, is its value, escapes decoded, written back in double quotes, so 'admin', `admin` and "\x61dmin" all give requireRole("admin"): the quotes a formatter picks are not a changed gate, and LP20i1 already reads a backtick with no substitution as the string it spells. A backtick with a substitution is …, its value being decided at run time. A spread whose contents the statement does not show is ... and the name of what it spreads (...guards). Anything else — a choice between handlers, an await, a new — is <computed>.
An inline function is left out, since its body is the registration's own and its rules, effects and calls are already the Symbol's. Arrays are flattened, as the framework flattens them. @aburi/framework-express names, for a route, every handler argument but the last, and for use, every argument after the path, the router a mount hands over included, each route or use of a chain in the order it registers them. Two shapes follow Express rather than that rule. An all with a later method in its chain (app.route("/users").all(requireUser).get(listUsers)) runs ahead of each of them and passes the request on, so every argument it takes is middleware, its last included. A use path is what Express reads as one: a string, a backtick with or without substitutions, a regex, or an array whose first entry, at any depth, is one of those, an empty array included; none of it is a name. Its README lists the shapes.
5.3 Extraction order
plugin.parseFile() [lang]
↓
plugin.extractSymbols() [lang]
↓
framework plugin classifySymbol() [framework]
↓
plugin.walkBody() [lang]
↓
effect plugin classify() for each call [effects]
↓
plugin.normalizeAst() [lang]
↓
core applies the drop list / computes fingerprints
↓
plugin.releaseTree() [lang, called by the core — §8.1]
↓
core assembles the IR6. Capabilities
LanguageCapabilities is a flag set through which the plugin declares "what is expressible in my language". The core and other plugins use it for branching.
interface LanguageCapabilities {
hasDecorators: boolean
hasGenerics: boolean
hasAsync: boolean
hasMacros: boolean
hasPatternMatching: boolean
hasAbstractTypes: boolean // abstract class / trait / interface
hasModules: boolean // ES module / Python module / Go package
hasNamespaces: boolean // TS namespace / C# namespace
hasTypeParameters: boolean
hasExplicitVisibility: boolean // public/private keywords
hasJsDoc: boolean // JSDoc / docstrings, etc.
}For the runtime resource budget (wasmHeapPerWorkerMB), the source-of-truth is the capabilities of the plugin manifest, not the runtime interface. The CLI reads the manifest to size its parser pool, so it is not duplicated at runtime (see §8.1 / cli-spec.md §14.2).
If a framework plugin requires decorator-based extraction from a language with hasDecorators: false, the core aborts with an error at startup.
7. Error Handling
7.1 Parse errors
recoverable: true→ the core proceeds to Symbol extraction (tree-sitter is normally recoverable)recoverable: false→ the core withdraws the file: no Symbols reach the IR, it is recorded inScanResult.skippedwithreason: "parse-failed"and a detail quoting the error's message and position, it is excluded fromstats.parsedFileswhile still counting towardstats.totalFiles, and the core logs a warning. Read as exactlyfalse, not as falsiness: plugins arrive as plain JavaScript, and a plugin that omits the key gets the behaviour it had before the field was read at all rather than having every file it warned about withdrawn.- A
treeofnullwithdraws the file on the same terms, and is expected to carry arecoverable: falseerror beside it (§4.2). The two are read as one condition, so a plugin that sets only one still gets what it asked for — and a plugin that built a usable tree and then decided the file must not be used (a wrong dialect, a generated blob) does not have to discard the tree to say so. - Its parse errors are still reported on
ScanResult.parseErrors, for the reason §7.1.2 gives: they are diagnostic rather than IR, and here they are the entire account of why the file went. - Its import edges are kept — the one place this differs from a file abandoned on its
parseTimeoutMsbudget, which is being withdrawn deliberately. A file whose contents could not be used still told us truthfully what it imports. Nothing consumes them yet: call resolution looks the list up by the file a Symbol came from, and a withdrawn file has none, so the entry waits for the dependency-extraction pass. aburi scanstays at exit0. An unparseable file is a property of the source, like an over-size or timed-out one; no skip reason moves the code by being that reason, andextraction-failedalone moves it by being one (§7.2, cli-spec.md §5.4). What does move it regardless of reason is how much was lost: a scan that parsed nothing exits3, as does one that fell below aminParsedFileRatiothe workspace set (cli-spec.md §5.7). Refuse every file in a workspace and the run is not green.- warning stderr:
Skipped <file>: parse reported a non-recoverable error at <line>:<column> — <message>. With no tree and no such error, the first recoverable one is quoted instead —Skipped <file>: the language plugin returned no tree; first error at <line>:<column> — <message>— because a withdrawn file is excluded from the CLI's recoverable-error count and this line is then the only place its errors can be read.Skipped <file>: the language plugin returned no treewhen there were none at all.
7.1.1 Large-file skip
Files whose size exceeds config.maxFileSizeBytes (default: 2 * 1024 * 1024 = 2MB) are skipped without parsing.
- Normal code does not exceed 2MB (only generated bundles / minified files do)
- Large files exhaust the WASM heap and make parse time explode
- Skipped files are returned on
ScanResult.skippedwithreason: "over-size"and named in the Document atstats.skippedFiles[](ir-schema.md §2), so a lateraburi diffcan tell a file that was never read from one whose API was deleted - warning stderr:
Skipped <file>: <size>MB exceeds maxFileSizeBytes (2MB). Override with config.maxFileSizeBytes.
7.1.2 Timeout
If the total of parse + extractSymbols + walkBody for one file exceeds config.parseTimeoutMs (default: 5000 = 5 seconds; the config schema's minimum is 100 and it has no maximum), abort, skip that file, and warn. This prevents a broken grammar or pathological source (deep nesting, etc.) from stalling the whole run. Following a decorator's name into other modules (§5.2.4) is not part of the total: the clock stops while it runs.
The budget is cooperative, for the reason effect-plugin.md §5.1.1 gives for the classify budget: extractSymbols and walkBody are synchronous plugin calls, and nothing can interrupt one that has already started. It is read at the three points that bound the work still to come — after parseFile, after extractSymbols, and before each candidate's walkBody — so what it guarantees is that an over-budget file is handed no further work. A file costs at most its budget plus one stage, and one enormous candidate can still overrun by however long that candidate takes. A hang inside a single call is not something a wall-clock budget can catch at all.
An aborted file contributes nothing to the IR: no Symbols, no import edges, and no stats.effectClassifyTimeouts entries accumulated from the candidates it did finish. Keeping whichever Symbols it produced before the budget ran out would make the Document depend on how fast the machine was that day, so the outcome is binary per file. It is recorded in ScanResult.skipped with reason: "parse-timeout", repeated on ScanResult.parseTimeouts with the budget and the elapsed, and excluded from stats.parsedFiles while still counting toward stats.totalFiles.
Its parse errors are still reported. They are diagnostic rather than IR, and they are what a slow file most needs to keep: backtracking over malformed input is a common reason for a slow parse, so a run that swallowed them would tell the reader to raise parseTimeoutMs when the fix is the syntax. A file that is both broken and slow appears in parseErrors and in parseTimeouts — but never in both parseTimeouts and a §7.1 withdrawal. The withdrawal is decided before the first deadline reading, and the two would compete for the one skipped entry the file gets: a plugin's outright refusal reported as a file that was merely slow sends the reader to raise a budget that was never the problem.
- warning stderr:
Skipped <file>: extraction reached <elapsed>ms, exceeding parseTimeoutMs (<budget>ms). Override with config.parseTimeoutMs.
A file being skipped on wall clock does mean the IR can differ between a fast machine and a slow one, at file granularity. That is inherent in asking for a time budget; a run that wants reproducibility across machines sets parseTimeoutMs high enough that nothing reaches it.
7.2 Extraction exceptions
- If any plugin call for a file throws —
parseFile,extractSymbols,symbolDropHint,walkBody,normalizeAst, a frameworkclassifySymbol, or an effectclassify— the core withdraws that file and keeps going. One file's bug does not halt IR generation. - A file whose Symbols cannot enter the Document is withdrawn on the same terms, though nothing threw. Three faults do that. Two are ir-schema.md invariant #1, read off the file being extracted: two of its own Symbols under one id, or one whose id names a path that is not this file's (§4.3); both carry
code: "duplicate-symbol-id". The third is a candidate whosesource.filebreaks the path grammar of invariant #10: the core reads it throughdocumentPathOrViolation, the checktoDocumentPaththrows from, and recordscode: "non-posix-path"with a message naming the language plugin andSymbolCandidate.source.file. The path is checked first, so a file whose candidate has both a refusedsource.fileand an id naming another file is withdrawn for the path. Each fault is in what the plugin reported about this file (ctx.file.pathwas minted at discovery, so a refusedsource.fileis a path the plugin built), so the file it reported is the one that goes. None of the three is a plugin-set fault (below): a plugin can get one generated file wrong and every other file right. The check runs per file, before any of the file's output is accumulated, because that is the last point at which the file can still be withdrawn and named —assertIRIntegritysees the assembled Document and can only refuse the whole of it, which is what used to happen. Which of two Symbols to keep is not the core's to decide — the plugin reported nothing that separates them — so the file goes whole, with the fault's code on itsScanResult.extractionFailuresentry and the fault named indetail. The document-wide check stays where it is, as the backstop. - A file a parser worker ended under is withdrawn on the same terms: a plugin that calls
process.exit()or throws outside the core's handling, from a timer say, ends the worker thread rather than the call, and the file it was extracting goes, withcode: "extraction-thread-ended"and what ended the thread indetail(performance.md §8). On the main thread, under--concurrency 1, either ends the process instead. A file whose extraction holds a value that cannot be sent back from a worker, such as a function left in a Symbol, is withdrawn there as a throw is, withcode: "extraction-uncloneable"(performance.md Rule PF-7). - The withdrawn file is named in
ScanResult.skippedwithreason: "extraction-failed", and the thrown message is kept beside it inScanResult.extractionFailures, with the error's stringcodewhen it has one, whatever its class. That code is how a consumer tells a shared guard's refusal (§4.4) from the plugin's own bug without reading the message. The core logs a warning per file;aburi scanexits3when the list is non-empty, so a run that dropped a file is not green. - A file withdrawn because a plugin threw loses its recoverable parse errors, unlike one abandoned for its
parseTimeoutMsbudget: the pipeline result never materialized, so the thrown message is the diagnostic in their place. A file withdrawn for one of the three faults above keeps them, on the same reasoning read the other way — its extraction ran to a result, so those errors are observations the parse really made about the file, and dropping them would hide a genuine parse fault behind a fault in its Symbols that may well be its consequence. - Some are not absorbed. An error whose code names a fault in the plugin set rather than in the file propagates and ends the run, because it repeats for every file and withdrawing them one at a time would report the workspace as broken instead of the plugin. Today that is
scan-plugin-misconfigured(an effect plugin returning a Promise fromclassify, a language plugin emitting Symbol ids with no language prefix or with a prefix other than its manifest'slanguageId, or a plugin refusing its ownpluginOptionsvalue),invalid-language-id(the prefix is present but is not a legalLanguageId), andvocab-undeclared(an id the emitting plugin's manifest does not claim —effect-plugin.mdEP1 — or one a plugin refused through the registry's ownassertEffectDeclared/assertExtKindDeclared, which raise the registry's error under that code). The code decides, not the class, andaburi scanexits3for each (cli-spec.md§5.4). Everything else describes the file —anonymous-symbol-id-attemptedfrom a qualified name the grammar refuses,non-posix-pathfrom a file whose path a Symbol id cannot hold (a:or#in it) — and is absorbed. So are the shared guards'unnormalized-*codes (§4.4). An unnormalized value is a language-plugin bug, but one that a construct in the file triggers, so it repeats only in the files that contain that construct. Withdrawing those names exactly them (effect-plugin.mdEP3a), where ending the run would hide every file the plugin extracted correctly. - A plugin-wide bug that carries none of those codes still presents as one failure per file rather than one crash. That is the intended shape — every file named, the messages identical, the count the whole workspace — but it is a weaker diagnostic than a code that says outright what is wrong.
- The behaviour above is unconditional: there is no "stop at the first extraction exception" mode. (
config.strictis about something else: whether the core's own vocabulary check ends the run, which it does throughvocab-undeclaredabove. A refusal a plugin asks for throughctx.registryends it either way.)
7.3 Manifest violations
- If a plugin puts an
extKindnot declared in its manifest into a SymbolCandidate → extraction-time error (drop-list §6.3 / extension-vocab §6.3) - In
--discovermode this is downgraded to a warning (extension-vocab §11.5)
7.4 Syntax the language plugin does not support
- Example: the TS plugin encounters an unknown syntax element (a future TS language extension) → skip without creating a SymbolCandidate, debug log
- This is not an error (to allow incremental support of new syntax)
8. Parser Implementation Options
A language plugin may choose its parser freely, provided it satisfies the following:
- Position information (line/column) is available per node
- Recovery from partial parse failures is possible (recommended)
- Node kinds are distinguishable (statement / expression / declaration classification)
- Access to a raw AST that does not desugar the language's syntactic sugar (e.g. does not collapse
async functionintofunction+ flag)
Representative options:
| Parser | Applies to | Notes |
|---|---|---|
| tree-sitter (WASM) | multi-language | rich grammars, recoverable, first choice for official Aburi language plugins |
| tree-sitter (native) | multi-language | faster than WASM but requires a node-gyp build |
| oxc-parser | TS/JS | faster than tree-sitter, TS-only |
| ast-grep | multi-language | tree-sitter based, easy pattern authoring |
| swc | TS/JS | written in Rust, TS-only |
| ruff (internal AST) | Python | written in Rust, limited public AST API |
| go/parser | Go | standard library |
| syn | Rust | proc-macro only, heavy for standalone CLI use |
The official @aburi/lang-typescript plugin adopts tree-sitter WASM for its initial implementation (proven in a PoC; zero-build on Windows is an advantage). Replacement with oxc-parser is under consideration for a later version.
8.1 Memory-management convention for WASM parsers
WASM parsers such as web-tree-sitter hold a WASM heap separate from the Node heap; there is a known issue where failing to explicitly free parser instances leads to RangeError: WebAssembly.Memory() crashes after parsing thousands of files.
Each plugin must follow these conventions:
- Release the parser and the tree, each on the side that owns it
- Create the parser inside
parseFile()and callparser.delete()after obtaining the result. It never leaves the function, so the plugin frees it. - The tree is handed over. The plugin implements
releaseTree(tree)and the core calls it once per non-null tree, after the last ofextractSymbols()/walkBody()/normalizeAst()has read it — including when one of those threw, when the file was withdrawn, and when it ran out of parse budget. A plugin that deleted the tree on its own way out ofparseFile()would be handing the core a dead handle. - The exception is a
parseFile()that fails after parsing: the caller never receives the handle there, so the plugin releases the tree itself before propagating. - Node references taken out of the tree (
SymbolCandidate.bodyNode,fullNode) are valid for as long as the tree is, which is the file's pipeline run rather than the scope ofparseFile(). None of them may outlive the tree: what the pipeline returns is the strings and ranges read out of the nodes, never the nodes. - A
releaseTreethat throws is recorded onScanResult.treeReleaseFailuresand does not fail the file, whose Symbols are already in the IR. AreleaseTreethat is declared as something other than a function is recorded there too, saying so — it is a contract violation rather than a parser fault, and the two are not described in the same words.
- Create the parser inside
- WASM heap budget under parallel execution
capabilities.wasmHeapPerWorkerMBin the plugin manifest (range: 16–4096 MiB, implicit default 256 MiB when undeclared) is the source-of-truth- The CLI sizes its parser pool so that every worker's budget fits in the memory the runtime reports free: at most
floor(availableMemoryMB / wasmHeapPerWorkerMB)workers, whatever--concurrencyasks for (performance.mdRule PF-2). The budget sizes the pool and caps no worker's heap, since a WebAssembly memory sits outside the JavaScript heap a cap would limit (performance.md §6.2) - When multiple lang plugins coexist in the same run, the maximum of each plugin's declared value is used (sized for the hungriest lang)
- Reservation for a native-binding fallback
- In a future release, switching to native bindings (e.g. the
tree-sitterNode bindings) may be added via flags such ascapabilities.preferNative(see the roadmap) - Currently only WASM is implemented; no native fallback is provided
- In a future release, switching to native bindings (e.g. the
8.2 Cost convention for WASM node access
The same heap boundary has a cost consequence that is easy to miss, because the JS surface hides it. A getter like node.children or node.namedChildren is not a field read: it unmarshals every child across the WASM boundary into a fresh JS object, and the array it returns is cached on that JS wrapper only — the next node.parent hands back a new wrapper and pays for the list again.
So a per-node question must be asked of the node, never of its container:
- Ask the node:
previousSibling,previousNamedSibling,nextSibling,childForFieldName,childrenForFieldName. Each crosses the boundary once per node it returns, and a backwards walk over a run of siblings stops as soon as the run ends.childrenForFieldNameis bounded by the node's own children — a handful for a declaration — and unmarshals only the ones the grammar tagged, so it is a question about the node even though it returns a list. - Do not ask the container: reading the parent's whole child list to find the node's own index in it. It answers the same question, but a top-level declaration's parent is the entire file. Doing it once per declaration makes a file of N declarations cost O(N²) — the shape a generated API client or a Prisma type file has, comfortably inside
maxFileSizeBytesand minutes long to extract.
Reading the container is right when the container is what the question is about: every member of a class body, every argument of a call. It is the per-node use that has to be avoided. When a per-node question can only be answered by the container — whether a class of a namespace's name is declared in the same statement list — read the container once per tree and remember what it holds, keyed by the container, so every later node is answered by a lookup instead of another read of the list.
9. Verifiable Properties (Test Criteria)
Every language plugin must pass the following tests.
9.1 Structural extraction
| ID | Input | Expected |
|---|---|---|
| LP1 | top-level function | SymbolCandidate.kind = "function", name = the function name |
| LP2 | class | SymbolCandidate.kind = "class", name = the class name |
| LP3 | class method | SymbolCandidate.kind = "method", name = Class.method |
| LP4 | class static method, or an export of a namespace merged into the class (LP8n) | name = Class::method |
| LP5 | interface (TS/Java/Go) | SymbolCandidate.kind = "interface" |
| LP6 | default export of anonymous function | name = <default> |
| LP6a | a default export written apart from the declaration it names — const Page = () => … followed by export default Page | the declaration's own SymbolCandidate, visibility = "public" and derivedBy carrying export-default, exactly as the wrapped spelling (export default function Page()) reports. The two are one boundary and the frameworks that read export-default to find a page or a component must not depend on which was written — which is also why the value is read through LP7a's wrappers, export default Page satisfies NextPage being an ordinary spelling of the same export. What the reading stops at is what is not a reference to a declaration: a call (withAuth(Page), by LP7b), a value the module builds ({ Page }), a member of one (Routes.Page), and an identifier that names an import, which declares nothing here to reach. A declaration reached by name is reached by a bare name: a class member called Page (Shell.Page, Shell::Page) and a namespaced one (Routes.Page) carry a separator no bare identifier can spell, and a call Symbol (LP20g), whose qname is one identifier-legal segment and so has no separator to rely on, is refused by kind. export { Page as default } is the same default export written as a clause and answers the same way; LP6c reads it, with every other clause spelling |
| LP6b | a declaration carrying the export keyword, of any kind — export interface I {} beside export const x = 1 | visibility = "public" and derivedBy carrying export-keyword, for every kind alike. Whether a declaration was exported is a question about the statement it was written as, so the answer cannot depend on which declaration follows the keyword — and for four kinds it did: the interface, type alias, enum and namespace builders wrote a one-token derivedBy naming the kind and stopped there, where visibility was right throughout. The cost was not a missing field but a spelling-dependent answer: a consumer asking a Symbol "was this exported?" was told so for the const and told nothing at all for the interface beside it. derivedBy is the closed vocabulary diffs and filters read (§4.3, ir-schema.md §5.5) and LP6a already puts exportedness in it — a framework plugin finds a page by reading export-default off a Symbol — so the token is evidence about the declaration, not a note about how the module was written. One reader answers it for every kind, for LP7a's reason: the node it is handed differs per kind (the module for a namespace, the enclosing lexical_declaration or variable_declaration for a variable, the declaration itself for the rest), and a second reader is where the kinds start to disagree again. It reaches the statement through the declare wrapper, so export declare interface I {} answers as LP36 has it. Within one statement export default replaces the keyword rather than joining it — the statement cannot be written with both, and LP6a's token is the one a framework reads; across two statements they join, LP6a's detached spelling carrying export-keyword and export-default alike, so exclusivity is a rule about a statement and never about a Symbol. Illegal source the grammar still accepts answers rather than crashing: export default const x = 1 reports the default export, as the same two keywords on a class do. A declaration written inside an exported namespace is not exported by it, and one written export inside a plain namespace is: the keyword is read off the declaration's own statement, which is what visibility answers too. An export clause is a statement of its own and LP6c's, and its evidence joins this token as LP6a's does. Where the two answers can come apart is a Symbol several declarations wrote, and only in source the language rejects: §4.3.1 gives visibility from the leading declaration and derivedBy from the union, so interface I {} reopened as export interface I {} (TS2395) is internal and carries the token. Legal source cannot reach it — a merge's declarations must agree about being exported — which is why the fold keeps one rule for every scalar rather than deriving this one from the union |
| LP6c | a declaration an export clause names — function POST() {} followed by export { POST }, export { handler as GET, handler as POST }, export { Page as default }, export type { T }, export { type T }, export { x as "x-y" } | the declaration's own SymbolCandidate, visibility = "public" and derivedBy carrying export-clause:<name> for each name the module's clauses export it under, once each and in the order they are written, and export-default for the name default, quoted or not — LP6a's token, export { Page as default } being the default export export default Page writes. A module exports a binding under the name its clause gives, not the one it was declared with, and a reader keyed to the export needs that name: a Next.js route is whatever the module exports as GET, so export { handler as GET } is one and export { GET as handler } is not, and a token without the name would tell them apart by nothing. The token carries the name even where the two agree, so a consumer reads one shape. One reader answers every clause spelling together with LP6a's detached export default, so the answer depends on which declaration a clause names and never on how: covering the default spelling alone would have made it depend on the name a clause wrote. It joins what the declaration already carries across statements, as LP6b's tokens do: export function f() {} with export { f as g } carries export-keyword and export-clause:g. What it reaches is LP6a's — a top-level declaration by its bare name, a call Symbol refused by kind, nothing for a name that is an import — read off the module's own statement list. A clause inside a namespace is an error (TS1194) except in an ambient one: declare namespace N { function GET(): void; export { GET } } is legal, and its clause is not read, so N.GET stays internal where export function GET(): void in the same namespace is public by LP6b — a known limit. A type-only clause or specifier (export type { T }, export { type T }) is erased at runtime, so it exports only a declaration that is nothing but a type, an interface or a type alias, and leaves any other declaration it names as it was: function handler() {} with export type { handler as GET } gives the module no GET to call, and reading it as a value export would make a route of what Next.js answers 405 for. A clause with a source (export { x } from "./y", export { y as x } from "./y") is a re-export: it binds nothing in this module, so a declaration sharing its name is not exported by it, and the statement is read only for the import edge it adds (§5.2.2). The names are an api input (fingerprint.md §3.8), so a change to the names alone — export { handler as GET } becoming export { handler as DELETE } — moves the api fingerprint, and aburi diff reports the Symbol changed with the names it gained and lost; the keyword spelling exports a declaration under its own name, so the same change there reports it removed and added |
| LP7 | const f = () => ... | name = f (the variable name becomes the qname). The value is a function when it is an arrow, a function expression or a generator function (function* () {}, async function* () {}), and that one set is what every site that asks reads: a binding, an anonymous default export (LP6), a class field (LP20f), an object entry (LP7d) and a call's argument (LP7c, LP20f1, LP20g). A generator has parameters and a body, and defining one runs none of it: the body runs only as the iterator a call returns is consumed. So it is no more data than an arrow is, and it reads as function* g() {} already did. While the set held only the first two, const g = function* () { yield fetchPage() } was a bodiless const, so fetchPage and any effect it carried were on no Symbol, and a class of generator fields was a pure DTO dropped with the calls its owner carried for them |
| LP7a | the same binding written behind a wrapper that says nothing about the value — TypeScript's (f), f as T, f satisfies T, f! | the same answer as LP7. A wrapper the language uses to group, to name a type or to assert non-null does not replace the value, so the test for "is this a function?" reads through it. One reader answers what a wrapper is, for every question the plugin asks about a node — a binding, a member, a call's argument, a call's receiver and a default export's value (LP6a). Two readers is the defect, not the duplication: while the receiver side hand-unwrapped only parentheses, (app as Express).get(p, h) was not a registration at all |
| LP7b | a call in the same position — const f = withAuth(() => …) | not a function. A call returns one by convention and nothing in the tree says so, which is the line the unwrap stops at: past it the plugin would be guessing rather than reading. That line decides the kind only — the function written inside the call is still read, as the const's body (LP7c) |
| LP7c | LP7b's const, export const POST = withAuth(async (req) => { … }) — and memo(function Row() {…}), forwardRef((p, r) => …), t.procedure.query(() => …) | still a const with a null signature, and the functions written as direct arguments of a call on the initializer's spine are its bodies, the first as bodyNode and the rest on mergedDeclarations — LP20g's reading and LP20h's layout — with derivedBy carrying call-argument-function. LP7b decides what the const is; the function is still written in it and in no other declaration, so leaving it unwalked put its rules, calls and effects on no Symbol at all. The wrapping call is not a body, so withAuth is not one of the const's calls. Each function is a walk root, so a concise arrow's expression body is read as its return value (LP19a): const doubled = xs.map((x) => x * 2) reports return: x * 2, as xs.map((x) => { return x * 2 }) does. The spine is every call the receiver chain passes (§5.2.3), through a member access or an index alike. A function the spine invokes in place, const h = (() => { … })(), is read the same way and leads the bodies: the call is written to run it there, once, to make the value, which is what users.map((u) => …) does with its callback. It is read behind await too, const data = await (async () => { … })(), since the function runs whether or not its result is awaited. derivedBy then carries invoked-function, and call-argument-function only when an argument's function is read beside it ((async () => { … })().then(() => { … })). The reading asks nothing about the call, so it is wider than the wrappers: users.map((u) => u.name), xs.filter(…).map(…), Array.from(xs, (x) => …) and compareBy((item) => item.id) give their consts a body too. What it does not reach, each measured: a function inside an argument (withAuth(withLogging(async () => { … })), past the line LP20g draws) or in an object property (useQuery({ queryFn: () => { … } })); a function handed to new (new Promise((resolve) => { … })), since new_expression is not a call; a function an awaited call is handed (await withRetry(() => { … })), since the const holds what the call resolves to and not a function wrapping the one it is handed; a body of no width; and a destructuring declaration (const { GET, POST } = createHandlers(…)), whose bindings have no body of their own. The same call written as a default export is LP7c1's. A class field written the same way (handle = withAuth(() => { … })) is read the same way, as a member (LP20f1). A function a field's value invokes in place (seed = (() => { … })()) is not: the field runs it on construction, so it stays on the class's walk. The normalized string is the whole declaration, as LP20i's is the whole call: narrowing to the body would make withAuth(async (req) => { … }) and withRole(async (req) => { … }) serialize identically, and it keeps the string the const had before it had a body |
| LP7c1 | LP7c's call written as the default export — export default withAuth(async (req) => { … }), export default memo(function Row() { … }), export default connect(mapState)(function View() { … }) | a const named <default> (LP6), read as LP7c reads its const: the functions written as direct arguments of a call on the value's spine, through LP7a's wrappers, are its bodies, the first as bodyNode and the rest on mergedDeclarations; signature is null, visibility = "public", and derivedBy carries call-argument-function and export-default. A function the value invokes in place, export default (async () => { await main() })(), leads the bodies with invoked-function on derivedBy, as it does for LP7c's const, awaited or not. The statement declares nothing else, so without it the function written there was in no Symbol and an edit to it moved no fingerprint. The wrapping call is not a body, as it is not the const's, and the normalized string is the whole statement, so withAuth becoming withRole moves syntax. A caller importing the default reaches it, as it reaches any <default> (call-resolution.md §4.4). A call handed no function writes no function for a Symbol to carry and still produces no Symbol: export default defineConfig({ … }), and export default withAuth(Page), where LP7b's line also keeps Page from being exported by it (LP6a). The calls such a value makes on import are on no Symbol either, a gap LP20o records. Nor does one whose function is deeper than LP7c reads (withAuth(withLogging(() => …))). Frameworks read it as they read the const (§5.2.1) |
| LP7d | a binding initialised by an object literal holding functions — export const api = { get: async () => fetch("/x"), post() { send() } } | one member SymbolCandidate per function the object holds, api.get and api.post: kind = "method", visibility = "public", derivedBy carrying object-method, plus property-assigned-function for the pair spelling and accessor-declaration for get / set. LP20f's reason applies unchanged: defining the object creates the closure and only calling the property, or iterating what it returns, runs the body, so the body is the member's and the binding stops carrying it (LP20a). The binding stays a const with a null signature; its body is the object literal less those members, so client: makeClient() is reported on api, where it runs, and derivedBy carries object-literal-initializer to say why a const has a body. The member set is a method_definition — the class body's node, with its accessor, generator and async spellings — and a pair holding a function in LP7's set, read through LP7a's wrappers. The initializer is read through them too, as const and satisfies Api being how a handler map is ordinarily written, and let and var are read as const is. A body of no width is refused, as LP20g and LP7c refuse one: a half-written get: () => still parses as an arrow whose body is a zero-width placeholder, and a member for it would publish a method the source does not write. kind is a class member's whichever way the entry is written, so a reader keyed to a module-level function by its name — a Next.js route verb, a React component or hook — does not take { GET: () => … } or { Button: () => <b /> } for one; visibility is a class member's with no modifier, since an object literal can write none. The range is the entry's and the signature the function's, as LP20f's are. An accessor pair or a repeated key is one SymbolCandidate, the getter leading (LP8a). A namespace holding only types may be written beside the binding, and its export type get and the member api.get then fold, led by whichever is written first (§4.3.1). The binding's normalized string is still its whole declaration — the object is not the declaration's own child — so no binding's syntax fingerprint moves, and an edit to a member moves the binding's as an edit to a method moves its class's |
| LP7e | an object literal nested under a named entry — { v1: { get: () => … } } | its members one segment further down, api.v1.get, at any depth: the dotted path is how the source reaches the function. The depth costs one SymbolCandidate per function written and none per other value, so a configuration object of strings and numbers mints nothing, and the object in between declares no SymbolCandidate of its own. A dotted call target composes past the binding without one (call-resolution.md §4.3), so api.v1.get() reaches the member. What the nested object evaluates stays on the binding |
| LP7f | an entry LP7d does not admit — a computed key ([k]: () => …), a number, a quoted key that is not an identifier ("a-b"), a key the parser recovered, a #-private name; a value that is not a function in LP7's set (withAuth(() => …), [() => …]), or a function with a body of no width; a shorthand; a spread | no SymbolCandidate, and what the entry evaluates stays on the binding's walk — LP20c's answer for a class member. The key gate is a class member's (LP8m), so a quoted key that spells an identifier ("get": () => …) is the member get and a quoted "#v" is refused. The #-private name is where the two diverge: a class body reads #v as its private member (LP8o), but outside a class body #v is a SyntaxError, which the grammar parses anyway, so there is no private member for the segment to name. The object reader refuses it ahead of the shared gate, which would admit it, so the refusal is the reader's own and nothing behind it repeats it: without it the member's qualified name cannot be built and extraction throws. An object nested under a key with no segment is the binding's whole, functions included. A value that is a call handed a function (h: withAuth(() => …)) is where the entry deliberately stops short of LP7c and LP20f1, which read the same value on a const and on a class field: no case has asked for the entry yet, and reading it would bring LP20f1's known cost to every handler map, so the entry keeps the answer it had |
| LP7g | an object literal no binding names, or one a binding does not hold directly — export default { fetch() {} }, module.exports = { … }, an object handed to a call (Object.freeze({ … }), useQuery({ queryFn: … })), an element of an array, the initializer of a destructuring declaration — and an object a class field holds (handlers = { get() {} }) | no member SymbolCandidate. Nothing refuses them: the object reader is asked only of a binding's initializer and of an entry nested under one (LP7e), and none of these reaches it. So the limit rests on where objectLiteralOf is called rather than on a check, and a reader added at another site moves it. Why it is drawn here: <default>.fetch is not a qualified name, for LP6's reason about an anonymous class; a call returns whatever it returns (LP7b), so an object handed to one names no path; a destructuring declaration's bindings have no body of their own; and a class field holding a handler map holds no function, so its calls stay on the class (LP20f). A known limit, each measured: the functions in the first five are in no Symbol, as they were |
| LP7h | a binding initialised by a class expression — export const Registry = class { … }, read through LP7a's wrappers ((class { … }), class { … } as T), and with let or var | the class class Registry { … } declares: kind = "class", derivedBy carrying variable-assigned-class, and its members as a declared class's are (LP8a–LP8q; . and :: per ir-schema.md §3.2), so Registry.reset and Registry::make. A namespace beside it merges as it does into a declared class (LP8n): what it exports is on the static side, Registry::O. const Registry = class Inner { … } is named Registry, since Inner is in scope only inside the class body. The range is the statement's, as it is for a function a binding holds. The class's own body is its walk (LP20a), so its field initialisers and static blocks are walked on it; read as a const with no body, the class's methods, initialisers and static blocks were in no Symbol. Being a class, it takes a class's drop hints (drop-list.md §4.2): a class of fields alone is a pure DTO, so seed = compute() in one is dropped with its calls, as it is in a declared class of fields. The reading stops at LP7b's line: a class handed to a call (const A = mixin(class { … })) leaves the binding a const. A binding inside a function is never extracted, so a class it holds is that function's (LP20e). Known limits. A class the binding does not hold directly — handed to a call, in a conditional (cond ? class { … } : B, a ?? class { … }), under new — is walked by no Symbol. A type alias of the same name written first (export type R = InstanceType<typeof R> above export const R = class { … }) leads the merge (LP8h), so the Symbol is kind = "type" and takes the type alias hint, and the static blocks' calls are dropped with it; interface P {} above class P {} behaves the same. And a member calling through the class's own name (class Inner { static make() { Inner.build() } }) records Inner.build, which file scope has nothing to bind to, where the declared form's Registry.build() resolves to Registry::build |
| LP8 | nested class (Outer.Inner.method) | the . nesting in name is correct |
| LP8a | a getter and a setter for one property | one SymbolCandidate. The two are one member, and one id can only carry one Symbol (§4.3.1) |
| LP8b | LP8a's signature | the getter's. A property's type is what reading it answers; the setter's signature is the type of writing it |
| LP8c | LP8a's bodies | both, the setter's on mergedDeclarations. walkBody reports the calls in either of them |
| LP8d | a getter with no setter, or a setter with no getter | one SymbolCandidate, nothing merged into it |
| LP8e | a static accessor pair beside an instance pair of the same name | two SymbolCandidates — Class::v and Class.v are different entities |
| LP8f | an overload declaration beside its implementation | one SymbolCandidate, and the signature and body are the implementation's. The overload is written first, so a rule that took the first declaration would report the member as body-less and give it the wrong parameter types. The overload is not discarded: it folds in as a declaration with no body, which is how the syntax axis sees it (LP8q) |
| LP8g | a class body of overload declarations with no implementation | no member SymbolCandidate. The same answer a top-level overload with no implementation gets, so the construct does not depend on where it is written |
| LP8h | a declaration merged with an earlier one — a reopened interface or namespace, a namespace augmenting the class or function above it | one SymbolCandidate, carrying the earlier declaration's kind and range and every declaration's derivedBy. Anything the later declaration declares in turn (N.b from a reopened namespace N, f.b under a function) is its own Symbol and must still be there; under a class it is named by LP8n |
| LP8n | what a namespace merged into a class declares — class C {} beside namespace C { export function m() {} } | an export is the class's static member, C::m, apart from an instance member C.m; everything under it sits under that segment (C::Inner.g, and C::K::s for a nested class's static). A statement the namespace does not export is local to it and keeps the dot (C.local, internal). An ambient namespace exports without the keyword, and a dotted namespace C.D {} makes D the member (C::D.x). The class is looked for in the statement list the namespace is written in, so one declared in another block of a reopened outer namespace is not seen and the exports keep the dot (A.C.x) |
| LP8r | one file of namespaces with no class beside them, at two sizes, at the top level or all inside one outer namespace — the shape of a generated API client | LP8n's look-up reads each statement list's class names once, not once per namespace (§8.2), so the number of children read grows with the file rather than with its square. LP8n's answers are unchanged in every statement list. Read once per namespace instead, a generated client of a few thousand namespaces ran past parseTimeoutMs and was skipped as parse-timeout (§7.1.2) |
| LP8i | a file that declares nothing twice | no evidence of merging anywhere in it, and the mergedDeclarations key absent — not present and empty. The two stretches of that field are the exception, and carry the key only for a second body: a call Symbol with more than one handler (LP20h) and a const handing its call more than one function (LP7c) |
| LP8j | a merged declaration that has no body of its own — a reopened enum / namespace / type alias | its fullNode still reaches normalizeAst, so editing the second declaration changes the Symbol's normalized string |
| LP8l | a declaration whose name spells a path the language treats as nesting — TypeScript's namespace A.B {} | one SymbolCandidate per segment, and the body under all of them. The dotted text is not one qualified-name segment, so feeding it to the id builder loses the whole file (§4.3) |
| LP8m | a member whose name is written as a string literal — class C { "createInvoice"() {} } | the segment the literal decodes to, when that is an identifier the qualified-name grammar admits; otherwise no SymbolCandidate (LP20c). A decoded "#v" has no SymbolCandidate either: the segment #v is the #-private member's (LP8o), and a quoted key is a public property whatever its characters, so the producer refuses the leading # — the refusal is the producer's, not the grammar's, and it is the default isQnameSegment answers with. A property key is a string, so the quoted and the bare spelling of one identifier are one member and fold by id (§4.3.1) — and "constructor"() {} is the construction path, which the language decides by the property name and not by how it is written. A name the parser guessed at is refused in both shapes it arrives in: a literal that parsed in part, and one that did not parse at all — the second leaves no literal to refuse, so what says so is an ERROR among the member's own children, never hasError, which a broken body would trip |
| LP8o | a #-private member — class C { #v() {} static #w() {} }, a #-private field holding a function, accessor pair | C.#v and C::#w, with the #, and visibility = "private". #v and a v written beside it are two members, so dropping the # folds two entities onto one id (§4.3.1). The segment is ECMAScript's PrivateIdentifier: one #, leading, and only after a separator (ir-schema.md §3.1). Only the private name node asks the id builder for it — core's isQnameSegment admits #v only with privateName set — so a string key cannot reach it (LP8m, LP20j). Visibility is read off the node type rather than the segment's #, which carries it only because the string refusal holds. #constructor has its own segment and is an ordinary member, never the construction path |
| LP8k | a decorator written on a merged declaration that is not the leading one | among the Symbol's decorators. A boundary decorator lost here re-enters the Symbol into drop-list.md Category B |
| LP8p | a class's head — abstract, its type parameters, extends and implements — export abstract class UserService<T> extends BaseService implements Reader {…}, an anonymous export default class extends Base {…} included, and a class merged behind an interface of the same name | reaches the normalized string, straight after that class's own class_body and only when present, so a class with no head keeps the string it had. The head is read off each declaration rather than the leading one, so a class written after an interface keeps it, and a merged string is still each declaration's string alone, joined. A class is described by its body — describedNode's rule, of which §4.3.1 gives the bodiless half — and a function by its body and its parameter list (LP8p1), since the api axis hashes a function's head only as far as the api input reads it, a parameter's type and form. A class carries no Signature (ir-schema.md §7), so a re-parent, abstract added or dropped, or a new type parameter reached no axis and the diff reported nothing, though each moves the class's contract and fingerprint.md §5.4 already asks the syntax axis to see a renamed identifier or a changed modifier. LP20i is the general case: a describing node dropped from the string is a change the axis stops seeing. The head goes on the syntax axis rather than the api one because Signature has no place for heritage or abstractness, and decorators stay out, being on the api axis already. The type parameters are read as LP27c's recovery leaves them, so a variance-annotated class inherits that row's misread. Two boundaries are recorded rather than closed. A re-parent moves the class's contract but lands in the syntax-only tier, which fingerprint.md §5.5 files as an implementation refactor, low-priority, and shows collapsed; lifting it needs Signature to have a place for a head, which nothing else in this table asks for. And an interface is in the same position — its extends and type parameters sit beside its interface_body, and it carries no Signature either — but is not covered: only its body is read, so interface A extends B {…} → extends C still moves no fingerprint |
| LP8p1 | a function's parameter list — pick({ a: b }) → pick({ c: b }), second([, b]) → second([b]), f(limit = 20) → f(limit = 10), a parameter renamed and unused — for a function, a method, a constructor, an accessor and a field or an object entry holding a function | reaches the normalized string, straight after the body and only when the list holds a parameter, so a function with none keeps the string it had. The api axis reads a parameter's type and form (optional, rest) and not its name, its pattern or its default's value (fingerprint.md §3.1, A1, A22, A23), and the walk reads a default's calls and rules (LP20d) and not a literal, so each of these edits changed which value a binding receives and reached no axis. The list goes on the syntax axis, as LP8p's head does, which is where an edit to how the code is written belongs; it reaches the string as the parser wrote it, less the punctuation fingerprint.md §5.1 item 4 leaves out, so a trailing comma after the last parameter changes nothing. It goes in whole, types included, so an edit to a parameter's type, ? or ... moves syntax as well as api, and --fail-on syntax-changed counts it; a return type or a type parameter sits outside the list and moves api alone. A parenthesis-free arrow's lone parameter (x => …) is described as the parenthesised spelling parses, wherever the arrow is written, since a formatter adds those parentheses. A declaration described whole — an overload signature, an abstract member, a declare function, LP7c's const, LP20f1's field, LP20i's registration — already carried its list and is unchanged. One boundary is recorded rather than closed. A parameter's decorators (@Inject(X) → @Inject(Y)) and a parameter property's modifier (private s → public s) are in the list, so an edit to either moves the method or constructor, which before moved on no axis; but it lands in the syntax-only tier, which fingerprint.md §5.5 files as an implementation refactor, low-priority, and shows collapsed, though a parameter property's modifier changes the class's public surface. Lifting it needs the api input to read a parameter's decorators and modifiers |
| LP8q | an overload signature beside its implementation — function parse(input: string): Config; before function parse(input: any): any { … } at module level, or find(id: string): User; before find(id: any) { … } in an ordinary class body | one Symbol, led by the implementation (LP8f: it carries the body and the parameter types the function is called with) even though the overloads come first, with each overload folded in as a declaration with no body (bodyNode: null, fullNode the signature) and declaration-merged in derivedBy, once. Every scalar is the lead's, the range included, so the overload lines sit outside the Symbol's span. normalizeAst appends each overload's full node, so adding, removing or retyping an overload moves the Symbol's syntax axis. Dropped outright, the overload reached no fingerprint of the Symbol it belongs to: an edit to a method's overload moved only its class's syntax, whose body serializes every member, and one to a module-level overload moved nothing at all. The api axis still reads the implementation's one signature, since Signature holds one parameter list. An overload never leads, and that is decided ahead of LP8b's getter rule: a bodyless get x(): number; beside set x(v) { … } leaves the member to the setter, body and all, and beside get x() { … } to that getter. Overloads with nothing beside them that can lead (TS2391) produce no Symbol, as before; one written beside another declaration of its name — a namespace, say — folds into that declaration's Symbol as any merge does (§4.3.1). Under a declare the signatures are the declarations and the first leads (LP36). In a class, the class's walk still reads an overload whole, as it did when overloads were dropped: the member's walk starts from bodies and an overload has none. So a parameter decorator's arguments written on an overload are the class's, where an implementation's are too (LP20d), and so is a default written there, which tsc rejects (TS2371) and which never runs. One divergence is recorded rather than closed: tree-sitter does not parse a module-level generator overload, export function* g(a: string): Iterable<string>;, as a function_signature — it reads an expression statement beside an ERROR — so that overload set does not fold and an edit to it moves nothing, where a class body's *m(a: string): Iterable<string>; folds. The same overloads answer differently depending on where they are written, which LP36a exists to rule out; closing it needs the grammar to parse the form |
| LP35 | a member declared abstract — abstract class A { abstract doIt(): void } | a member SymbolCandidate, kind = "method", bodyNode null, derivedBy carrying abstract-declaration. The language forbids an implementation beside it, so nothing else in the class declares the member, and skipping it left an abstract class reporting only the methods it happened to implement — where the declared one is the API the class promises and what a subclass is checked against. An abstract accessor pair is LP8a's fold. Abstract overloads fold too, but LP8f's rule cannot apply as written — it takes the signature from the implementation, and an abstract pair has none — so the Symbol keeps the leading declaration's signature. An abstract field is a field, on LP20f's terms: it holds no function |
| LP36 | a declaration written under declare — declare function f(): void, export declare class C { m(): void }, declare namespace N { … }, declare const / enum / interface / type | the SymbolCandidate the same declaration gets written without the keyword, plus ambient-declaration on derivedBy, and the members and nested declarations under it. declare is a modifier the grammar spells as a wrapper node, so it is read through rather than matched on — including between export and the declaration, where a reader taking the immediate parent finds the wrapper rather than the export, and above it, where the JSDoc is written. One divergence is recorded rather than closed: an ambient namespace exports its members whether or not they carry the keyword — declare namespace N { function h(): void } makes N.h resolvable, and only an export {} or export = in the body switches that off — where computeTopLevelVisibility looks for an export_statement parent and so answers internal for h. Closing it needs visibility to be a question about the enclosing scope rather than about the statement, which nothing else in this table asks for. .d.ts files are dropped before extraction (drop-list.md Category A); these forms are written in ordinary .ts files and are not |
| LP36a | a signature with no body — function f(): void, class C { m(): void } | a SymbolCandidate that leads only under a declare (LP36). Written outside one it is an overload declaration, and the implementation beside it carries the body and the parameter types the entity is actually called with, so the implementation is the Symbol and the signature is not — it folds into the implementation's Symbol as a declaration with no body and never leads it (LP8q). That is the answer a top-level overload and a class member have to give alike, or the same source answers differently depending on where it is written. An ambient context has no implementations at all, so there is nothing beside the signature to defer to, and reading its members as overloads left export declare class with no methods |
| LP36b | a declare that augments a scope other than this module — declare global { … }, declare module "express" { … } | no SymbolCandidate, for the augmentation or for anything inside it, and no diagnostic. What either declares is a member of the global scope or of another module, and the only qualified name available is a top-level one — which would claim that name for this file and fold with the file's own declaration of it (§4.3.1). The specifier is not a qualified-name segment either, so building an id from it throws and costs the file every Symbol it had (§4.3). A known limit: covering these needs a qname convention for a scope that is not the file's, which ir-schema.md §3.2 does not have |
9.2 Signature extraction
| ID | Input | Expected |
|---|---|---|
| LP9 | async function f() | signature.async = true |
| LP10 | function* g() | signature.generator = true |
| LP11 | f(a: number, b: string): boolean | inputs = [{name:"a",type:"number"},{name:"b",type:"string"}], outputs = ["boolean"] |
| LP11a | a function that states a parameter without a parameter list — TypeScript's parenthesis-free arrow, x => x + 1 | inputs = [{name:"x",type:""}], the same the parenthesised spelling (x) => x + 1 reports |
| LP11b | f(a?: string, limit = 10, ...ids: string[]) | inputs = [{name:"a",type:"string",optional:true},{name:"limit",type:"",optional:true},{name:"ids",type:"string[]",rest:true}], and a required parameter carries neither key. What a caller sees of a parameter's form has fields of its own because the api fingerprint reads them and not name (fingerprint.md §3.1, §3.4): a ... spelled into the name would reach no axis. optional marks an optional parameter and a defaulted one alike, since a caller may omit either; the default's value is not recorded. name is the bare binding and type the annotation alone. Renderers print the markers in the parameter's spelling (a?: string, ...ids: string[], and limit? for a default) |
| LP11c | a parameter whose binding the parser repaired — function f(...: string[]), function f(...,), class C { m(...: T) {} }, function f(?: string) | inputs = [{name:"...",type:"string[]",rest:true}], [{name:"...",type:"",rest:true}], [{name:"...: T",type:"",rest:true}] and [{name:"?: string",type:"string",optional:true}]. The parser inserts a zero-width MISSING identifier for the binding, or, in the method, wraps the : in an ERROR node. fingerprint.md §5.1(6) treats a MISSING node as not written and an ERROR node is no binding, so the name is the text of the nearest node the source did write: the pattern, else the whole parameter. Neither rule gives way — nothing the parser invented becomes a name, and no name is the empty string the schema's minLength: 1 refuses |
| LP11d | a destructuring parameter — f({ save }: D), f([a, b = c]), f({ p: { q } }), f(...[x]) | name = the pattern text, without a rest parameter's ... ([x], beside rest: true); bindings = the names it binds in source order (["save"], ["a","b"], ["q"], ["x"]). A single-name parameter omits bindings, a rest one included: f(...ids) is {name:"ids",type:"",rest:true}. So does a pattern that binds no name: f({}: P) is {name:"{}",type:"P"}. name is always the written text, and bindings lists the names the parser placed in binding position. Anything else in the pattern binds nothing and is passed over, and the file is still scanned. A MISSING identifier binds nothing (f({ a: }) has no bindings), and neither does the text of an ERROR node: f({ a, ? }), f({ a = }) and f({ a b }) bind ["a"], f({ a, ?, b }) binds ["a","b"], and f([...]) and f({ ... }) have no bindings. Nor does an expression the grammar places where a binding belongs, which no compiler accepts in a parameter, so such a pattern drops only that binding: f({ a: b!, c }) binds ["c"], and f({ a: obj.b }), f([obj.a]), f([a[0]]) and f({ a: undefined }) have no bindings. A malformed array pattern the parser could keep only as an expression, by inserting a ! after it (non_null_expression > array, the ! MISSING), is read as the pattern it spells: f([a, ?, b]) and f([a, b c]) bind ["a","b"], and f({ q, k: [a, ?] }), which the same repair turns into an object expression, binds ["q","a"]. A parameter the parser read as some other expression is no pattern and has no bindings: f([a, b c], [d, ?]) is one subscript expression. A destructuring declaration refuses the ERROR node, the placed expression and the repaired pattern alike, since each name it lists becomes a Symbol; a parameter reads around them |
| LP11e | a type broken over lines — provider:\n | ClassProvider\n | FactoryProvider, parts: Array<\n | A\n | B\n>, handler: (\n req: Request,\n) => void, x: A &\n B, o: {\n a: A\n b: B\n} — and the same punctuation or a comment written on one line, Map<| A | B, | C>, (): & Base & Extra, <T extends | A = | B>, o: { a: A, b: B, }, x: /* c */ A | the type as it reads on one line: ClassProvider | FactoryProvider, Array<A | B>, (req: Request) => void, A & B, { a: A; b: B }, Map<A | B, C>, Base & Extra, T extends A = B, { a: A; b: B }, A, in a parameter type, a return type and a type parameter alike. A formatter that breaks a type over lines adds line breaks, a trailing comma before a closing bracket and a union's leading | (an intersection it breaks after each &), drops the ; between an object type's members, and undoes each of these when it joins the type, so keeping any of them would move api (fingerprint.md §3.4) and put a row whose two sides read alike in ⚠ API changes. The text is rebuilt from the syntax tree's tokens: each run of whitespace becomes one space, none is kept just inside < ( [ or before > ) ], a comment and a , before a closing bracket are left out, an object type's members are separated by ; whatever separated them, with none after the last, and the operator of a union_type or intersection_type whose first child is that operator is left out. A string literal type and a template literal type are kept as written, so a | or , inside one ("a, | b") stays, and so does an operator the parser gave no operand (x: | records |) |
| LP12 | function f<T>() | typeParameters = ["T"] |
| LP13 | function f() { throw new MyError() } | throws = ["MyError"] |
| LP13a | a JSDoc @throws above the function. With braces: @throws {ValidationError} if malformed, @throws {@link NotFoundError} if missing, @throws {@linkcode errors.Gone}, @throws {@linkplain Conflict the conflict}, @throws {@link}. Without: @throws PaymentDeclined, @throws If the id is unknown., @throws NotFoundError when …, @throws errors.Gone, @throws PaymentDeclined.. Two on one line: @throws {A} first @throws {B} second | with braces, the text they hold, verbatim and unchecked: ValidationError; for a link, its target: NotFoundError, errors.Gone and Conflict; and nothing for a link that names no declaration, as {@link} and a URL do not. Without braces, the tag's whole text when that reads as a type name, and nothing otherwise: PaymentDeclined; nothing for the description If the id is unknown., nor for NotFoundError when …, which only begins with one; nothing for errors.Gone, whose first segment is lower case, nor for PaymentDeclined., whose full stop leaves no segment after it. Two on one line: A and B. A type name is an ASCII identifier or dotted path whose first segment starts upper-case — the later ones are not held to it, so Errors.notFound is one — and a type that does not read as one is written in braces, as {errors.Gone} is. The braces must open and close on the tag's own line, and the tag's text runs to the next tag — on a later line, or on the same one after a blank — or to the end of its comment, so neither reads into another tag's line or into the next block of a joined run. throws is an api fingerprint input (fingerprint.md §3.1), so a word of a description read as a type would turn a reworded comment into an api change; where a tag's text is not plainly a type, the rule records nothing |
LP11a is where the two spellings of one parameter have to agree. inputs is compared positionally by the api fingerprint (fingerprint.md §3.1), so a reader that knows only the parameter list reports the wrong arity in both directions: dropping the parameter (x => … → () => …) reads as no change at all, and adding the parentheses (x => … → (x) => …) reads as an api change.
9.3 Decorator extraction (languages with decorators)
| ID | Input | Expected |
|---|---|---|
| LP14 | @Post('/x') method() | decorators[0] = { name: "Post", raw: "Post('/x')", arguments: ["'/x'"], boundary: <determined by the framework plugin>, line: ... } |
| LP14a | @nest.Post('/x') method() | name = "Post", qualifier = "nest", raw = "nest.Post('/x')". The leaf and the receiver are reported apart so a consumer can tell a namespace import from a bare name (§5.2.2); raw still quotes the whole written form |
| LP14b | a decorator written as a bare name (@Post(), @Post) | no qualifier key at all — Class B per ir-schema.md §1.1, never null and never "" |
| LP14c | a nested receiver (@a.b.C()) | qualifier = "a.b", carried whole. Which segment names a binding is the consumer's rule, not the extractor's |
| LP14d | a receiver that is not a plain path — @arr[0].C(), @(a).C(), @pick().C(), @ns["C"]() | decorators = [], so there is nothing to qualify. Not because the grammar refuses them: each parses as a decorator of the fragment the grammar could take, inside an ERROR node that leaves it no longer a preceding sibling of the declaration, which is what puts it out of the run. A plugin must not read this as a grammar guarantee — it is where error recovery happens to put the node |
| LP14e | a receiver the grammar reaches but that binds nothing — @this.C() (parses cleanly), @a?.C() (recovered, the ? an ERROR child of the member expression) | the object verbatim: this, and a. The extractor quotes what was written; a consumer matching it against an import edge finds nothing and falls in the unbound row of §5.2.2 |
| LP14f | a path written in parentheses — @(a.b) | name = "b", qualifier = "a", as for @a.b. The rule is the extractor's own and not the grammar's: a qualifier is reported when what the parentheses enclose is a member expression with an object, and in no other case |
| LP14g | a name, a path or a call in parentheses, which the grammar parses cleanly — @(Controller), @(nest\n .Controller), @(Controller('/x')) — or with a repair only inside the argument list, @(Controller(a b)) | read through the parentheses: Controller, Controller with qualifier nest, and Controller with arguments ["'/x'"], so each matches the vocabulary its unparenthesized form does. A comment inside is skipped. raw quotes the parentheses, and a line break inside them stays in raw and out of name |
| LP14h | a parenthesized expression the grammar had to repair — @(x as any), @(x!), @(a[b]), @(C<T>), @(new C()), @(a, b), @(pick().C), @(a?.C), @(nest.) | one decorator, name: "<expression>" (UNNAMED_DECORATOR in @aburi/types), no qualifier, no arguments, the text in raw. TypeScript accepts any expression there and the grammar's decorator rule does not, so the parse holds an ERROR node beside a fragment (x, a, a call of new) that is not the decorator. The repair that counts is one in the head, an ERROR or MISSING token among the children of the parentheses or of what they enclose; a broken argument list nests deeper, so @(Controller(a b)) is Controller, as @Controller(a b) is (LP14g). @(a?.C) is the one form whose unparenthesized spelling reads differently: LP14e names @a?.C() C with qualifier a, from the same repaired member expression. The difference is this row's choice, since a repair inside parentheses is refused wherever it sits. Decorator.name is never a node's text: it is an identifier or this marker, which begins with < and so matches no vocabulary |
| LP15 | two decorators | 2 entries in decorators[], ascending by source position — not by line, which two on one line share, and never by name, which would make a consumer that reads the first one depend on the alphabet. On a Symbol several declarations wrote (§4.3.1) the order is still source position, across all of them: the lists join in declaration order, which is why the fold visits declarations in source order rather than leading declaration first |
| LP15a | a decorated member followed by an undecorated one | the second member's decorators = [] — the run belongs to the member it sits above, and does not leak down |
| LP15b | a comment between two decorators, or between the decorators and the declaration | all of the decorators, in source order — a comment is written wherever the author put it and does not end the run |
| LP15c | a decorator the grammar parents inside the declaration rather than beside it (@A() class C {}, export @A() class C {}, export default @A() class C {}, @A() abstract class C {}) | read the same as a preceding one — where a decorator is written must not change what the Symbol reports |
| LP15d | a parameter decorator (m(@P() x)) | not among the method's decorators, nor the owning class's — it decorates the parameter |
| LP15e | a JSDoc block above a decorator (/** @throws E */ @A() m() {}) | read as the member's; the decorator does not end the comment run |
| LP15f | a decorator on both sides of export (@A() export @B() class C {}) | both. TypeScript rejects the source as TS8038, but a grammar that accepts it hands the extractor a half-edited file, and reading one side would drop a decorator from it silently |
9.4 Body walk
| ID | Input | Expected |
|---|---|---|
| LP16 | if (x) throw new E() | guard + throw in rules |
| LP17 | return 1 | no return in rules (trivial) |
| LP18 | return foo() | no return in rules, foo in calls |
| LP19 | return a + b | return in rules (expr: "a + b") |
| LP19a | an arrow with an expression body — (u) => u.role === "admin", wherever the arrow is a walk root (a variable, a class field per LP20f, a property of a binding's object literal per LP7d, a registered handler per LP20g, a function a const or a class field hands its call per LP7c and LP20f1, a default export) | the rules its block twin function f(u) { return u.role === "admin" } gets: the body is the arrow's return value, so it goes through the triviality and call-only tests a return does (drop-list.md §5.3–§5.5). Parentheses around the value are taken off before the tests, every pair and past a comment inside one, and the block return reads its value the same way, so () => (g()), return (g()) and return g() are all call-only, and () => (a ? b : c) and return (a ? b : c) both give expr: a ? b : c (drop-list.md §5.3). The two record the same calls: the body is walked whole, and a block return is walked unless it is trivial, which an expression holding a call never is, so (a) => a[g()] and return a[g()] both take the rule and record g (drop-list.md §5.5). Read as a bare expression the body earned no rule, and an edit to it moved no logic fingerprint where the block twin's does. The rule is the only addition: the body's own walk is unchanged, so it records the same calls whether or not the rule is added |
| LP19b | rule strings differing only in a comment with whitespace, or the start or end of the string, on at least one side of it — if (a /* why */ || b) against if (a || b), a line comment ending one line of a wrapped guard, a comment in a throw value, in a return expression or in a switch value | identical strings, holding no comment: a || b. A comment that is the only thing between two tokens reads as one space (§4.4, rule-string contract): a/**/||b gives a ||b, and a-/**/-b gives a- -b, never a--b. A /* … */ inside a string literal is not a comment and stays |
| LP19c | rule strings differing only in whitespace that is already there — a guard re-wrapped over several lines, re-indented, or with a run of spaces made longer or shorter | identical strings: a guard wrapped as a < 18 || / b || / c === 1 over three lines gives a < 18 || b || c === 1, as its one-line spelling does. Whitespace appearing between two tokens that had none, or vanishing from between them, is not covered: a||b and a || b stay two strings (fingerprint.md §4.3) |
| LP20 | for (let i...) ... | loop in rules (loopKind: "for") |
| LP20a | a type whose members are Symbols of their own — a class and its methods, and a binding's object literal and its members (LP7d) | the owner's walk reports its own body only: field initialisers, static blocks, and whatever the language runs on construction — for an object literal, the values defining it evaluates, at every depth LP7e reads. A member body reported twice is reported on two Symbols, and any resolution that reaches the owner (call-resolution.md CR15 resolves new C() to the class) carries the duplicate up into callers that touch nothing |
| LP20b | the construction path — a constructor body | reported on the owner, because that is the Symbol an instantiation resolves to, and on the member's own Symbol. Reporting it twice costs nothing only while no call resolves to a constructor; a resolver that grew super() resolution (call-resolution.md CR18 is adjacent) would make the second copy propagate, so the plugin owes this row a check against its core. Whether a static member named constructor is on the construction path is the language's answer, not the name's: in ECMAScript it is not |
| LP20c | a member with no Symbol of its own — a computed name, a name the qualified-name grammar has no segment for ("a-b"() {}, 1() {}), a quoted "#v" (LP8m), a member of an anonymous default export, an object literal's entry LP7f does not admit | its body stays on the owner. Skipping it would lose the calls in it with no Symbol, no diagnostic and nothing to say so. The plugin needs one predicate for "is this member a Symbol?" that both extraction and the walk read — one for a class body and one for an object literal's entries — and both must ask it about the same owner node. The walk reads the owner off the body it is walking, not off the Symbol: a folded Symbol's fullNode is its leading declaration (§4.3.1) and need not be the owner at all |
| LP20d | a function's parameter defaults — function f(x = g()), (y = k()) => l(), m(x = f()) {}, an inline handler's | on the function's own Symbol, walked with its body and ahead of it. A default runs on every call that omits its argument, so it is what calling the function runs; outside a class there is no other Symbol to carry it, and a default not walked here is in the IR nowhere. For a member the owner then skips the parameter list as it skips the body (LP20a), so the default is not reported twice — except the constructor's, which the owner keeps whole under LP20b, so it is on both. A decorator is not a default and stays on the owner, whether it sits beside the member (a method's, a sibling in tree-sitter-typescript), inside the field, or on a parameter (m(@Body(pipe()) x)): a decorator's arguments run where the decorator is applied, when the class is defined |
| LP20f | a member written as a field holding a function — create = (d) => { … } | a member. Constructing the owner creates the closure and does not enter it, so the body is what calling the member, or iterating what it returns, runs, and LP20a applies unchanged: the body is the member's Symbol's and the owner stops carrying it. What separates it from seed = makeSeed(), which stays on the owner, is when the value runs — not what the member is called or how it is spelled. The function set is the one the language's module level already uses for the same decision, so const f = … and class C { f = … } are not two answers. The member's body is one level further down than a method's, so the skip follows the path to it rather than filtering the member's own children |
| LP20f1 | a field holding a call handed a function — handle = withAuth(async (d) => { … }), debounced = debounce(() => { … }, 300), q = t.procedure.query(() => { … }) | a member, as LP20f's. Constructing the owner, or defining it for a static field, calls withAuth and stores what it returns, and a wrapper's function runs when the member is called, so the function is read as the member's body and the owner stops carrying it. The functions are LP7c's: the direct arguments of a call on the value's spine, read through LP7a's wrappers, the first as bodyNode and the rest on mergedDeclarations (LP20h), each with its own parameter defaults (LP20d). kind = "method", with a null signature and derivedBy carrying call-argument-function where LP20f's carries field-assigned-function: LP7b's line holds, and the call, not the function, decides what the member is called with. The calls the functions sit under run on construction or definition and stay on the owner's walk, with anything else the field's value evaluates outside those functions: debounce(() => { … }, delay()) puts debounce and delay on the owner. The normalized string is the whole field, for LP7c's reason, so withAuth becoming withRole, or a type annotation or modifier written on the field, moves the member's syntax: adding private moves its api and its syntax, where a field holding the function itself moves only api. The drop list reads the same predicate (drop-list.md §4.2), so a class of such fields is not a data model. The member takes the empty body hint only when every body is an empty block, so ready = p.then(() => {}).catch((e) => report(e)) is kept with report on it. What LP7c does not reach stays on the owner here too: a function inside an argument (withAuth(withLogging(() => …))) and one handed to new. A known cost, shared with LP7c's const. The reading asks nothing about the call, and nothing in the tree tells a wrapper from another call handed a function, so two kinds of call that are not wrappers read as one. One runs its argument at once: doubled = xs.map((x) => …), migrate = this.prisma.$transaction(async () => { … }). The other registers it to run later: timer = setInterval(() => { … }, 1000), sub = store.subscribe(() => { … }), ready = this.prisma.$connect().then(() => { … }), off = emitter.on("x", () => { … }), Angular's effect(…), MobX's reaction(…). Construction is what runs or schedules either kind of callback, but the callback is reported on the member, so its effects no longer reach the callers of new C(); and where the call returns a disposer the class calls later (close() { this.off() }), a this.off() that LSP enrichment resolves reaches the member and takes the callback's effects. Telling these apart from a wrapper would take a list of callee names, which would have to be one list for the const and the field, so the field reads as the const does. An object literal's entry stops short of this reading (LP7f) |
| LP20g | a Symbol whose declaration is a call that registers a function — app.post('/users', async (req, res) => { … }) | the registered function is the Symbol's body. The registration is the only Symbol the statement produces, so a handler written inline is otherwise in no Symbol at all; and it is what the registration runs, so it is the body by the same reading as LP20a. Every function written as a direct argument of a call on the statement's spine counts, in source order — a chained registration (app.route(p).get(h1).post(h2)) is one statement and one Symbol, and so is app.use(h0).router.get(h1), where a property access stands between the two calls. "Function" is the plugin's own predicate (LP7, read through LP7a's wrappers) and no wider; a generator argument (Koa's app.use(function* (ctx, next) {…})) is in it and registers its body as an arrow does. A body of no width is refused, so a half-written handler the parser recovered does not claim one. The Symbol's signature stays null: it is the registration, and reading the handler's would publish the framework's callback shape as the route's API |
| LP20g1 | a registration handed no function — app.use(cors()), app.get("/x", handler), app.listen(3000), await prisma.user.delete({ … }) | the call itself is the Symbol's body. Handed no function, the registration defers nothing, so what it runs is the call, when the module is imported: the walk records the callee and the calls in its arguments, app.use and cors, and a function written deeper than an argument (app.use(withAuth(() => { … }))) is absorbed as into any parent. Without it those calls were in no Symbol, since <module> (LP20o) leaves out a statement that has a Symbol of its own: a top-level write whose method a router also has, prisma.user.delete, is named as a registration (LP20i1), and its db.write was reported nowhere. A registration handed a function still walks only the function (LP20g), so its own call and the calls in its other arguments (app.get(p, rateLimit(), (req, res) => { … })) stay on no Symbol: reading them beside the handler would mix what runs on import with what runs per request in one walk. derivedBy carries no inline-handler, which is how a reader tells the two apart. The normalized string is the whole call either way (LP20i), and mergedDeclarations stays absent (LP8i) |
| LP20h | LP20g with more than one handler | the first in source order is bodyNode and the rest ride on mergedDeclarations, which is a stretch of that field: they are further bodies of one declaration, not further declarations of one entity (§4.3.1), so each entry's fullNode is that declaration, and they carry no declaration-merged. The field is reused because every reader of it (bodyNodesOf, the empty-body hint) wants exactly "every body this Symbol has". A single-body reader gets the source-order-first function, which need not be the handler: makeRouter(() => setup()).get(p, h) leads with the factory's callback |
| LP20i | LP20g's normalized string | the whole call, not the body. What the registration runs is the walk's question; what it is — its path, its method, the middleware between them and the handler — is the fingerprint's, and narrowing to the body makes app.get(p, authenticate, h) and app.get(p, h) serialize identically. This is LP8j's rule read from the other side: a describing node dropped from the string is a change the axis stops seeing. The syntax axis is not where a reviewer looks for a removed gate, so a framework plugin also names the middleware (§5.2.5), and the logic axis sees it too |
| LP20i1 | LP20g's name, the one qname segment <receiver>__<method>__<discriminator>__d<N> | the discriminator is the path when a method call on the statement's chain is handed a literal string as its first argument — quoted, or a backtick with no substitution, which is the same value (app.get(`/users`, h) names the route app.get("/users", h) does, as LP26j reads a specifier), read past a comment and through LP7a's wrappers (LP26i's hazard: a comment written in front of the path must not rename the route). The chain is one Symbol (LP20g), so the path may be written up it — app.route('/a').get(h) is named by /a — and the earliest written wins when it carries several. The call that starts the chain is not read (require("express")().get(h)): its argument makes the receiver rather than mounting it. The path is slugged (/ → $, : → Z, anything else outside the segment grammar → _), and an empty literal is no path. With no path, it is the names the leaf call's arguments carry, joined by $: an identifier (authMw), a dotted reference (express.json → express_json), the callee of a call (cors() → cors, express.static("public") → express_static), a constructor (new Logger() → Logger), what a spread spreads (...mws → mws). Absent when neither says anything (an inline function, a number). The characters kept are the qualified-name grammar's (ir-schema.md §3.1), so app.use(認証) is app__use__認証__d0 rather than a fold to _, and the segment is in NFC (§1.2 there). derivedBy carries call-statement:<receiver>.<method>, the receiver being the name the call's receiver chain starts from, unslugged (call-statement:app.get for app.route('/a').get(h)); chained-call when that chain passes through a call; inline-handler when the registration has a body (LP20g); and path-literal:<path> or argument-names:<slug>, whichever named it and never both: $ is both a path's / and the joiner, so app.use($api) and app.use("/api", x) share a stem and only the tag says which reading it was. N counts earlier registrations with the same stem — the uniqueness tiebreaker ir-schema.md §3.3 admits, never the name. With only the bare app__use stem, inserting app.use(compression()) above app.use(cors()) renamed every later middleware, and the diff paired each with the body its id used to hold. Three trades are deliberate. The discriminators are exclusive: a registration with a path is named by the path alone, so app.use('/api', authenticate) and app.use('/api', apiRouter) share app__use__$api and stay separated by order — inserting a third app.use('/api', …) above them renumbers both — because naming them by their arguments as well would rename every route that gains a middleware, where app.get(p, h) → app.get(p, auth, h) is one changed (LP20i). The reverse follows for a registration with no path: its arguments are its name, so app.use(a) → app.use(a, b) moves the stem from a to a$b and reports as removed and added, and renaming the binding it passes renames it (ir-schema.md §3.4). And what a call is handed is not read: express.static("public") and express.static("uploads") share express_static, so renaming a directory does not rename the registration serving it. A backtick with a substitution is not a path, its value being decided at run time |
| LP20j | prisma["user"].create(d), prisma.user["create"](d) | one call each, target prisma.user.create, no dynamicReceiver — a string-literal index is the segment it spells, in the receiver slot and in the terminal one (§4.4), unless that segment is a private name (LP20k) |
| LP20j1 | prisma["user" "audit"].create(d), obj["a\u12b"].m() | prisma.<computed>.create / obj.<computed>.m — an index the parser recovered rather than read names no segment, whether the ERROR stands beside the literal or inside it |
| LP20k | prisma[model].create(d), items[0].save(), obj["a-b"].m(), obj["#v"].m() | one call each, targets prisma.<computed>.create, items.<computed>.save, obj.<computed>.m, all dynamicReceiver — an index that names no segment is reported as one that names none, where dropping it would report a call the program does not contain. "#v" spells the private segment and still names none: obj.#v is another member (§4.4) |
| LP20k1 | handlers[name](), prisma.user[verb](d) | handlers.<computed> / prisma.user.<computed>, both dynamicReceiver — the terminal slot answers the same way, so a call whose name is computed is reported as a call rather than as a call to its receiver |
| LP20l | [...names].sort(), 'a...'.trim(), (.5).toFixed(2), new Date().getTime(), (async () => { … })(), ([...a] as T).m() | <computed>.sort, <computed>.trim, <computed>.toFixed, <computed>.getTime, <computed>, <computed>.m, all dynamicReceiver — an unmodelled receiver contributes the reserved segment, never its source text (§4.4). svc!.save() stays svc!.save, not dynamic, and import("./m") stays import. A type assertion around a name contributes the name, whatever its type spells: (x as { … }).m() is x.m |
| LP20e | an owner-shaped node the walk meets rather than owns — function f() { class Inner { m() { x() } } } | walked whole. Inner is not extracted, so every call in it belongs to f; LP20a applies to the Symbol's own body nodes and to nothing else |
| LP20m | try { a() } catch (e) { if (!e) return; b() } finally { if (x) return; c() } | rules try and the finally block's guard; calls a, b, c. The try block and the finally block are walked like any block, the finally block because it runs on every path. The catch clause is walked as a try block is, and every rule that walk produces is discarded (ir-schema.md §8.2), so it records exactly the calls the same statements would record in the try block: try { return a[g()] } catch (e) { return a[h()] } records g and h and keeps one return rule, the try block's, and a finally nested inside a catch gives no rule, whatever it holds. Collecting every call under the clause instead, as a throw's argument is collected, would record the same calls today, but only because a trivial return holds no call (drop-list.md §5.5); walking the clause as a block does not depend on that. A try statement at module top level is walked the same way, as <module>'s (LP20o) |
| LP20n | a call through this.<field> — this.eventEmitter.emit(…) beside constructor(private readonly eventEmitter: EventEmitter2), a typed field (private events: EventEmitter2, #events: EventEmitter2), a namespace-qualified or generic type (ee.EventEmitter2, Emitter<Payload>) | receiverType is the type's name (EventEmitter2, ee.EventEmitter2, Emitter), read off the class this is bound to: the nearest method, accessor, field initializer or static block walking up from the call, through arrows and past a member's name, its decorators and its parameters' decorators, which are evaluated outside it, and not through a function, which binds its own this. A static member reads the static fields and an instance member the instance fields and the constructor's parameter properties (a parameter with an accessibility modifier, readonly or override). Absent for a field the class does not declare with a named type — no annotation, a union, an inherited field — for a member of a field (this.events.bus.emit()), for a non-null assertion (this.events!.emit(), whose target keeps the !), for an object literal's method, and for a plain name (events.emit() beside events: EventEmitter2) |
| LP20n1 | a call through this or super — static { this.make() }, static first = this.make(), static m() { return () => super.make() }, second = this.make(), m() { this.repo.save() } | thisBinding is class for the first three and instance for the others, read off the class this is bound to as LP20n reads it: the nearest method, accessor, field initializer or static block walking up from the call, through arrows and past a member's name, its decorators and its parameters' decorators. Absent inside a function, which binds its own this, for a computed member name ([this.key()]() {}) or a decorator's argument (@Use(this.guard()), m(@Inject(this.token()) a)), whose this is the one around the class, for an object literal's method, and for a call through anything but this or super, this!.m() included, whose target keeps the ! |
| LP20o | a file's top-level statements that are not declarations — await prisma.user.deleteMany({}), doThing(), process.on("SIGTERM", () => shutdown()); an if, for, while, do, try, switch, with, block, labelled statement or throw at the top level; and the statements of a namespace body, registrations included, which run when the module does | one SymbolCandidate for the file, <module> (ir-schema.md §3.3): kind = "module", visibility = "internal", a null signature, derivedBy ["module-scope"], and a source from the first such statement to the last. Each statement is a body, in source order — the first as bodyNode, the rest on mergedDeclarations — and each is its own fullNode, so the walk reads them as it reads any body (a callback written in one is absorbed, an immediately invoked function's body with it) and normalizeAst describes the module scope by their text alone: an edit to a declaration written between two of them is that declaration's change and not <module>'s. Left out, because they are another construct's or run nothing: a declaration; an import or export, a default export written as a call included, which is LP7c1's question; a registration LP20i1 names, which is its own Symbol, walking its handler (LP20g) or, handed none, its own call (LP20g1); a directive, an expression statement holding one string, which a throw of a string is not; and a statement the parser recovered, whose ERROR is what is left of something else (export function* g(a: string): T;, a signature the grammar cannot parse). A file with no such statement has no <module>. LP20i1 names only a file's own registrations, so one in a namespace body is <module>'s whole. Two gaps are recorded rather than closed. A const whose initializer is a call handed no function, const n = await prisma.user.deleteMany({}) or export const app = express(), and a default export written as one, export default defineConfig({ … }) (LP7c1), make calls on import that no Symbol carries: each statement is a declaration, so it is not <module>'s, and the const and <default> walk only the functions a call is handed or invokes (LP7c). Closing them needs either the const to walk its whole initializer, which moves the logic of every const computed by a call, or <module> to take the initializer, which splits one declaration across two Symbols |
9.5 normalizeAst
| ID | Input | Expected |
|---|---|---|
| LP21 | code differing only in comments | normalizeAst yields identical strings |
| LP22 | code differing only in whitespace | normalizeAst yields identical strings |
| LP23 | code with different identifiers | normalizeAst yields different strings |
| LP23a | code differing only in an operator, a declaration keyword, a modifier or a primitive type — a + b / a - b, let / const, private / public, x as string / x as number | normalizeAst yields different strings. These are unnamed tokens in most grammars, and a walk over named nodes alone drops them (fingerprint.md §5.1) |
| LP23b | code differing only in punctuation fingerprint.md §5.1 item 4 leaves out — for example the quotes around a string that needs no escape either way, or ; against , between interface members | normalizeAst yields identical strings |
| LP23c | code differing only in a hole in an array or an array pattern — [, token] / [token], [1, , 3] / [1, 3], [x, ,] / [x,] | normalizeAst yields different strings. The grammar has no node for a hole, so the commas around it are all that record it: a comma right after [ or after another comma is kept, and every other comma, a trailing one included, is dropped. A destructuring parameter is outside the body this string describes, so a hole in one is not covered here |
9.6 Import extraction
| ID | Input | Expected |
|---|---|---|
| LP24 | import { X } from './y' | imports = [{source: "./y", symbols: ["X"], line: 1, dynamic: false}] |
| LP24a | import X from './y' | imports = [{source: "./y", symbols: ["default as X"], line: 1, dynamic: false}]: the binding is the module's default export, written as { default as X } is, so call resolution looks for the default export and not for a named X (call-resolution.md §4.4, CR5c) |
| LP25 | import * as Y from 'z' | imports = [{source: "z", symbols: "*", line: 1, dynamic: false}] |
| LP26 | await import('./x') | imports = [{source: "./x", symbols: "*", dynamic: true}] |
| LP26a | an empty specifier on a form the reader already produces an edge for — import a from "", import "", export * from "", export { X } from "", import type { B } from '', import(""), import x = require(""), import()`` | no edge, and one recoverable ParseError at the literal's line and column, naming which construct it belongs to. The specifier names no module, so no edge can carry it (§4.4), and a silent drop would leave the file looking as though the import were never written |
| LP26b | an empty specifier beside a valid one | only the broken edge is withdrawn |
| LP26c | two empty specifiers, on one line or on two | two errors. Edges are deduplicated on (line, source, dynamic, symbols), so the only pair that could ever have merged is two writings on one line; diagnostics are per occurrence either way |
| LP26d | a blank specifier (import a from " ") | an ordinary edge. §4.4 rejects empty, not blank |
| LP26e | a computed specifier — import(p), import("" + x), import(`./${p}`) | no edge and no diagnostic. The reader does not follow computed specifiers, which is not a fault in the source. Joining a substituting template's fragments would answer "./" here — an edge to a module nobody named, which is worse than none |
| LP26f | import x = require('./m'), written at the top level of a file | one edge, {source: "./m", symbols: "*", line: 1, dynamic: false, namespaceBinding: "x"}. x binds the module object as import * as x does, so the namespace shape is what lets call resolution strip the head off x.foo() and look for foo in the target; a default binding (symbols: ["default as x"]) would send it looking for the default export's member foo there instead. dynamic is false because the field means "written as import()" (§4.2) and this form is not |
| LP26g | import type x = require('./m') | the same edge. Type-only imports produce edges throughout §9.6 |
| LP26g1 | a require-equals whose argument is not a lone string literal — require("a" + b), require('./m', 'y'), require(f('./m')) | no edge. Each is a syntax error the parser already reports, but tree-sitter's recovery leaves an operand it could read as a direct child of the clause with the source field attached, so a reader that took it would answer a, or the second argument. A clause that did not parse is not read |
| LP26g2 | export import x = require('./m'), and a require-equals inside declare module / namespace | no edge, and the reader does not follow either form. Both are valid TypeScript. The export form is a grammar gap: tree-sitter reads it as an import_alias with a MISSING ";" plus a stray parenthesised expression, so the clause never exists to be read. The nested form is the general limit of walking root.namedChildren — a plain import { A } from './m' inside declare module is missed on the same terms — and is softened by .d.ts files being dropped before extraction |
| LP26h | import x = A.B.C | no edge and no diagnostic. The alias renames a local namespace; no module is named |
| LP26i | import(/* webpackChunkName: "x" */ './m') | the ordinary dynamic edge. A comment is a named node standing in front of the specifier, and reading the first argument by position would find the comment |
| LP26j | import(`./m`) | the ordinary dynamic edge. A template with no substitution names a fixed module and is a static specifier written with different quotes |
| LP26k | a specifier carrying an escape sequence — "./a\tb", "\x2E/e", import(`./a\nb`) | the escape is decoded, not skipped: ./a+TAB+b, ./e, ./a+LF+b. Skipping it answers a module that does not exist, and for an escaped leading dot it answers one that is no longer relative — so isRelativeSpecifier refuses it (the predicate is a ./ or ../ prefix, or exactly . or ..) and every call through the binding is bucketed external rather than resolved against the sibling file it names |
| LP26l | an escape the grammar refuses — "./a\uZZZZb", "./a\xZZb" | recoverable syntax errors from the parser, and the fragment that survived. These parse as ERROR nodes rather than escape_sequence, so no decoder is asked to repair source the grammar rejected. The criterion is that the grammar rejected it — see LP26n for the escapes it accepts without a legal value |
| LP26m | a literal that is only a line continuation — "\<newline>" | no edge, and the LP26a diagnostic. A continuation joins two source lines and contributes no character, so the literal names no module. A literal made only of other escapes ("\n\t") is a non-empty name and gets an ordinary edge, on LP26d's terms |
| LP26n | an escape the grammar accepts and ECMAScript has no value for — "./a\u{110000}b", "./a\1b", "./a\8b" | the escape's own text, minus the backslash, with no diagnostic and no throw. The grammar checks a braced escape's shape and not its range, so \u{110000} reaches the reader where \uZZZZ does not, and String.fromCodePoint throws on it — which would cost the whole file. Legacy octal and non-octal decimal escapes are the same case: a SyntaxError in a module, so no correct value exists, and inventing one would put a module name in the IR the source does not contain |
| LP26o | export { A as B } from './m'; export * as ns from './m'; import { A as L } from './m' with export { L as B }; import A from './m' with export default A; export type { T } from './m', export { type T } from './m', export * from './m', and an import the module only uses | reexports = [{imported: "A", exported: "B"}], [{imported: "*", exported: "ns"}], [{imported: "A", exported: "B"}] on the import's edge, [{imported: "default", exported: "default"}], and no entry for the rest (§4.2) |
9.7 Error recovery
| ID | Input | Expected |
|---|---|---|
| LP27 | file containing a syntax error | returns a recoverable error, extracts Symbols where possible |
| LP27a | a bare & in JSX — <p>Subscription & Billing</p>, href="/x?a=1&b=2" | no parse error. The tsx grammar reads & as the opening of an HTML character reference and errors when no ; closes it, which makes prose and a tracking URL indistinguishable from a broken file; the plugin drops that one shape so the recoverable-error count stays worth reading. Narrow on purpose: the run has to open with an ampersand-led token, sit among a JSX element's children or inside a JSX attribute's string, and — among children — hold none of {, }, <, >, which JSX text cannot contain. The last rule is what stops an & swallowing a real break merged into the same ERROR node, as in <div>a & } b</div>; it does not apply inside an attribute's string, where all four are ordinary. A truncation whose ERROR sits outside both positions still reports, including in a file that carries both |
| LP27b | an import("…") type the grammar reads as a call and cannot place — first in a call's type arguments (importActual<typeof import("./m")>(), the vitest mocking idiom) or before [] (import("./m").Rule[]) | no parse error, and the declarations after it survive, including a run of them that recovery reads as the whole file broken. The file is parsed a second time with each such import(…) replaced by an identifier of the same length, and the tree reads the original text, so no Symbol name, call target or node.text shows the replacement. Node kinds are the second parse's: the import(…) is an identifier there, so it adds no import call target (a clean typeof import("./m") in a body adds one), and the masked shape is what normalizeAst serialises. Its import edge is kept, so type-only imports produce edges here as LP26g says. Only an import(…) with a non-empty string specifier, on one line, in the nearest statement, declaration, member definition or signature holding an error, or inside an ERROR node, is replaced, so a type alias that parsed keeps its tree and import("") keeps its empty-specifier error; a replacement the second parse does not read as a type is withdrawn, so a dynamic import("./x") in the same statement stays a dynamic import; and the second tree is used only when it has fewer errors. When the second parse throws, the first tree is kept and the failure is one more recoverable error |
| LP27c | a type parameter's in / out variance modifier — interface A<out T>, class E<in out T = X>, class F<const out T> | no parse error. The typescript grammar has no rule for TypeScript 4.7's variance annotations, and recovery splits the parameter's words three ways: <out T> usually leaves ERROR "T" after a parameter named out; with a constraint or a default the ERROR sits inside that parameter, straight after the name; and in some longer lists each out is the ERROR, before a parameter that parsed clean. The plugin reads the words before the parameter's constraint and default back across those pieces and drops the ERROR when they are in, out or in out and then one name, in the type parameters of a class, an interface or a type alias. A const among them is allowed on a class only, and the name has to be one tsc accepts for a type parameter. So <out out T>, <out in T>, <out T U>, <out in>, interface A<const out T>, a name after a constraint, a stray token and a modifier on a function's or method's own type parameters still report, as tsc's parser rejects them too. The rule does not read a type alias's right-hand side, so type A<out T> = T is silent although tsc's checker refuses it (TS2637). The Symbols are the same with and without the modifiers: the declarations that admit one carry no Signature for the misread name to reach. normalizeAst is the exception for a type alias, which it serialises whole, and for a class, whose type parameters it serialises with the rest of its head (LP8p): the grammar reads the modifier as the parameter's name, so renaming an annotated parameter changes neither string where nothing else in it names the parameter, and both move again if the grammar gains the rule |
| LP27d | an escape that only a tagged template may hold — String.raw`C:\Users\u\Aburi` , tag`\u{zz}` | no parse error. Since ES2018 a tag reads the template's raw text, so \u, \x and \u{…} need not form an escape there, and String.raw over a Windows path is how such text is written; the grammar holds every template to a string's escapes and errors at the backslash. The plugin drops an ERROR that opens with a backslash and sits directly in a template that is a call's arguments, and the tokens recovery placed inside it. So the same escape in an untagged template or a string still reports, as tsc rejects it there, and so does a broken substitution in a tagged template, whose ERROR sits inside the substitution. Recovery can fold a broken substitution written right after such an escape (tag`\xZ${a b}`) into the escape's own ERROR, so an ERROR that also holds a ${ still reports. A tag with type arguments (tag<T>`…` ) is read as two comparisons rather than a call and still reports |
| LP28 | completely broken file | returns a non-recoverable error and a null tree, the core withdraws it |
| LP28a | a file the plugin parsed but refuses — a usable tree paired with a recoverable: false error | the core withdraws it on the same terms as LP28. The tree is never handed to extractSymbols, walkBody or normalizeAst, and the refusal is quoted in ScanResult.skipped |
| LP28b | a plugin emitting two Symbols under one id for one file | that file is withdrawn with reason: "extraction-failed" and code: "duplicate-symbol-id", naming the id and both declarations' lines; every other file still reaches the Document, and the run exits 3 like any other extraction failure. The file keeps its recoverable parse errors, unlike one a plugin threw on (§7.2) |
| LP28c | a plugin emitting a Symbol whose id names a file other than the one being extracted (§4.3) | the file that wrote the id is withdrawn on LP28b's terms, whichever of the two discovery reached first, and the message names the path the id claims against the file it came from. Withdrawing the file the id names would take a healthy file for another's fault |
9.8 Symbol id construction
| ID | Input | Expected |
|---|---|---|
| LP29 | Any extracted Symbol | SymbolCandidate.id came from makeSymbolId; a hand-assembled `${lang}:${file}#${qname}` does not type-check against SymbolId (§4.3) |
| LP30 | A qualified name the §3.2 grammar rejects (empty, anonymous marker, non-identifier segment) | makeSymbolId throws a coded CoreError; the id never reaches the IR |
9.9 Tree lifetime (§8.1)
| ID | Input | Expected |
|---|---|---|
| LP31 | A plugin holding a resource its trees do not release on their own | it implements releaseTree, and a tree passed to it is unusable afterwards |
| LP32 | Many files scanned in one process | the parser's heap does not grow with the file count — the core released every tree the plugin handed over |
| LP33 | A file whose extractSymbols / walkBody / normalizeAst throws, is withdrawn, or overruns parseTimeoutMs | its tree is released all the same; the diagnostic the file was already carrying is what the caller sees |
| LP34 | A releaseTree that throws | the file keeps its Symbols and its exit code; the plugin, the file and the message are on ScanResult.treeReleaseFailures |
9.10 Import resolution and origins (§4.8, §5.2.4)
| ID | Input | Expected |
|---|---|---|
| LP37 | paths: { "@app/common": ["libs/common/src/index.ts"] }, asked for @app/common | ["libs/common/src/index.ts"] |
| LP38 | wildcard keys @app/* and @app/common/*, asked for @app/common/x | the substitutions of @app/common/* alone, with x in place of each * |
| LP39 | an exact key beside a wildcard key that also matches | the exact key's substitutions |
| LP40 | baseUrl: "src" and paths: { "@/*": ["*"] }, asked for @/x | ["src/x", "src/@/x"] |
| LP41 | paths declared by a config that extends reaches, relative or in a package | resolved against the declaring config's directory; a value starting ${configDir} against the extending config's |
| LP42 | the nearest config is not valid JSON, or exists and cannot be read | one warning naming it, with the line and column of a JSON error, and nothing mapped for any file under it, the config above it included |
| LP42a | a config with a byte order mark, and an empty config | read as tsc reads them, with no warning: the first maps its paths, the second maps nothing in place of the config above it |
| LP42b | baseUrl declared by a config that extends reaches (tsconfig.base.json with baseUrl: ".", extended from apps/*) | resolved against the declaring config's directory |
| LP42c | an extends entry that names no config | one warning, and the rest of the chain applies |
| LP42d | a paths or baseUrl value tsc refuses | one warning per value, and the rest of the config applies |
| LP42e | an extends entry that names a config outside the workspace root | that config is read |
| LP43 | a decorator imported through a path alias, or a relative specifier, to a barrel that re-exports it from @nestjs/common, directly or through another barrel | origins maps the imported name to @nestjs/common, and the NestJS plugin grades the decorator high, renamed on import or read through a namespace import alike |
| LP43a | the barrel republishes an import of @nestjs/common in an export clause or as its default export, re-exports @nestjs/common as a namespace the decorator reads through, or re-exports a competing library's decorator under another name before @nestjs/common's | high |
| LP44 | the barrel reaches the name through export *, declares it itself, or the alias maps to no file | no origin, and the decorator stays medium |
| LP44a | the barrel exports @nestjs/common's decorator only under another name, before or after re-exporting or declaring its own, or imports it only for its own use | no origin, and the decorator stays medium, whichever order the edges are in |
| LP44b | the resolver fails on a specifier in the middle of a chain, or a module the chain reaches cannot be parsed | no origin |
| LP44c | a language plugin returns an edge with origins | the scan drops it |
| LP45 | two barrels re-exporting the name from each other | the chain ends, with no origin |
| LP46 | one barrel imported by several files | parsed once beyond its own turn if discovery reaches an importer first, not at all beyond it otherwise, and every tree it was parsed into released |
| LP46a | a barrel whose parse takes longer than parseTimeoutMs | the barrel is skipped in its own turn, and the file whose chain reached it is not |
| LP47 | no framework plugin loaded | no resolver created and no barrel parsed |
10. Design Decisions
10.1 Why effect classification is excluded from the plugin's responsibilities
If language plugins carried effect classification, @aburi/lang-typescript would have to know hundreds of call patterns for Prisma/Drizzle/Stripe and so on. To avoid responsibility bloat, the separation is strictly enforced: language plugins handle structure, effect plugins handle identifier patterns.
10.2 Why the final drop decision is excluded from the plugin
The drop list (drop-list.md) is evaluated by integrating input from the config and other plugins. The language plugin only reports the fact "this is a type alias" as a DropHint; the core makes the final drop decision.
10.3 Why fingerprint hashing is excluded from the plugin
Fingerprint consistency (fingerprint.md §8) must be guaranteed across languages. SHA-256 / 12-hex truncation / canonical JSON are implemented in one place in the core; plugins only return normalized strings.
10.4 Why ImportEdge comes from the plugin
Import statement syntax differs greatly per language (TS import, Python from X import Y, Go import (...)). Having the core understand each language's imports directly is too heavy a burden, so it is delegated to the plugin.
10.5 Why extractSymbols and walkBody are separate
Extraction is two-phased:
- Produce the list of symbol candidates (framework plugins can return extKind hints here)
- Walk each symbol body (the walk must happen after extKind is decided)
This anticipates cases where, after the framework plugin decides the extKind, walkBody wants to change its behavior based on that information (e.g. treat @Body parameters specially for a NestJS Controller).
10.6 Why normalizeAst is a separate function
Syntax fingerprint computation is a step independent of IR assembly. normalizeAst is not called for dropped symbols (fingerprint.md §6). Separating it explicitly minimizes overhead.