@g3nomaly/analyze 0.1.0 → 0.1.1

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

@@ -1,66 +1,84 @@
 import type { EdgeKind, LinkedText, NodeRef } from '../../model';
 import type { GraphBuilder } from '../graph/builder';
-/** Where a type name is used. Decides which declaration it means. */
+/**
+ * @brief Where a type name is used. Decides which declaration it means.
+ *
+ * @property path - Display path of the file the name is in. `null` for a name in prose, which has no file of its own.
+ * @property family - Language family of the name. `null` matches every language.
+ * @property typeParameters - Type parameters in scope, such as `T`. They are never linked.
+ */
 export interface TypeScope {
-    /** Display path of the file the name is in. `null` for a name in prose, which has no file of its own. */
     readonly path: string | null;
-    /** Language family of the name. `null` matches every language. */
     readonly family: string | null;
-    /** Type parameters in scope, such as `T`. They are never linked. */
     readonly typeParameters: ReadonlySet<string>;
 }
 /** Scope of a name in a document: any language, no file. */
 export declare const PROSE_SCOPE: TypeScope;
 /**
- * Every class, interface, struct, enum, trait and type alias of the scan, by name.
+ * @brief Every class, interface, struct, enum, trait and type alias of the scan, by name.
  *
  * Holds every declaration of each name. Created per scan by `RepositoryScanner` in
  * `scanner/scanner.ts`; `SymbolPlanner` in `symbols.ts` registers each type it adds,
- * and {@link TypeLinker} resolves names against it.
+ * and {@link TypeLinker} resolves names against it. Created with `new TypeIndex()`.
+ *
+ * @property byName - Declarations of each name.
  */
 export declare class TypeIndex {
     private readonly byName;
     /**
-     * Adds a type declaration under its name.
+     * @brief Adds a type declaration under its name.
      *
+     * @param name - Name the type is declared with.
+     * @param ref - Node of the declaration.
      * @param path - Display path of the file that declares it.
      * @param family - Language family of that file, from `familyOf`.
      */
     register(name: string, ref: NodeRef, path: string, family: string): void;
     /**
-     * The declaration a name refers to, or `null` when there is none or the name is ambiguous.
+     * @brief The declaration a name refers to, or `null` when there is none or the name is ambiguous.
+     *
      * A declaration in the same file wins, then the one whose directory is closest.
+     *
+     * @param name - Identifier to resolve.
+     * @param scope - Where the name is used.
+     * @returns The node of the declaration, or `null`.
      */
     resolve(name: string, scope: TypeScope): NodeRef | null;
 }
 /**
- * Every function and method of the scan, by name and by `Owner.name`. Lets
+ * @brief Every function and method of the scan, by name and by `Owner.name`. Lets
  * prose refer to a function the way it refers to a type.
  *
  * Holds every declaration of each key. Created per scan by `RepositoryScanner` in
  * `scanner/scanner.ts`; `SymbolPlanner` in `symbols.ts` registers each function and
  * method it adds, and {@link TypeLinker.mention} resolves inline code against it.
+ * Created with `new CallableIndex()`.
+ *
+ * @property byName - Declarations of each key: the name, and `Owner.name` for a method.
  */
 export declare class CallableIndex {
     private readonly byName;
     /**
-     * Adds a function or method under its name and, when it has an owner, under `Owner.name`.
+     * @brief Adds a function or method under its name and, when it has an owner, under `Owner.name`.
      *
+     * @param name - Name the function is declared with.
      * @param owner - Name of the type or namespace it is declared in, or `null`.
+     * @param ref - Node of the declaration.
      * @param path - Display path of its file.
      * @param family - Language family of its file, from `familyOf`.
      */
     register(name: string, owner: string | null, ref: NodeRef, path: string, family: string): void;
     /**
-     * The function a piece of inline code names.
+     * @brief The function a piece of inline code names.
      *
      * @param text - Inline code, such as `choose_route()` or `Invoice.add`.
+     * @param scope - Where the code is used.
      * @returns The function, or `null` when the text names none or more than one.
      */
     resolve(text: string, scope: TypeScope): NodeRef | null;
 }
 /**
- * Turns type names in source text into links between nodes, and records each link as an edge.
+ * @brief Turns type names in source text into links between nodes, and records each link as an edge.
  *
  * Holds the type and callable indexes it resolves names against and the graph it adds
  * edges to. Created per scan by `RepositoryScanner` in `scanner/scanner.ts`; used by
@@ -75,18 +93,33 @@ export declare class TypeLinker {
     private readonly index;
     private readonly callables;
     private readonly graph;
-    /** Takes the indexes it resolves names against and the graph it adds edges to. */
+    /**
+     * Takes the indexes it resolves names against and the graph it adds edges to.
+     *
+     * @param index - Type declarations the names resolve against.
+     * @param callables - Functions and methods the inline code resolves against.
+     * @param graph - Graph the edges are added to.
+     */
     constructor(index: TypeIndex, callables: CallableIndex, graph: GraphBuilder);
     /**
-     * Links every known type name in `text`, such as `Booking` in `Promise<Booking>`.
+     * @brief Links every known type name in `text`, such as `Booking` in `Promise<Booking>`.
+     *
      * Records one `relation` edge from `from` to each type it finds.
+     *
+     * @param text - Source text to scan for names.
+     * @param from - Node the text belongs to. The edges start here.
+     * @param relation - Kind of edge to record.
+     * @param scope - Where the names are used.
+     * @returns The text with the links to the types it names.
      */
     link(text: string, from: NodeRef, relation: EdgeKind, scope: TypeScope): LinkedText;
     /**
-     * The type or function that inline code names, and an edge to it.
+     * @brief The type or function that inline code names, and an edge to it.
      *
      * @param text - Inline code, such as `Booking` or `choose_route()`.
      * @param from - Node the code is written in. The edge starts here.
+     * @param scope - Where the code is used.
+     * @param relation - Kind of edge to record, `mentions` by default.
      * @returns The node the code names, or `null` when it names none, more than one, or `from` itself.
      */
     mention(text: string, from: NodeRef, scope: TypeScope, relation?: EdgeKind): NodeRef | null;

