@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/query/graph.d.ts

@@ -0,0 +1,123 @@
+import { type BundleMeta, type DocsBundle, type Edge, type GraphNode, type NodeType, type NodeRef, type Route, type Section, type SemanticIndex } from '../model';
+/**
+ * Tells whether a kind is a row of its entry (`parameter` or `field`) rather than a page or entry of its own.
+ *
+ * @param kind - Kind of a node, such as `parameter`.
+ */
+export declare function isDeclarationKind(kind: NodeType): kind is 'parameter' | 'field';
+/**
+ * @brief The bundle as a graph the app can walk: children, routes and edges in both
+ * directions. Built once at startup.
+ *
+ * Holds the bundle's nodes and meta, the semantic index, and lookup tables
+ * built from them: child lists, the route of every node, pages by path,
+ * entries by `path#hash`, and edges by source and by target. `web/main.tsx`
+ * creates it from the embedded bundle and `api/source.ts` from a loaded one.
+ * The web app, `retrieval/` and the search functions in `query/` read it.
+ *
+ * Create one with `new Graph(bundle)`.
+ *
+ * @property meta - Title, generation time and generator of the bundle.
+ * @property semantic - The embedding model and node vectors for search by meaning, when the bundle has them.
+ * @property sections - The sections of the bundle, in display order. Some bundles lack `database`, so a walk over every section goes through this list.
+ */
+export declare class Graph {
+    readonly meta: BundleMeta;
+    readonly semantic: SemanticIndex | undefined;
+    private readonly nodes;
+    private readonly childRefs;
+    private readonly routes;
+    private readonly pages;
+    private readonly anchors;
+    private readonly outgoing;
+    private readonly incoming;
+    readonly sections: readonly {
+        readonly slug: Section;
+        readonly node: NodeRef;
+    }[];
+    /**
+     * Indexes the nodes and edges of a bundle.
+     *
+     * @param bundle - Bundle to index, from the embedded data or a loaded file.
+     */
+    constructor(bundle: DocsBundle);
+    /**
+     * Returns the node at `ref`, and throws when there is none.
+     *
+     * @param ref - Index of the node in the bundle.
+     */
+    node(ref: NodeRef): GraphNode;
+    /**
+     * Returns the children of a node in display order.
+     *
+     * @param ref - Index of the parent node.
+     */
+    children(ref: NodeRef): readonly NodeRef[];
+    /**
+     * From the section down to the parent of `ref`.
+     *
+     * @param ref - Index of the node.
+     */
+    ancestors(ref: NodeRef): NodeRef[];
+    /**
+     * Returns the route of the page that shows a node, and throws when there is no node at `ref`.
+     *
+     * @param ref - Index of the node.
+     * @returns The route of the page, with the hash of the entry when the node is one.
+     */
+    route(ref: NodeRef): Route;
+    /**
+     * The node a location shows: the entry `hash` names on the page at `path`, else that page.
+     *
+     * @param path - Page path, with or without leading and trailing slashes, such as `code/src/app.ts`.
+     * @param hash - Anchor of an entry on that page, such as `symbol:App.run`, without `#`.
+     * @returns The node, or `undefined` when the location names none.
+     */
+    at(path: string, hash?: string): NodeRef | undefined;
+    /**
+     * Returns the root node of a section, and throws when the bundle lacks it.
+     *
+     * @param slug - Section slug, such as `code`.
+     */
+    section(slug: Section): NodeRef;
+    /**
+     * The section a node is in.
+     *
+     * @param ref - Index of the node.
+     * @returns Index of the section node, or `ref` itself when it is a section.
+     */
+    sectionOf(ref: NodeRef): NodeRef;
+    /**
+     * Every node below `ref`, depth first, in display order.
+     *
+     * @param ref - Index of the node whose descendants are listed.
+     */
+    descendants(ref: NodeRef): Generator<NodeRef>;
+    /**
+     * Number of nodes below `ref` whose kind is one of `kinds`.
+     *
+     * @param ref - Index of the node whose descendants are counted.
+     * @param kinds - Kinds to count, such as `table` or `field`.
+     */
+    count(ref: NodeRef, kinds: ReadonlySet<NodeType>): number;
+    /**
+     * Returns the edges that start at a node.
+     *
+     * @param ref - Index of the source node.
+     */
+    edgesFrom(ref: NodeRef): readonly Edge[];
+    /**
+     * Returns the edges that end at a node.
+     *
+     * @param ref - Index of the target node.
+     */
+    edgesTo(ref: NodeRef): readonly Edge[];
+    /**
+     * @brief Name of a node as other places refer to it: `Class.method` for a symbol,
+     * `Class.method(parameter)` for a parameter, `table.column` for a column,
+     * `query(:placeholder)` for a placeholder of a query, the file path for a page.
+     *
+     * @param ref - Index of the node.
+     */
+    qualifiedName(ref: NodeRef): string;
+}

