@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/scanner/decisions/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';
+/**
+ * @brief 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.
+     *
+     * @param graph - Graph the file and decision nodes are added to.
+     * @param files - Renders the text of the decision log around the decisions.
+     * @param markdown - Renders the body of each decision.
+     * @param resolvers - Resolves the links of the decision log and its decisions.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, markdown: MarkdownRenderer, resolvers: ProseResolvers);
+    /**
+     * @brief Reads one decision log and adds its nodes.
+     *
+     * @param parent - Folder or section the file is in.
+     * @param root - Absolute directory `path` is relative to.
+     * @param path - Path of the file inside `root`.
+     * @param displayPath - Path the site shows.
+     * @param prefix - Prefix the bundle puts in front of paths from `root`.
+     * @returns The node of the file.
+     */
+    plan(parent: NodeRef, { root, path, displayPath, prefix }: DocFile): Promise<NodeRef>;
+}

package/dist/scanner/docs.d.ts

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

package/dist/scanner/files.d.ts

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

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

@@ -0,0 +1,40 @@
+/**
+ * @brief One term as the glossary file writes it.
+ *
+ * @property name - Name of the term, as written.
+ * @property group - Text of the heading the term is listed under, or `''`.
+ * @property definition - Markdown of the definition, without the `_Avoid_:` lines.
+ * @property avoid - Words the glossary tells writers to replace with this term.
+ */
+export interface ParsedTerm {
+    readonly name: string;
+    readonly group: string;
+    readonly definition: string;
+    readonly avoid: readonly string[];
+}
+/**
+ * @brief A glossary file split into the text around the terms and the terms.
+ *
+ * @property intro - Markdown of everything that is not a term: the title and the text around the terms.
+ * @property terms - The terms in file order.
+ */
+export interface ParsedGlossary {
+    readonly intro: string;
+    readonly terms: readonly ParsedTerm[];
+}
+/**
+ * @brief Reads the terms of a glossary.
+ *
+ * Two layouts are recognized:
+ *
+ * - **Bold terms**: a line that opens with a bold name, followed by its
+ *   definition. Headings group the terms.
+ * - **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,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 { MarkdownRenderer } from '../markdown/renderer';
+import type { TermIndex } from './terms';
+/**
+ * @brief 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 graph - Graph the file and term nodes are added to.
+     * @param files - Renders the text of the glossary around the terms.
+     * @param markdown - Renders the definition of each term.
+     * @param terms - Receives every term. Must be the index the `TermLinker` of `resolvers` reads.
+     * @param resolvers - Resolves the links of the glossary and its terms.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, markdown: MarkdownRenderer, terms: TermIndex, resolvers: ProseResolvers);
+    /**
+     * @brief Reads one glossary file and adds its nodes.
+     *
+     * @param parent - Folder or section the file is in.
+     * @param root - Absolute directory `path` is relative to.
+     * @param path - Path of the file inside `root`.
+     * @param displayPath - Path the site shows.
+     * @param prefix - Prefix the bundle puts in front of paths from `root`.
+     * @returns The node of the file.
+     */
+    plan(parent: NodeRef, { root, path, displayPath, prefix }: DocFile): Promise<NodeRef>;
+}

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