package/dist/scanner/config.d.ts

@@ -0,0 +1,42 @@
+import type { NodeRef } from '../model';
+import type { FileRenderer } from './content';
+import type { Source } from './files';
+import type { GraphBuilder } from './graph/builder';
+import type { ProseResolvers } from './markdown/links';
+import type { SpecPlanner } from './specs';
+/**
+ * @brief Adds the JSON, TOML and YAML files of the code section to the graph, in the folders they are in.
+ *
+ * A file that is an OpenAPI document or a JSON Schema goes to the `SpecPlanner`, which adds its
+ * operations and definitions. Every other file becomes a page that shows it as it is. Created by
+ * `RepositoryScanner` for every scan and handed to `CodePlanner`, which calls `planFile` for each
+ * file `handles` accepts, in the same pass as the source files so the tree stays in path order.
+ *
+ * @example
+ * const configs = new ConfigPlanner(graph, files, resolvers, specs);
+ * if (configs.handles(path)) await configs.planFile(section, source, path);
+ */
+export declare class ConfigPlanner {
+    private readonly graph;
+    private readonly files;
+    private readonly resolvers;
+    private readonly specs;
+    /**
+     * @brief Keeps the graph to add to, the renderer of plain files and the planner of specs.
+     *
+     * @param files - Renders a plain file to its page.
+     * @param resolvers - Resolves the links of each page.
+     * @param specs - Plans OpenAPI documents and JSON Schemas.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, resolvers: ProseResolvers, specs: SpecPlanner);
+    /** Tells whether a file is a JSON, TOML or YAML file, by its extension. */
+    handles(path: string): boolean;
+    /**
+     * @brief Adds one JSON, TOML or YAML file below the folder of its directory: as a spec when it is one, else as a page.
+     *
+     * @param section - Node of the code section.
+     * @param source - Directory the file is in.
+     * @param path - Path of the file inside the source, accepted by `handles`.
+     */
+    planFile(section: NodeRef, { root, prefix }: Source, path: string): Promise<void>;
+}

package/dist/scanner/content.d.ts

@@ -1,38 +1,73 @@
 import type { FileContent } from '../model';
 import type { CodeHighlighter } from './highlight';
 import type { LinkResolver, MarkdownRenderer } from './markdown/renderer';