package/dist/query/index.d.ts

@@ -0,0 +1,4 @@
+export { Graph, isDeclarationKind } from './graph';
+export { buildSearchIndex, type SearchEntry, type SearchMatch, search } from './name-search';
+export { embeddingModelName, type MeaningOptions, searchByMeaning, similarNodes } from './semantic';
+export { codeText, firstParagraph, plainText } from './text';

package/dist/query/name-search.d.ts

@@ -0,0 +1,65 @@
+import { type NodeRef, type NodeType } from '../model';
+import type { Graph } from './graph';
+/**
+ * What search by words knows about one page or entry. Built by `buildSearchIndex`
+ * and matched by `search`.
+ *
+ * @property node - Node the entry is for.
+ * @property kind - Kind of that node.
+ * @property group - Name of the section the node is in. Results are grouped by it.
+ * @property title - Name shown in the results.
+ * @property detail - Text shown beside the title, such as a file path.
+ * @property haystack - Lowercase text that names the node: its title, the words of its name, the words it replaces.
+ * @property place - Lowercase words of `detail`, each with a space in front of it.
+ * @property text - Lowercase words that describe the node: its description, its definition, the page.
+ *   Every word has a space in front of it, so a search can tell the start of a word from its middle.
+ * @property member - True for a parameter, field, operation or definition. Such an entry lets a query that keeps
+ *   to its kind match it; the search box of the site skips it, because the entry of its owner holds its words too.
+ */
+export interface SearchEntry {
+    readonly node: NodeRef;
+    readonly member: boolean;
+    readonly kind: NodeType;
+    readonly group: string;
+    readonly title: string;
+    readonly detail: string;
+    readonly haystack: string;
+    readonly place: string;
+    readonly text: string;
+}
+/**
+ * One result of a search by words.
+ *
+ * @property entry - The entry that matched.
+ * @property found - `name` when every word of the query is in what names the node. `text` when at least one word is only in what describes it.
+ */
+export interface SearchMatch {
+    readonly entry: SearchEntry;
+    readonly found: 'name' | 'text';
+}
+/**
+ * @brief Builds the index for search by words: one entry per file, symbol, glossary term, decision, table,
+ * query and task.
+ *
+ * Folders are not searched. The name and the text of a parameter, field, operation or definition are added to
+ * the entry of the nearest ancestor that is none of these, such as its function or its file, so a search for
+ * it finds that node. It also gets an entry of its own, marked `member`, for a query that keeps to its kind.
+ *
+ * @param graph - Graph to index.
+ * @returns The entries in display order.
+ */
+export declare function buildSearchIndex(graph: Graph): SearchEntry[];
+/**
+ * @brief Finds the entries that contain every word of a query.
+ *
+ * Entries that are named by the words come first: an exact title, then a title
+ * that starts with the query, then other names. Entries in a file whose path
+ * holds a word follow, then entries that mention a word in their description.
+ * A word of the query may be the start of a word of the description.
+ *
+ * @param index - The index from `buildSearchIndex`.
+ * @param query - What the reader typed.
+ * @param limit - Most matches to return.
+ * @returns The matches, best first.
+ */
+export declare function search(index: readonly SearchEntry[], query: string, limit: number): SearchMatch[];

package/dist/query/semantic.d.ts

