@g3nomaly/analyze 0.0.0-stage → 0.1.0

package/dist/retrieval/describe.d.ts

@@ -0,0 +1,26 @@
+import { type EdgeKind, type NodeRef } from '../model';
+import { type Graph } from '../query';
+import type { NodeReport, References } from './report';
+/** Which edges of a node to report. */
+export interface ReferenceOptions {
+    readonly direction: 'in' | 'out' | 'both';
+    /** Edge kinds to keep. Empty keeps every kind. */
+    readonly kinds: readonly EdgeKind[];
+}
+/** The options that keep every edge in both directions. */
+export declare const ALL_REFERENCES: ReferenceOptions;
+/**
+ * Lists the edges of a node in both directions. The edges of its parameters
+ * and fields count as its own, as on its page.
+ *
+ * @param node - A page or an entry.
+ * @returns What the node links to and what links to it.
+ */
+export declare function referencesOf(graph: Graph, node: NodeRef, options: ReferenceOptions): References;
+/**
+ * Builds the full report of a node: everything its page shows, as data.
+ *
+ * @param node - A page or an entry.
+ * @returns The report. Texts are markdown.
+ */
+export declare function describeNode(graph: Graph, node: NodeRef): NodeReport;

package/dist/retrieval/filter.d.ts

@@ -0,0 +1,17 @@
+import type { NodeKind, NodeRef, Section } from '../model';
+import { type Graph } from '../query';
+/** Which nodes a query looks at. An empty filter accepts every page and entry. */
+export interface NodeFilter {
+    /** Kinds to keep. Empty keeps every kind. */
+    readonly kinds: readonly NodeKind[];
+    /** Section to stay in. `null` looks in every section. */
+    readonly section: Section | null;
+}
+/** The filter that keeps every page and entry. */
+export declare const NO_FILTER: NodeFilter;
+/**
+ * Turns a filter into a test for one node.
+ *
+ * @returns A function that says whether a node passes. Parameters and fields never pass: they have no id.
+ */
+export declare function nodeTest(graph: Graph, filter: NodeFilter): (node: NodeRef) => boolean;

package/dist/retrieval/index.d.ts

@@ -0,0 +1,7 @@
+export { ALL_REFERENCES, describeNode, type ReferenceOptions, referencesOf } from './describe';
+export { NO_FILTER, type NodeFilter, nodeTest } from './filter';
+export { codeBlock, htmlToMarkdown } from './markdown';
+export type { ContentReport, DatabaseObjectReport, DeclarationReport, ForeignKeyReport, NodeReport, NodeSummary, OperationReport, QueryReport, Reference, References, TableReport, TagReport, TaskReport, } from './report';
+export { type Resolution, resolveNode } from './resolve';
+export { Retriever, SEARCH_MODES, type SearchHit, type SearchMode, type SearchOptions } from './retriever';
+export { nodeId, normalizeId, summarize } from './summary';

package/dist/retrieval/markdown.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Turns scanner HTML back into markdown, for output that is read in a
+ * terminal or by a program. Headings, lists, tables and code blocks keep
+ * their structure. Links into the site and images are reduced to text.
+ *
+ * @param html - HTML of a description or a page.
+ * @returns Markdown without a trailing line break. `''` for empty HTML.
+ */
+export declare function htmlToMarkdown(html: string): string;
+/**
+ * Wraps code in a markdown code block that the code itself cannot close.
+ *
+ * @param language - Display name of its language, such as `TypeScript`, or `null`.
+ * @returns The block, or `''` for empty code. The fence is longer than any run of backticks in the code.
+ */
+export declare function codeBlock(code: string, language: string | null): string;

package/dist/retrieval/report.d.ts

