@g3nomaly/analyze 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,149 @@
+import type { SymbolKind } from '../../model';
+import type { Node } from 'web-tree-sitter';
+/**
+ * Doc comment dialect.
+ * - `tagged`: `@param`-style tags (JSDoc, Javadoc, Doxygen, PHPDoc, KDoc, Scaladoc).
+ * - `yard`: `tagged`, with the title of an `@example` on the tag line.
+ * - `markdown`: free markdown with headed sections (rustdoc, godoc).
+ * - `python`: docstrings in Google, NumPy or reST layout.
+ * - `xml`: C# XML documentation.
+ */
+export type DocStyle = 'tagged' | 'yard' | 'markdown' | 'python' | 'xml';
+/** What a language spec can inspect when it classifies one definition. */
+export interface DefinitionFacts {
+    readonly node: Node;
+    /** Declaration head, without the body. */
+    readonly signature: string;
+    readonly annotations: readonly string[];
+    /** Declared return type text, when the grammar exposes one. */
+    readonly returnType: string | null;
+    /** True when the parameter list starts with a receiver such as `self`. */
+    readonly hasReceiver: boolean;
+}
+/** What an import hook knows about the symbol an example uses. */
+export interface ImportContext {
+    /** Root-relative path of the file that declares the symbol. */
+    readonly filePath: string;
+    /** Outermost symbol around the one the example uses: the class of a method, or the function itself. */
+    readonly name: string;
+    readonly kind: SymbolKind;
+    readonly modifiers: readonly string[];
+    /** Package or namespace the file declares with a statement, such as Java's `package a.b;`. */
+    readonly packageName: string | null;
+}
+/** How a language spells a call. Drives generated examples. */
+export interface CallStyle {
+    /** Statement terminator, `';'` or `''`. */
+    readonly terminator: string;
+    readonly variableCase: 'camel' | 'snake';
+    /** Prefix of variable names, `'$'` in PHP. */
+    readonly variablePrefix?: string;
+    readonly memberAccess: string;
+    readonly staticAccess: string;
+    /** Separator between a namespace and its member. `null` means members are called unqualified. */
+    readonly namespaceAccess: string | null;
+    /** Binds the value of `expression` to `variable`. */
+    declare(variable: string, expression: string, returnType: string | null): string;
+    /**
+     * Statement that creates an instance of `type` named `variable`.
+     * `hasConstructor` is false when the scanner found no constructor in the file.
+     * Returns `null` when the language cannot build the type without one.
+     */
+    construct(type: string, args: string, variable: string, hasConstructor: boolean): string | null;
+    /** Wraps an expression that must be awaited. */
+    await?(expression: string): string;
+    /** Rewrites one argument, for languages with named arguments. */
+    argument?(name: string, parameter: Node): string;
+    /** Line that brings the symbol into scope, or `null` when it cannot be derived. */
+    importLine?(context: ImportContext): string | null;
+}
+/**
+ * Everything the scanner needs to support one language. Adding a language
+ * means adding one spec and listing it in `languages/index.ts`.
+ */
+export interface LanguageSpec {
+    readonly id: string;
+    readonly label: string;
+    /**
+     * Languages whose types can refer to each other, such as TypeScript and
+     * JavaScript. A type name never links across families. Defaults to `id`.
+     */
+    readonly family?: string;
+    readonly extensions: readonly string[];
+    /**
+     * For an extension that several languages share, such as `.h`: answers
+     * whether this source is in this language. Specs are tried in registry order.
+     */
+    readonly accepts?: (source: string) => boolean;
+    /** Path of the tree-sitter grammar `.wasm`. */
+    readonly grammarPath: string;
+    /** shiki language id. */
+    readonly highlight: string;
+    /**
+     * Tree-sitter query. Captures: `@definition.<kind>` on the definition node,
+     * `@name`, and optionally `@params`, `@body`, `@return`, `@owner`.
+     * `@owner` names the type a method belongs to when the method is declared
+     * outside it (Go receivers, Rust `impl` blocks).
+     *
+     * `@definition.field` marks a field, property or enum member. It takes
+     * `@name` and optionally `@type` and `@value`. With `@receiver` (Python's
+     * `self.x = ...`) the field belongs to the type around the enclosing method.
+     *
+     * `@package` captures the package or namespace the file declares.
+     */
+    readonly query: string;
+    /**
+     * Where a declaration puts its type: `prefix` as in `int count`, `suffix`
+     * as in `count: int`, `none` for languages without declared types.
+     */
+    readonly typeSyntax: 'prefix' | 'suffix' | 'none';
+    /** What the language calls its annotations, for example `Decorators`. */
+    readonly annotationLabel: string;
+    readonly docStyle: DocStyle;
+    /** `docstring` reads the first string of the body instead of leading comments. */
+    readonly docSource: 'leading-comment' | 'docstring';
+    readonly commentTypes: readonly string[];
+    /** Restricts which leading comments count as documentation. */
+    readonly isDocComment?: (text: string) => boolean;
+    /** Node types of decorators, attributes and annotations. */
+    readonly annotationTypes: readonly string[];
+    /** Parent node types that wrap a definition, such as `export_statement`. */
+    readonly wrapperTypes: readonly string[];
+    /** Node types whose descendants are local, such as closures. */
+    readonly localScopeTypes: readonly string[];
+    /** Parents whose leading comment documents their first child (a tree-sitter-ruby quirk). */
+    readonly hoistedCommentParents?: readonly string[];
+    /** Parameter node types that are receivers. */
+    readonly receiverTypes?: readonly string[];
+    /** Parameter names that are receivers. */
+    readonly receiverNames?: readonly string[];
+    /** Parameter node types that never appear in a call. */
+    readonly skippedParamTypes?: readonly string[];
+    /** When set, only these node types inside a parameter list are parameters. */
+    readonly paramTypes?: readonly string[];
+    /** Answers from a declaration head whether the type can be constructed. Abstract types are excluded already. */
+    readonly isInstantiable?: (signature: string) => boolean;
+    /** Kind given to an owner type that is not declared in the same file. */
+    readonly inferredOwnerKind?: SymbolKind;
+    /** Splits a qualified name such as `Foo::bar` into owner and member. */
+    readonly splitQualifiedName?: (name: string) => {
+        owner: string;
+        name: string;
+    } | null;
+    /** Names a constructor can have inside a class called `className`. */
+    constructorNames(className: string): readonly string[];
+    /** True when the definition is called on its type rather than on an instance. */
+    isStatic(facts: DefinitionFacts): boolean;
+    /** True when a call to the definition yields a value, so a generated example binds it to a variable. */
+    returnsValue(facts: DefinitionFacts): boolean;
+    /** Reads the return type when the `@return` capture cannot express it, such as a C pointer. */
+    readonly declaredReturnType?: (facts: DefinitionFacts) => string | null;
+    readonly call: CallStyle;
+}
+/** Language family of a spec: its `family`, or its `id` when it sets none. */
+export declare function familyOf(spec: LanguageSpec): string;
+/**
+ * Decides from a declared return type whether a call yields a value.
+ * `implicit` answers for declarations without a return type.
+ */
+export declare function returnsValueFrom(returnType: string | null, implicit: boolean): boolean;