@@ -0,0 +1,38 @@
+import { type SemanticHit } from '../embeddings';
+import { type NodeRef } from '../model';
+import type { Graph } from './graph';
+/**
+ * Narrows a search by meaning.
+ *
+ * @property limit - Most hits to return. Default: the number the search dialog shows.
+ * @property accepts - Says which nodes count. Default: every node.
+ */
+export interface MeaningOptions {
+    readonly limit?: number;
+    readonly accepts?: (node: NodeRef) => boolean;
+}
+/**
+ * Finds nodes by the meaning of a query, such as the term `Sailing` for the query `ship`.
+ *
+ * @param graph - Graph to search.
+ * @param query - What the reader typed.
+ * @param exclude - Nodes that are listed already.
+ * @param options - Limit and filter of the search.
+ * @returns The closest nodes, best first. Empty for a graph without embeddings.
+ */
+export declare function searchByMeaning(graph: Graph, query: string, exclude: ReadonlySet<NodeRef>, options?: MeaningOptions): SemanticHit[];
+/**
+ * Finds the nodes whose meaning is closest to that of a node.
+ *
+ * @param graph - Graph the node is in.
+ * @param node - Node to compare with.
+ * @returns The closest nodes, best first. Empty for a graph without embeddings.
+ */
+export declare function similarNodes(graph: Graph, node: NodeRef): SemanticHit[];
+/**
+ * Names the embedding model of a graph.
+ *
+ * @param graph - Graph to read the model from.
+ * @returns The name, or `null` for a graph without embeddings.
+ */
+export declare function embeddingModelName(graph: Graph): string | null;

package/dist/query/text.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reduces scanner HTML to the text a reader sees, on one line.
+ *
+ * @param html - HTML of a description or a page.
+ * @returns The text without tags, with whitespace collapsed. Inline tags leave no gap, so `<code>a</code>.` reads `a.`
+ */
+export declare function plainText(html: string): string;
+/**
+ * Reads source code back out of a highlighted `<pre>` block.
+ *
+ * @param html - HTML of a signature, an example or a file shown as text.
+ * @returns The code with its line breaks, without the highlighting.
+ */
+export declare function codeText(html: string): string;
+/**
+ * Takes the first paragraph of a description as its summary.
+ *
+ * @param html - HTML of a description or a page.
+ * @param maxLength - Longest summary. A longer paragraph is cut at a word and ends with `...`.
+ * @returns The paragraph as plain text, or `''` when the HTML has no paragraph.
+ */
+export declare function firstParagraph(html: string, maxLength?: number): string;

package/dist/retrieval/describe.d.ts