@@ -0,0 +1,116 @@
+import type { NodeRef } from '../../model';
+import type { GraphBuilder } from '../graph/builder';
+/**
+ * @brief A glossary term found in a run of prose.
+ *
+ * @property start - Offset where the term starts in the text.
+ * @property end - Offset where the term ends in the text.
+ * @property href - In-site href of the term's entry.
+ * @property title - The definition as plain text, for a tooltip.
+ */
+export interface TermMatch {
+    readonly start: number;
+    readonly end: number;
+    readonly href: string;
+    readonly title: string;
+}
+/**
+ * @brief Finds the glossary terms of one piece of prose.
+ *
+ * @param text - Plain prose to search.
+ * @returns The matches in text order.
+ */
+export type TermFinder = (text: string) => TermMatch[];
+/**
+ * @brief One definition of a term in the index.
+ *
+ * @property ref - Node of the term's entry.
+ * @property path - Path of the glossary file that defines the term.
+ * @property summary - The definition as plain text.
+ */
+interface TermEntry {
+    readonly ref: NodeRef;
+    readonly path: string;
+    readonly summary: string;
+}
+/**
+ * @brief 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`. Created with `new TermIndex()`.
+ *
+ * @property byName - Definitions of each term, keyed by its normalized name.
+ * @property pattern - Matches any term. `null` until built, and reset when a term is added.
+ */
+export declare class TermIndex {
+    private readonly byName;
+    private pattern;
+    /**
+     * @brief Adds a term.
+     *
+     * @param name - The term as the glossary writes it.
+     * @param ref - Node of the term's entry.
+     * @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;
+    /**
+     * @brief 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;
+    }[];
+    /**
+     * @brief Builds one regex that matches any term, longest first, with an optional plural ending.
+     *
+     * @returns The regex.
+     */
+    private buildPattern;
+    /**
+     * @brief Finds the definition a written term names. The glossary closest to the file wins when
+     * several define the term.
+     *
+     * @param written - The term as the prose writes it.
+     * @param path - Path of the file the prose is in, or `null`.
+     * @returns The definition, or `null` when none matches.
+     */
+    private resolve;
+}
+/**
+ * @brief 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`.
+     *
+     * @param index - The terms the prose is searched for.
+     * @param graph - Graph the `uses` edges are added to.
+     */
+    constructor(index: TermIndex, graph: GraphBuilder);
+    /**
+     * @brief 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,114 @@
+import { type Edge, type EdgeKind, type GraphNode, type NodeType, type NodeRef } from '../../model';
+import type { PackageInfo } from '../packages';
+/** 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 NodeType, 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 NodeType> = 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 NodeType> = Omit<NodeOf<K>, IdentityKey>;
+/**
+ * @brief Produces the rest of a node. Runs in `build`, when every node has its place, so it can link to any of them.
+ *
+ * @param self - Ref of the node being built, which the source may link from.
+ * @returns The fields of the node that its identity does not hold.
+ */
+export type ContentSource<K extends NodeType> = (self: NodeRef) => ContentOf<K> | Promise<ContentOf<K>>;
+/**
+ * @brief 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.
+ *
+ * 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.
+ *
+ * @property identities - Routable identity of each node, by `NodeRef`. Together with `contents` it makes the node.
+ * @property contents - Content source of each node by `NodeRef`, or `null` for a node that has none.
+ * @property edges - Edges by `from:kind:to`, so an edge recorded twice is kept once.
+ * @property folders - Folder nodes by `parent/name`.
+ * @property files - File nodes by normalized path.
+ * @property packages - Packages by display path of their directory, set by `markPackages`.
+ * @property packageSections - Sections whose folders become `package` nodes where a package sits.
+ * @example
+ * const graph = new GraphBuilder();
+ */
+export declare class GraphBuilder {
+    private readonly identities;
+    private readonly contents;
+    private readonly edges;
+    private readonly folders;
+    private readonly files;
+    private packages;
+    private readonly packageSections;
+    /**
+     * @brief Adds a node. Kinds without content of their own, such as folders, take no `content`.
+     *
+     * @param identity - Fields that place the node: its name and parent, plus the slug or anchor of kinds that have them.
+     * @param content - Source of the rest of the node. Omitted for a kind without content.
+     * @returns Ref of the new node.
+     */
+    add<K extends NodeType>(kind: K, identity: IdentityOf<K>, ...content: Record<never, never> extends ContentOf<K> ? [] : [ContentSource<K>]): NodeRef;
+    /**
+     * @brief Makes `folder` create a `package` node instead of a folder for every package directory below the given sections.
+     *
+     * @param sections - Sections whose `folder` paths are display paths of the repository, such as the code and docs sections.
+     * @param packages - Packages by display path of their directory, as `detectPackages` returns them.
+     */
+    markPackages(sections: readonly NodeRef[], packages: ReadonlyMap<string, PackageInfo>): void;
+    /**
+     * @brief Finds the folder at `directory` below `parent`, creating it and its ancestors on first use.
+     *
+     * Below a section passed to `markPackages`, a directory that holds a package becomes a `package` node.
+     *
+     * @param parent - Node the directory is below.
+     * @param directory - Slash-separated path, such as `docs/guides`. `''` names `parent` itself.
+     * @returns Ref of the folder at the end of the path.
+     */
+    folder(parent: NodeRef, directory: string): NodeRef;
+    /**
+     * @brief Records which node shows the file at `path`, so links to that file can find it.
+     *
+     * @param path - Display path of the file, as `DocFile.displayPath` gives it. Normalized before storing.
+     * @param ref - Node that shows the file.
+     */
+    registerFile(path: string, ref: NodeRef): void;
+    /**
+     * @brief Finds the node registered for the file at `path`.
+     *
+     * @param path - Display path of the file, as passed to `registerFile`.
+     * @returns The node, or `undefined` when no file is registered at that path.
+     */
+    fileAt(path: string): NodeRef | undefined;
+    /**
+     * @brief Builds the in-site href of a node.
+     *
+     * @param ref - Node to link to.
+     * @param fragment - Replaces the node's own anchor, for a heading on a page.
+     * @returns The href, relative to the site root.
+     */
+    href(ref: NodeRef, fragment?: string): string;
+    /**
+     * @brief Records an edge. The same edge recorded twice is kept once.
+     *
+     * @param from - Node the edge starts at.
+     * @param kind - Relation the edge expresses.
+     * @param to - Node the edge ends at.
+     */
+    link(from: NodeRef, kind: EdgeKind, to: NodeRef): void;
+    /**
+     * @brief 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,54 @@
+import type { Element } from 'hast';
+/**
+ * @brief Highlights code of a language into HTML or into a HAST `<pre>` element.
+ *
+ * @property toHtml - Highlights code into an HTML string.
+ * @property toHast - Highlights code into the HAST `<pre>` element shiki produces.
+ */
+export interface CodeHighlighter {
+    toHtml(code: string, language: string): Promise<string>;
+    toHast(code: string, language: string): Promise<Element>;
+}
+/**
+ * @brief Highlights with shiki. Colors are emitted as `var(--syntax-*)` references,
+ * so the page stylesheet owns the palette in light and dark mode. 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.
+ *
+ * @property highlighter - The shiki highlighter, created on first use. `null` until then.
+ * @property loading - Pending load of each language by name, shared between callers.
+ * @example
+ * const highlighter = new ShikiHighlighter();
+ */
+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>;
+    /**
+     * @brief Creates the shiki highlighter on first use and loads a language.
+     *
+     * @param language - Language name as the code block gives it, in any case.
+     * @returns The highlighter and the language name to pass to it: the lowercased `language`, or `text` when shiki lacks it.
+     */
+    private prepare;
+    /**
+     * @brief Loads a language once, sharing the pending load between callers.
+     *
+     * @param highlighter - The shiki highlighter the language is loaded into.
+     * @param language - Lowercased language name.
+     * @returns The name to highlight with: `language`, or `text` when it cannot be loaded.
+     */
+    private resolveLanguage;
+    /**
+     * @brief Loads a bundled language into shiki, or returns `text` when it is not bundled or fails to load.
+     *
+     * @param highlighter - The shiki highlighter the language is loaded into.
+     * @param language - Lowercased language name.
+     * @returns The language name, or `text`.
+     */
+    private load;
+}