package/dist/scanner/code/languages/c-family.d.ts

@@ -0,0 +1,5 @@
+import { type LanguageSpec } from '../language';
+/** C: `.c` files and `.h` files without C++-only syntax. */
+export declare const c: LanguageSpec;
+/** C++, including `.h` files that C does not accept. */
+export declare const cpp: LanguageSpec;

package/dist/scanner/code/languages/csharp.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** C#, documented with XML doc comments. */
+export declare const csharp: LanguageSpec;

package/dist/scanner/code/languages/ecmascript.d.ts

@@ -0,0 +1,7 @@
+import { type LanguageSpec } from '../language';
+/** JavaScript, including JSX. */
+export declare const javascript: LanguageSpec;
+/** TypeScript without JSX. */
+export declare const typescript: LanguageSpec;
+/** TypeScript with JSX, in `.tsx` files. */
+export declare const tsx: LanguageSpec;

package/dist/scanner/code/languages/go.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** Go. Methods are declared outside their struct and attach to it through the receiver type. */
+export declare const go: LanguageSpec;

package/dist/scanner/code/languages/index.d.ts

@@ -0,0 +1,19 @@
+import type { LanguageSpec } from '../language';
+/** Every supported language. Add a spec here to support another one. */
+export declare const LANGUAGES: readonly LanguageSpec[];
+/**
+ * Maps files to language specs, by extension and, where languages share one, by content.
+ *
+ * Holds the specs that claim each lowercase extension, in registry order. Created by
+ * `RepositoryScanner` in `scanner/scanner.ts` and consumed by `CodePlanner` in
+ * `code/planner.ts`.
+ */
+export declare class LanguageRegistry {
+    private readonly byExtension;
+    /** Indexes the specs by extension. Order matters: `forFile` tries them in this order. */
+    constructor(languages?: readonly LanguageSpec[]);
+    /** True when some language claims the extension of `path`. */
+    supports(path: string): boolean;
+    /** The first language that accepts the source. Falls back to the last one that claims the extension. */
+    forFile(path: string, source: string): LanguageSpec | null;
+}

