@g3nomaly/analyze 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,60 @@
+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';
+/**
+ * @brief The markdown file whose links are resolved.
+ *
+ * @property node - The node that shows the text. Edges start here.
+ * @property root - Absolute directory `path` is relative to.
+ * @property path - Path of the file inside `root`.
+ * @property prefix - Prefix the bundle puts in front of paths from `root`.
+ */
+export interface LinkOrigin {
+    readonly node: NodeRef;
+    readonly root: string;
+    readonly path: string;
+    readonly prefix: string;
+}
+/**
+ * @brief Creates the link resolver for each piece of markdown of a scan. One place
+ * decides what prose can link to: files, types, functions and glossary terms.
+ *
+ * Holds the graph, the type linker and the term linker. Created once per scan
+ * 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;
+    /**
+     * @brief Creates the resolver factory.
+     *
+     * @param graph - Receives the edges that resolved references record.
+     * @param linker - Links type and function names in inline code.
+     * @param terms - Links glossary terms in prose.
+     */
+    constructor(graph: GraphBuilder, linker: TypeLinker, terms: TermLinker);
+    /**
+     * @brief Makes the resolver for markdown that comes from a file: a page, a term, a decision.
+     *
+     * @param origin - The file the markdown is in.
+     * @param relation - Kind of the edge a link to a file, type or function records.
+     * @returns A resolver for one render of that text.
+     */
+    forFile(origin: LinkOrigin, relation?: EdgeKind): LinkResolver;
+    /**
+     * @brief Makes the resolver for the description of a symbol, parameter or field. A doc
+     * comment has no links to files, so only inline code and terms resolve.
+     *
+     * @param from - Node the description belongs to.
+     * @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,35 @@
+/**
+ * @brief One line of a markdown text.
+ *
+ * @property text - The line as written, without its line break.
+ * @property heading - Depth and plain text of the line when it is an ATX heading such as `## Terms`. `null` otherwise.
+ */
+export interface MarkdownLine {
+    readonly text: string;
+    readonly heading: {
+        readonly depth: number;
+        readonly text: string;
+    } | null;
+}
+/**
+ * @brief Splits markdown into lines and marks the headings. A `#` line inside a
+ * fenced code block is code, not a heading.
+ *
+ * @param markdown - Markdown text without frontmatter.
+ * @returns One entry per line, in order.
+ */
+export declare function outlineLines(markdown: string): MarkdownLine[];
+/**
+ * @brief Removes inline markdown markers from a short text such as a heading.
+ *
+ * @param markdown - Inline markdown, for example `**Lane** (_route_)`.
+ * @returns The text a reader sees, for example `Lane (route)`.
+ */
+export declare function plainText(markdown: string): string;
+/**
+ * @brief Joins lines back into markdown and drops blank lines at both ends.
+ *
+ * @param lines - Lines to join, in order.
+ * @returns The markdown text, with no blank lines at either end.
+ */
+export declare function joinLines(lines: readonly MarkdownLine[]): string;

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

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

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