package/dist/scanner/ignore.d.ts

@@ -0,0 +1,25 @@
+/** Name of the file at the root of a repository that lists what analyze skips. */
+export declare const IGNORE_FILE = ".analyzeignore";
+/** Lines of the `.analyzeignore` that analyze writes when a repository has none. */
+export declare const DEFAULT_IGNORE_LINES: readonly string[];
+/**
+ * @brief Turns the lines of an ignore file into globs that `Bun.Glob` matches against root-relative paths.
+ *
+ * A pattern without a slash matches at any depth, a leading `/` anchors it to the root, and a
+ * trailing `/` matches a directory. A pattern without a trailing `/` matches a file or a directory.
+ * Blank lines and `#` comments are skipped. Negation with `!` is not supported, so such a line is skipped too.
+ *
+ * @param text - Contents of the ignore file.
+ * @returns Globs, two per pattern that may name a file or a directory. `dist/` gives one: any `dist` directory and all below it.
+ */
+export declare function ignoreGlobs(text: string): string[];
+/**
+ * @brief Reads the `.analyzeignore` of a repository, and writes one with {@link DEFAULT_IGNORE_LINES} when it has none.
+ *
+ * @param repo - Absolute path of the repository.
+ * @returns The globs of the file, and whether this call created the file.
+ */
+export declare function loadIgnoreFile(repo: string): {
+    globs: string[];
+    created: boolean;
+};

package/dist/scanner/index.d.ts

@@ -0,0 +1,43 @@
+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 { ConfigPlanner } from './config';
+export { addFilePage, type DocFile, type DocKind, DocPlanner, docKind } from './docs';
+export { compareTreePaths, type FileLister, RepoFileLister, type Source } from './files';
+export { DEFAULT_IGNORE_LINES, IGNORE_FILE, ignoreGlobs, loadIgnoreFile } from './ignore';
+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 { detectPackages, type PackageInfo } from './packages';
+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,24 @@
+/**
+ * @brief A markdown document split into its YAML frontmatter and the rest.
+ *
+ * @property data - Parsed frontmatter fields. `{}` when there is no valid frontmatter.
+ * @property body - The markdown after the frontmatter block, as written.
+ */
+export interface Frontmatter {
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly body: string;
+}
+/**
+ * @brief Splits a leading YAML block from a markdown document. Invalid YAML yields empty data.
+ *
+ * @param source - Markdown text, with or without frontmatter.
+ * @returns The parsed frontmatter and the text after it.
+ */
+export declare function splitFrontmatter(source: string): Frontmatter;
+/**
+ * @brief Reads a frontmatter field as trimmed text, or `null` when it is missing, blank or no string.
+ *
+ * @param data - Parsed frontmatter, as `Frontmatter.data` holds it.
+ * @param key - Name of the field, such as `title`.
+ */
+export declare function stringField(data: Readonly<Record<string, unknown>>, key: string): string | null;