package/dist/scanner/code/languages/java.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** Java, documented with Javadoc. */
+export declare const java: LanguageSpec;

package/dist/scanner/code/languages/kotlin.d.ts

@@ -0,0 +1,3 @@
+import type { LanguageSpec } from '../language';
+/** Kotlin, documented with KDoc. `object` and `companion object` members count as static. */
+export declare const kotlin: LanguageSpec;

package/dist/scanner/code/languages/php.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** PHP, documented with PHPDoc. */
+export declare const php: LanguageSpec;

package/dist/scanner/code/languages/python.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** Python, documented with docstrings. Fields come from `self.x = ...` in `__init__`. */
+export declare const python: LanguageSpec;

package/dist/scanner/code/languages/ruby.d.ts

@@ -0,0 +1,3 @@
+import type { LanguageSpec } from '../language';
+/** Ruby, documented with YARD. */
+export declare const ruby: LanguageSpec;

package/dist/scanner/code/languages/rust.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** Rust, documented with `///` and `/**` comments. Methods attach to their type through `impl` blocks. */
+export declare const rust: LanguageSpec;

package/dist/scanner/code/languages/scala.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageSpec } from '../language';
+/** Scala, documented with Scaladoc. `object` members count as static. */
+export declare const scala: LanguageSpec;

package/dist/scanner/code/languages/shared.d.ts

@@ -0,0 +1,17 @@
+import type { Node } from 'web-tree-sitter';
+import type { DefinitionFacts, ImportContext } from '../language';
+/** True when the declaration head contains the `static` keyword. */
+export declare function hasStaticKeyword(facts: DefinitionFacts): boolean;
+/**
+ * Walks up from a definition and reports whether it reaches one of `staticScopes`
+ * before one of `instanceScopes`. Used for Kotlin and Scala `object` members.
+ */
+export declare function isInsideScope(node: Node, staticScopes: readonly string[], instanceScopes: readonly string[]): boolean;
+/** False for a Kotlin or Scala `object` declaration head, which declares a singleton. */
+export declare function isNotSingleton(signature: string): boolean;
+/** `*` or `&` when a C or C++ function returns a pointer or reference, which the `type` field does not show. */
+export declare function returnIndirection(node: Node): string;
+/** Path of a file without its extension, for module specifiers. */
+export declare function withoutExtension(path: string): string;
+/** `import pkg.Name` in the given statement shape, for languages with a declared package. */
+export declare function packageImport(context: ImportContext, format: (qualifiedName: string) => string): string | null;

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

@@ -0,0 +1,71 @@
+import type { NodeRef } from '../../model';
+import type { FileRenderer } from '../content';
+import { type Source } from '../files';
+import type { GraphBuilder } from '../graph/builder';
+import { type Reporter } from '../reporter';
+import type { SqlPlanner } from '../sql/planner';
+import type { SymbolExtractor } from './extract';
+import type { GrammarLoader } from './grammar';
+import type { LanguageRegistry } from './languages';
+import type { SymbolPlanner } from './symbols';
+/** One source file to add. */
+export interface SourceFile {
+    /** Absolute directory `path` is relative to. */
+    readonly root: string;
+    readonly path: string;
+    /** Path as the bundle shows it: `path` behind the prefix of its source. */
+    readonly displayPath: string;
+}
+/**
+ * Adds source files and their symbols to the graph. The SQL files of a
+ * repository are no code: `DatabasePlanner` adds them. A SQL file of a skill
+ * that creates tables goes to the `SqlPlanner`.
+ *
+ * Holds the planners and loaders it delegates to: it parses a file with the
+ * grammar from `GrammarLoader`, extracts symbols with `SymbolExtractor`, and
+ * hands them to `SymbolPlanner`. Created per scan by `RepositoryScanner` in
+ * `scanner/scanner.ts`, which calls `planTree` for the code section;
+ * `SkillPlanner` in `skills/planner.ts` calls `isSource` and `planFile`.
+ *
+ * @example
+ * const code = new CodePlanner(graph, registry, grammars, extractor, symbols, files, sql, reporter);
+ * await code.planTree(sections.code, source);
+ */
+export declare class CodePlanner {
+    private readonly graph;
+    private readonly registry;
+    private readonly grammars;
+    private readonly extractor;
+    private readonly symbols;
+    private readonly files;
+    private readonly sql;
+    private readonly reporter;
+    /**
+     * Takes the graph it adds nodes to and the helpers it delegates each file to.
+     *
+     * @param reporter - Receives a warning for each file that cannot be read or parsed. Silent by default.
+     */
+    constructor(graph: GraphBuilder, registry: LanguageRegistry, grammars: GrammarLoader, extractor: SymbolExtractor, symbols: SymbolPlanner, files: FileRenderer, sql: SqlPlanner, reporter?: Reporter);
+    /** True for a file that is source code, whether or not the scanner can read its symbols. */
+    isSource(path: string): boolean;
+    /**
+     * Adds every file of `source` that declares a class or a function, in
+     * folders below `section`. Files in unsupported languages are skipped.
+     */
+    planTree(section: NodeRef, source: Source): Promise<void>;
+    /**
+     * Adds one file below `parent` with its text embedded, whatever it
+     * declares. Used for the code that belongs to a skill. A SQL file that
+     * creates tables is added as a database instead.
+     */
+    planFile(parent: NodeRef, file: SourceFile): Promise<NodeRef>;
+    /**
+     * Adds a `source` node for the file below `parent`, registers its display path, and plans its symbols.
+     *
+     * @param extracted - Symbols of the file, or `null` to add the file without symbols.
+     * @param embedText - Whether the node carries the file's full text.
+     */
+    private add;
+    /** The symbols of a file, or `null` when its language is unsupported or it cannot be read. */
+    private extract;
+}

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