-/** A file as its page shows it. */
+/**
+ * @brief A file as its page shows it.
+ *
+ * @property title - Frontmatter `title` or `name`, else the first heading, else the file name.
+ * @property description - Frontmatter `description`, or `''`.
+ * @property content - What the page shows of the file: rendered markdown, highlighted text or an image.
+ */
 export interface RenderedFile {
-    /** Frontmatter `title` or `name`, else the first heading, else the file name. */
     readonly title: string;
-    /** Frontmatter `description`, or `''`. */
     readonly description: string;
     readonly content: FileContent;
 }
-/** Tells a markdown or MDX file by its extension. */
+/**
+ * @brief Tells whether a file is markdown or MDX, by its extension.
+ *
+ * @param path - Path of the file.
+ * @returns `true` for a `.md`, `.markdown` or `.mdx` file.
+ */
 export declare function isMarkdown(path: string): boolean;
-/** Reads an image file into a `data:` URI, or returns `null` when it is no image, is missing or is too large. */
+/**
+ * @brief Reads an image file into a `data:` URI.
+ *
+ * @param absolutePath - Absolute path of the image file.
+ * @returns The `data:` URI, or `null` when the file is no image, is missing, or is larger than `MAX_IMAGE_BYTES`.
+ */
 export declare function imageDataUri(absolutePath: string): Promise<string | null>;
 /**
- * Turns a file of any type into what its page shows: rendered markdown,
- * highlighted text or an image. Holds the markdown renderer and the code
- * highlighter it uses. Created by `RepositoryScanner`, and used by the
- * planners of the docs, skills, code, glossary, decisions, JSON Schema and
- * tasks sections.
+ * @brief Turns a file of any type into what its page shows: rendered markdown,
+ * highlighted text or an image.
+ *
+ * Holds the markdown renderer and the code highlighter it uses. Created by `RepositoryScanner`
+ * with `new FileRenderer(markdown, highlighter)`, and used by the planners of the docs, skills,
+ * code, glossary, decisions, JSON Schema and tasks sections.
  */
 export declare class FileRenderer {
     private readonly markdownRenderer;
     private readonly highlighter;
-    /** Keeps the renderer and the highlighter for every file it renders. */
+    /**
+     * Keeps the renderer and the highlighter for every file it renders.
+     *
+     * @param markdownRenderer - Renders markdown to HTML and collects its headings.
+     * @param highlighter - Highlights text files by their language.
+     */
     constructor(markdownRenderer: MarkdownRenderer, highlighter: CodeHighlighter);
     /**
-     * Reads a file and renders it by its type.
+     * @brief Reads a file and renders it by its type.
      *
+     * @param absolutePath - Absolute path of the file.
      * @param resolver - Rewrites the links of a markdown file.
+     * @returns The title, description and content of the file.
      */
     render(absolutePath: string, resolver?: LinkResolver): Promise<RenderedFile>;
-    /** Renders markdown that is already read. `fallbackTitle` is used when the text names no title. */
+    /**
+     * @brief Renders markdown that is already read. `fallbackTitle` is used when the text names no title.
+     *
+     * @param source - Markdown source, with its frontmatter if it has any.
+     * @param fallbackTitle - Title used when neither the frontmatter nor the text names one.
+     * @param resolver - Rewrites the links of the markdown.
+     * @param mdx - Whether the source is MDX, whose `import` and `export` lines are removed first.
+     * @returns The title, description and content of the file.
+     */
     markdown(source: string, fallbackTitle: string, resolver?: LinkResolver, mdx?: boolean): Promise<RenderedFile>;
-    /** Reads a file as text, highlighted by its extension when it is small enough, or omitted when it is large or binary. */
+    /**
+     * @brief Reads a file as text, highlighted by its extension when it is small enough, or omitted when it is large or binary.
+     *
+     * @param absolutePath - Absolute path of the file.
+     * @returns The highlighted text, or an `omitted` content with its reason and size.
+     */
     text(absolutePath: string): Promise<FileContent>;
 }

package/dist/scanner/decisions/parse.d.ts