@@ -0,0 +1,214 @@
+import type { ApiServer, DocTagKind, EdgeKind, NodeKind, QueryEffect, Section, TableIndex, TaskPriority, TaskStatus } from '../model';
+/** What every listing shows of a node. */
+export interface NodeSummary {
+    /**
+     * Route of the node, as in the address of its page: `code/src/app.ts#symbol:App.run`.
+     * Every retrieval command takes it where it takes a node.
+     */
+    readonly id: string;
+    readonly kind: NodeKind;
+    /** Name as other places refer to it: `App.run`, the title of a page, `3. Use hash routes`. */
+    readonly title: string;
+    /** A short fact that belongs beside the title: the status of a decision, a plan, a phase or a task, the language of a source file, the version of an API, the verb of a query. `''` for other nodes. */
+    readonly note: string;
+    /** Path on disk of the file the node is or is in. For a catalog, the path of its directory. `null` for a section or a folder. */
+    readonly path: string | null;
+    /** Line of a symbol, a table or a query in its file. `null` for every other node. */
+    readonly line: number | null;
+    /**
+     * First paragraph of its description, as plain text. A table or a query
+     * without a description gets what its SQL states instead: the number of
+     * columns and the tables it is connected to, or the tables it reads and
+     * writes. `''` for any other node without a description.
+     */
+    readonly summary: string;
+}
+/** A parameter or a field of a symbol, a parameter of an operation, a property of a definition, a column of a table, or a placeholder or a result column of a query. */
+export interface DeclarationReport {
+    readonly name: string;
+    readonly type: string | null;
+    readonly defaultValue: string | null;
+    readonly optional: boolean;
+    /** Where an operation takes a parameter from: `path`, `query`, `header` or `cookie`. `null` for every other declaration. */
+    readonly location: string | null;
+    /** Further facts about a field, verbatim: annotations in code, constraints of a property or a column, the expression behind a result column. */
+    readonly annotations: readonly string[];
+    /** The table column a placeholder or a result column of a query stands for, as `table.column`. `null` for every other declaration, and when the scan does not have the column. */
+    readonly column: string | null;
+    /** Markdown. */
+    readonly description: string;
+}
+/** One media type of a request body or a response. */
+export interface ContentReport {
+    readonly mediaType: string;
+    /** The schema as a type expression, or `null`. */
+    readonly schema: string | null;
+}
+/** What an operation of an API states beside its parameters. */
+export interface OperationReport {
+    readonly method: string;
+    /** Path template, or the name of a webhook. */
+    readonly path: string;
+    readonly operationId: string;
+    readonly tags: readonly string[];
+    readonly deprecated: boolean;
+    /** The ways a caller can authenticate. */
+    readonly security: readonly string[];
+    readonly requestBody: {
+        readonly required: boolean;
+        /** Markdown. */
+        readonly description: string;
+        readonly content: readonly ContentReport[];
+    } | null;
+    readonly responses: readonly {
+        readonly status: string;
+        /** Markdown. */
+        readonly description: string;
+        readonly content: readonly ContentReport[];
+    }[];
+}
+/** A foreign key of a table. */
+export interface ForeignKeyReport {
+    readonly name: string;
+    readonly columns: readonly string[];
+    /** Name of the referenced table. */
+    readonly table: string;
+    /** Id of the referenced table, or `null` when the scan does not have it. */
+    readonly tableId: string | null;
+    readonly referencedColumns: readonly string[];
+    readonly onDelete: string;
+    readonly onUpdate: string;
+}
+/** What a table states beside its columns. */
+export interface TableReport {
+    readonly primaryKey: readonly string[];
+    readonly foreignKeys: readonly ForeignKeyReport[];
+    readonly indexes: readonly TableIndex[];
+    readonly constraints: readonly string[];
+    readonly options: readonly string[];
+}
+/** A view or a trigger of a database. */
+export interface DatabaseObjectReport {
+    readonly kind: 'view' | 'trigger';
+    readonly name: string;
+    /** The table a trigger fires on. `''` for a view. */
+    readonly table: string;
+    readonly line: number;
+    /** Markdown. */
+    readonly description: string;
+    readonly sql: string;
+}
+/** What an entry of a query catalog states beside its placeholders and result columns. */
+export interface QueryReport {
+    readonly effect: QueryEffect;
+    /** The keywords that open the statement, in capitals. */
+    readonly verb: string;
+    /** The SQL as the file writes it. */
+    readonly sql: string;
+    /** The tables the SQL names. */
+    readonly tables: readonly {
+        readonly name: string;
+        readonly access: 'read' | 'write';
+        /** Id of the table, or `null` when the scan does not have it. */
+        readonly tableId: string | null;
+    }[];
+}
+/** A doc comment tag that is not a parameter or a return value, such as `throws`. */
+export interface TagReport {
+    readonly kind: DocTagKind;
+    /** Label to print: the kind, or the original label of an `other` tag. */
+    readonly label: string;
+    /** What the tag is about, such as the exception type of a `throws` tag. */
+    readonly subject: string | null;
+    /** Markdown. */
+    readonly text: string;
+}
+/** One edge of the graph, seen from the node a report is about. */
+export interface Reference {
+    readonly relation: EdgeKind;
+    /** The node at the other end. For a parameter or a field, the symbol that declares it. */
+    readonly node: NodeSummary;
+    /** Name of the parameter or field the edge starts at, when it does not start at a page or an entry. */
+    readonly via: string | null;
+}
+/** Both directions of the edges of a node. */
+export interface References {
+    readonly linksTo: readonly Reference[];
+    readonly linkedFrom: readonly Reference[];
+}
+/** Everything the site shows about one node, as data. Texts are markdown. */
+export interface NodeReport extends NodeSummary, References {
+    readonly section: Section | null;
+    /** Declaration head of a symbol. */
+    readonly signature: string | null;
+    /** Language of a source file or of the file a symbol is in. */
+    readonly language: string | null;
+    readonly modifiers: readonly string[];
+    readonly annotations: readonly string[];
+    /** Description of a symbol, an operation, a definition or a table, note of a query, definition of a term, text of a decision, frontmatter description of a file. */
+    readonly description: string;
+    /** Content of a file: its markdown, or its text in a code block. The description of an API, the opening comment of a database. `''` for every other node. */
+    readonly body: string;
+    readonly parameters: readonly DeclarationReport[];
+    readonly fields: readonly DeclarationReport[];
+    readonly returns: {
+        readonly type: string | null;
+        readonly description: string;
+    } | null;
+    readonly tags: readonly TagReport[];
+    readonly example: {
+        readonly code: string;
+        readonly origin: 'documented' | 'generated';
+    } | null;
+    /** Set for a glossary term. */
+    readonly term: {
+        readonly group: string;
+        readonly avoid: readonly string[];
+    } | null;
+    /** Set for a decision. */
+    readonly decision: {
+        readonly number: string;
+        readonly status: string;
+        readonly date: string;
+    } | null;
+    /** Set for a plan, a phase and a task. */
+    readonly task: TaskReport | null;
+    /** Set for an API document. */
+    readonly api: {
+        readonly version: string;
+        readonly specVersion: string;
+        readonly servers: readonly ApiServer[];
+    } | null;
+    /** Set for an operation of an API. */
+    readonly operation: OperationReport | null;
+    /** Set for a schema definition. */
+    readonly definition: {
+        readonly type: string | null;
+        readonly constraints: readonly string[];
+        /** Values of an `enum`, as JSON. */
+        readonly values: readonly string[];
+    } | null;
+    /** Set for a table. */
+    readonly table: TableReport | null;
+    /** Views and triggers. Set for a database. */
+    readonly objects: readonly DatabaseObjectReport[];
+    /** Set for an entry of a query catalog. */
+    readonly query: QueryReport | null;
+    /** The pages and entries inside the node: files of a folder or a skill, symbols of a file, members of a class, tables of a database, queries of a catalog. */
+    readonly contains: readonly NodeSummary[];
+}
+/** Where a plan, a phase or a task of the task tree stands, as `show` reports it. */
+export interface TaskReport {
+    /** The id of a task, such as `TASK-006`. `null` for a plan or a phase. */
+    readonly id: string | null;
+    readonly status: TaskStatus;
+    readonly priority: TaskPriority;
+    /** Names or ids of what it waits for, as the file writes them. */
+    readonly dependsOn: readonly string[];
+    /** The package a task changes. `null` for a plan or a phase. */
+    readonly package: string | null;
+    /** From 1 to 5. `null` when a task states none, and for a plan or a phase. */
+    readonly complexity: number | null;
+    /** Whether the tasks of a phase run side by side. `null` for a plan or a task. */
+    readonly parallel: boolean | null;
+}

