@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/model/index.d.ts

@@ -0,0 +1,788 @@
+import { type EdgeKind, type KindsIn, type NodeType, type Section } from './registry';
+/** Index of a node in {@link DocsBundle.nodes}. */
+export type NodeRef = number;
+export { ALL_NODE_KINDS, ALL_NODE_TYPES, EDGE_KINDS, type EdgeKind, kindsIn, kindsWith, isMemberKind, kindOf, NODE_KINDS, NODE_TYPES, type NodeGroup, type NodeKind, type NodeKindSpec, type NodeType, type NodeTypeSpec, RELATION_FAMILIES, RELATION_FAMILY_NAMES, RELATION_KINDS, type RelationFamily, type RelationFamilySpec, type RelationKindSpec, SECTION_SPECS, SECTIONS, type Section, type SectionSpec, } from './registry';
+/** Kinds of a declaration in code. */
+export declare const SYMBOL_KINDS: readonly KindsIn<"symbol">[];
+/** A kind of a declaration in code. */
+export type SymbolKind = KindsIn<'symbol'>;
+/** Kinds a type name can refer to. */
+export declare const TYPE_KINDS: ReadonlySet<SymbolKind>;
+/** Kinds that own member symbols. */
+export declare const CONTAINER_KINDS: ReadonlySet<SymbolKind>;
+/**
+ * Kinds of a file that has a page. See `NODE_TYPE_REGISTRY` for what each one is.
+ * A `glossary`, `decisions`, `schema`, `api`, `database` or `catalog` node has its entries as children.
+ */
+export declare const FILE_KINDS: readonly KindsIn<"file">[];
+/** A kind of a file that has a page. */
+export type FileKind = KindsIn<'file'>;
+/**
+ * Kinds shown as an **entry**: a block on the page of the file they are in,
+ * with an anchor of its own. Symbols are entries of a source file, terms of a
+ * glossary, decisions of a decision log, operations of an OpenAPI document,
+ * definitions of an OpenAPI document or a JSON Schema, tables of a database,
+ * queries of a query catalog.
+ */
+export declare const ENTRY_KINDS: readonly KindsIn<"entry" | "symbol">[];
+/** A kind shown as an entry. */
+export type EntryKind = KindsIn<'symbol' | 'entry'>;
+/** Kinds a node with an id can have: every kind but parameter and field. */
+export declare const LISTED_KINDS: readonly KindsIn<"entry" | "file" | "folder" | "section" | "source" | "symbol">[];
+/**
+ * Tells a symbol kind from the others.
+ *
+ * @param kind - Kind of a node, such as `class` or `function`.
+ */
+export declare function isSymbolKind(kind: NodeType): kind is SymbolKind;
+/**
+ * Tells the kind of a file with a page from the others.
+ *
+ * @param kind - Kind of a node, such as `skill` or `document`.
+ */
+export declare function isFileKind(kind: NodeType): kind is FileKind;
+/**
+ * Tells an entry kind, a symbol included, from the others.
+ *
+ * @param kind - Kind of a node, such as `term` or `table`.
+ */
+export declare function isEntryKind(kind: NodeType): kind is EntryKind;
+/**
+ * What every node states, whatever its kind.
+ *
+ * @property kind - Kind of the node, such as `class`, `table` or `parameter`.
+ * @property name - Shown in the tree: a file name, a symbol name, a parameter name.
+ * @property parent - The node this one belongs to. `null` for a section.
+ * @property slug - Segment of the node's route. Defaults to `name`.
+ */
+interface NodeBase<K extends NodeType> {
+    readonly kind: K;
+    readonly name: string;
+    readonly parent: NodeRef | null;
+    readonly slug?: string;
+}
+/**
+ * One of the top-level groups.
+ *
+ * @property slug - Section slug, such as `code`.
+ */
+export interface SectionNode extends NodeBase<'section'> {
+    readonly slug: Section;
+}
+/** A directory of the scanned repository. */
+export type FolderNode = NodeBase<'folder'>;
+/** What a package is: an `app` runs, a `library` is used by other packages, a `workspace` holds packages. */
+export type PackageRole = 'app' | 'library' | 'workspace';
+/**
+ * @brief A directory of the scanned repository with a package manifest, such as a `package.json` or a `Cargo.toml`.
+ *
+ * @property path - Display path of the directory, such as `packages/core`.
+ * @property packageName - Name the manifest gives, such as `@g3nomaly/core`, or the directory name when it gives none.
+ * @property manifest - Display path of the manifest, such as `packages/core/package.json`.
+ * @property version - Version the manifest gives, or `null`.
+ * @property description - Description the manifest gives, or `''`.
+ */
+export interface PackageNode extends NodeBase<'package'> {
+    readonly path: string;
+    readonly packageName: string;
+    readonly role: PackageRole;
+    readonly manifest: string;
+    readonly version: string | null;
+    readonly description: string;
+}
+/**
+ * A heading of a markdown page, for its table of contents.
+ *
+ * @property id - Anchor of the heading.
+ * @property text - Heading text as plain text.
+ * @property depth - Heading level, such as `2` for `##`.
+ */
+export interface Heading {
+    readonly id: string;
+    readonly text: string;
+    readonly depth: number;
+}
+/**
+ * @brief What a file looks like on its page.
+ *
+ * `markdown` holds the rendered HTML and the headings of the page, `text` a
+ * highlighted `<pre>` block (highlighted when the file is small enough),
+ * `image` a `data:` URI in `src`, and `omitted` the reason and size of a file
+ * that is left out.
+ */
+export type FileContent = {
+    readonly format: 'markdown';
+    readonly html: string;
+    readonly headings: readonly Heading[];
+} | {
+    readonly format: 'text';
+    readonly html: string;
+} | {
+    readonly format: 'image';
+    readonly src: string;
+} | {
+    readonly format: 'omitted';
+    readonly reason: 'binary' | 'large';
+    readonly bytes: number;
+};
+/**
+ * What every file with a page states.
+ *
+ * @property path - Path as it is on disk, relative to the scanned root. For a `catalog`, the path of its directory.
+ * @property title - Frontmatter `title` or `name`, else the first heading, else the file name.
+ * @property description - Frontmatter `description`, or `''`.
+ * @property content - What the file looks like on its page.
+ */
+interface FileFacts {
+    readonly path: string;
+    readonly title: string;
+    readonly description: string;
+    readonly content: FileContent;
+}
+/**
+ * @brief A file shown as it is.
+ *
+ * A `skill` node is the skill's `SKILL.md`, and the skill's other files are its descendants.
+ * For a `glossary` or `decisions` node, `content` is the text around its entries, and the entries are its children.
+ * A `schema` node that is a JSON Schema has its definitions as children.
+ * A `catalog` node has no content of its own: its queries are its children.
+ */
+export interface FileNode extends NodeBase<Exclude<FileKind, 'api' | 'database' | 'plan' | 'phase'>>, FileFacts {
+}
+/**
+ * A base URL an API is served from.
+ *
+ * @property url - Base URL as the document writes it.
+ * @property description - Plain text, or `''`.
+ */
+export interface ApiServer {
+    readonly url: string;
+    readonly description: string;
+}
+/**
+ * A group of operations of an OpenAPI document.
+ *
+ * @property name - Name of the group.
+ * @property descriptionHtml - Description rendered as HTML.
+ */
+export interface ApiTag {
+    readonly name: string;
+    readonly descriptionHtml: string;
+}
+/**
+ * @brief An OpenAPI document.
+ *
+ * Its operations and its schema definitions are its children. `title` is the
+ * title of the API, `description` its summary, and `content` its description.
+ *
+ * @property version - Version of the API, from `info.version`.
+ * @property specVersion - Version of the OpenAPI format the document is written in, such as `3.1.0`.
+ * @property servers - Base URLs the API is served from.
+ * @property tags - Tags the document declares, in its order. An operation can name a tag that is not listed here.
+ */
+export interface ApiNode extends NodeBase<'api'>, FileFacts {
+    readonly version: string;
+    readonly specVersion: string;
+    readonly servers: readonly ApiServer[];
+    readonly tags: readonly ApiTag[];
+}
+/**
+ * A view or a trigger of a database schema.
+ *
+ * @property kind - `view` or `trigger`.
+ * @property name - Name of the view or the trigger.
+ * @property table - The table a trigger fires on. `''` for a view.
+ * @property line - Line of the file where it is created.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property sqlHtml - The highlighted statement that creates it.
+ */
+export interface DatabaseObject {
+    readonly kind: 'view' | 'trigger';
+    readonly name: string;
+    readonly table: string;
+    readonly line: number;
+    readonly descriptionHtml: string;
+    readonly sqlHtml: string;
+}
+/**
+ * @brief A `.sql` file that creates tables.
+ *
+ * Its tables are its children. `content` is the comment that opens the file.
+ *
+ * @property objects - Views and triggers, in file order.
+ */
+export interface DatabaseNode extends NodeBase<'database'>, FileFacts {
+    readonly objects: readonly DatabaseObject[];
+}
+/**
+ * A source file. Its symbols are its descendants.
+ *
+ * @property path - Path of the file, relative to the scanned root.
+ * @property language - Name of the language of the file.
+ * @property annotationLabel - What the language calls its annotations: `Decorators`, `Attributes` or `Annotations`.
+ * @property content - The file's text. Set for a skill's code, `null` in the code section.
+ */
+export interface SourceNode extends NodeBase<'source'> {
+    readonly path: string;
+    readonly language: string;
+    readonly annotationLabel: string;
+    readonly content: FileContent | null;
+}
+/** `[start, end, target]`: the characters `start` to `end` of a text name the node `target`. */
+export type TextLink = readonly [start: number, end: number, target: NodeRef];
+/**
+ * Source text in which some spans name other nodes, such as `Promise<Booking>` with `Booking` linked.
+ *
+ * @property text - The text as written in the source.
+ * @property links - Spans of the text that name a node, in text order, not overlapping.
+ */
+export interface LinkedText {
+    readonly text: string;
+    readonly links: readonly TextLink[];
+}
+/** Doc comment tags that are not folded into parameters, return value or fields. */
+export type DocTagKind = 'throws' | 'deprecated' | 'see' | 'since' | 'other';
+/**
+ * A tag of a doc comment, such as `@throws` or `@deprecated`.
+ *
+ * @property kind - Which tag it is: `throws`, `deprecated`, `see`, `since` or `other`.
+ * @property label - Original tag label, for example `typeParam`. Set when `kind` is `other`.
+ * @property subject - What the tag is about, such as the exception type of a `throws` tag, or `null`.
+ * @property html - Text of the tag as HTML.
+ */
+export interface DocTag {
+    readonly kind: DocTagKind;
+    readonly label?: string;
+    readonly subject: LinkedText | null;
+    readonly html: string;
+}
+/**
+ * What a function returns: its type and the description of its doc comment.
+ *
+ * @property type - Return type, or `null` when none is known.
+ * @property descriptionHtml - Description of the return value as HTML.
+ */
+export interface ReturnInfo {
+    readonly type: LinkedText | null;
+    readonly descriptionHtml: string;
+}
+/**
+ * A highlighted usage example of a symbol.
+ *
+ * @property html - The highlighted code.
+ * @property origin - `documented` comes from the doc comment, `generated` from the signature.
+ */
+export interface SymbolExample {
+    readonly html: string;
+    readonly origin: 'documented' | 'generated';
+}
+/**
+ * A class, function or other definition. Its parameters, fields and member symbols are its children.
+ *
+ * @property anchor - Unique within the file and safe in a URL hash.
+ * @property line - Line of the file where the declaration starts.
+ * @property signatureHtml - Highlighted declaration head. Empty for a type the scanner inferred from its members.
+ * @property modifiers - Keywords in front of the declaration, such as `export`, `static` or `async`.
+ * @property annotations - Decorators, attributes and annotations, verbatim.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property returns - What the symbol returns, or `null`.
+ * @property tags - Doc comment tags that are not folded into parameters, return value or fields.
+ * @property example - Usage example, or `null`.
+ */
+export interface SymbolNode extends NodeBase<SymbolKind> {
+    readonly anchor: string;
+    readonly line: number;
+    readonly signatureHtml: string;
+    readonly modifiers: readonly string[];
+    readonly annotations: readonly string[];
+    readonly descriptionHtml: string;
+    readonly returns: ReturnInfo | null;
+    readonly tags: readonly DocTag[];
+    readonly example: SymbolExample | null;
+}
+/** Where an operation of an API takes a parameter from. */
+export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
+/**
+ * What parameters and fields share: a declaration from the signature, a description from the doc comment.
+ *
+ * @property type - Declared type, or `null`.
+ * @property defaultValue - Default value of a parameter, initializer of a field, value of an enum member. `null` when none.
+ * @property optional - Whether it may be left out.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property column - The table column a declaration of a query stands for: the column a
+ *   parameter is compared with or stored in, the column a result column
+ *   selects. Set when the statement shows one and the scan has that table.
+ */
+interface Declaration {
+    readonly type: LinkedText | null;
+    readonly defaultValue: string | null;
+    readonly optional: boolean;
+    readonly descriptionHtml: string;
+    readonly column?: NodeRef;
+}
+/**
+ * @brief A parameter of a function, of a type's constructor, of an API operation or of a query.
+ *
+ * `name` carries a variadic marker, as in `...rest`, or the marker of a SQL placeholder, as in `:map_id`.
+ *
+ * @property location - Where an API operation takes it from. Set for a parameter of an API operation.
+ */
+export interface ParameterNode extends NodeBase<'parameter'>, Declaration {
+    readonly location?: ParameterLocation;
+}
+/**
+ * @brief A field, property or enum member of a type, a property of a schema
+ * definition, a column of a table, or a column of the rows a query returns.
+ *
+ * @property annotations - Further facts about the field, verbatim: annotations in code, constraints
+ *   of a property such as `format: date`, constraints of a column such as
+ *   `UNIQUE`, the expression behind a result column such as `COUNT(*)`.
+ */
+export interface FieldNode extends NodeBase<'field'>, Declaration {
+    readonly annotations: readonly string[];
+}
+/**
+ * One term of a glossary: a word of the project's language and what it means.
+ *
+ * @property anchor - Unique within the glossary and safe in a URL hash.
+ * @property group - Heading the glossary lists the term under, or `''`.
+ * @property definitionHtml - Definition rendered as HTML.
+ * @property avoid - Words the glossary tells writers to replace with this term.
+ */
+export interface TermNode extends NodeBase<'term'> {
+    readonly anchor: string;
+    readonly group: string;
+    readonly definitionHtml: string;
+    readonly avoid: readonly string[];
+}
+/**
+ * One decision of a decision log: what was decided and why.
+ *
+ * @property anchor - Unique within the log and safe in a URL hash.
+ * @property id - Number or id in front of the title, such as `3` or `ADR-0003`. `''` when the title has none.
+ * @property status - As written in the log, such as `accepted` or `superseded by 7`. `''` when the decision states none.
+ * @property date - As written in the log. `''` when the decision states none.
+ * @property html - Text of the decision rendered as HTML.
+ */
+export interface DecisionNode extends NodeBase<'decision'> {
+    readonly anchor: string;
+    readonly id: string;
+    readonly status: string;
+    readonly date: string;
+    readonly html: string;
+}
+/**
+ * One media type of a request body or a response, with the schema of its content.
+ *
+ * @property mediaType - Such as `application/json`.
+ * @property schema - The schema as a type expression, such as `Booking[]`. `null` when the document gives none.
+ */
+export interface ApiContent {
+    readonly mediaType: string;
+    readonly schema: LinkedText | null;
+}
+/**
+ * The request body of an operation.
+ *
+ * @property required - Whether the body must be sent.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property content - Media types the body can have.
+ */
+export interface ApiRequestBody {
+    readonly required: boolean;
+    readonly descriptionHtml: string;
+    readonly content: readonly ApiContent[];
+}
+/**
+ * One response of an operation.
+ *
+ * @property status - Status code or range as the document writes it: `200`, `4XX`, `default`.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property content - Media types of the response body.
+ */
+export interface ApiResponse {
+    readonly status: string;
+    readonly descriptionHtml: string;
+    readonly content: readonly ApiContent[];
+}
+/**
+ * @brief One operation of an OpenAPI document: a method on a path, or a webhook.
+ *
+ * `name` is the method and the path, as in `GET /bookings/{id}`. Its
+ * parameters are its children.
+ *
+ * @property anchor - Unique within the document and safe in a URL hash.
+ * @property method - HTTP method in capitals.
+ * @property urlPath - Path template, such as `/bookings/{id}`. For a webhook, its name.
+ * @property operationId - `operationId` of the document, or `''`.
+ * @property tags - Tags the operation is listed under. A webhook without tags is listed under `Webhooks`.
+ * @property deprecated - Whether the document marks it deprecated.
+ * @property summary - One line of plain text, or `''`.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property requestBody - The request body, or `null`.
+ * @property responses - Responses, in the order of the document.
+ * @property security - The ways a caller can authenticate, each as the names of the security
+ *   schemes it needs, joined with ` + `. Empty when the operation is open.
+ */
+export interface OperationNode extends NodeBase<'operation'> {
+    readonly anchor: string;
+    readonly method: string;
+    readonly urlPath: string;
+    readonly operationId: string;
+    readonly tags: readonly string[];
+    readonly deprecated: boolean;
+    readonly summary: string;
+    readonly descriptionHtml: string;
+    readonly requestBody: ApiRequestBody | null;
+    readonly responses: readonly ApiResponse[];
+    readonly security: readonly string[];
+}
+/**
+ * @brief A named JSON Schema: the root schema of a file, an entry of its `$defs`, or
+ * an entry of `components.schemas` of an OpenAPI document.
+ *
+ * Its properties are its `field` children, nested ones under a dotted name such as `address.city`.
+ *
+ * @property anchor - Unique within the file and safe in a URL hash.
+ * @property type - What the schema allows, as a type expression: `object`, `string[]`, `Cat | Dog`. `null` when none is stated.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property constraints - Keywords that narrow the type, verbatim: `format: uuid`, `minimum: 0`.
+ * @property values - The values of an `enum` or a `const`, as JSON. Empty for every other schema.
+ * @property deprecated - Whether the document marks it deprecated.
+ */
+export interface DefinitionNode extends NodeBase<'definition'> {
+    readonly anchor: string;
+    readonly type: LinkedText | null;
+    readonly descriptionHtml: string;
+    readonly constraints: readonly string[];
+    readonly values: readonly string[];
+    readonly deprecated: boolean;
+}
+/**
+ * A foreign key of a table.
+ *
+ * @property name - Name of the constraint, or `''`.
+ * @property columns - Columns of this table, in key order.
+ * @property table - Name of the referenced table, as the statement writes it.
+ * @property target - The referenced table, when the scan has it, else `null`.
+ * @property referencedColumns - Columns of the referenced table, in key order. Its primary key when the statement names none.
+ * @property onDelete - Action in capitals, such as `CASCADE` or `SET NULL`. `''` when the statement states none.
+ * @property onUpdate - Action on update, in the same form as `onDelete`.
+ */
+export interface ForeignKey {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly table: string;
+    readonly target: NodeRef | null;
+    readonly referencedColumns: readonly string[];
+    readonly onDelete: string;
+    readonly onUpdate: string;
+}
+/**
+ * An index on a table.
+ *
+ * @property name - Name of the index.
+ * @property columns - Indexed columns or expressions, in index order.
+ * @property unique - Whether the index is unique.
+ */
+export interface TableIndex {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+}
+/**
+ * A table of a database schema. Its columns are its `field` children.
+ *
+ * @property anchor - Unique within the file and safe in a URL hash.
+ * @property line - Line of the file where the table is created.
+ * @property descriptionHtml - Description rendered as HTML.
+ * @property primaryKey - Columns of the primary key, in key order. Empty for a table without one.
+ * @property foreignKeys - Foreign keys of the table.
+ * @property indexes - Indexes on the table.
+ * @property constraints - Table constraints that are no key, verbatim: `UNIQUE (a, b)`, `CHECK (a < b)`.
+ * @property options - Table options in capitals: `WITHOUT ROWID`, `STRICT`, `VIRTUAL`.
+ */
+export interface TableNode extends NodeBase<'table'> {
+    readonly anchor: string;
+    readonly line: number;
+    readonly descriptionHtml: string;
+    readonly primaryKey: readonly string[];
+    readonly foreignKeys: readonly ForeignKey[];
+    readonly indexes: readonly TableIndex[];
+    readonly constraints: readonly string[];
+    readonly options: readonly string[];
+}
+/**
+ * @brief What running an entry of a query catalog does.
+ *
+ * - `read`: it returns rows and changes nothing, as `SELECT` does.
+ * - `write`: it changes rows or the schema, as `INSERT`, `UPDATE`, `DELETE` and `CREATE INDEX` do.
+ * - `control`: it changes the state of the transaction or the connection, as `BEGIN`, `COMMIT` and `PRAGMA` do.
+ */
+export type QueryEffect = 'read' | 'write' | 'control';
+/**
+ * A table an entry of a query catalog names, and what it does with it.
+ *
+ * @property name - Name of the table, as the statement writes it.
+ * @property target - The table, when the scan has it, else `null`.
+ * @property access - Whether the entry reads or writes it.
+ */
+export interface QueryTable {
+    readonly name: string;
+    readonly target: NodeRef | null;
+    readonly access: 'read' | 'write';
+}
+/**
+ * @brief One entry of a query catalog: the SQL of one `.sql` file, or of one named
+ * block of such a file.
+ *
+ * `name` is the name the code runs it by: the file name
+ * without `.sql`, or the name of the block. Its placeholders are its
+ * `parameter` children, and the columns of the rows it returns are its
+ * `field` children.
+ *
+ * @property anchor - Unique within the catalog and safe in a URL hash.
+ * @property sourcePath - Path of the file the entry is in, relative to the scanned root.
+ * @property line - Line of the file where the statement starts.
+ * @property effect - What running the entry does.
+ * @property verb - The keywords that open the statement, in capitals: `SELECT`, `INSERT`, `BEGIN IMMEDIATE`.
+ * @property descriptionHtml - The comment above the statement, as HTML. `''` for an entry without one.
+ * @property sqlHtml - The highlighted SQL, as the file writes it.
+ * @property tables - The tables the SQL names, each once per access, in the order they first appear.
+ */
+export interface QueryNode extends NodeBase<'query'> {
+    readonly anchor: string;
+    readonly sourcePath: string;
+    readonly line: number;
+    readonly effect: QueryEffect;
+    readonly verb: string;
+    readonly descriptionHtml: string;
+    readonly sqlHtml: string;
+    readonly tables: readonly QueryTable[];
+}
+/** Where a plan, a phase or a task stands, in the order task-manager moves it through. */
+export declare const TASK_STATUSES: readonly ['open', 'in-progress', 'in-review', 'completed', 'blocked'];
+/** One of {@link TASK_STATUSES}. */
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+/** How urgent a plan, a phase or a task is, most urgent first. */
+export declare const TASK_PRIORITIES: readonly ['critical', 'high', 'medium', 'low'];
+/** One of {@link TASK_PRIORITIES}. */
+export type TaskPriority = (typeof TASK_PRIORITIES)[number];
+/**
+ * What every plan, phase and task of the task tree states in its frontmatter.
+ *
+ * @property status - Where it stands.
+ * @property priority - How urgent it is.
+ * @property summary - One line of plain text.
+ * @property dependsOn - Names of the plans or phases, or ids of the tasks, this one waits for, as the file writes them.
+ */
+interface TrackedFacts {
+    readonly status: TaskStatus;
+    readonly priority: TaskPriority;
+    readonly summary: string;
+    readonly dependsOn: readonly string[];
+}
+/**
+ * @brief A plan of the task tree: `<plan>/<plan>.md`.
+ *
+ * Its phases are its children, and the decision log of its `decisions/` folder when it has one.
+ * `name` is the plan's folder name, `title` its title.
+ */
+export interface PlanNode extends NodeBase<'plan'>, FileFacts, TrackedFacts {
+}
+/**
+ * A phase of a plan: `<plan>/<phase>/<phase>.md`. Its tasks are its children.
+ *
+ * @property parallel - Whether its tasks can run side by side.
+ */
+export interface PhaseNode extends NodeBase<'phase'>, FileFacts, TrackedFacts {
+    readonly parallel: boolean;
+}
+/**
+ * One task of a phase: `<phase>/tasks/<id>.md`, shown as an entry on the page of its phase. `name` is its title.
+ *
+ * @property anchor - Unique within the phase and safe in a URL hash.
+ * @property id - Such as `TASK-006`.
+ * @property sourcePath - Path of the task file, relative to the scanned root.
+ * @property package - The package the task changes, as the file names it.
+ * @property complexity - From 1 for small to 5 for large. `null` when the file states none.
+ * @property html - Description rendered as HTML.
+ */
+export interface TaskNode extends NodeBase<'task'>, TrackedFacts {
+    readonly anchor: string;
+    readonly id: string;
+    readonly sourcePath: string;
+    readonly package: string;
+    readonly complexity: number | null;
+    readonly html: string;
+}
+/** A file node of any kind. */
+export type AnyFileNode = FileNode | ApiNode | DatabaseNode | PlanNode | PhaseNode;
+/** A node of any kind. */
+export type GraphNode = SectionNode | FolderNode | PackageNode | AnyFileNode | SourceNode | SymbolNode | TermNode | DecisionNode | OperationNode | DefinitionNode | TableNode | QueryNode | TaskNode | ParameterNode | FieldNode;
+/** An entry of any kind. */
+export type EntryNode = SymbolNode | TermNode | DecisionNode | OperationNode | DefinitionNode | TableNode | QueryNode | TaskNode;
+/**
+ * Tells a symbol node from the others.
+ *
+ * @param node - Node to test.
+ */
+export declare function isSymbolNode(node: GraphNode): node is SymbolNode;
+/**
+ * Tells an entry node, a symbol included, from the others.
+ *
+ * @param node - Node to test.
+ */
+export declare function isEntryNode(node: GraphNode): node is EntryNode;
+/**
+ * Tells a node of a file with a page from the others.
+ *
+ * @param node - Node to test.
+ */
+export declare function isFileNode(node: GraphNode): node is AnyFileNode;
+/** Kinds of an entry that is described in markdown and can have parameters or fields. */
+export type DescribedNode = SymbolNode | OperationNode | DefinitionNode | TableNode | QueryNode;
+/**
+ * Tells the entries with a `descriptionHtml` from the others.
+ *
+ * @param node - Node to test.
+ * @returns True for a symbol, an operation, a definition, a table and a query.
+ */
+export declare function isDescribedNode(node: GraphNode): node is DescribedNode;
+/** A relation other than `parent` between two nodes, such as a parameter that has a class as its type. */
+export type Edge = readonly [from: NodeRef, kind: EdgeKind, to: NodeRef];
+/**
+ * What the bundle says about its own making.
+ *
+ * @property title - Title of the site.
+ * @property generatedAt - ISO 8601 timestamp of the generation.
+ * @property generator - Name of the tool that made the bundle.
+ */
+export interface BundleMeta {
+    readonly title: string;
+    readonly generatedAt: string;
+    readonly generator: string;
+}
+/** Version of the layout of {@link SemanticIndex}. A reader skips an index of another version. */
+export declare const SEMANTIC_FORMAT = 3;
+/**
+ * @brief What a reader needs to search by meaning: a small text embedding model,
+ * one vector per searchable node and the words of each node.
+ *
+ * An **embedding** is a list of numbers that stands for the meaning of a text.
+ * Texts with a similar meaning get similar numbers, so `vessel` is found by a search for `ship`.
+ *
+ * The model is a table with one vector per word. A contextual model computed
+ * each vector in advance, from the word on its own. The vector of a text is
+ * the mean of the vectors of its words, computed by the reader without a neural network.
+ *
+ * @property format - Layout version, `SEMANTIC_FORMAT`.
+ * @property model - Name of the embedding model, for display.
+ * @property dimensions - Length of every vector.
+ * @property vocabulary - The words of the model, joined with `\n`. The line number of a word is its row in `vocabularyVectors`.
+ * @property vocabularyVectors - Base64 of the model table: one row of `dimensions` values per word, each value in four bits.
+ * @property nodes - The nodes that have a vector, in the order of `nodeVectors`.
+ * @property nodeVectors - Base64 of signed bytes: one vector of length 1 per node, scaled to the range of a signed byte.
+ * @property words - Every word that carries meaning in the name or the text of a node, each once, joined with `\n`.
+ * @property nodeWords - For each node of `nodes`, the words of its name and the further words of
+ *   its text, as line numbers in `words`. A one-word query is compared with
+ *   these words, because the mean of a whole text hides a single word.
+ */
+export interface SemanticIndex {
+    readonly format: typeof SEMANTIC_FORMAT;
+    readonly model: string;
+    readonly dimensions: number;
+    readonly vocabulary: string;
+    readonly vocabularyVectors: string;
+    readonly nodes: readonly NodeRef[];
+    readonly nodeVectors: string;
+    readonly words: string;
+    readonly nodeWords: readonly (readonly [name: readonly number[], text: readonly number[]])[];
+}
+/**
+ * @brief The data contract between the scanner and the web app: the CLI serializes
+ * one bundle into the generated HTML file, and the app reads it back.
+ *
+ * The bundle is a graph. A **node** is one thing the site shows: a folder, a
+ * skill, a document, a class, a parameter, a glossary term, an API operation,
+ * a database table, a query. `parent` puts every node in one tree, and that
+ * tree is the navigation. An **edge** is any other relation between two nodes,
+ * such as "this parameter has that class as its type".
+ *
+ * @property meta - What the bundle says about its making.
+ * @property nodes - Every node. A node comes after its parent, and siblings are in display order.
+ * @property edges - Relations other than `parent`.
+ * @property semantic - Index for search by meaning. Left out when the site was generated without embeddings.
+ */
+export interface DocsBundle {
+    readonly meta: BundleMeta;
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly Edge[];
+    readonly semantic?: SemanticIndex;
+}
+/**
+ * Where a node is shown: a page, and for an entry an anchor on that page.
+ *
+ * @property path - Slugs from the section down, joined with `/` and not URL-encoded: `code/src/app.ts`.
+ * @property hash - Anchor of the entry on that page, without `#`. Set for an entry only.
+ */
+export interface Route {
+    readonly path: string;
+    readonly hash?: string;
+}
+/**
+ * The part of a node that decides its route.
+ *
+ * @property kind - Kind of the node.
+ * @property name - Name of the node.
+ * @property parent - The node this one belongs to, or `null` for a section.
+ * @property slug - Segment of the route. Defaults to `name`.
+ * @property anchor - Anchor of an entry, which its route turns into the hash.
+ */
+export interface Routable {
+    readonly kind: NodeType;
+    readonly name: string;
+    readonly parent: NodeRef | null;
+    readonly slug?: string;
+    readonly anchor?: string;
+}
+/**
+ * @brief DOM id and URL hash of an entry on the page of its file.
+ *
+ * Examples: `symbol:App.run`, `term:lane`, `decision:3-use-hash-routes`,
+ * `table:Booking`, `query:list_bookings`. The kind is the prefix, so entry
+ * anchors never equal a heading anchor.
+ *
+ * @param kind - Kind of the entry, such as `symbol` or `term`.
+ * @param anchor - Anchor of the entry, unique within its file.
+ */
+export declare function entryAnchor(kind: EntryKind, anchor: string): string;
+/**
+ * @brief Route of a node.
+ *
+ * Sections, folders and files are pages. An entry is an anchor on the page of
+ * its file, and a parameter or field shares the route of its symbol. The
+ * scanner and the web app both use this function.
+ *
+ * @param nodes - Nodes the route is read from, usually the nodes of a bundle.
+ * @param ref - Index of the node in `nodes`.
+ * @returns The page path, and the hash for an entry.
+ */
+export declare function routeOf(nodes: readonly Routable[], ref: NodeRef): Route;
+/**
+ * Link to a route from inside the generated page: `#/code/src/app.ts#symbol:App.run`.
+ *
+ * @param route - Route to link to.
+ * @returns The hash link to the route.
+ */
+export declare function hrefOf(route: Route): string;
+/** Id of the `<script type="application/json">` element that holds the bundle. */
+export declare const DATA_ELEMENT_ID = "analyze-data";
+/** Id of the element the app mounts into. */
+export declare const MOUNT_ELEMENT_ID = "analyze-root";
+/** `localStorage` key of the reader's color mode. The template reads it before first paint. */
+export declare const COLOR_MODE_STORAGE_KEY = "analyze:color-mode";
+/** Template marker the CLI replaces with the serialized bundle. */
+export declare const DATA_PLACEHOLDER = "__ANALYZE_DATA__";
+/** Template marker the CLI replaces with the title of the site. */
+export declare const TITLE_PLACEHOLDER = "__ANALYZE_TITLE__";