@@ -1,26 +1,35 @@
-/** One decision as the decision log writes it. */
+/**
+ * @brief One decision as the decision log writes it.
+ *
+ * @property id - Number or id in front of the title, such as `3` or `ADR-0003`. `''` when the title has none.
+ * @property title - Title of the decision, without its id or date.
+ * @property status - As written, such as `accepted`. `''` when the decision states none.
+ * @property date - As written. `''` when the decision states none.
+ * @property body - Markdown of the decision without its heading, status line and date line.
+ */
 export interface ParsedDecision {
-    /** Number or id in front of the title, such as `3` or `ADR-0003`. `''` when the title has none. */
     readonly id: string;
     readonly title: string;
-    /** As written, such as `accepted`. `''` when the decision states none. */
     readonly status: string;
-    /** As written. `''` when the decision states none. */
     readonly date: string;
-    /** Markdown of the decision without its heading, status line and date line. */
     readonly body: string;
 }
-/** A decision log split into its intro and its decisions. */
+/**
+ * @brief A decision log split into its intro and its decisions.
+ *
+ * @property intro - Markdown of everything in front of the first decision, with the title.
+ * @property decisions - The decisions in file order.
+ */
 export interface ParsedDecisions {
-    /** Markdown of everything in front of the first decision, with the title. */
     readonly intro: string;
     readonly decisions: readonly ParsedDecision[];
 }
 /**
- * Reads the decisions of a decision log. Each heading of the highest level
- * below the title starts one decision. The heading may carry a number or a
- * date in front of the title. `Status:` and `Date:` lines at the top of a
- * decision become its status and date.
+ * @brief Reads the decisions of a decision log.
+ *
+ * Each heading of the highest level below the title starts one decision. The heading may carry a
+ * number or a date in front of the title. `Status:` and `Date:` lines at the top of a decision
+ * become its status and date.
  *
  * @param markdown - The decision log without frontmatter.
  * @returns The decisions in file order and the text in front of them.

package/dist/scanner/decisions/planner.d.ts

@@ -5,25 +5,37 @@ import type { GraphBuilder } from '../graph/builder';
 import type { ProseResolvers } from '../markdown/links';
 import type { MarkdownRenderer } from '../markdown/renderer';
 /**
- * Adds a decision log to the graph: one node for the file and one `decision`
- * node per decision. Used by `DocPlanner` for every `decisions.md` of the docs
- * section. What a decision links to or names in inline code becomes an
- * `affects` edge from the decision.
+ * @brief Adds a decision log to the graph: one node for the file and one `decision`
+ * node per decision.
  *
- * Holds the graph, the file renderer, the markdown renderer and the prose
- * resolvers. Created by `RepositoryScanner`, which hands it to `DocPlanner`.
+ * Used by `DocPlanner` for every `decisions.md` of the docs section. What a decision links to or
+ * names in inline code becomes an `affects` edge from the decision.
+ *
+ * Holds the graph, the file renderer, the markdown renderer and the prose resolvers. Created by
+ * `RepositoryScanner`, which hands it to `DocPlanner`.
  */
 export declare class DecisionPlanner {
     private readonly graph;
     private readonly files;
     private readonly markdown;
     private readonly resolvers;
-    /** Creates a planner. */
+    /**
+     * Creates a planner.
+     *
+     * @param graph - Graph the file and decision nodes are added to.
+     * @param files - Renders the text of the decision log around the decisions.
+     * @param markdown - Renders the body of each decision.
+     * @param resolvers - Resolves the links of the decision log and its decisions.
+     */
     constructor(graph: GraphBuilder, files: FileRenderer, markdown: MarkdownRenderer, resolvers: ProseResolvers);
     /**
-     * Reads one decision log and adds its nodes.
+     * @brief Reads one decision log and adds its nodes.
      *
      * @param parent - Folder or section the file is in.
+     * @param root - Absolute directory `path` is relative to.
+     * @param path - Path of the file inside `root`.
+     * @param displayPath - Path the site shows.
+     * @param prefix - Prefix the bundle puts in front of paths from `root`.
      * @returns The node of the file.
      */
     plan(parent: NodeRef, { root, path, displayPath, prefix }: DocFile): Promise<NodeRef>;

package/dist/scanner/docs.d.ts

@@ -5,32 +5,43 @@ import { type Source } from './files';
 import type { GlossaryPlanner } from './glossary/planner';
 import type { GraphBuilder } from './graph/builder';
 import type { ProseResolvers } from './markdown/links';
-import type { SpecPlanner } from './specs';
 /** What a file of the docs section becomes. */
-export type DocKind = 'document' | 'json' | 'glossary' | 'decisions';
-/** A file of the docs section, with the paths the planners need. */
+export type DocKind = 'document' | 'glossary' | 'decisions';
+/**
+ * @brief A file of the docs section, with the paths the planners need.
+ *
+ * @property root - Absolute directory `path` is relative to.
+ * @property path - Path of the file inside `root`.
+ * @property displayPath - Path the site shows: `path` behind the prefix of its source.
+ * @property prefix - Prefix the bundle puts in front of paths from `root`.
+ */
 export interface DocFile {
-    /** Absolute directory `path` is relative to. */
     readonly root: string;
-    /** Path of the file inside `root`. */
     readonly path: string;
-    /** Path the site shows: `path` behind the prefix of its source. */
     readonly displayPath: string;
-    /** Prefix the bundle puts in front of paths from `root`. */
     readonly prefix: string;
 }
 /**
- * Tells what a file of the docs section becomes, from its extension and name.
+ * @brief Tells what a file of the docs section becomes, from its extension and name.
  *
+ * @param path - Path of the file.
  * @returns The kind, or `null` for a file that does not belong in the docs section.
  */
 export declare function docKind(path: string): DocKind | null;
 /**
- * Adds the docs section to the graph: markdown and JSON files in the folders
- * they are in. A `glossary.md` and a `decisions.md` go to their own planners,
- * which add one node per term and per decision. A JSON or YAML file that is
- * an OpenAPI document or a JSON Schema goes to the `SpecPlanner`. Created by
- * `RepositoryScanner` for every scan.
+ * @brief Adds a file as a page of its own, rendered as it is, and registers its path so links can find it.
+ *
+ * @param kind - Node kind the file becomes, such as `document` or `json`.
+ * @param parent - Folder the page is added below.
+ * @param file - The file, with its root, path and display path.
+ * @returns Ref of the new page.
+ */
+export declare function addFilePage(graph: GraphBuilder, files: FileRenderer, resolvers: ProseResolvers, kind: 'document' | 'json' | 'toml' | 'yaml', parent: NodeRef, { root, path, displayPath, prefix }: DocFile): NodeRef;
+/**
+ * @brief Adds the docs section to the graph: the markdown files in the folders they are in.
+ *
+ * A `glossary.md` and a `decisions.md` go to their own planners, which add one node per term and
+ * per decision. Created by `RepositoryScanner` for every scan.
  */
 export declare class DocPlanner {
     private readonly graph;
@@ -38,15 +49,21 @@ export declare class DocPlanner {
     private readonly resolvers;
     private readonly glossaries;
     private readonly decisions;
-    private readonly specs;
-    /** Keeps the graph to add to and the renderer and planners each file goes to. */
-    constructor(graph: GraphBuilder, files: FileRenderer, resolvers: ProseResolvers, glossaries: GlossaryPlanner, decisions: DecisionPlanner, specs: SpecPlanner);
     /**
-     * Adds every doc file of the sources.
+     * @brief Keeps the graph to add to and the renderer and planners each file goes to.
+     *
+     * @param graph - Graph the page nodes are added to.
+     * @param files - Renders markdown files to their pages.
+     * @param resolvers - Resolves the links of each page.
+     * @param glossaries - Plans each `glossary.md`.
+     * @param decisions - Plans each `decisions.md`.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, resolvers: ProseResolvers, glossaries: GlossaryPlanner, decisions: DecisionPlanner);
+    /**
+     * @brief Adds every doc file of the sources.
      *
      * @param section - Node of the docs section.
+     * @param sources - Directories whose files are read.
      */
     plan(section: NodeRef, sources: readonly Source[]): Promise<void>;
-    /** Adds a markdown or JSON file as a page of its own and registers its path. */
-    private planFile;
 }

package/dist/scanner/files.d.ts

@@ -1,60 +1,85 @@
 /** Directory at the root of a repository where analyze writes its site and its cache. */
 export declare const OUTPUT_DIR = "analyze_out";
-/** Directories and files skipped in every scan, on top of `.gitignore`. The output of analyze is one, so it never documents itself. */
-export declare const DEFAULT_EXCLUDES: readonly string[];
-/** A directory to read: its files, and the prefix their paths get in the bundle. */
+/**
+ * @brief A directory to read: its files, and the prefix their paths get in the bundle.
+ *
+ * @property root - Absolute directory.
+ * @property files - Root-relative POSIX paths.
+ * @property prefix - Put in front of paths in the bundle. `''` for the repository, `name/` for a directory outside it.
+ * @property skillsAnywhere - Set for a directory the reader names as skills: a `SKILL.md` anywhere in it is a skill, not only inside an AI directory.
+ */
 export interface Source {
-    /** Absolute directory. */
     readonly root: string;
-    /** Root-relative POSIX paths. */
     readonly files: readonly string[];
-    /** Put in front of paths in the bundle. `''` for the repository, `name/` for a directory outside it. */
     readonly prefix: string;
+    readonly skillsAnywhere?: boolean;
 }
 /** Lists the files of a directory tree. */
 export interface FileLister {
-    /** Returns root-relative POSIX paths, sorted. */
+    /**
+     * @brief Lists the files below a directory.
+     *
+     * @param root - Absolute directory.
+     * @returns Root-relative POSIX paths, sorted.
+     */
     list(root: string): Promise<string[]>;
 }
 /**
- * Lists the files of a directory tree. Inside a git work tree it queries git, so
- * `.gitignore` applies. Elsewhere it walks the directory. Holds the globs it
- * skips: {@link DEFAULT_EXCLUDES} and the excludes it is created with.
- * Created in `api/services.ts` and used by `BundleBuilder` for every source.
+ * @brief Lists the files of a directory tree. Inside a git work tree it queries git, so
+ * `.gitignore` applies. Elsewhere it walks the directory.
+ *
+ * Holds the globs it skips: `analyze_out/`, `.git/` and the excludes it is created with.
+ * Created in `api/services.ts` with `new RepoFileLister(excludes)` and used by `BundleBuilder`
+ * for every source.
+ *
+ * @property excludes - Compiled globs of the files to skip.
  */
 export declare class RepoFileLister implements FileLister {
     private readonly excludes;
     /**
-     * Compiles the exclude globs.
+     * @brief Compiles the exclude globs.
      *
-     * @param excludes - Globs on top of {@link DEFAULT_EXCLUDES}, matched against root-relative POSIX paths.
+     * @param excludes - Globs matched against root-relative POSIX paths, such as the ones `ignoreGlobs` makes of an
+     * `.analyzeignore`. Defaults to the globs of {@link DEFAULT_IGNORE_LINES}.
      */
     constructor(excludes?: readonly string[]);
     /**
-     * Lists the files below a directory, without the excluded ones.
+     * @brief Lists the files below a directory, without the excluded ones.
      *
      * @param root - Absolute directory.
      * @returns Root-relative POSIX paths, sorted.
      */
     list(root: string): Promise<string[]>;
-    /** Tells whether a root-relative path matches an exclude glob. */
+    /**
+     * @brief Tells whether a root-relative path matches an exclude glob.
+     *
+     * @param file - Root-relative POSIX path.
+     * @returns `true` when a glob matches the path.
+     */
     private isExcluded;
     /**
-     * Lists the tracked and untracked files git does not ignore.
+     * @brief Lists the tracked and untracked files git does not ignore.
      *
+     * @param root - Absolute directory.
      * @returns Root-relative paths, or `null` when `root` is not in a git work tree or git fails.
      */
     private listWithGit;
     /**
-     * Walks a directory recursively, skipping excluded directories.
+     * @brief Walks a directory recursively, skipping excluded directories.
      *
+     * @param root - Absolute directory the walk starts from.
      * @param relative - Path of the directory inside `root`, `''` for `root` itself.
      * @returns Root-relative paths, unsorted.
      */
     private walk;
 }
 /**
- * Orders paths the way a file tree lists them: directories before files,
- * then by name. A README leads the files of its directory.
+ * @brief Orders paths the way a file tree lists them: directories before files, then by name.
+ *
+ * A README leads the files of its directory.
+ *
+ * @param a - Root-relative POSIX path.
+ * @param b - Root-relative POSIX path.
+ * @returns Negative when `a` lists first, positive when `b` does, zero for equal paths.
  */
 export declare function compareTreePaths(a: string, b: string): number;

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

@@ -1,21 +1,31 @@
-/** One term as the glossary file writes it. */
+/**
+ * @brief One term as the glossary file writes it.
+ *
+ * @property name - Name of the term, as written.
+ * @property group - Text of the heading the term is listed under, or `''`.
+ * @property definition - Markdown of the definition, without the `_Avoid_:` lines.
+ * @property avoid - Words the glossary tells writers to replace with this term.
+ */
 export interface ParsedTerm {
     readonly name: string;
-    /** Text of the heading the term is listed under, or `''`. */
     readonly group: string;
-    /** Markdown. */
     readonly definition: string;
-    /** Words the glossary tells writers to replace with this term. */
     readonly avoid: readonly string[];
 }
-/** A glossary file split into the text around the terms and the terms. */
+/**
+ * @brief A glossary file split into the text around the terms and the terms.
+ *
+ * @property intro - Markdown of everything that is not a term: the title and the text around the terms.
+ * @property terms - The terms in file order.
+ */
 export interface ParsedGlossary {
-    /** Markdown of everything that is not a term: the title and the text around the terms. */
     readonly intro: string;
     readonly terms: readonly ParsedTerm[];
 }
 /**
- * Reads the terms of a glossary. Two layouts are recognized:
+ * @brief Reads the terms of a glossary.
+ *
+ * Two layouts are recognized:
  *
  * - **Bold terms**: a line that opens with a bold name, followed by its
  *   definition. Headings group the terms.

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

@@ -6,14 +6,13 @@ import type { ProseResolvers } from '../markdown/links';
 import type { MarkdownRenderer } from '../markdown/renderer';
 import type { TermIndex } from './terms';
 /**
- * Adds a glossary to the graph: one node for the file and one `term` node per
- * term. Used by `DocPlanner` for every `glossary.md` of the docs section. Each
- * term is also registered in the term index, so prose anywhere in the scan
- * can link to it.
+ * @brief Adds a glossary to the graph: one node for the file and one `term` node per term.
  *
- * Holds the graph, the file renderer, the markdown renderer, the shared
- * `TermIndex` and the prose resolvers. Created by `RepositoryScanner`, which
- * hands it to `DocPlanner` and `TaskPlanner`.
+ * Used by `DocPlanner` for every `glossary.md` of the docs section. Each term is also registered
+ * in the term index, so prose anywhere in the scan can link to it.
+ *
+ * Holds the graph, the file renderer, the markdown renderer, the shared `TermIndex` and the prose
+ * resolvers. Created by `RepositoryScanner`, which hands it to `DocPlanner` and `TaskPlanner`.
  *
  * @example
  * const terms = new TermIndex();
@@ -29,13 +28,21 @@ export declare class GlossaryPlanner {
     /**
      * Creates a planner.
      *
+     * @param graph - Graph the file and term nodes are added to.
+     * @param files - Renders the text of the glossary around the terms.
+     * @param markdown - Renders the definition of each term.
      * @param terms - Receives every term. Must be the index the `TermLinker` of `resolvers` reads.
+     * @param resolvers - Resolves the links of the glossary and its terms.
      */
     constructor(graph: GraphBuilder, files: FileRenderer, markdown: MarkdownRenderer, terms: TermIndex, resolvers: ProseResolvers);
     /**
-     * Reads one glossary file and adds its nodes.
+     * @brief Reads one glossary file and adds its nodes.
      *
      * @param parent - Folder or section the file is in.
+     * @param root - Absolute directory `path` is relative to.
+     * @param path - Path of the file inside `root`.
+     * @param displayPath - Path the site shows.
+     * @param prefix - Prefix the bundle puts in front of paths from `root`.
      * @returns The node of the file.
      */
     plan(parent: NodeRef, { root, path, displayPath, prefix }: DocFile): Promise<NodeRef>;