package/dist/retrieval/resolve.d.ts

@@ -0,0 +1,27 @@
+import { type NodeRef } from '../model';
+import { type Graph } from '../query';
+/** What a reference to a node turned out to name. */
+export type Resolution = {
+    readonly kind: 'found';
+    readonly node: NodeRef;
+}
+/** Several nodes fit equally well. The caller has to pick one by id. */
+ | {
+    readonly kind: 'ambiguous';
+    readonly candidates: readonly NodeRef[];
+} | {
+    readonly kind: 'missing';
+};
+/**
+ * Finds the node a caller means. The first of these rules that fits any node decides:
+ *
+ * 1. The text is the id of a node, with or without `#/` in front. An id with the anchor of a heading names its page.
+ * 2. The text is the path of a file on disk. The path of a query file names its query.
+ * 3. The text is the name of a node, with the same capitals.
+ * 4. The text is the name of a node, capitals ignored.
+ *
+ * @param text - An id, a path or a name.
+ * @param accepts - Narrows the nodes that count, such as to one kind.
+ * @returns The node, the candidates when several fit the deciding rule, or `missing`.
+ */
+export declare function resolveNode(graph: Graph, text: string, accepts: (node: NodeRef) => boolean): Resolution;

package/dist/retrieval/retriever.d.ts