@@ -0,0 +1,33 @@
+import { type EdgeKind, type NodeRef } from '../model';
+import { type Graph } from '../query';
+import type { NodeReport, References } from './report';
+/**
+ * @brief Which edges of a node to report.
+ *
+ * @property direction - `in` for links into the node, `out` for links from it, `both` for either.
+ * @property kinds - Edge kinds to keep, such as `references`. Empty keeps every kind.
+ */
+export interface ReferenceOptions {
+    readonly direction: 'in' | 'out' | 'both';
+    readonly kinds: readonly EdgeKind[];
+}
+/** The options that keep every edge in both directions. */
+export declare const ALL_REFERENCES: ReferenceOptions;
+/**
+ * @brief 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 graph - Graph the node belongs to.
+ * @param node - A page or an entry.
+ * @param options - Which edges to keep, by direction and kind.
+ * @returns What the node links to and what links to it.
+ */
+export declare function referencesOf(graph: Graph, node: NodeRef, options: ReferenceOptions): References;
+/**
+ * @brief Builds the full report of a node: everything its page shows, as data.
+ *
+ * @param graph - Graph the node belongs to.
+ * @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,36 @@
+import { type NodeKind, type NodeRef, type Section } from '../model';
+import type { Graph } from '../query';
+/**
+ * @brief Which nodes a query looks at. An empty filter accepts every node but the sections.
+ *
+ * @property kinds - Kinds to match, such as `function` or `field`. Empty matches every kind. A member kind matches its nodes, and the query returns the node each belongs to.
+ * @property section - Section the results are in. `null` looks in every section.
+ */
+export interface NodeFilter {
+    readonly kinds: readonly NodeKind[];
+    readonly section: Section | null;
+}
+/** The filter that keeps every node. */
+export declare const NO_FILTER: NodeFilter;
+/**
+ * @brief Finds the node a query returns for a matched node: the node itself, or for a parameter, field,
+ * operation or definition the nearest ancestor that is none of these, such as the function of a parameter
+ * or the file of an operation.
+ *
+ * @param node - Node that matched, such as a field of a definition.
+ * @returns The node to return, such as the OpenAPI file the definition is in.
+ */
+export declare function resultOf(graph: Graph, node: NodeRef): NodeRef;
+/**
+ * @brief Turns a filter into a test for one node that a query matches against.
+ *
+ * @returns A function that says whether a node matches. A section never matches. A member node matches by its own kind and by the section of its result.
+ */
+export declare function nodeTest(graph: Graph, filter: NodeFilter): (node: NodeRef) => boolean;
+/**
+ * @brief Maps matched nodes to the nodes a query returns, each once, in the order first met.
+ *
+ * @param nodes - Matched nodes, such as the hits of a search.
+ * @returns Their results, see `resultOf`.
+ */
+export declare function resultsOf(graph: Graph, nodes: readonly NodeRef[]): NodeRef[];

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, resultOf, resultsOf } 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,17 @@
+/**
+ * @brief 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;
+/**
+ * @brief Wraps code in a markdown code block that the code itself cannot close.
+ *
+ * @param code - Source text to wrap.
+ * @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,291 @@
+import type { ApiServer, DocTagKind, EdgeKind, NodeKind, NodeType, PackageRole, QueryEffect, Section, TableIndex, TaskPriority, TaskStatus } from '../model';
+/**
+ * @brief What every listing shows of a node.
+ *
+ * @property id - 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.
+ * @property kind - Kind of the node, such as `function` or `file`.
+ * @property type - Type of the node, such as `method` or `api`, which says what sort of file or symbol it is.
+ * @property title - Name as other places refer to it: `App.run`, the title of a page, `3. Use hash routes`.
+ * @property note - 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.
+ * @property path - 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.
+ * @property line - Line of a symbol, a table or a query in its file. `null` for every other node.
+ * @property summary - 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.
+ */
+export interface NodeSummary {
+    readonly id: string;
+    readonly kind: NodeKind;
+    readonly type: NodeType;
+    readonly title: string;
+    readonly note: string;
+    readonly path: string | null;
+    readonly line: number | null;
+    readonly summary: string;
+}
+/**
+ * @brief 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.
+ *
+ * @property name - Name of the declaration.
+ * @property type - Type as text, or `null` when none is written.
+ * @property defaultValue - Default value as written, or `null`.
+ * @property optional - Whether the declaration may be left out.
+ * @property location - Where an operation takes a parameter from: `path`, `query`, `header` or `cookie`. `null` for every other declaration.
+ * @property annotations - Further facts about a field, verbatim: annotations in code, constraints of a property or a column, the expression behind a result column.
+ * @property column - 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.
+ * @property description - Markdown.
+ */
+export interface DeclarationReport {
+    readonly name: string;
+    readonly type: string | null;
+    readonly defaultValue: string | null;
+    readonly optional: boolean;
+    readonly location: string | null;
+    readonly annotations: readonly string[];
+    readonly column: string | null;
+    readonly description: string;
+}
+/**
+ * @brief One media type of a request body or a response.
+ *
+ * @property mediaType - Media type, such as `application/json`.
+ * @property schema - The schema as a type expression, or `null`.
+ */
+export interface ContentReport {
+    readonly mediaType: string;
+    readonly schema: string | null;
+}
+/**
+ * @brief What an operation of an API states beside its parameters.
+ *
+ * @property method - HTTP method of the operation.
+ * @property path - Path template, or the name of a webhook.
+ * @property operationId - Id of the operation, as the API document names it.
+ * @property tags - Tags of the operation.
+ * @property deprecated - Whether the operation is deprecated.
+ * @property security - The ways a caller can authenticate.
+ * @property requestBody - The request body, or `null`. Holds `required`, the markdown `description` and the `content` media types.
+ * @property responses - One entry per response, with its status, markdown `description` and `content` media types.
+ */
+export interface OperationReport {
+    readonly method: string;
+    readonly path: string;
+    readonly operationId: string;
+    readonly tags: readonly string[];
+    readonly deprecated: boolean;
+    readonly security: readonly string[];
+    readonly requestBody: {
+        readonly required: boolean;
+        readonly description: string;
+        readonly content: readonly ContentReport[];
+    } | null;
+    readonly responses: readonly {
+        readonly status: string;
+        readonly description: string;
+        readonly content: readonly ContentReport[];
+    }[];
+}
+/**
+ * @brief A foreign key of a table.
+ *
+ * @property name - Name of the key.
+ * @property columns - Columns of this table in the key.
+ * @property table - Name of the referenced table.
+ * @property tableId - Id of the referenced table, or `null` when the scan does not have it.
+ * @property referencedColumns - Columns of the referenced table.
+ * @property onDelete - Action on delete, as the file writes it.
+ * @property onUpdate - Action on update, as the file writes it.
+ */
+export interface ForeignKeyReport {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly table: string;
+    readonly tableId: string | null;
+    readonly referencedColumns: readonly string[];
+    readonly onDelete: string;
+    readonly onUpdate: string;
+}
+/**
+ * @brief What a table states beside its columns.
+ *
+ * @property primaryKey - Columns of the primary key.
+ * @property foreignKeys - Foreign keys of the table.
+ * @property indexes - Indexes of the table.
+ * @property constraints - Constraints, as the file writes them.
+ * @property options - Table options, as the file writes them.
+ */
+export interface TableReport {
+    readonly primaryKey: readonly string[];
+    readonly foreignKeys: readonly ForeignKeyReport[];
+    readonly indexes: readonly TableIndex[];
+    readonly constraints: readonly string[];
+    readonly options: readonly string[];
+}
+/**
+ * @brief A view or a trigger of a database.
+ *
+ * @property kind - Whether the object is a `view` or a `trigger`.
+ * @property name - Name of the object.
+ * @property table - The table a trigger fires on. `''` for a view.
+ * @property line - Line of the object in its file.
+ * @property description - Markdown.
+ * @property sql - The SQL of the object, as the file writes it.
+ */
+export interface DatabaseObjectReport {
+    readonly kind: 'view' | 'trigger';
+    readonly name: string;
+    readonly table: string;
+    readonly line: number;
+    readonly description: string;
+    readonly sql: string;
+}
+/**
+ * @brief What an entry of a query catalog states beside its placeholders and result columns.
+ *
+ * @property effect - Whether the query reads or changes data.
+ * @property verb - The keywords that open the statement, in capitals.
+ * @property sql - The SQL as the file writes it.
+ * @property tables - The tables the SQL names. Each has its `name`, its `access` (`read` or `write`) and the `tableId` of the table, or `null` when the scan does not have it.
+ */
+export interface QueryReport {
+    readonly effect: QueryEffect;
+    readonly verb: string;
+    readonly sql: string;
+    readonly tables: readonly {
+        readonly name: string;
+        readonly access: 'read' | 'write';
+        readonly tableId: string | null;
+    }[];
+}
+/**
+ * @brief A doc comment tag that is not a parameter or a return value, such as `throws`.
+ *
+ * @property kind - Kind of the tag.
+ * @property label - Label to print: the kind, or the original label of an `other` tag.
+ * @property subject - What the tag is about, such as the exception type of a `throws` tag, or `null`.
+ * @property text - Markdown.
+ */
+export interface TagReport {
+    readonly kind: DocTagKind;
+    readonly label: string;
+    readonly subject: string | null;
+    readonly text: string;
+}
+/**
+ * @brief One edge of the graph, seen from the node a report is about.
+ *
+ * @property relation - Kind of the edge.
+ * @property node - The node at the other end. For a parameter or a field, the symbol that declares it.
+ * @property via - Name of the parameter or field the edge starts at, when it does not start at a page or an entry.
+ */
+export interface Reference {
+    readonly relation: EdgeKind;
+    readonly node: NodeSummary;
+    readonly via: string | null;
+}
+/**
+ * @brief Both directions of the edges of a node.
+ *
+ * @property linksTo - Edges that start at the node.
+ * @property linkedFrom - Edges that end at the node.
+ */
+export interface References {
+    readonly linksTo: readonly Reference[];
+    readonly linkedFrom: readonly Reference[];
+}
+/**
+ * @brief Everything the site shows about one node, as data. Texts are markdown.
+ *
+ * @property section - Section the node is in, or `null`.
+ * @property signature - Declaration head of a symbol, or `null`.
+ * @property language - Language of a source file or of the file a symbol is in.
+ * @property modifiers - Modifiers of a symbol, as the file writes them.
+ * @property annotations - Annotations of a symbol, as the file writes them.
+ * @property description - 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.
+ * @property body - 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.
+ * @property parameters - Parameters of the node, in source order.
+ * @property fields - Fields of the node, in source order.
+ * @property returns - Return value of a symbol, or `null`. Holds its `type` and its markdown `description`.
+ * @property tags - Doc comment tags that are not parameters or return values.
+ * @property example - Example of a symbol, or `null`. Holds its `code` and whether it is `documented` or `generated`.
+ * @property term - Set for a glossary term: its `group` and the words it `avoid`s.
+ * @property decision - Set for a decision: its `number`, `status` and `date`.
+ * @property task - Set for a plan, a phase and a task.
+ * @property api - Set for an API document: its `version`, `specVersion` and `servers`.
+ * @property package - Set for a package: its `name` and `role`, the path of its `manifest`, and its `version` or `null`.
+ * @property operation - Set for an operation of an API.
+ * @property definition - Set for a schema definition: its `type`, `constraints` and enum `values`, as JSON.
+ * @property table - Set for a table.
+ * @property objects - Views and triggers of a database. Empty for every other node.
+ * @property query - Set for an entry of a query catalog.
+ * @property contains - 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.
+ */
+export interface NodeReport extends NodeSummary, References {
+    readonly section: Section | null;
+    readonly signature: string | null;
+    readonly language: string | null;
+    readonly modifiers: readonly string[];
+    readonly annotations: readonly string[];
+    readonly description: string;
+    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;
+    readonly term: {
+        readonly group: string;
+        readonly avoid: readonly string[];
+    } | null;
+    readonly decision: {
+        readonly number: string;
+        readonly status: string;
+        readonly date: string;
+    } | null;
+    readonly task: TaskReport | null;
+    readonly api: {
+        readonly version: string;
+        readonly specVersion: string;
+        readonly servers: readonly ApiServer[];
+    } | null;
+    readonly package: {
+        readonly name: string;
+        readonly role: PackageRole;
+        readonly manifest: string;
+        readonly version: string | null;
+    } | null;
+    readonly operation: OperationReport | null;
+    readonly definition: {
+        readonly type: string | null;
+        readonly constraints: readonly string[];
+        readonly values: readonly string[];
+    } | null;
+    readonly table: TableReport | null;
+    readonly objects: readonly DatabaseObjectReport[];
+    readonly query: QueryReport | null;
+    readonly contains: readonly NodeSummary[];
+}
+/**
+ * @brief Where a plan, a phase or a task of the task tree stands, as `show` reports it.
+ *
+ * @property id - The id of a task, such as `TASK-006`. `null` for a plan or a phase.
+ * @property status - Status of the plan, phase or task.
+ * @property priority - Priority of the plan, phase or task.
+ * @property dependsOn - Names or ids of what it waits for, as the file writes them.
+ * @property package - The package a task changes. `null` for a plan or a phase.
+ * @property complexity - From 1 to 5. `null` when a task states none, and for a plan or a phase.
+ * @property parallel - Whether the tasks of a phase run side by side. `null` for a plan or a task.
+ */
+export interface TaskReport {
+    readonly id: string | null;
+    readonly status: TaskStatus;
+    readonly priority: TaskPriority;
+    readonly dependsOn: readonly string[];
+    readonly package: string | null;
+    readonly complexity: number | null;
+    readonly parallel: boolean | null;
+}

package/dist/retrieval/resolve.d.ts

@@ -0,0 +1,31 @@
+import { type NodeRef } from '../model';
+import type { Graph } from '../query';
+/**
+ * @brief What a reference to a node turned out to name.
+ *
+ * @property node - The node, when `kind` is `found`.
+ * @property candidates - Nodes that fit equally well, when `kind` is `ambiguous`. The caller has to pick one by id.
+ */
+export type Resolution = {
+    readonly kind: 'found';
+    readonly node: NodeRef;
+} | {
+    readonly kind: 'ambiguous';
+    readonly candidates: readonly NodeRef[];
+} | {
+    readonly kind: 'missing';
+};
+/**
+ * @brief 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 graph - Graph to search.
+ * @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`. A match by name on a parameter, field, operation or definition returns the node it belongs to, see `resultOf`; its id returns the node itself.
+ */
+export declare function resolveNode(graph: Graph, text: string, accepts: (node: NodeRef) => boolean): Resolution;