@g3nomaly/analyze 0.0.0-stage → 0.1.0

package/dist/scanner/files.d.ts

@@ -0,0 +1,60 @@
+/** 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. */
+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;
+}
+/** Lists the files of a directory tree. */
+export interface FileLister {
+    /** 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.
+ */
+export declare class RepoFileLister implements FileLister {
+    private readonly excludes;
+    /**
+     * Compiles the exclude globs.
+     *
+     * @param excludes - Globs on top of {@link DEFAULT_EXCLUDES}, matched against root-relative POSIX paths.
+     */
+    constructor(excludes?: readonly string[]);
+    /**
+     * 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. */
+    private isExcluded;
+    /**
+     * Lists the tracked and untracked files git does not ignore.
+     *
+     * @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.
+     *
+     * @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.
+ */
+export declare function compareTreePaths(a: string, b: string): number;

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

@@ -0,0 +1,30 @@
+/** One term as the glossary file writes it. */
+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. */
+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:
+ *
+ * - **Bold terms**: a line that opens with a bold name, followed by its
+ *   definition. Headings group the terms.
+ * - **Heading terms**: when no line opens with a bold name, each heading of
+ *   the deepest level is a term, and the headings above it are groups.
+ *
+ * In both layouts an `_Avoid_: a, b` line lists the words a term replaces.
+ *
+ * @param markdown - The glossary file without frontmatter.
+ * @returns The terms in file order and the text around them.
+ */
+export declare function parseGlossary(markdown: string): ParsedGlossary;

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

@@ -0,0 +1,42 @@
+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';
+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.
+ *
+ * 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();
+ * const resolvers = new ProseResolvers(graph, linker, new TermLinker(terms, graph));
+ * const glossaries = new GlossaryPlanner(graph, files, markdown, terms, resolvers);
+ */
+export declare class GlossaryPlanner {
+    private readonly graph;
+    private readonly files;
+    private readonly markdown;
+    private readonly terms;
+    private readonly resolvers;
+    /**
+     * Creates a planner.
+     *
+     * @param terms - Receives every term. Must be the index the `TermLinker` of `resolvers` reads.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, markdown: MarkdownRenderer, terms: TermIndex, resolvers: ProseResolvers);
+    /**
+     * Reads one glossary file 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/glossary/terms.d.ts

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

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

@@ -0,0 +1,55 @@
+import { type Edge, type EdgeKind, type GraphNode, type NodeKind, type NodeRef } from '../../model';
+/** The fields of a node that fix its place in the tree and its route. Known when the node is added. */
+type IdentityKey = 'kind' | 'name' | 'parent' | 'slug' | 'anchor';
+/** The node types whose `kind` can be `K`. */
+type NodeOf<K extends NodeKind, N = GraphNode> = N extends GraphNode ? (K extends N['kind'] ? N : never) : never;
+/** The identity fields of a node of kind `K`, as `add` takes them. */
+export type IdentityOf<K extends NodeKind> = Omit<Pick<NodeOf<K>, Extract<keyof NodeOf<K>, IdentityKey>>, 'kind'>;
+/** The fields of a node of kind `K` that its `ContentSource` produces. */
+export type ContentOf<K extends NodeKind> = Omit<NodeOf<K>, IdentityKey>;
+/** Produces the rest of a node. Runs in `build`, when every node has its place, so it can link to any of them. */
+export type ContentSource<K extends NodeKind> = (self: NodeRef) => ContentOf<K> | Promise<ContentOf<K>>;
+/**
+ * Builds the graph in two passes.
+ *
+ * 1. The scanners `add` every node: its kind, name and parent. That fixes the
+ *    tree, the routes and the refs.
+ * 2. `build` requests the content of every node. By then a link from any node to
+ *    any other can be resolved.
+ *
+ * Holds the identity and content source of every node, the edges, the folder
+ * nodes by path and the file nodes by path. A node's `NodeRef` is its index.
+ * Created once per scan by `RepositoryScanner`, which calls `build` at the end;
+ * every planner (`code/`, `sql/`, `docs`, `skills/`, `tasks/`, `glossary/`,
+ * `decisions/`, `schema/`, `openapi/`) and `ProseResolvers` add nodes and edges to it.
+ */
+export declare class GraphBuilder {
+    /** `identities[ref]` and `contents[ref]` together make the node at `ref`. */
+    private readonly identities;
+    private readonly contents;
+    private readonly edges;
+    private readonly folders;
+    private readonly files;
+    /** Adds a node. Kinds without content of their own, such as folders, take no `content`. */
+    add<K extends NodeKind>(kind: K, identity: IdentityOf<K>, ...content: Record<never, never> extends ContentOf<K> ? [] : [ContentSource<K>]): NodeRef;
+    /** The folder at `directory` below `parent`, created with its ancestors on first use. `''` is `parent` itself. */
+    folder(parent: NodeRef, directory: string): NodeRef;
+    /** Records which node shows the file at `path`, so links to that file can find it. */
+    registerFile(path: string, ref: NodeRef): void;
+    /** Finds the node registered for the file at `path`, or `undefined`. */
+    fileAt(path: string): NodeRef | undefined;
+    /** In-site href of a node. `fragment` replaces the node's own anchor, for a heading on a page. */
+    href(ref: NodeRef, fragment?: string): string;
+    /** Records an edge. The same edge recorded twice is kept once. */
+    link(from: NodeRef, kind: EdgeKind, to: NodeRef): void;
+    /**
+     * Runs the content source of every node and returns the finished graph.
+     *
+     * @returns Nodes in `NodeRef` order, and edges sorted by source, kind (in `EDGE_KINDS` order) and target.
+     */
+    build(): Promise<{
+        nodes: GraphNode[];
+        edges: Edge[];
+    }>;
+}
+export {};

package/dist/scanner/highlight.d.ts

@@ -0,0 +1,31 @@
+import type { Element } from 'hast';
+/** Highlights code of a language into HTML or into a HAST `<pre>` element. */
+export interface CodeHighlighter {
+    toHtml(code: string, language: string): Promise<string>;
+    toHast(code: string, language: string): Promise<Element>;
+}
+/**
+ * Highlights with shiki. Colors are emitted as `var(--syntax-*)` references,
+ * so the page stylesheet owns the palette in light and dark mode. Holds one
+ * shiki highlighter, created on first use, and loads each language once; an
+ * unknown language falls back to plain text. Created in `api/services.ts` and
+ * passed to `RepositoryScanner`, which hands it to the renderers and planners.
+ */
+export declare class ShikiHighlighter implements CodeHighlighter {
+    private highlighter;
+    private readonly loading;
+    /** Highlights code into an HTML string. */
+    toHtml(code: string, language: string): Promise<string>;
+    /** Highlights code into the HAST `<pre>` element shiki produces. */
+    toHast(code: string, language: string): Promise<Element>;
+    /**
+     * Creates the shiki highlighter on first use and loads a language.
+     *
+     * @returns The highlighter and the language name to pass to it: the lowercased `language`, or `text` when shiki lacks it.
+     */
+    private prepare;
+    /** Loads a language once, sharing the pending load between callers. */
+    private resolveLanguage;
+    /** Loads a bundled language into shiki, or returns `text` when it is not bundled or fails to load. */
+    private load;
+}

package/dist/scanner/index.d.ts

@@ -0,0 +1,40 @@
+export { type ExtractedFile, type RawField, type RawParameter, type RawSymbol, SymbolExtractor } from './code/extract';
+export { GrammarLoader } from './code/grammar';
+export type { CallStyle, DocStyle, LanguageSpec } from './code/language';
+export { LANGUAGES, LanguageRegistry } from './code/languages';
+export { CodePlanner, type SourceFile } from './code/planner';
+export { type FileContext, SymbolPlanner } from './code/symbols';
+export { CallableIndex, PROSE_SCOPE, TypeIndex, TypeLinker, type TypeScope } from './code/types';
+export { FileRenderer, type RenderedFile } from './content';
+export { type ParsedDecision, type ParsedDecisions, parseDecisions } from './decisions/parse';
+export { DecisionPlanner } from './decisions/planner';
+export { type DocFile, type DocKind, DocPlanner, docKind } from './docs';
+export { compareTreePaths, DEFAULT_EXCLUDES, type FileLister, RepoFileLister, type Source } from './files';
+export { type ParsedGlossary, type ParsedTerm, parseGlossary } from './glossary/parse';
+export { GlossaryPlanner } from './glossary/planner';
+export { type TermFinder, TermIndex, TermLinker, type TermMatch } from './glossary/terms';
+export { type ContentOf, type ContentSource, GraphBuilder, type IdentityOf } from './graph/builder';
+export { type CodeHighlighter, ShikiHighlighter } from './highlight';
+export { type LinkOrigin, ProseResolvers } from './markdown/links';
+export { joinLines, type MarkdownLine, outlineLines, plainText } from './markdown/outline';
+export { type LinkResolver, MarkdownRenderer, type RenderedMarkdown } from './markdown/renderer';
+export { OpenApiPlanner } from './openapi/planner';
+export { type Reporter, silentReporter } from './reporter';
+export { RepositoryScanner, type ScanInput, type ScannerOptions } from './scanner';
+export { type DefinitionOwner, DefinitionPlanner } from './schema/definitions';
+export { describeSchema, type JsonObject, refName, type SchemaDescription, type SchemaProperty, type SchemaRef, type TypeExpression, typeOf, } from './schema/describe';
+export { JsonSchemaPlanner } from './schema/planner';
+export { DefinitionRegistry, normalizePointer, type RefTarget } from './schema/registry';
+export { classifySkillFile, type SkillFileKind } from './skills/classify';
+export { isInside, SKILL_FILE, type SkillLayout, skillLayouts, skillOwnedFiles } from './skills/layout';
+export { SkillPlanner } from './skills/planner';
+export { type SpecKind, SpecPlanner, specKind } from './specs';
+export { type CatalogFile, type CatalogPlace, CatalogPlanner } from './sql/catalog';
+export { DatabasePlanner } from './sql/database';
+export { type ParsedColumn, type ParsedForeignKey, type ParsedIndex, type ParsedObject, type ParsedSchema, type ParsedTable, parseSqlSchema, } from './sql/parse';
+export { SqlPlanner } from './sql/planner';
+export { type ParsedColumnRef, type ParsedParameter, type ParsedQuery, type ParsedQueryTable, type ParsedResultColumn, parseQueryFile, } from './sql/query';
+export { type ColumnEntry, columnOf, type TableEntry, TableRegistry } from './sql/registry';
+export { type SqlComment, type SqlToken, tokenizeSql } from './sql/tokens';
+export { layoutTree, type PlanFiles, type PhaseFiles, type TreeFiles } from './tasks/layout';
+export { TaskPlanner, type TaskTreeSource } from './tasks/planner';

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

@@ -0,0 +1,9 @@
+/** A markdown document split into its YAML frontmatter and the rest. */
+export interface Frontmatter {
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly body: string;
+}
+/** Splits a leading YAML block from a markdown document. Invalid YAML yields empty data. */
+export declare function splitFrontmatter(source: string): Frontmatter;
+/** Reads a frontmatter field as trimmed text, or `null` when it is missing, blank or no string. */
+export declare function stringField(data: Readonly<Record<string, unknown>>, key: string): string | null;

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

@@ -0,0 +1,50 @@
+import type { EdgeKind, NodeRef } from '../../model';
+import { type TypeLinker, type TypeScope } from '../code/types';
+import type { TermLinker } from '../glossary/terms';
+import type { GraphBuilder } from '../graph/builder';
+import type { LinkResolver } from './renderer';
+/** The markdown file whose links are resolved. */
+export interface LinkOrigin {
+    /** The node that shows the text. Edges start here. */
+    readonly node: NodeRef;
+    /** Absolute directory `path` is relative to. */
+    readonly root: string;
+    /** Path of the file inside `root`. */
+    readonly path: string;
+    /** Prefix the bundle puts in front of paths from `root`. */
+    readonly prefix: string;
+}
+/**
+ * Creates the link resolver for each piece of markdown of a scan. One place
+ * decides what prose can link to: files, types, functions and glossary terms.
+ *
+ * Holds the graph, the type linker and the term linker. Created once per scan
+ * by `RepositoryScanner` and passed to every planner that renders markdown.
+ *
+ * @example
+ * const resolvers = new ProseResolvers(graph, linker, new TermLinker(terms, graph));
+ */
+export declare class ProseResolvers {
+    private readonly graph;
+    private readonly linker;
+    private readonly terms;
+    /** Creates the resolver factory. */
+    constructor(graph: GraphBuilder, linker: TypeLinker, terms: TermLinker);
+    /**
+     * Resolver for markdown that comes from a file: a page, a term, a decision.
+     *
+     * @param relation - Kind of the edge a link to a file, type or function records.
+     * @returns A resolver for one render of that text.
+     */
+    forFile(origin: LinkOrigin, relation?: EdgeKind): LinkResolver;
+    /**
+     * Resolver for the description of a symbol, parameter or field. A doc
+     * comment has no links to files, so only inline code and terms resolve.
+     *
+     * @param from - Node the description belongs to.
+     * @param path - Path of the source file.
+     * @param scope - Decides which declaration a type name in inline code means.
+     * @returns A resolver for one render of that description.
+     */
+    forDescription(from: NodeRef, path: string, scope: TypeScope): LinkResolver;
+}

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

@@ -0,0 +1,27 @@
+/** One line of a markdown text. */
+export interface MarkdownLine {
+    readonly text: string;
+    /** Set when the line is an ATX heading such as `## Terms`. */
+    readonly heading: {
+        readonly depth: number;
+        readonly text: string;
+    } | null;
+}
+/**
+ * Splits markdown into lines and marks the headings. A `#` line inside a
+ * fenced code block is code, not a heading.
+ *
+ * @param markdown - Markdown text without frontmatter.
+ */
+export declare function outlineLines(markdown: string): MarkdownLine[];
+/**
+ * Removes inline markdown markers from a short text such as a heading.
+ *
+ * @param markdown - Inline markdown, for example `**Lane** (_route_)`.
+ * @returns The text a reader sees, for example `Lane (route)`.
+ */
+export declare function plainText(markdown: string): string;
+/**
+ * Joins lines back into markdown and drops blank lines at both ends.
+ */
+export declare function joinLines(lines: readonly MarkdownLine[]): string;

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

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

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

@@ -0,0 +1,84 @@
+import type { NodeRef } from '../../model';
+import type { DocFile } from '../docs';
+import type { GraphBuilder } from '../graph/builder';
+import type { ProseResolvers } from '../markdown/links';
+import type { MarkdownRenderer } from '../markdown/renderer';
+import type { DefinitionPlanner } from '../schema/definitions';
+import { type JsonObject } from '../schema/describe';
+import type { DefinitionRegistry } from '../schema/registry';
+/**
+ * Adds an OpenAPI document to the graph: one `api` node for the document,
+ * one `operation` node per method on a path and per webhook, one `parameter`
+ * node per parameter, and one definition per entry of `components.schemas`.
+ *
+ * Holds the graph, the markdown renderer, the prose resolvers, the shared
+ * `DefinitionPlanner` and the `DefinitionRegistry`. Created by
+ * `RepositoryScanner` and used by `SpecPlanner` for every JSON or YAML file
+ * that is an OpenAPI 3 document.
+ *
+ * @example
+ * const registry = new DefinitionRegistry();
+ * const definitions = new DefinitionPlanner(graph, markdown, resolvers, registry);
+ * const apis = new OpenApiPlanner(graph, markdown, resolvers, definitions, registry);
+ */
+export declare class OpenApiPlanner {
+    private readonly graph;
+    private readonly markdown;
+    private readonly resolvers;
+    private readonly definitions;
+    private readonly registry;
+    /**
+     * Creates a planner.
+     *
+     * @param resolvers - Links what descriptions refer to.
+     * @param definitions - Adds the schema definitions and links type expressions.
+     * @param registry - Receives the document, so refs to it from other files resolve.
+     */
+    constructor(graph: GraphBuilder, markdown: MarkdownRenderer, resolvers: ProseResolvers, definitions: DefinitionPlanner, registry: DefinitionRegistry);
+    /**
+     * Adds one OpenAPI document.
+     *
+     * @param parent - Folder or skill the file is in.
+     * @param document - The parsed file.
+     * @returns The node of the document.
+     */
+    plan(parent: NodeRef, file: DocFile, document: JsonObject): NodeRef;
+    /**
+     * Renders the tags a document declares, in document order, each with its description.
+     *
+     * @param node - Node of the document.
+     */
+    private tags;
+    /**
+     * Adds one operation with its parameters.
+     *
+     * @param owner - The document the operation is in.
+     * @param document - The parsed document, for resolving refs.
+     */
+    private planOperation;
+    /**
+     * Reads the request body of an operation.
+     *
+     * @param document - The parsed document, for resolving refs.
+     * @param node - Node of the operation. Schemas of the body become `type` edges from it.
+     * @returns The body, or `null` for an operation without one.
+     */
+    private requestBody;
+    /**
+     * Reads the responses of an operation.
+     *
+     * @param document - The parsed document, for resolving refs.
+     * @param node - Node of the operation. A schema of a response becomes a `returns` edge from it, or a `throws` edge for an error.
+     * @returns The responses in document order.
+     */
+    private responses;
+    /**
+     * Reads the media types of a request body or a response.
+     *
+     * @param content - The `content` object: media type to media type object.
+     * @param node - Node of the operation.
+     * @param relation - Kind of the edge a schema records from the operation.
+     * @returns One entry per media type, in document order.
+     */
+    private content;
+}

package/dist/scanner/reporter.d.ts

@@ -0,0 +1,7 @@
+/** Receives problems that should not stop a scan. */
+export interface Reporter {
+    /** Reports one problem, as one line of plain text. */
+    warn(message: string): void;
+}
+/** A reporter that drops every warning. */
+export declare const silentReporter: Reporter;

package/dist/scanner/scanner.d.ts

@@ -0,0 +1,52 @@
+import { type DocsBundle } from '../model';
+import type { Source } from './files';
+import type { CodeHighlighter } from './highlight';
+import { type Reporter } from './reporter';
+import { type TaskTreeSource } from './tasks/planner';
+/**
+ * The directories one scan reads. Skills and docs each have their own. The
+ * code section and the database section are both read from `code`: source
+ * files go to the one, SQL files to the other.
+ */
+export interface ScanInput {
+    readonly skills: readonly Source[];
+    readonly docs: readonly Source[];
+    readonly code: readonly Source[];
+    /** The task-manager trees. Their files are shown in the tasks section, and nowhere else. */
+    readonly tasks: readonly TaskTreeSource[];
+}
+/** What a {@link RepositoryScanner} is built with. */
+export interface ScannerOptions {
+    /** Directory that relative grammar paths resolve against. */
+    readonly grammarDir: string;
+    readonly highlighter: CodeHighlighter;
+    readonly reporter?: Reporter;
+}
+/**
+ * Turns directories into the graph of a documentation site. Holds the parts
+ * that outlive one scan: the language registry, the symbol extractor, the
+ * grammar loader and the markdown and file renderers. Each scan builds a fresh
+ * graph and wires up every planner for it. Created in `api/services.ts` and
+ * run by `BundleBuilder`.
+ *
+ * @example
+ * const scanner = new RepositoryScanner({ grammarDir: import.meta.dir, highlighter: new ShikiHighlighter(), reporter });
+ * const { nodes, edges } = await scanner.scan({ skills: [], docs: [repository], code: [repository], tasks: [] });
+ */
+export declare class RepositoryScanner {
+    private readonly options;
+    private readonly registry;
+    private readonly extractor;
+    private readonly grammars;
+    private readonly markdown;
+    private readonly files;
+    /** Creates the grammar loader and the renderers the scans share. */
+    constructor(options: ScannerOptions);
+    /**
+     * Scans the directories of every section into one graph: skills, docs,
+     * code, database and tasks, in that order.
+     *
+     * @returns The nodes and edges of the bundle, without its meta and semantic index.
+     */
+    scan(input: ScanInput): Promise<Pick<DocsBundle, 'nodes' | 'edges'>>;
+}