@@ -0,0 +1,94 @@
+import type { NodeRef } from '../model';
+import { type Graph } from '../query';
+import { type ReferenceOptions } from './describe';
+import { type NodeFilter } from './filter';
+import type { NodeReport, NodeSummary, References } from './report';
+import { type Resolution } from './resolve';
+/** The search modes a caller can pick from, the default first. */
+export declare const SEARCH_MODES: readonly ['both', 'name', 'meaning'];
+/** How a search matches: `name` by the words of a name or a description, `meaning` by the embedding model, `both` by words first and then by meaning. */
+export type SearchMode = (typeof SEARCH_MODES)[number];
+/** How one search is run. */
+export interface SearchOptions {
+    readonly mode: SearchMode;
+    /** Most hits to return, both ways of matching together. */
+    readonly limit: number;
+    readonly filter: NodeFilter;
+}
+/** One result of a search. */
+export interface SearchHit extends NodeSummary {
+    /**
+     * `name`: every word of the query is in the name or the path of the node.
+     * `text`: at least one word is only in its description.
+     * `meaning`: the node is close to the query in the embedding model.
+     */
+    readonly match: 'name' | 'text' | 'meaning';
+    /** From 0 to 1 for a match by meaning. `null` for a match by words. */
+    readonly score: number | null;
+}
+/**
+ * Answers queries on one bundle: search, list, look up, describe.
+ *
+ * Holds the graph of the bundle and, after the first search by name, the
+ * search index. `openRetriever` in `api/source.ts` creates one per request;
+ * `listIn`, `searchIn`, `showIn` and `refsIn` in `api/` each call one method.
+ * Every answer is plain data with ids, so a caller can print it, serialize it
+ * or feed an id into the next call.
+ */
+export declare class Retriever {
+    private readonly graph;
+    /** Built on the first search by name. */
+    private nameIndex;
+    /** Creates a retriever for one bundle. */
+    constructor(graph: Graph);
+    /**
+     * Names the embedding model that searches by meaning.
+     *
+     * @returns The name, or `null` when the bundle was built without embeddings.
+     */
+    get model(): string | null;
+    /**
+     * Finds pages and entries for a query. Matches by words come first, in the
+     * order the site lists them. Matches by meaning follow, best first.
+     *
+     * @param query - Words of a name, or a query in plain language.
+     * @returns The hits, each once.
+     */
+    search(query: string, options: SearchOptions): SearchHit[];
+    /**
+     * Lists pages and entries in display order.
+     *
+     * @param limit - Most rows to return. `null` returns all of them.
+     * @returns One row per node.
+     */
+    list(filter: NodeFilter, limit: number | null): NodeSummary[];
+    /**
+     * Finds the node a caller means by an id, a file path or a name.
+     *
+     * @param text - What the caller wrote.
+     * @param filter - Narrows the nodes that count, to tell two nodes with one name apart.
+     * @returns The node, the candidates when several fit, or `missing`.
+     */
+    resolve(text: string, filter: NodeFilter): Resolution;
+    /**
+     * Describes a node in one row.
+     *
+     * @param node - A page or an entry.
+     * @returns Its id, kind, title, place on disk and summary.
+     */
+    summarize(node: NodeRef): NodeSummary;
+    /**
+     * Builds the full report of a node.
+     *
+     * @param node - A page or an entry.
+     * @returns Everything its page shows, with texts as markdown.
+     */
+    describe(node: NodeRef): NodeReport;
+    /**
+     * Lists the edges of a node.
+     *
+     * @param node - A page or an entry.
+     * @returns What the node links to and what links to it.
+     */
+    references(node: NodeRef, options?: ReferenceOptions): References;
+}