@@ -0,0 +1,96 @@
+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';
+/**
+ * @brief 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;
+    /**
+     * @brief Creates a planner.
+     *
+     * @param graph - Receives the API, operation and parameter nodes and their edges.
+     * @param markdown - Renders the descriptions.
+     * @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);
+    /**
+     * @brief Adds one OpenAPI document.
+     *
+     * @param parent - Folder or skill the file is in.
+     * @param file - The file: its root, path, display path and prefix.
+     * @param document - The parsed file.
+     * @returns The node of the document.
+     */
+    plan(parent: NodeRef, file: DocFile, document: JsonObject): NodeRef;
+    /**
+     * @brief Renders the tags a document declares, in document order, each with its description.
+     *
+     * @param document - The parsed document.
+     * @param node - Node of the document.
+     * @param file - The file the document is in.
+     * @returns The tags, with their descriptions rendered as HTML.
+     */
+    private tags;
+    /**
+     * @brief Adds one operation with its parameters.
+     *
+     * @param owner - The document the operation is in.
+     * @param document - The parsed document, for resolving refs.
+     * @param found - The operation as found in the document.
+     */
+    private planOperation;
+    /**
+     * @brief Reads the request body of an operation.
+     *
+     * @param document - The parsed document, for resolving refs.
+     * @param operation - The operation object of the document.
+     * @param node - Node of the operation. Schemas of the body become `type` edges from it.
+     * @param file - The file the document is in.
+     * @returns The body, or `null` for an operation without one.
+     */
+    private requestBody;
+    /**
+     * @brief Reads the responses of an operation.
+     *
+     * @param document - The parsed document, for resolving refs.
+     * @param operation - The operation object of the document.
+     * @param file - The file the document is in.
+     * @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;
+    /**
+     * @brief 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 file - The file the document is in.
+     * @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/packages.d.ts

@@ -0,0 +1,28 @@
+import type { PackageRole } from '../model';
+import type { Source } from './files';
+/**
+ * @brief A directory with a package manifest, as `detectPackages` reads it.
+ *
+ * @property packageName - Name the manifest gives, such as `@g3nomaly/core`, or the directory name when it gives none.
+ * @property role - `app`, `library` or `workspace`. A manifest that declares an executable makes an app; otherwise a directory named `apps`/`app` above it makes an app, one named `libs`/`lib` a library, and else the manifest decides.
+ * @property manifest - Display path of the manifest that marks the package, such as `packages/core/package.json`.
+ * @property version - Version the manifest gives, or `null`.
+ * @property description - Description the manifest gives, or `''`.
+ */
+export interface PackageInfo {
+    readonly packageName: string;
+    readonly role: PackageRole;
+    readonly manifest: string;
+    readonly version: string | null;
+    readonly description: string;
+}
+/**
+ * @brief Finds the packages of a set of sources: every directory below a root with a manifest that one of the readers understands.
+ *
+ * A directory with several manifests is read by the first reader in `READERS` that understands one. The root
+ * directory of a source is left out: it is the repository itself.
+ *
+ * @param sources - Directories with their files, such as the code sources of a scan.
+ * @returns Packages by display path of their directory, such as `packages/core`.
+ */
+export declare function detectPackages(sources: readonly Source[]): Promise<Map<string, PackageInfo>>;

package/dist/scanner/reporter.d.ts

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

package/dist/scanner/scanner.d.ts

@@ -0,0 +1,66 @@
+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';
+/**
+ * @brief 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.
+ *
+ * @property skills - Directories of the skills section.
+ * @property docs - Directories of the docs section.
+ * @property code - Directories of the code and database sections.
+ * @property tasks - The task-manager trees. Their files are shown in the tasks section, and nowhere else.
+ */
+export interface ScanInput {
+    readonly skills: readonly Source[];
+    readonly docs: readonly Source[];
+    readonly code: readonly Source[];
+    readonly tasks: readonly TaskTreeSource[];
+}
+/**
+ * @brief What a {@link RepositoryScanner} is built with.
+ *
+ * @property grammarDir - Directory that relative grammar paths resolve against.
+ * @property highlighter - Highlights the code blocks of the markdown.
+ * @property reporter - Receives problems that do not stop a scan. Defaults to `silentReporter`.
+ */
+export interface ScannerOptions {
+    readonly grammarDir: string;
+    readonly highlighter: CodeHighlighter;
+    readonly reporter?: Reporter;
+}
+/**
+ * @brief 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;
+    /**
+     * @brief Creates the grammar loader and the renderers the scans share.
+     *
+     * @param options - Grammar directory, highlighter and optional reporter.
+     */
+    constructor(options: ScannerOptions);
+    /**
+     * @brief Scans the directories of every section into one graph: skills, docs,
+     * code, database and tasks, in that order.
+     *
+     * @param input - The directories of each section.
+     * @returns The nodes and edges of the bundle, without its meta and semantic index.
+     */
+    scan(input: ScanInput): Promise<Pick<DocsBundle, 'nodes' | 'edges'>>;
+}

package/dist/scanner/schema/definitions.d.ts

