@g3nomaly/analyze 0.1.0 → 0.1.2

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

@@ -1,47 +1,65 @@
-import { type NodeKind, type NodeRef } from '../model';
+import { type NodeRef, type NodeType } from '../model';
 import type { Graph } from './graph';
-/** What search by words knows about one page or entry. */
+/**
+ * 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 kind: NodeKind;
-    /** Name of the section the node is in. Results are grouped by it. */
+    readonly member: boolean;
+    readonly kind: NodeType;
     readonly group: string;
     readonly title: string;
     readonly detail: string;
-    /** Lowercase text that names the node: its title, the words of its name, the words it replaces. */
     readonly haystack: string;
-    /** Lowercase words of `detail`, each with a space in front of it. */
     readonly place: string;
-    /**
-     * 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.
-     */
     readonly text: string;
 }
-/** One result of a search by words. */
+/**
+ * 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;
-    /** `name`: every word of the query is in what names the node. `text`: at least one is only in what describes it. */
     readonly found: 'name' | 'text';
 }
 /**
- * Builds the index for search by words: one entry per file, symbol, glossary
- * term, decision, API operation, schema definition, table and query. Folders,
- * parameters and fields are not searched.
+ * @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[];
 /**
- * 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.
+ * @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

@@ -1,30 +1,38 @@
 import { type SemanticHit } from '../embeddings';
 import { type NodeRef } from '../model';
 import type { Graph } from './graph';
-/** Narrows a search by meaning. */
+/**
+ * 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 {
-    /** Most hits to return. Default: the number the search dialog shows. */
     readonly limit?: number;
-    /** Says which nodes count. Default: every node. */
     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/retrieval/describe.d.ts

@@ -1,25 +1,32 @@
 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. */
+/**
+ * @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';
-    /** 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
+ * @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;
 /**
- * Builds the full report of a node: everything its page shows, as data.
+ * @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.
  */

package/dist/retrieval/filter.d.ts

@@ -1,17 +1,36 @@
-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. */
+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 {
-    /** 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. */
+/** The filter that keeps every node. */
 export declare const NO_FILTER: NodeFilter;
 /**
- * Turns a filter into a test for one node.
+ * @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.
  *
- * @returns A function that says whether a node passes. Parameters and fields never pass: they have no id.
+ * @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

@@ -1,5 +1,5 @@
 export { ALL_REFERENCES, describeNode, type ReferenceOptions, referencesOf } from './describe';
-export { NO_FILTER, type NodeFilter, nodeTest } from './filter';
+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';

package/dist/retrieval/markdown.d.ts

@@ -1,5 +1,5 @@
 /**
- * Turns scanner HTML back into markdown, for output that is read in a
+ * @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.
  *
@@ -8,8 +8,9 @@
  */
 export declare function htmlToMarkdown(html: string): string;
 /**
- * Wraps code in a markdown code block that the code itself cannot close.
+ * @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.
  */

package/dist/retrieval/report.d.ts

@@ -1,85 +1,117 @@
-import type { ApiServer, DocTagKind, EdgeKind, NodeKind, QueryEffect, Section, TableIndex, TaskPriority, TaskStatus } from '../model';
-/** What every listing shows of a node. */
+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 {
-    /**
-     * 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 type: NodeType;
     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. */
+/**
+ * @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;
-    /** 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. */
+/**
+ * @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;
-    /** The schema as a type expression, or `null`. */
     readonly schema: string | null;
 }
-/** What an operation of an API states beside its parameters. */
+/**
+ * @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;
-    /** 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. */
+/**
+ * @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[];
-    /** 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. */
+/**
+ * @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[];
@@ -87,67 +119,112 @@ export interface TableReport {
     readonly constraints: readonly string[];
     readonly options: readonly string[];
 }
-/** A view or a trigger of a database. */
+/**
+ * @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;
-    /** 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. */
+/**
+ * @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;
-    /** 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`. */
+/**
+ * @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;
-    /** 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. */
+/**
+ * @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;
-    /** 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. */
+/**
+ * @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[];
 }
-/** Everything the site shows about one node, as data. Texts are markdown. */
+/**
+ * @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;
-    /** 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[];
@@ -160,55 +237,55 @@ export interface NodeReport extends NodeSummary, References {
         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 package: {
+        readonly name: string;
+        readonly role: PackageRole;
+        readonly manifest: string;
+        readonly version: string | null;
+    } | null;
     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. */
+/**
+ * @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 {
-    /** 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

@@ -1,27 +1,31 @@
 import { type NodeRef } from '../model';
-import { type Graph } from '../query';
-/** What a reference to a node turned out to name. */
+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;
-}
-/** 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:
+ * @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`.
+ * @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;