@g3nomaly/analyze 0.0.0-stage → 0.1.1

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,33 @@
+import type { LanguageSpec } from '../language';
+/** Every supported language. Add a spec here to support another one. */
+export declare const LANGUAGES: readonly LanguageSpec[];
+/**
+ * @brief 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 with
+ * `new LanguageRegistry()` 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.
+     *
+     * @param languages - Specs to index, in priority order. Defaults to {@link LANGUAGES}.
+     */
+    constructor(languages?: readonly LanguageSpec[]);
+    /**
+     * True when some language claims the extension of `path`.
+     *
+     * @param path - File path; the extension is matched case-insensitively.
+     */
+    supports(path: string): boolean;
+    /**
+     * The first language that accepts the source. Falls back to the last one that claims the extension.
+     *
+     * @param path - File path; its extension selects the candidates.
+     * @param source - Full text of the file, given to each candidate's `accepts`.
+     * @returns The chosen spec, or `null` when no language 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,36 @@
+import type { Node } from 'web-tree-sitter';
+import type { DefinitionFacts, ImportContext } from '../language';
+/**
+ * True when the declaration head contains the `static` keyword.
+ *
+ * @param facts - What the spec can inspect about the definition.
+ */
+export declare function hasStaticKeyword(facts: DefinitionFacts): boolean;
+/**
+ * @brief Walks up from a definition and reports whether it reaches one of `staticScopes`
+ * before one of `instanceScopes`. Used for Kotlin and Scala `object` members.
+ *
+ * @param node - Tree-sitter node of the definition.
+ * @param staticScopes - Node types whose members are static.
+ * @param instanceScopes - Node types whose members are instance members, which stop the walk.
+ */
+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.
+ *
+ * @param node - Function definition node.
+ * @returns One mark per pointer or reference layer, or `''` for a plain return.
+ */
+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.
+ *
+ * @param context - What the import needs to know about the symbol.
+ * @param format - Builds the statement from the qualified name, such as `import pkg.Name;`.
+ * @returns The statement, or `null` when the file declares no package.
+ */
+export declare function packageImport(context: ImportContext, format: (qualifiedName: string) => string): string | null;

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

@@ -0,0 +1,107 @@
+import type { NodeRef } from '../../model';
+import type { ConfigPlanner } from '../config';
+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';
+/**
+ * @brief One source file to add.
+ *
+ * @property root - Absolute directory `path` is relative to.
+ * @property path - Path of the file below `root`, in POSIX form.
+ * @property displayPath - Path as the bundle shows it: `path` behind the prefix of its source.
+ */
+export interface SourceFile {
+    readonly root: string;
+    readonly path: string;
+    readonly displayPath: string;
+}
+/**
+ * @brief 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 graph - Graph the source nodes are added to.
+     * @param registry - Says which languages are supported and which spec reads a file.
+     * @param grammars - Loads the parser and query of a language spec.
+     * @param extractor - Extracts the raw symbols from a parsed syntax tree.
+     * @param symbols - Adds the symbols of a file below its source node.
+     * @param files - Reads the text of a file, to embed it in its node.
+     * @param sql - Adds SQL files that create tables as databases.
+     * @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);
+    /**
+     * @brief Tells whether a file is source code, whether or not the scanner can read its symbols.
+     *
+     * @param path - Path of the file, with its extension.
+     */
+    isSource(path: string): boolean;
+    /**
+     * @brief Adds every file of `source` that declares a class or a function, in folders below `section`.
+     *
+     * Files in unsupported languages are skipped. JSON, TOML and YAML files go to `configs`, in the same
+     * pass, so the tree stays in path order.
+     *
+     * @param section - Node the folders are added below.
+     * @param source - Directory whose files are read.
+     * @param configs - Plans the JSON, TOML and YAML files. Without it they are skipped.
+     */
+    planTree(section: NodeRef, source: Source, configs?: ConfigPlanner): Promise<void>;
+    /**
+     * @brief Adds one file below `parent` with its text embedded, whatever it declares.
+     *
+     * A SQL file that creates tables is added as a database instead.
+     *
+     * @param parent - Node the file is added below.
+     * @param file - File to add.
+     * @returns Node of the file, or of the database it creates.
+     */
+    planFile(parent: NodeRef, file: SourceFile): Promise<NodeRef>;
+    /**
+     * @brief Adds a `source` node for the file below `parent`, registers its display path, and plans its symbols.
+     *
+     * @param parent - Node the file is added below.
+     * @param file - File to add.
+     * @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.
+     * @returns Node of the file.
+     */
+    private add;
+    /**
+     * @brief Reads the symbols of a file.
+     *
+     * @param file - File to read.
+     * @returns Symbols with their language spec, or `null` when the language is unsupported, the file is
+     * missing or larger than `MAX_SOURCE_BYTES`, or it cannot be parsed.
+     */
+    private extract;
+}

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