@@ -0,0 +1,68 @@
+import { type NodeRef } from '../../model';
+import type { GraphBuilder } from '../graph/builder';
+import type { CodeHighlighter } from '../highlight';
+import type { ProseResolvers } from '../markdown/links';
+import type { MarkdownRenderer } from '../markdown/renderer';
+import type { RawSymbol } from './extract';
+import { type LanguageSpec } from './language';
+import type { CallableIndex, TypeIndex, TypeLinker } from './types';
+/** What the planner needs to know about the file a symbol tree comes from. */
+export interface FileContext {
+    readonly spec: LanguageSpec;
+    /** Display path of the file: its path below the source root, behind the source's prefix. */
+    readonly path: string;
+    /** Package or namespace the file declares. */
+    readonly packageName: string | null;
+}
+/**
+ * Adds the symbols of a file to the graph: one node per class or function,
+ * with a child node per parameter and field. Type names in signatures become
+ * links to the types they name.
+ *
+ * Holds the graph, the renderers, and the indexes and linkers it registers into and
+ * links through. Created per scan by `RepositoryScanner` in `scanner/scanner.ts`;
+ * `CodePlanner` in `planner.ts` calls `plan` for each file it extracts symbols from.
+ *
+ * @example
+ * const symbols = new SymbolPlanner(graph, highlighter, markdown, types, callables, linker, resolvers);
+ * symbols.plan(fileRef, { spec, path: 'src/app.ts', packageName: null }, extracted.symbols);
+ */
+export declare class SymbolPlanner {
+    private readonly graph;
+    private readonly highlighter;
+    private readonly markdown;
+    private readonly types;
+    private readonly callables;
+    private readonly linker;
+    private readonly resolvers;
+    /** Takes the graph and renderers it writes with, and the indexes and linkers that resolve names. */
+    constructor(graph: GraphBuilder, highlighter: CodeHighlighter, markdown: MarkdownRenderer, types: TypeIndex, callables: CallableIndex, linker: TypeLinker, resolvers: ProseResolvers);
+    /** Adds `symbols` and everything inside them below the file node `fileRef`. */
+    plan(fileRef: NodeRef, file: FileContext, symbols: readonly RawSymbol[]): void;
+    /**
+     * Adds one symbol node with its parameter and field nodes, registers it in the type or
+     * callable index, and recurses into its children.
+     */
+    private planSymbol;
+    /**
+     * Builds the content of a symbol node: highlighted signature, rendered description,
+     * return value, tags and example. Records `extends` edges for its heritage.
+     *
+     * @param self - Node of the symbol itself, where the edges start.
+     */
+    private symbolContent;
+    /** Builds the content of a parameter or field node: linked type, default, optional flag and rendered description. */
+    private declarationContent;
+    /**
+     * Return value of a symbol from its declared return type and `@returns` tag.
+     *
+     * @returns `null` when there is no tag and the symbol returns no typed value.
+     */
+    private returns;
+    /** Prefers the documented example. Falls back to one generated from the signature. */
+    private example;
+    /** Renders a plain doc tag. The subject of a `throws` tag links to the types it names. */
+    private tag;
+    /** Renders a description. Inline code that names a type or function, and glossary terms, become links. */
+    private html;
+}

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