package/dist/retrieval/summary.d.ts

@@ -0,0 +1,24 @@
+import { type NodeRef } from '../model';
+import { type Graph } from '../query';
+import type { NodeSummary } from './report';
+/**
+ * Builds the id of a node: its route as the address of its page spells it,
+ * without the leading `#/`.
+ *
+ * @param node - The node. A parameter or a field has the id of its symbol.
+ * @returns The id, such as `docs/glossary.md#term:lane`.
+ */
+export declare function nodeId(graph: Graph, node: NodeRef): string;
+/**
+ * Reduces an id, an address copied from the browser or an href of the site to an id.
+ *
+ * @param text - What the caller wrote, such as `#/code/src/app.ts#symbol:App.run` or `file:///site/docs.html#/code/src/app.ts`.
+ * @returns The id without the file, `#/` or slashes around it, with percent escapes decoded.
+ */
+export declare function normalizeId(text: string): string;
+/**
+ * Describes a node in one row: what a search hit, a list row and a reference show.
+ *
+ * @param node - The node. A parameter or a field is not listed on its own, so pass its symbol.
+ */
+export declare function summarize(graph: Graph, node: NodeRef): NodeSummary;

package/dist/scanner/code/doc/clean.d.ts

@@ -0,0 +1,10 @@
+/** Strips comment markers from the text of consecutive comment nodes. */
+export declare function cleanComments(comments: readonly string[]): string;
+/** Content of a Python string literal used as a docstring, laid out like `inspect.cleandoc`. */
+export declare function cleanDocstring(literal: string): string;
+/** Text of the first fenced code block, or `null`. */
+export declare function firstFencedBlock(markdown: string): string | null;
+/** Applies `transform` to every line outside fenced code blocks. */
+export declare function mapProseLines(markdown: string, transform: (line: string) => string): string;
+/** Turns markdown headings into bold lines, so a description never outranks its symbol title. */
+export declare function demoteHeadings(markdown: string): string;

package/dist/scanner/code/doc/index.d.ts

@@ -0,0 +1,6 @@
+import type { DocStyle } from '../language';
+import { type ParsedDoc } from './types';
+export { cleanComments, cleanDocstring } from './clean';
+export type { ParsedDoc, ParsedTag, ParsedTagKind } from './types';
+/** Parses cleaned doc comment text in the given dialect. */
+export declare function parseDoc(style: DocStyle, text: string | null): ParsedDoc;

package/dist/scanner/code/doc/markdown.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedDoc } from './types';
+/** Parses a markdown doc comment (rustdoc, godoc). An "Examples" section becomes the example. */
+export declare function parseMarkdownDoc(text: string): ParsedDoc;