@@ -0,0 +1,134 @@
+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';
+/**
+ * @brief What the planner needs to know about the file a symbol tree comes from.
+ *
+ * @property spec - Language spec that reads the file.
+ * @property path - Display path of the file: its path below the source root, behind the source's prefix.
+ * @property packageName - Package or namespace the file declares, or `null`.
+ */
+export interface FileContext {
+    readonly spec: LanguageSpec;
+    readonly path: string;
+    readonly packageName: string | null;
+}
+/**
+ * @brief 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.
+     *
+     * @param graph - Graph the symbol nodes are added to.
+     * @param highlighter - Highlights signatures and examples as HTML.
+     * @param markdown - Renders doc descriptions as HTML.
+     * @param types - Index of type declarations, where each new type is registered.
+     * @param callables - Index of functions and methods, where each new callable is registered.
+     * @param linker - Links the type names of signatures to their declarations.
+     * @param resolvers - Resolves the names in prose descriptions to links.
+     */
+    constructor(graph: GraphBuilder, highlighter: CodeHighlighter, markdown: MarkdownRenderer, types: TypeIndex, callables: CallableIndex, linker: TypeLinker, resolvers: ProseResolvers);
+    /**
+     * @brief Adds `symbols` and everything inside them below the file node `fileRef`.
+     *
+     * @param fileRef - Node of the file the symbols are in.
+     * @param file - Language spec and path of the file.
+     * @param symbols - Top-level symbols of the file, in file order.
+     */
+    plan(fileRef: NodeRef, file: FileContext, symbols: readonly RawSymbol[]): void;
+    /**
+     * @brief Adds one symbol node with its parameter and field nodes, registers it in the type or
+     * callable index, and recurses into its children.
+     *
+     * @param symbol - Symbol to add, as the extractor found it.
+     * @param scope - Where the symbol sits in the file.
+     */
+    private planSymbol;
+    /**
+     * @brief Builds the content of a symbol node: highlighted signature, rendered description,
+     * return value, tags and example.
+     *
+     * Records `extends` edges for its heritage.
+     *
+     * @param symbol - Symbol the content is built for.
+     * @param doc - Parsed doc comment of the symbol.
+     * @param scope - Where the symbol sits in the file.
+     * @param typeScope - Scope that the names of the symbol resolve in.
+     * @param self - Node of the symbol itself, where the edges start.
+     * @returns Content of the symbol node.
+     */
+    private symbolContent;
+    /**
+     * @brief Builds the content of a parameter or field node: linked type, default, optional flag and rendered description.
+     *
+     * @param declaration - Parameter or field to build the content of.
+     * @param self - Node of the parameter or field itself, where the type edge starts.
+     * @param file - File the declaration is in.
+     * @param typeScope - Scope that the type name resolves in.
+     * @returns Content of the node.
+     */
+    private declarationContent;
+    /**
+     * @brief Builds the return value of a symbol from its declared return type and `@returns` tag.
+     *
+     * @param symbol - Symbol whose return value is built.
+     * @param doc - Parsed doc comment of the symbol.
+     * @param self - Node of the symbol, where the type edge starts.
+     * @param file - File the symbol is in.
+     * @param typeScope - Scope that the type name resolves in.
+     * @returns The return value, or `null` when there is no tag and the symbol returns no typed value.
+     */
+    private returns;
+    /**
+     * @brief Builds the example of a symbol: the documented one, or one generated from its signature.
+     *
+     * @param symbol - Symbol the example is for.
+     * @param scope - Where the symbol sits in the file.
+     * @param documented - Example from the doc comment, or `null` when there is none.
+     * @returns The highlighted example with its origin, or `null` when none can be built.
+     */
+    private example;
+    /**
+     * @brief Renders a plain doc tag. The subject of a `throws` tag links to the types it names.
+     *
+     * @param tag - Tag to render.
+     * @param self - Node of the symbol the tag belongs to.
+     * @param file - File the symbol is in.
+     * @param typeScope - Scope that the names in the tag resolve in.
+     * @returns The tag as the symbol's page shows it.
+     */
+    private tag;
+    /**
+     * @brief Renders a description. Inline code that names a type or function, and glossary terms, become links.
+     *
+     * @param markdown - Markdown to render.
+     * @param from - Node the description belongs to. Links start here.
+     * @param file - File the description is in.
+     * @param typeScope - Scope that the names in the description resolve in.
+     * @returns The rendered HTML, `''` for an empty description.
+     */
+    private html;
+}

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

@@ -0,0 +1,126 @@
+import type { EdgeKind, LinkedText, NodeRef } from '../../model';
+import type { GraphBuilder } from '../graph/builder';
+/**
+ * @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 {
+    readonly path: string | null;
+    readonly family: string | null;
+    readonly typeParameters: ReadonlySet<string>;
+}
+/** Scope of a name in a document: any language, no file. */
+export declare const PROSE_SCOPE: TypeScope;
+/**
+ * @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. Created with `new TypeIndex()`.
+ *
+ * @property byName - Declarations of each name.
+ */
+export declare class TypeIndex {
+    private readonly byName;
+    /**
+     * @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;
+    /**
+     * @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;
+}
+/**
+ * @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;
+    /**
+     * @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;
+    /**
+     * @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;
+}
+/**
+ * @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
+ * `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.
+     *
+     * @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);
+    /**
+     * @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;
+    /**
+     * @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

@@ -0,0 +1,73 @@
+import type { FileContent } from '../model';
+import type { CodeHighlighter } from './highlight';
+import type { LinkResolver, MarkdownRenderer } from './markdown/renderer';
+/**
+ * @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 {
+    readonly title: string;
+    readonly description: string;
+    readonly content: FileContent;
+}
+/**
+ * @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;
+/**
+ * @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>;
+/**
+ * @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.
+     *
+     * @param markdownRenderer - Renders markdown to HTML and collects its headings.
+     * @param highlighter - Highlights text files by their language.
+     */
+    constructor(markdownRenderer: MarkdownRenderer, highlighter: CodeHighlighter);
+    /**
+     * @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>;
+    /**
+     * @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>;
+    /**
+     * @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

@@ -0,0 +1,37 @@
+/**
+ * @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 {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    readonly date: string;
+    readonly body: string;
+}
+/**
+ * @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 {
+    readonly intro: string;
+    readonly decisions: readonly ParsedDecision[];
+}
+/**
+ * @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.
+ */
+export declare function parseDecisions(markdown: string): ParsedDecisions;