@@ -0,0 +1,79 @@
+import type { EdgeKind, LinkedText, 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 TypeExpression } from './describe';
+import type { DefinitionRegistry } from './registry';
+/**
+ * @brief The file a definition is in.
+ *
+ * @property ref - Node of the file. Definitions become its children.
+ * @property file - The file the definitions are in.
+ * @property anchors - Anchors already used on the page of the file.
+ */
+export interface DefinitionOwner {
+    readonly ref: NodeRef;
+    readonly file: DocFile;
+    readonly anchors: Set<string>;
+}
+/**
+ * @brief Adds named JSON Schemas to the graph: one `definition` node per schema and
+ * one `field` node per property. A `$ref` in a type becomes a link to the
+ * definition it names, and an edge: `type` from a property, `extends` from a
+ * definition.
+ *
+ * Holds the graph, the markdown renderer, the prose resolvers and the
+ * definition registry. Created once per scan by `RepositoryScanner`. Used by
+ * `JsonSchemaPlanner` for the schemas of a schema file and by
+ * `OpenApiPlanner` for `components.schemas` and for the schemas of
+ * parameters, request bodies and responses.
+ *
+ * @example
+ * const registry = new DefinitionRegistry();
+ * const definitions = new DefinitionPlanner(graph, markdown, resolvers, registry);
+ */
+export declare class DefinitionPlanner {
+    private readonly graph;
+    private readonly markdown;
+    private readonly resolvers;
+    private readonly registry;
+    /**
+     * @brief Creates a planner.
+     *
+     * @param graph - Receives the definition and field nodes and their edges.
+     * @param markdown - Renders the descriptions.
+     * @param resolvers - Links what descriptions refer to.
+     * @param registry - Receives every definition, and finds the targets of refs.
+     */
+    constructor(graph: GraphBuilder, markdown: MarkdownRenderer, resolvers: ProseResolvers, registry: DefinitionRegistry);
+    /**
+     * @brief Adds one definition with its properties.
+     *
+     * @param owner - The file the definition is in.
+     * @param name - Name of the definition, as the page shows it.
+     * @param pointer - JSON pointer of the schema inside its file. Refs to that place link to the definition.
+     * @param schema - The schema: an object, or `true` or `false`.
+     * @returns The node of the definition.
+     */
+    add(owner: DefinitionOwner, name: string, pointer: string, schema: unknown): NodeRef;
+    /**
+     * @brief Turns a type expression into text with links to the definitions its refs name.
+     *
+     * @param expression - The type expression, with the spans of its refs.
+     * @param from - Node the expression belongs to.
+     * @param file - The file the expression is in. A relative ref starts there.
+     * @param relation - Kind of the edge each resolved ref records from `from`.
+     * @returns The text with a link for every ref the scan can resolve. A resolved ref reads as the name of its target, so a ref to a whole file reads as the title of its schema.
+     */
+    linked(expression: TypeExpression, from: NodeRef, file: DocFile, relation: EdgeKind): LinkedText;
+    /**
+     * @brief Renders a description as HTML.
+     *
+     * @param markdown - Markdown of the description, or `''`.
+     * @param node - Node the description belongs to. Links in it become edges from this node.
+     * @param file - The file the description is in. Its root, path and prefix resolve links.
+     * @returns HTML, or `''`.
+     */
+    html(markdown: string, node: NodeRef, { root, path, prefix }: DocFile): Promise<string>;
+}

package/dist/scanner/schema/describe.d.ts