package/dist/scanner/code/doc/python.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedDoc } from './types';
+/** Parses a docstring in Google, NumPy or reST layout. */
+export declare function parsePythonDoc(text: string): ParsedDoc;

package/dist/scanner/code/doc/tagged.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedDoc } from './types';
+/** Dialect switches for `parseTagged`. */
+export interface TaggedOptions {
+    /** YARD puts an example title on the `@example` line. */
+    readonly titledExamples?: boolean;
+    /** YARD links to code with braces, as in `{Label.parse}` and `{#render}`. */
+    readonly braceLinks?: boolean;
+}
+/** Parses a doc comment written with `@tag` lines. */
+export declare function parseTagged(text: string, options?: TaggedOptions): ParsedDoc;

package/dist/scanner/code/doc/types.d.ts

@@ -0,0 +1,22 @@
+import type { DocTagKind } from '../../../model';
+/** Tag kinds a parser emits. The planner folds the first three into parameters, return value and fields. */
+export type ParsedTagKind = 'param' | 'returns' | 'field' | DocTagKind;
+/** One tag of a parsed doc comment, such as a parameter or a return value. */
+export interface ParsedTag {
+    readonly kind: ParsedTagKind;
+    readonly label?: string;
+    readonly name?: string;
+    readonly type?: string;
+    /** Markdown. */
+    readonly text: string;
+}
+/** A doc comment parsed into description, tags and example, the same for every dialect. */
+export interface ParsedDoc {
+    /** Markdown. */
+    readonly description: string;
+    readonly tags: readonly ParsedTag[];
+    /** Example source code, when the comment documents one. */
+    readonly example: string | null;
+}
+/** Result for a symbol with no doc comment. */
+export declare const EMPTY_DOC: ParsedDoc;

package/dist/scanner/code/doc/xml.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedDoc } from './types';
+/** Parses C# XML documentation comments. Text without XML elements is the description. */
+export declare function parseXmlDoc(text: string): ParsedDoc;

package/dist/scanner/code/example.d.ts

@@ -0,0 +1,36 @@
+import { type SymbolKind } from '../../model';
+import type { CallStyle, ImportContext } from './language';
+/** What a generated example needs to know about the type a method belongs to. */
+export interface ParentTarget {
+    readonly kind: SymbolKind;
+    readonly name: string;
+    /** Constructor arguments of the type. */
+    readonly args: readonly string[];
+    readonly hasConstructor: boolean;
+    readonly instantiable: boolean;
+}
+/** The symbol a generated example calls or constructs, with what decides how. */
+export interface CallTarget {
+    readonly kind: SymbolKind;
+    readonly name: string;
+    /** Argument expressions, receivers excluded. */
+    readonly args: readonly string[];
+    readonly parent: ParentTarget | null;
+    readonly isStatic: boolean;
+    readonly isAsync: boolean;
+    /** For types: false when abstract or a singleton. */
+    readonly instantiable: boolean;
+    readonly isConstructor: boolean;
+    /** For types: whether a constructor was found. */
+    readonly hasConstructor: boolean;
+    readonly returnsValue: boolean;
+    readonly returnType: string | null;
+    /** What to import, or `null` when the symbol needs no import or none can be derived. */
+    readonly importContext: ImportContext | null;
+}
+/**
+ * Builds a usage example from a signature: an import where the language
+ * allows one, the instance a method needs, then the call.
+ * Returns `null` for symbols that are not called.
+ */
+export declare function buildExample(style: CallStyle, target: CallTarget): string | null;

package/dist/scanner/code/extract.d.ts

