@g3nomaly/analyze 0.1.0 → 0.1.1

package/dist/scanner/glossary/terms.d.ts

@@ -1,47 +1,64 @@
 import type { NodeRef } from '../../model';
 import type { GraphBuilder } from '../graph/builder';
-/** A glossary term found in a run of prose. */
+/**
+ * @brief A glossary term found in a run of prose.
+ *
+ * @property start - Offset where the term starts in the text.
+ * @property end - Offset where the term ends in the text.
+ * @property href - In-site href of the term's entry.
+ * @property title - The definition as plain text, for a tooltip.
+ */
 export interface TermMatch {
-    /** Offsets of the term in the text. */
     readonly start: number;
     readonly end: number;
-    /** In-site href of the term's entry. */
     readonly href: string;
-    /** The definition as plain text, for a tooltip. */
     readonly title: string;
 }
-/** Finds the glossary terms of one piece of prose. */
+/**
+ * @brief Finds the glossary terms of one piece of prose.
+ *
+ * @param text - Plain prose to search.
+ * @returns The matches in text order.
+ */
 export type TermFinder = (text: string) => TermMatch[];
-/** One definition of a term in the index. */
+/**
+ * @brief One definition of a term in the index.
+ *
+ * @property ref - Node of the term's entry.
+ * @property path - Path of the glossary file that defines the term.
+ * @property summary - The definition as plain text.
+ */
 interface TermEntry {
     readonly ref: NodeRef;
-    /** Path of the glossary file that defines the term. */
     readonly path: string;
     readonly summary: string;
 }
 /**
- * Every term of every glossary of the scan, by name, and finds uses of them
- * in text.
+ * @brief Every term of every glossary of the scan, by name, and finds uses of them in text.
+ *
+ * Holds the definitions of each term, keyed by its lowercased name, and one regex that matches any
+ * term. Created once per scan by `RepositoryScanner`, filled by `GlossaryPlanner` and read by
+ * `TermLinker`. Created with `new TermIndex()`.
  *
- * Holds the definitions of each term, keyed by its lowercased name, and one
- * regex that matches any term. Created once per scan by `RepositoryScanner`,
- * filled by `GlossaryPlanner` and read by `TermLinker`.
+ * @property byName - Definitions of each term, keyed by its normalized name.
+ * @property pattern - Matches any term. `null` until built, and reset when a term is added.
  */
 export declare class TermIndex {
     private readonly byName;
-    /** Matches any term. Rebuilt after a term is added. */
     private pattern;
     /**
-     * Adds a term.
+     * @brief Adds a term.
      *
      * @param name - The term as the glossary writes it.
+     * @param ref - Node of the term's entry.
      * @param path - Path of the glossary file, as the site shows it.
      * @param summary - The definition as plain text.
      */
     register(name: string, ref: NodeRef, path: string, summary: string): void;
     /**
-     * Finds every use of a term in a text. Case is ignored and a plural ending
-     * is allowed. Where two terms overlap, the longer one wins.
+     * @brief Finds every use of a term in a text.
+     *
+     * Case is ignored and a plural ending is allowed. Where two terms overlap, the longer one wins.
      *
      * @param text - Plain prose.
      * @param path - Path of the file the prose is in, or `null`. Chooses between glossaries that define the same term.
@@ -52,30 +69,43 @@ export declare class TermIndex {
         end: number;
         term: TermEntry;
     }[];
-    /** Builds one regex that matches any term, longest first, with an optional plural ending. */
+    /**
+     * @brief Builds one regex that matches any term, longest first, with an optional plural ending.
+     *
+     * @returns The regex.
+     */
     private buildPattern;
     /**
-     * Finds the definition a written term names. The glossary closest to the
-     * file wins when several define the term.
+     * @brief Finds the definition a written term names. The glossary closest to the file wins when
+     * several define the term.
+     *
+     * @param written - The term as the prose writes it.
+     * @param path - Path of the file the prose is in, or `null`.
+     * @returns The definition, or `null` when none matches.
      */
     private resolve;
 }
 /**
- * Turns the glossary terms in prose into links to their entries, and records each use as an edge.
+ * @brief Turns the glossary terms in prose into links to their entries, and records each use as an edge.
  *
- * Holds the `TermIndex` and the graph. Created once per scan by
- * `RepositoryScanner` and handed to `ProseResolvers`, which asks it for a
- * finder per piece of prose.
+ * Holds the `TermIndex` and the graph. Created once per scan by `RepositoryScanner` and handed to
+ * `ProseResolvers`, which asks it for a finder per piece of prose.
  */
 export declare class TermLinker {
     private readonly index;
     private readonly graph;
-    /** Creates a linker that reads `index` and records edges in `graph`. */
+    /**
+     * Creates a linker that reads `index` and records edges in `graph`.
+     *
+     * @param index - The terms the prose is searched for.
+     * @param graph - Graph the `uses` edges are added to.
+     */
     constructor(index: TermIndex, graph: GraphBuilder);
     /**
-     * Creates the finder for one piece of prose, such as a page or a
-     * description. The finder links each term once, at its first use, and
-     * records a `uses` edge from the owner to the term.
+     * @brief Creates the finder for one piece of prose, such as a page or a description.
+     *
+     * The finder links each term once, at its first use, and records a `uses` edge from the owner to
+     * the term.
      *
      * @param from - Node that owns the prose.
      * @param path - Path of the file the prose is in, or `null` when it has none.

package/dist/scanner/graph/builder.d.ts

@@ -1,49 +1,108 @@
-import { type Edge, type EdgeKind, type GraphNode, type NodeKind, type NodeRef } from '../../model';
+import { type Edge, type EdgeKind, type GraphNode, type NodeType, type NodeRef } from '../../model';
+import type { PackageInfo } from '../packages';
 /** The fields of a node that fix its place in the tree and its route. Known when the node is added. */
 type IdentityKey = 'kind' | 'name' | 'parent' | 'slug' | 'anchor';
 /** The node types whose `kind` can be `K`. */
-type NodeOf<K extends NodeKind, N = GraphNode> = N extends GraphNode ? (K extends N['kind'] ? N : never) : never;
+type NodeOf<K extends NodeType, N = GraphNode> = N extends GraphNode ? (K extends N['kind'] ? N : never) : never;
 /** The identity fields of a node of kind `K`, as `add` takes them. */
-export type IdentityOf<K extends NodeKind> = Omit<Pick<NodeOf<K>, Extract<keyof NodeOf<K>, IdentityKey>>, 'kind'>;
+export type IdentityOf<K extends NodeType> = Omit<Pick<NodeOf<K>, Extract<keyof NodeOf<K>, IdentityKey>>, 'kind'>;
 /** The fields of a node of kind `K` that its `ContentSource` produces. */
-export type ContentOf<K extends NodeKind> = Omit<NodeOf<K>, IdentityKey>;
-/** Produces the rest of a node. Runs in `build`, when every node has its place, so it can link to any of them. */
-export type ContentSource<K extends NodeKind> = (self: NodeRef) => ContentOf<K> | Promise<ContentOf<K>>;
+export type ContentOf<K extends NodeType> = Omit<NodeOf<K>, IdentityKey>;
 /**
- * Builds the graph in two passes.
+ * @brief Produces the rest of a node. Runs in `build`, when every node has its place, so it can link to any of them.
+ *
+ * @param self - Ref of the node being built, which the source may link from.
+ * @returns The fields of the node that its identity does not hold.
+ */
+export type ContentSource<K extends NodeType> = (self: NodeRef) => ContentOf<K> | Promise<ContentOf<K>>;
+/**
+ * @brief Builds the graph in two passes.
  *
  * 1. The scanners `add` every node: its kind, name and parent. That fixes the
  *    tree, the routes and the refs.
  * 2. `build` requests the content of every node. By then a link from any node to
  *    any other can be resolved.
  *
- * Holds the identity and content source of every node, the edges, the folder
- * nodes by path and the file nodes by path. A node's `NodeRef` is its index.
- * Created once per scan by `RepositoryScanner`, which calls `build` at the end;
- * every planner (`code/`, `sql/`, `docs`, `skills/`, `tasks/`, `glossary/`,
- * `decisions/`, `schema/`, `openapi/`) and `ProseResolvers` add nodes and edges to it.
+ * A node's `NodeRef` is its index. Created once per scan by `RepositoryScanner`,
+ * which calls `build` at the end; every planner (`code/`, `sql/`, `docs`,
+ * `skills/`, `tasks/`, `glossary/`, `decisions/`, `schema/`, `openapi/`) and
+ * `ProseResolvers` add nodes and edges to it.
+ *
+ * @property identities - Routable identity of each node, by `NodeRef`. Together with `contents` it makes the node.
+ * @property contents - Content source of each node by `NodeRef`, or `null` for a node that has none.
+ * @property edges - Edges by `from:kind:to`, so an edge recorded twice is kept once.
+ * @property folders - Folder nodes by `parent/name`.
+ * @property files - File nodes by normalized path.
+ * @property packages - Packages by display path of their directory, set by `markPackages`.
+ * @property packageSections - Sections whose folders become `package` nodes where a package sits.
+ * @example
+ * const graph = new GraphBuilder();
  */
 export declare class GraphBuilder {
-    /** `identities[ref]` and `contents[ref]` together make the node at `ref`. */
     private readonly identities;
     private readonly contents;
     private readonly edges;
     private readonly folders;
     private readonly files;
-    /** Adds a node. Kinds without content of their own, such as folders, take no `content`. */
-    add<K extends NodeKind>(kind: K, identity: IdentityOf<K>, ...content: Record<never, never> extends ContentOf<K> ? [] : [ContentSource<K>]): NodeRef;
-    /** The folder at `directory` below `parent`, created with its ancestors on first use. `''` is `parent` itself. */
+    private packages;
+    private readonly packageSections;
+    /**
+     * @brief Adds a node. Kinds without content of their own, such as folders, take no `content`.
+     *
+     * @param identity - Fields that place the node: its name and parent, plus the slug or anchor of kinds that have them.
+     * @param content - Source of the rest of the node. Omitted for a kind without content.
+     * @returns Ref of the new node.
+     */
+    add<K extends NodeType>(kind: K, identity: IdentityOf<K>, ...content: Record<never, never> extends ContentOf<K> ? [] : [ContentSource<K>]): NodeRef;
+    /**
+     * @brief Makes `folder` create a `package` node instead of a folder for every package directory below the given sections.
+     *
+     * @param sections - Sections whose `folder` paths are display paths of the repository, such as the code and docs sections.
+     * @param packages - Packages by display path of their directory, as `detectPackages` returns them.
+     */
+    markPackages(sections: readonly NodeRef[], packages: ReadonlyMap<string, PackageInfo>): void;
+    /**
+     * @brief Finds the folder at `directory` below `parent`, creating it and its ancestors on first use.
+     *
+     * Below a section passed to `markPackages`, a directory that holds a package becomes a `package` node.
+     *
+     * @param parent - Node the directory is below.
+     * @param directory - Slash-separated path, such as `docs/guides`. `''` names `parent` itself.
+     * @returns Ref of the folder at the end of the path.
+     */
     folder(parent: NodeRef, directory: string): NodeRef;
-    /** Records which node shows the file at `path`, so links to that file can find it. */
+    /**
+     * @brief Records which node shows the file at `path`, so links to that file can find it.
+     *
+     * @param path - Display path of the file, as `DocFile.displayPath` gives it. Normalized before storing.
+     * @param ref - Node that shows the file.
+     */
     registerFile(path: string, ref: NodeRef): void;
-    /** Finds the node registered for the file at `path`, or `undefined`. */
+    /**
+     * @brief Finds the node registered for the file at `path`.
+     *
+     * @param path - Display path of the file, as passed to `registerFile`.
+     * @returns The node, or `undefined` when no file is registered at that path.
+     */
     fileAt(path: string): NodeRef | undefined;
-    /** In-site href of a node. `fragment` replaces the node's own anchor, for a heading on a page. */
+    /**
+     * @brief Builds the in-site href of a node.
+     *
+     * @param ref - Node to link to.
+     * @param fragment - Replaces the node's own anchor, for a heading on a page.
+     * @returns The href, relative to the site root.
+     */
     href(ref: NodeRef, fragment?: string): string;
-    /** Records an edge. The same edge recorded twice is kept once. */
+    /**
+     * @brief Records an edge. The same edge recorded twice is kept once.
+     *
+     * @param from - Node the edge starts at.
+     * @param kind - Relation the edge expresses.
+     * @param to - Node the edge ends at.
+     */
     link(from: NodeRef, kind: EdgeKind, to: NodeRef): void;
     /**
-     * Runs the content source of every node and returns the finished graph.
+     * @brief Runs the content source of every node and returns the finished graph.
      *
      * @returns Nodes in `NodeRef` order, and edges sorted by source, kind (in `EDGE_KINDS` order) and target.
      */

package/dist/scanner/highlight.d.ts

@@ -1,15 +1,25 @@
 import type { Element } from 'hast';
-/** Highlights code of a language into HTML or into a HAST `<pre>` element. */
+/**
+ * @brief Highlights code of a language into HTML or into a HAST `<pre>` element.
+ *
+ * @property toHtml - Highlights code into an HTML string.
+ * @property toHast - Highlights code into the HAST `<pre>` element shiki produces.
+ */
 export interface CodeHighlighter {
     toHtml(code: string, language: string): Promise<string>;
     toHast(code: string, language: string): Promise<Element>;
 }
 /**
- * Highlights with shiki. Colors are emitted as `var(--syntax-*)` references,
- * so the page stylesheet owns the palette in light and dark mode. Holds one
- * shiki highlighter, created on first use, and loads each language once; an
- * unknown language falls back to plain text. Created in `api/services.ts` and
- * passed to `RepositoryScanner`, which hands it to the renderers and planners.
+ * @brief Highlights with shiki. Colors are emitted as `var(--syntax-*)` references,
+ * so the page stylesheet owns the palette in light and dark mode. Loads each
+ * language once; an unknown language falls back to plain text. Created in
+ * `api/services.ts` and passed to `RepositoryScanner`, which hands it to the
+ * renderers and planners.
+ *
+ * @property highlighter - The shiki highlighter, created on first use. `null` until then.
+ * @property loading - Pending load of each language by name, shared between callers.
+ * @example
+ * const highlighter = new ShikiHighlighter();
  */
 export declare class ShikiHighlighter implements CodeHighlighter {
     private highlighter;
@@ -19,13 +29,26 @@ export declare class ShikiHighlighter implements CodeHighlighter {
     /** Highlights code into the HAST `<pre>` element shiki produces. */
     toHast(code: string, language: string): Promise<Element>;
     /**
-     * Creates the shiki highlighter on first use and loads a language.
+     * @brief Creates the shiki highlighter on first use and loads a language.
      *
+     * @param language - Language name as the code block gives it, in any case.
      * @returns The highlighter and the language name to pass to it: the lowercased `language`, or `text` when shiki lacks it.
      */
     private prepare;
-    /** Loads a language once, sharing the pending load between callers. */
+    /**
+     * @brief Loads a language once, sharing the pending load between callers.
+     *
+     * @param highlighter - The shiki highlighter the language is loaded into.
+     * @param language - Lowercased language name.
+     * @returns The name to highlight with: `language`, or `text` when it cannot be loaded.
+     */
     private resolveLanguage;
-    /** Loads a bundled language into shiki, or returns `text` when it is not bundled or fails to load. */
+    /**
+     * @brief Loads a bundled language into shiki, or returns `text` when it is not bundled or fails to load.
+     *
+     * @param highlighter - The shiki highlighter the language is loaded into.
+     * @param language - Lowercased language name.
+     * @returns The language name, or `text`.
+     */
     private load;
 }

package/dist/scanner/ignore.d.ts

@@ -0,0 +1,25 @@
+/** Name of the file at the root of a repository that lists what analyze skips. */
+export declare const IGNORE_FILE = ".analyzeignore";
+/** Lines of the `.analyzeignore` that analyze writes when a repository has none. */
+export declare const DEFAULT_IGNORE_LINES: readonly string[];
+/**
+ * @brief Turns the lines of an ignore file into globs that `Bun.Glob` matches against root-relative paths.
+ *
+ * A pattern without a slash matches at any depth, a leading `/` anchors it to the root, and a
+ * trailing `/` matches a directory. A pattern without a trailing `/` matches a file or a directory.
+ * Blank lines and `#` comments are skipped. Negation with `!` is not supported, so such a line is skipped too.
+ *
+ * @param text - Contents of the ignore file.
+ * @returns Globs, two per pattern that may name a file or a directory. `dist/` gives one: any `dist` directory and all below it.
+ */
+export declare function ignoreGlobs(text: string): string[];
+/**
+ * @brief Reads the `.analyzeignore` of a repository, and writes one with {@link DEFAULT_IGNORE_LINES} when it has none.
+ *
+ * @param repo - Absolute path of the repository.
+ * @returns The globs of the file, and whether this call created the file.
+ */
+export declare function loadIgnoreFile(repo: string): {
+    globs: string[];
+    created: boolean;
+};

package/dist/scanner/index.d.ts

@@ -8,8 +8,10 @@ export { CallableIndex, PROSE_SCOPE, TypeIndex, TypeLinker, type TypeScope } fro
 export { FileRenderer, type RenderedFile } from './content';
 export { type ParsedDecision, type ParsedDecisions, parseDecisions } from './decisions/parse';
 export { DecisionPlanner } from './decisions/planner';
-export { type DocFile, type DocKind, DocPlanner, docKind } from './docs';
-export { compareTreePaths, DEFAULT_EXCLUDES, type FileLister, RepoFileLister, type Source } from './files';
+export { ConfigPlanner } from './config';
+export { addFilePage, type DocFile, type DocKind, DocPlanner, docKind } from './docs';
+export { compareTreePaths, type FileLister, RepoFileLister, type Source } from './files';
+export { DEFAULT_IGNORE_LINES, IGNORE_FILE, ignoreGlobs, loadIgnoreFile } from './ignore';
 export { type ParsedGlossary, type ParsedTerm, parseGlossary } from './glossary/parse';
 export { GlossaryPlanner } from './glossary/planner';
 export { type TermFinder, TermIndex, TermLinker, type TermMatch } from './glossary/terms';
@@ -19,6 +21,7 @@ export { type LinkOrigin, ProseResolvers } from './markdown/links';
 export { joinLines, type MarkdownLine, outlineLines, plainText } from './markdown/outline';
 export { type LinkResolver, MarkdownRenderer, type RenderedMarkdown } from './markdown/renderer';
 export { OpenApiPlanner } from './openapi/planner';
+export { detectPackages, type PackageInfo } from './packages';
 export { type Reporter, silentReporter } from './reporter';
 export { RepositoryScanner, type ScanInput, type ScannerOptions } from './scanner';
 export { type DefinitionOwner, DefinitionPlanner } from './schema/definitions';

package/dist/scanner/markdown/frontmatter.d.ts

@@ -1,9 +1,24 @@
-/** A markdown document split into its YAML frontmatter and the rest. */
+/**
+ * @brief A markdown document split into its YAML frontmatter and the rest.
+ *
+ * @property data - Parsed frontmatter fields. `{}` when there is no valid frontmatter.
+ * @property body - The markdown after the frontmatter block, as written.
+ */
 export interface Frontmatter {
     readonly data: Readonly<Record<string, unknown>>;
     readonly body: string;
 }
-/** Splits a leading YAML block from a markdown document. Invalid YAML yields empty data. */
+/**
+ * @brief Splits a leading YAML block from a markdown document. Invalid YAML yields empty data.
+ *
+ * @param source - Markdown text, with or without frontmatter.
+ * @returns The parsed frontmatter and the text after it.
+ */
 export declare function splitFrontmatter(source: string): Frontmatter;
-/** Reads a frontmatter field as trimmed text, or `null` when it is missing, blank or no string. */
+/**
+ * @brief Reads a frontmatter field as trimmed text, or `null` when it is missing, blank or no string.
+ *
+ * @param data - Parsed frontmatter, as `Frontmatter.data` holds it.
+ * @param key - Name of the field, such as `title`.
+ */
 export declare function stringField(data: Readonly<Record<string, unknown>>, key: string): string | null;

package/dist/scanner/markdown/links.d.ts

@@ -3,19 +3,22 @@ import { type TypeLinker, type TypeScope } from '../code/types';
 import type { TermLinker } from '../glossary/terms';
 import type { GraphBuilder } from '../graph/builder';
 import type { LinkResolver } from './renderer';
-/** The markdown file whose links are resolved. */
+/**
+ * @brief The markdown file whose links are resolved.
+ *
+ * @property node - The node that shows the text. Edges start here.
+ * @property root - Absolute directory `path` is relative to.
+ * @property path - Path of the file inside `root`.
+ * @property prefix - Prefix the bundle puts in front of paths from `root`.
+ */
 export interface LinkOrigin {
-    /** The node that shows the text. Edges start here. */
     readonly node: NodeRef;
-    /** Absolute directory `path` is relative to. */
     readonly root: string;
-    /** Path of the file inside `root`. */
     readonly path: string;
-    /** Prefix the bundle puts in front of paths from `root`. */
     readonly prefix: string;
 }
 /**
- * Creates the link resolver for each piece of markdown of a scan. One place
+ * @brief Creates the link resolver for each piece of markdown of a scan. One place
  * decides what prose can link to: files, types, functions and glossary terms.
  *
  * Holds the graph, the type linker and the term linker. Created once per scan
@@ -28,17 +31,24 @@ export declare class ProseResolvers {
     private readonly graph;
     private readonly linker;
     private readonly terms;
-    /** Creates the resolver factory. */
+    /**
+     * @brief Creates the resolver factory.
+     *
+     * @param graph - Receives the edges that resolved references record.
+     * @param linker - Links type and function names in inline code.
+     * @param terms - Links glossary terms in prose.
+     */
     constructor(graph: GraphBuilder, linker: TypeLinker, terms: TermLinker);
     /**
-     * Resolver for markdown that comes from a file: a page, a term, a decision.
+     * @brief Makes the resolver for markdown that comes from a file: a page, a term, a decision.
      *
+     * @param origin - The file the markdown is in.
      * @param relation - Kind of the edge a link to a file, type or function records.
      * @returns A resolver for one render of that text.
      */
     forFile(origin: LinkOrigin, relation?: EdgeKind): LinkResolver;
     /**
-     * Resolver for the description of a symbol, parameter or field. A doc
+     * @brief Makes the resolver for the description of a symbol, parameter or field. A doc
      * comment has no links to files, so only inline code and terms resolve.
      *
      * @param from - Node the description belongs to.

package/dist/scanner/markdown/outline.d.ts

@@ -1,27 +1,35 @@
-/** One line of a markdown text. */
+/**
+ * @brief One line of a markdown text.
+ *
+ * @property text - The line as written, without its line break.
+ * @property heading - Depth and plain text of the line when it is an ATX heading such as `## Terms`. `null` otherwise.
+ */
 export interface MarkdownLine {
     readonly text: string;
-    /** Set when the line is an ATX heading such as `## Terms`. */
     readonly heading: {
         readonly depth: number;
         readonly text: string;
     } | null;
 }
 /**
- * Splits markdown into lines and marks the headings. A `#` line inside a
+ * @brief Splits markdown into lines and marks the headings. A `#` line inside a
  * fenced code block is code, not a heading.
  *
  * @param markdown - Markdown text without frontmatter.
+ * @returns One entry per line, in order.
  */
 export declare function outlineLines(markdown: string): MarkdownLine[];
 /**
- * Removes inline markdown markers from a short text such as a heading.
+ * @brief Removes inline markdown markers from a short text such as a heading.
  *
  * @param markdown - Inline markdown, for example `**Lane** (_route_)`.
  * @returns The text a reader sees, for example `Lane (route)`.
  */
 export declare function plainText(markdown: string): string;
 /**
- * Joins lines back into markdown and drops blank lines at both ends.
+ * @brief Joins lines back into markdown and drops blank lines at both ends.
+ *
+ * @param lines - Lines to join, in order.
+ * @returns The markdown text, with no blank lines at either end.
  */
 export declare function joinLines(lines: readonly MarkdownLine[]): string;

package/dist/scanner/markdown/renderer.d.ts

@@ -1,44 +1,63 @@
 import type { Heading } from '../../model';
 import type { TermMatch } from '../glossary/terms';
 import type { CodeHighlighter } from '../highlight';
-/** Turns what one document refers to into links inside the site. */
+/**
+ * @brief Turns what one document refers to into links inside the site.
+ *
+ * @property link - In-site href for a relative link, or `null` when it points outside the bundle.
+ * @property image - `data:` URI for a relative image, or `null` when it cannot be embedded.
+ * @property code - In-site href for inline code that names something in the bundle, such as a class. Optional.
+ * @property terms - The glossary terms in one run of prose that should become links. Optional.
+ */
 export interface LinkResolver {
-    /** In-site href for a relative link, or `null` when it points outside the bundle. */
     link(href: string): string | null;
-    /** `data:` URI for a relative image, or `null` when it cannot be embedded. */
     image(src: string): Promise<string | null>;
-    /** In-site href for inline code that names something in the bundle, such as a class. */
     code?(text: string): string | null;
-    /** The glossary terms in one run of prose that should become links. */
     terms?(text: string): TermMatch[];
 }
-/** The HTML of a markdown text, with its headings and title. */
+/**
+ * @brief The HTML of a markdown text, with its headings and title.
+ *
+ * @property html - The rendered HTML.
+ * @property headings - Headings of depth 2 and 3 that have an id, in document order.
+ * @property title - Text of the first level-1 heading, or `null` when there is none.
+ */
 export interface RenderedMarkdown {
     readonly html: string;
     readonly headings: Heading[];
-    /** Text of the first level-1 heading. */
     readonly title: string | null;
 }
 /**
- * Markdown to HTML. Raw HTML in the source is dropped, so the output is safe
+ * @brief Markdown to HTML. Raw HTML in the source is dropped, so the output is safe
  * to inject into the generated page. Code blocks are highlighted, and links,
  * images, inline code and glossary terms are resolved through a `LinkResolver`.
  *
- * Holds only the code highlighter. Created once per scan by
- * `RepositoryScanner` and used by `FileRenderer` and the planners in
+ * Holds only the code highlighter. Created once by the constructor of
+ * `RepositoryScanner`, and used by `FileRenderer` and the planners in
  * `code/`, `sql/`, `schema/`, `openapi/`, `glossary/`, `decisions/` and `tasks/`.
+ *
+ * @example
+ * const renderer = new MarkdownRenderer(new ShikiHighlighter());
  */
 export declare class MarkdownRenderer {
     private readonly highlighter;
-    /** Creates a renderer that highlights code blocks with `highlighter`. */
+    /**
+     * @brief Creates a renderer that highlights code blocks.
+     *
+     * @param highlighter - Highlights the code blocks of the markdown.
+     */
     constructor(highlighter: CodeHighlighter);
     /**
-     * Renders markdown to HTML.
+     * @brief Renders markdown to HTML.
      *
      * @param resolver - Resolves links, images, inline code and terms. Without one, relative links lose their href and relative images become their alt text.
      * @returns The HTML, the level-2 and level-3 headings, and the text of the first level-1 heading as title.
      */
     render(markdown: string, resolver?: LinkResolver): Promise<RenderedMarkdown>;
-    /** Replaces the content of every `<pre><code>` block with highlighted HTML. */
+    /**
+     * @brief Replaces the content of every `<pre><code>` block with highlighted HTML.
+     *
+     * @param tree - The hast tree, changed in place.
+     */
     private highlightCode;
 }