@@ -0,0 +1,105 @@
+/** A JSON object as parsed from JSON or YAML. */
+export type JsonObject = Readonly<Record<string, unknown>>;
+/**
+ * @brief Tells a JSON object from every other value: true for an object that is no
+ * array and not `null`.
+ *
+ * @param value - Any value, as parsed from JSON or YAML.
+ */
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/**
+ * @brief A span of a type expression that stands for a `$ref`.
+ *
+ * @property start - Offset in the type text where the span starts.
+ * @property end - Offset in the type text where the span ends.
+ * @property ref - The `$ref` as the schema writes it.
+ */
+export interface SchemaRef {
+    readonly start: number;
+    readonly end: number;
+    readonly ref: string;
+}
+/**
+ * @brief What a schema allows, as text: `string[]`, `Cat | Dog`, `"open" | "closed"`.
+ *
+ * @property text - The type as text.
+ * @property refs - The spans of the text that are `$ref`s, in text order, not overlapping.
+ */
+export interface TypeExpression {
+    readonly text: string;
+    readonly refs: readonly SchemaRef[];
+}
+/**
+ * @brief One property of an object schema. A nested property has a dotted name.
+ *
+ * @property name - Name of the property, dotted for a nested one: `city`, `address.city`, `items[].sku`.
+ * @property type - The type of the property.
+ * @property required - True when the parent schema requires the property.
+ * @property defaultValue - The default as JSON, or `null`.
+ * @property description - Markdown.
+ * @property constraints - Keywords that narrow the type, as `keyword: value`.
+ */
+export interface SchemaProperty {
+    readonly name: string;
+    readonly type: TypeExpression;
+    readonly required: boolean;
+    readonly defaultValue: string | null;
+    readonly description: string;
+    readonly constraints: readonly string[];
+}
+/**
+ * @brief What a schema says, in the shape the site shows.
+ *
+ * @property type - The type of the schema.
+ * @property description - Markdown.
+ * @property constraints - Keywords that narrow the type, as `keyword: value`.
+ * @property values - Values of an `enum` or a `const`, as JSON. Empty when they fit inside `type`.
+ * @property deprecated - True when the schema is deprecated.
+ * @property properties - Every property, nested ones included, in schema order.
+ */
+export interface SchemaDescription {
+    readonly type: TypeExpression;
+    readonly description: string;
+    readonly constraints: readonly string[];
+    readonly values: readonly string[];
+    readonly deprecated: boolean;
+    readonly properties: readonly SchemaProperty[];
+}
+/**
+ * @brief Reads the last part of a `$ref` as a name.
+ *
+ * @param ref - A `$ref`, such as `#/$defs/Booking` or `cargo.schema.json`.
+ * @returns `Booking` for a ref into a file, the file name for a ref to a whole file.
+ */
+export declare function refName(ref: string): string;
+/**
+ * @brief Decodes one segment of a JSON pointer.
+ *
+ * @param segment - One segment between two `/`, possibly percent-encoded.
+ * @returns The key it names: percent escapes decoded, `~1` as `/` and `~0` as `~`.
+ */
+export declare function decodePointerSegment(segment: string): string;
+/**
+ * @brief Writes what a schema allows as a type expression.
+ *
+ * @param schema - A schema: an object, or `true` or `false`.
+ * @param depth - Nesting of the schema inside the one that is described.
+ * @returns The expression. `any` for a schema that states no type.
+ */
+export declare function typeOf(schema: unknown, depth?: number): TypeExpression;
+/**
+ * @brief Describes a JSON Schema in the shape the site shows: a type expression, a
+ * description, constraints and a flat list of properties.
+ *
+ * @param schema - The schema: an object, or `true` or `false`.
+ * @returns The description. A value that is no schema is described as `any`.
+ */
+export declare function describeSchema(schema: unknown): SchemaDescription;
+/**
+ * @brief Tells whether a schema says anything about a value: true when it has a
+ * type, properties, a composition, values or a `$ref`. A file that only
+ * holds `$defs` has a root schema that does not.
+ *
+ * @param schema - The schema to check.
+ */
+export declare function describesValue(schema: JsonObject): boolean;

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