@@ -0,0 +1,78 @@
+import { type SymbolKind } from '../../model';
+import type { Node, Query } from 'web-tree-sitter';
+import type { LanguageSpec } from './language';
+/** One parameter as declared. */
+export interface RawParameter {
+    /** Name with its variadic marker, such as `...rest` or `*args`. */
+    readonly name: string;
+    readonly type: string | null;
+    defaultValue: string | null;
+    optional: boolean;
+    /** Expression a generated call passes for this parameter. */
+    readonly argument: string;
+}
+/** A field, property or enum member as declared. */
+export interface RawField {
+    readonly name: string;
+    readonly type: string | null;
+    readonly defaultValue: string | null;
+    readonly optional: boolean;
+    readonly annotations: readonly string[];
+    /** Cleaned doc comment text, or `null`. */
+    readonly comment: string | null;
+}
+/** One definition as found in the syntax tree, before rendering. */
+export interface RawSymbol {
+    kind: SymbolKind;
+    readonly name: string;
+    readonly line: number;
+    /** Declaration head. Empty when `inferred`. */
+    readonly signature: string;
+    /** Keywords in front of the name, such as `export` or `static`. */
+    readonly modifiers: readonly string[];
+    readonly annotations: readonly string[];
+    /** Cleaned doc comment text, or `null`. */
+    readonly comment: string | null;
+    /** Receivers excluded. */
+    readonly parameters: readonly RawParameter[];
+    readonly fields: RawField[];
+    readonly returnType: string | null;
+    /** Names the declaration introduces as type parameters, such as `T`. They never name a real type. */
+    readonly typeParameters: readonly string[];
+    /** For a type: the text after its name that lists what it extends or is composed of. `''` otherwise. */
+    readonly heritage: string;
+    readonly isAsync: boolean;
+    /** False for abstract classes and singletons. */
+    readonly instantiable: boolean;
+    isStatic: boolean;
+    returnsValue: boolean;
+    /** True for an owner type that is not declared in this file. */
+    readonly inferred: boolean;
+    readonly children: RawSymbol[];
+}
+/** Symbols and package name extracted from one source file. */
+export interface ExtractedFile {
+    readonly symbols: RawSymbol[];
+    /** Package or namespace the file declares, when the language has one. */
+    readonly packageName: string | null;
+}
+/**
+ * Turns a parsed file into a tree of {@link RawSymbol}s, driven by a {@link LanguageSpec}.
+ *
+ * Holds no state, so one instance serves every file. Created by `RepositoryScanner`
+ * in `scanner/scanner.ts` and passed to `CodePlanner` in `planner.ts`, which calls
+ * {@link SymbolExtractor.extract} once per parsed file.
+ */
+export declare class SymbolExtractor {
+    /**
+     * Runs the language's tags query over the tree and builds the symbol tree from its matches.
+     *
+     * @param source - Full text of the file the tree was parsed from; node offsets index into it.
+     */
+    extract(root: Node, query: Query, spec: LanguageSpec, source: string): ExtractedFile;
+    /**
+     * Merges the query matches into one definition per node (per name for fields), sorted by
+     * position with outer nodes first, and picks up the declared package name.
+     */
+    private collect;
+}

package/dist/scanner/code/grammar.d.ts

@@ -0,0 +1,29 @@
+import { Parser, Query } from 'web-tree-sitter';
+import type { LanguageSpec } from './language';
+/** Parser and compiled tags query for one language. */
+export interface LoadedGrammar {
+    readonly parser: Parser;
+    readonly query: Query;
+}
+/**
+ * Loads tree-sitter grammars on first use and keeps one parser and compiled query per language.
+ *
+ * Holds the tree-sitter runtime init promise and one pending {@link LoadedGrammar} per
+ * language id. Created by `RepositoryScanner` in `scanner/scanner.ts`; `CodePlanner` in
+ * `planner.ts` loads a grammar for each file it parses.
+ */
+export declare class GrammarLoader {
+    private readonly baseDir;
+    private runtime;
+    private readonly grammars;
+    /**
+     * Stores the directory grammar paths resolve against. Nothing loads until the first `load`.
+     *
+     * @param baseDir - Absolute directory that relative grammar paths resolve against.
+     */
+    constructor(baseDir: string);
+    /** Returns the cached grammar of the spec's language, loading it on the first call. */
+    load(spec: LanguageSpec): Promise<LoadedGrammar>;
+    /** Initialises the tree-sitter runtime once, then loads the grammar `.wasm` and compiles the query. */
+    private create;
+}