@@ -0,0 +1,93 @@
+import type { EdgeKind, LinkedText, NodeRef } from '../../model';
+import type { GraphBuilder } from '../graph/builder';
+/** Where a type name is used. Decides which declaration it means. */
+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.
+ *
+ * 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.
+ */
+export declare class TypeIndex {
+    private readonly byName;
+    /**
+     * Adds a type declaration under its name.
+     *
+     * @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.
+     * A declaration in the same file wins, then the one whose directory is closest.
+     */
+    resolve(name: string, scope: TypeScope): NodeRef | null;
+}
+/**
+ * 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.
+ */
+export declare class CallableIndex {
+    private readonly byName;
+    /**
+     * Adds a function or method under its name and, when it has an owner, under `Owner.name`.
+     *
+     * @param owner - Name of the type or namespace it is declared in, or `null`.
+     * @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.
+     *
+     * @param text - Inline code, such as `choose_route()` or `Invoice.add`.
+     * @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.
+ *
+ * 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
+ * `SymbolPlanner` in `symbols.ts` for signatures and by the resolvers in
+ * `markdown/links.ts` for inline code in prose.
+ *
+ * @example
+ * const linker = new TypeLinker(new TypeIndex(), new CallableIndex(), graph);
+ * const type = linker.link('Promise<Booking>', methodRef, 'returns', scope);
+ */
+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. */
+    constructor(index: TypeIndex, callables: CallableIndex, graph: GraphBuilder);
+    /**
+     * Links every known type name in `text`, such as `Booking` in `Promise<Booking>`.
+     * Records one `relation` edge from `from` to each type it finds.
+     */
+    link(text: string, from: NodeRef, relation: EdgeKind, scope: TypeScope): LinkedText;
+    /**
+     * 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.
+     * @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/content.d.ts

@@ -0,0 +1,38 @@
+import type { FileContent } from '../model';
+import type { CodeHighlighter } from './highlight';
+import type { LinkResolver, MarkdownRenderer } from './markdown/renderer';
+/** A file as its page shows it. */
+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. */
+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. */
+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.
+ */
+export declare class FileRenderer {
+    private readonly markdownRenderer;
+    private readonly highlighter;
+    /** Keeps the renderer and the highlighter for every file it renders. */
+    constructor(markdownRenderer: MarkdownRenderer, highlighter: CodeHighlighter);
+    /**
+     * Reads a file and renders it by its type.
+     *
+     * @param resolver - Rewrites the links of a markdown file.
+     */
+    render(absolutePath: string, resolver?: LinkResolver): Promise<RenderedFile>;
+    /** Renders markdown that is already read. `fallbackTitle` is used when the text names no title. */
+    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. */
+    text(absolutePath: string): Promise<FileContent>;
+}

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

@@ -0,0 +1,28 @@
+/** One decision as the decision log writes it. */
+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. */
+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.
+ *
+ * @param markdown - The decision log without frontmatter.
+ * @returns The decisions in file order and the text in front of them.
+ */
+export declare function parseDecisions(markdown: string): ParsedDecisions;

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

@@ -0,0 +1,30 @@
+import type { NodeRef } from '../../model';
+import type { FileRenderer } from '../content';
+import type { DocFile } from '../docs';
+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.
+ *
+ * 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. */
+    constructor(graph: GraphBuilder, files: FileRenderer, markdown: MarkdownRenderer, resolvers: ProseResolvers);
+    /**
+     * Reads one decision log and adds its nodes.
+     *
+     * @param parent - Folder or section the file is in.
+     * @returns The node of the file.
+     */
+    plan(parent: NodeRef, { root, path, displayPath, prefix }: DocFile): Promise<NodeRef>;
+}

package/dist/scanner/docs.d.ts

@@ -0,0 +1,52 @@
+import type { NodeRef } from '../model';
+import type { FileRenderer } from './content';
+import type { DecisionPlanner } from './decisions/planner';
+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 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.
+ *
+ * @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.
+ */
+export declare class DocPlanner {
+    private readonly graph;
+    private readonly files;
+    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.
+     *
+     * @param section - Node of the docs section.
+     */
+    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;
+}