@@ -0,0 +1,49 @@
+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 { DefinitionPlanner } from './definitions';
+import { type JsonObject } from './describe';
+import type { DefinitionRegistry } from './registry';
+/**
+ * @brief Adds a JSON Schema file to the graph: one `schema` node for the file, with
+ * its text, and one definition per schema it names. The root schema is a
+ * definition when it describes a value.
+ *
+ * Holds the graph, the file 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 a JSON Schema.
+ *
+ * @example
+ * const registry = new DefinitionRegistry();
+ * const definitions = new DefinitionPlanner(graph, markdown, resolvers, registry);
+ * const schemas = new JsonSchemaPlanner(graph, files, resolvers, definitions, registry);
+ */
+export declare class JsonSchemaPlanner {
+    private readonly graph;
+    private readonly files;
+    private readonly resolvers;
+    private readonly definitions;
+    private readonly registry;
+    /**
+     * @brief Creates a planner.
+     *
+     * @param graph - Receives the schema and definition nodes and their edges.
+     * @param files - Renders the text of the file.
+     * @param resolvers - Links what the file refers to.
+     * @param definitions - Adds the definitions the schema names.
+     * @param registry - Receives the file and its `$id`, so refs to the file resolve.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, resolvers: ProseResolvers, definitions: DefinitionPlanner, registry: DefinitionRegistry);
+    /**
+     * @brief Adds one schema file.
+     *
+     * @param parent - Folder or skill the file is in.
+     * @param file - The file: its root, path, display path and prefix.
+     * @param schema - The parsed file.
+     * @returns The node of the file.
+     */
+    plan(parent: NodeRef, file: DocFile, schema: JsonObject): NodeRef;
+}

package/dist/scanner/schema/registry.d.ts

@@ -0,0 +1,68 @@
+import type { NodeRef } from '../../model';
+/**
+ * @brief Writes a JSON pointer in one spelling, so two spellings of one place compare equal.
+ *
+ * @param pointer - A pointer, with or without the `#` in front.
+ * @returns The pointer with every segment decoded. `''` names the root.
+ */
+export declare function normalizePointer(pointer: string): string;
+/**
+ * @brief What a `$ref` points at.
+ *
+ * @property ref - The node that shows the place.
+ * @property name - Name of the node, as a type expression shows it.
+ */
+export interface RefTarget {
+    readonly ref: NodeRef;
+    readonly name: string;
+}
+/**
+ * @brief Finds the nodes that `$ref`s point at, across the JSON Schema files and
+ * OpenAPI documents of one scan.
+ *
+ * Created once per scan by `RepositoryScanner` and shared by `JsonSchemaPlanner`,
+ * `OpenApiPlanner` and `DefinitionPlanner`. The planners register every file and
+ * definition when they add it; `DefinitionPlanner` resolves refs when the content
+ * of the graph is built. By then every file is read, so a ref can point into a
+ * later file.
+ *
+ * @property places - The node at each `path#pointer` place.
+ * @property ids - Path of each schema file by its `$id`.
+ * @example
+ * const registry = new DefinitionRegistry();
+ */
+export declare class DefinitionRegistry {
+    private readonly places;
+    private readonly ids;
+    /**
+     * @brief Records the node that shows a place in a file.
+     *
+     * @param path - Path of the file, as the site shows it.
+     * @param pointer - JSON pointer of the place inside the file. `''` is the whole file.
+     * @param target - The node that shows the place, and its name.
+     */
+    register(path: string, pointer: string, target: RefTarget): void;
+    /**
+     * @brief Records the `$id` of a schema file, so a ref by that id finds the file.
+     *
+     * @param id - The `$id`, an absolute URI.
+     * @param path - Path of the file, as the site shows it.
+     */
+    registerId(id: string, path: string): void;
+    /**
+     * @brief Finds the node a `$ref` points at.
+     *
+     * @param ref - The `$ref` as written: `#/$defs/Cargo`, `cargo.schema.json#/$defs/Cargo`, or the `$id` of a file.
+     * @param fromPath - Path of the file the ref is in. A relative ref starts there.
+     * @returns The node and its name, or `null` when the ref leaves the scan or names nothing the site shows.
+     */
+    resolve(ref: string, fromPath: string): RefTarget | null;
+    /**
+     * @brief Finds the file a URI names.
+     *
+     * @param uri - The part of a ref in front of the `#`.
+     * @param fromPath - Path of the file the ref is in, as the site shows it.
+     * @returns Path of the file: the same file for an empty URI, a registered `$id`, or a relative path. `null` for any other absolute URI.
+     */
+    private pathOf;
+}