@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/api/refs.d.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import type { NodeFilter, NodeSummary, ReferenceOptions, References, Retriever } from '../retrieval';
+/**
+ * Schema of the `refs` options.
+ *
+ * @property target - Id, path or name of the node.
+ * @property incoming - Only what links to the node.
+ * @property outgoing - Only what the node links to.
+ * @property edges - Only edges of these kinds. Empty or absent keeps every kind.
+ */
+declare const refsSchema: z.ZodPipe<z.ZodObject<{
+    onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
+    kinds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        class: "class";
+        decision: "decision";
+        definition: "definition";
+        enum: "enum";
+        field: "field";
+        file: "file";
+        folder: "folder";
+        function: "function";
+        interface: "interface";
+        namespace: "namespace";
+        operation: "operation";
+        package: "package";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        struct: "struct";
+        table: "table";
+        task: "task";
+        term: "term";
+        trait: "trait";
+        type: "type";
+    }>>>>;
+    section: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        database: "database";
+        docs: "docs";
+        skills: "skills";
+        tasks: "tasks";
+    }>>;
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    cache: z.ZodOptional<z.ZodBoolean>;
+    target: z.ZodString;
+    incoming: z.ZodOptional<z.ZodBoolean>;
+    outgoing: z.ZodOptional<z.ZodBoolean>;
+    edges: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        affects: "affects";
+        depends: "depends";
+        extends: "extends";
+        mentions: "mentions";
+        names: "names";
+        reads: "reads";
+        references: "references";
+        returns: "returns";
+        throws: "throws";
+        type: "type";
+        uses: "uses";
+        writes: "writes";
+    }>>>>;
+}, z.core.$strict>, z.ZodTransform<{
+    source: import("./source").BundleSource;
+    reporter: import("../scanner").Reporter;
+    request: {
+        target: string;
+        filter: NodeFilter;
+        references: {
+            direction: "both" | "in" | "out";
+            kinds: readonly ("affects" | "depends" | "extends" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+        };
+    };
+}, {
+    onWarning?: import("./options").WarningHandler | undefined;
+    kinds?: readonly ("class" | "decision" | "definition" | "enum" | "field" | "file" | "folder" | "function" | "interface" | "namespace" | "operation" | "package" | "parameter" | "phase" | "plan" | "query" | "struct" | "table" | "task" | "term" | "trait" | "type")[] | undefined;
+    section?: "code" | "database" | "docs" | "skills" | "tasks" | undefined;
+    repo?: string | undefined;
+    skillDirs?: readonly string[] | undefined;
+    docDirs?: readonly string[] | undefined;
+    excludes?: readonly string[] | undefined;
+    embeddings?: boolean | undefined;
+    from?: string | undefined;
+    cache?: boolean | undefined;
+    target: string;
+    incoming?: boolean | undefined;
+    outgoing?: boolean | undefined;
+    edges?: readonly ("affects" | "depends" | "extends" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+}>>;
+/** Options of `refs`: the node, which links to follow, and the bundle to read. */
+export type RefsOptions = z.input<typeof refsSchema>;
+/**
+ * One `refs` on a loaded bundle.
+ *
+ * @property target - Id, path or name of the node.
+ * @property filter - Narrows a name to one node.
+ * @property references - Which links to keep: direction and edge kinds.
+ */
+export interface RefsRequest {
+    readonly target: string;
+    readonly filter: NodeFilter;
+    readonly references: ReferenceOptions;
+}
+/**
+ * What `refs` finds. The CLI prints it with `refs --json`.
+ *
+ * @property node - The node the references are of.
+ */
+export interface RefsResult extends References {
+    readonly node: NodeSummary;
+}
+/**
+ * Lists the references of one node of a loaded bundle.
+ *
+ * @param retriever - The loaded bundle to read.
+ * @param request - The node, the filter that narrows a name, and the references to keep.
+ * @returns The node with what it links to and what links to it.
+ * @throws {QueryError} When no node fits the target, or several do.
+ */
+export declare function refsIn(retriever: Retriever, request: RefsRequest): RefsResult;
+/**
+ * Lists what a node links to and what links to it.
+ *
+ * @param options - The node, which links to follow, and the repository or site to read.
+ * @returns The node with its references.
+ * @throws {OptionsError} When the options are not valid.
+ * @throws {SourceError} When the repository or the site cannot be read.
+ * @throws {QueryError} When no node fits the target, or several do.
+ */
+export declare function refs(options: RefsOptions): Promise<RefsResult>;
+export {};

package/dist/api/scan.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+/**
+ * What decides the content of a scan.
+ *
+ * @property repo - Absolute path of the repository to document.
+ * @property skillDirs - Absolute skill directories. Empty means: find every `SKILL.md` in the repository.
+ * @property docDirs - Absolute docs directories. Empty means: every markdown, JSON and YAML file in the repository.
+ * @property excludes - Glob patterns of paths to skip.
+ * @property embeddings - Whether the bundle gets the embedding model and search by meaning.
+ */
+export interface ScanOptions {
+    readonly repo: string;
+    readonly skillDirs: readonly string[];
+    readonly docDirs: readonly string[];
+    readonly excludes: readonly string[];
+    readonly embeddings: boolean;
+}
+/**
+ * The options that choose what to scan, as a caller passes them. Relative paths resolve against the working directory.
+ *
+ * @property repo - Repository to read. Default: the working directory.
+ * @property skillDirs - Read skills from these directories instead of the repository.
+ * @property docDirs - Read docs from these directories instead of the repository.
+ * @property excludes - Glob patterns of paths to skip, such as `src/legacy/**`.
+ * @property embeddings - `false` leaves out search by meaning. Default: `true`.
+ */
+export declare const scanShape: {
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+};
+/** The scan options after validation, before defaults. */
+export type ScanFields = z.output<z.ZodObject<typeof scanShape>>;
+/**
+ * Fills in the defaults of validated scan options and makes their paths absolute against the working directory.
+ *
+ * @param fields - Validated scan options.
+ * @returns The scan options, with defaults filled in.
+ */
+export declare function scanOf(fields: ScanFields): ScanOptions;
+/**
+ * Names the site file of a repository. `createDocs` writes it, and nothing else outside the cache.
+ *
+ * @param repo - Absolute path of the repository.
+ * @returns `<repo>/analyze_out/index.html`.
+ */
+export declare function siteFileOf(repo: string): string;
+/**
+ * Names the directory where the retrieval functions keep the scans of a repository.
+ *
+ * @param repo - Absolute path of the repository.
+ * @returns `<repo>/analyze_out/cache`.
+ */
+export declare function cacheDirOf(repo: string): string;

package/dist/api/search.d.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { type NodeFilter, type Retriever, type SearchHit, type SearchMode } from '../retrieval';
+/** Most hits of a search without a limit. */
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+/**
+ * Schema of the `search` options.
+ *
+ * @property query - Words to find.
+ * @property by - `name` searches by words, `meaning` by the embedding model, `both` by both. Default: `both`.
+ * @property limit - Most hits. Default: 10.
+ */
+declare const searchSchema: z.ZodPipe<z.ZodObject<{
+    onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
+    kinds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        class: "class";
+        decision: "decision";
+        definition: "definition";
+        enum: "enum";
+        field: "field";
+        file: "file";
+        folder: "folder";
+        function: "function";
+        interface: "interface";
+        namespace: "namespace";
+        operation: "operation";
+        package: "package";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        struct: "struct";
+        table: "table";
+        task: "task";
+        term: "term";
+        trait: "trait";
+        type: "type";
+    }>>>>;
+    section: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        database: "database";
+        docs: "docs";
+        skills: "skills";
+        tasks: "tasks";
+    }>>;
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    cache: z.ZodOptional<z.ZodBoolean>;
+    query: z.ZodString;
+    by: z.ZodOptional<z.ZodEnum<{
+        both: "both";
+        meaning: "meaning";
+        name: "name";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodTransform<{
+    source: import("./source").BundleSource;
+    reporter: import("../scanner").Reporter;
+    request: {
+        query: string;
+        mode: "both" | "meaning" | "name";
+        limit: number;
+        filter: NodeFilter;
+    };
+}, {
+    onWarning?: import("./options").WarningHandler | undefined;
+    kinds?: readonly ("class" | "decision" | "definition" | "enum" | "field" | "file" | "folder" | "function" | "interface" | "namespace" | "operation" | "package" | "parameter" | "phase" | "plan" | "query" | "struct" | "table" | "task" | "term" | "trait" | "type")[] | undefined;
+    section?: "code" | "database" | "docs" | "skills" | "tasks" | undefined;
+    repo?: string | undefined;
+    skillDirs?: readonly string[] | undefined;
+    docDirs?: readonly string[] | undefined;
+    excludes?: readonly string[] | undefined;
+    embeddings?: boolean | undefined;
+    from?: string | undefined;
+    cache?: boolean | undefined;
+    query: string;
+    by?: "both" | "meaning" | "name" | undefined;
+    limit?: number | undefined;
+}>>;
+/** Options of `search`: the words, how to match them, and the bundle to search. */
+export type SearchOptions = z.input<typeof searchSchema>;
+/**
+ * One search on a loaded bundle.
+ *
+ * @property query - The words to find.
+ * @property mode - How to match them: by words, by meaning, or both.
+ * @property limit - Most hits.
+ * @property filter - Narrows the nodes that count.
+ */
+export interface SearchRequest {
+    readonly query: string;
+    readonly mode: SearchMode;
+    readonly limit: number;
+    readonly filter: NodeFilter;
+}
+/**
+ * What `search` finds. The CLI prints it with `search --json`.
+ *
+ * @property query - The words searched for.
+ * @property mode - How the words were matched.
+ * @property model - Name of the embedding model of the bundle. `null` when the bundle has none.
+ * @property hits - Hits, best first.
+ */
+export interface SearchResult {
+    readonly query: string;
+    readonly mode: SearchMode;
+    readonly model: string | null;
+    readonly hits: readonly SearchHit[];
+}
+/**
+ * Searches a loaded bundle.
+ *
+ * @param retriever - The loaded bundle to search.
+ * @param request - The words, the mode, the limit and the filter.
+ * @returns The hits, best first.
+ * @throws {QueryError} When the search is by meaning and the bundle has no embeddings.
+ */
+export declare function searchIn(retriever: Retriever, request: SearchRequest): SearchResult;
+/**
+ * Finds pages and entries by their words and by meaning.
+ *
+ * @param options - The words, how to match them, and the repository or site to search.
+ * @returns The hits, best first.
+ * @throws {OptionsError} When the options are not valid.
+ * @throws {SourceError} When the repository or the site cannot be read.
+ * @throws {QueryError} When the search is by meaning and the bundle has no embeddings.
+ */
+export declare function search(options: SearchOptions): Promise<SearchResult>;
+export {};

package/dist/api/services.d.ts

@@ -0,0 +1,15 @@
+import { type Reporter } from '../scanner';
+import { BundleBuilder } from './bundle-builder';
+import type { ScanOptions } from './scan';
+/** Name and version of the tool, recorded in every bundle it builds. */
+export declare const GENERATOR: string;
+/**
+ * @brief Wires the services that scan one repository into a builder.
+ *
+ * Reads the `.analyzeignore` of the repository, creating it when absent, and skips its patterns and `scan.excludes`.
+ *
+ * @param scan - What to scan. Its `embeddings` flag decides whether the builder embeds the nodes.
+ * @param reporter - Receives the warnings of the scan.
+ * @returns A builder for that scan.
+ */
+export declare function createBuilder(scan: ScanOptions, reporter: Reporter): BundleBuilder;

package/dist/api/show.d.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import type { NodeFilter, NodeReport, Retriever } from '../retrieval';
+/**
+ * Schema of the `show` options.
+ *
+ * @property target - Id, path or name of the node.
+ */
+declare const showSchema: z.ZodPipe<z.ZodObject<{
+    onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
+    kinds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        class: "class";
+        decision: "decision";
+        definition: "definition";
+        enum: "enum";
+        field: "field";
+        file: "file";
+        folder: "folder";
+        function: "function";
+        interface: "interface";
+        namespace: "namespace";
+        operation: "operation";
+        package: "package";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        struct: "struct";
+        table: "table";
+        task: "task";
+        term: "term";
+        trait: "trait";
+        type: "type";
+    }>>>>;
+    section: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        database: "database";
+        docs: "docs";
+        skills: "skills";
+        tasks: "tasks";
+    }>>;
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    cache: z.ZodOptional<z.ZodBoolean>;
+    target: z.ZodString;
+}, z.core.$strict>, z.ZodTransform<{
+    source: import("./source").BundleSource;
+    reporter: import("../scanner").Reporter;
+    request: {
+        target: string;
+        filter: NodeFilter;
+    };
+}, {
+    onWarning?: import("./options").WarningHandler | undefined;
+    kinds?: readonly ("class" | "decision" | "definition" | "enum" | "field" | "file" | "folder" | "function" | "interface" | "namespace" | "operation" | "package" | "parameter" | "phase" | "plan" | "query" | "struct" | "table" | "task" | "term" | "trait" | "type")[] | undefined;
+    section?: "code" | "database" | "docs" | "skills" | "tasks" | undefined;
+    repo?: string | undefined;
+    skillDirs?: readonly string[] | undefined;
+    docDirs?: readonly string[] | undefined;
+    excludes?: readonly string[] | undefined;
+    embeddings?: boolean | undefined;
+    from?: string | undefined;
+    cache?: boolean | undefined;
+    target: string;
+}>>;
+/** Options of `show`: the node, and the bundle to read it from. */
+export type ShowOptions = z.input<typeof showSchema>;
+/**
+ * One `show` on a loaded bundle.
+ *
+ * @property target - Id, path or name of the node.
+ * @property filter - Narrows a name to one node.
+ */
+export interface ShowRequest {
+    readonly target: string;
+    readonly filter: NodeFilter;
+}
+/**
+ * Describes one node of a loaded bundle.
+ *
+ * @param retriever - The loaded bundle to read.
+ * @param request - The node and the filter that narrows a name.
+ * @returns The report of the node: text, parameters, references.
+ * @throws {QueryError} When no node fits the target, or several do.
+ */
+export declare function showIn(retriever: Retriever, request: ShowRequest): NodeReport;
+/**
+ * Describes one page or entry: text, parameters, references.
+ *
+ * @param options - The node, and the repository or site to read it from.
+ * @returns The report of the node. The CLI prints it with `show --json`.
+ * @throws {OptionsError} When the options are not valid.
+ * @throws {SourceError} When the repository or the site cannot be read.
+ * @throws {QueryError} When no node fits the target, or several do.
+ */
+export declare function show(options: ShowOptions): Promise<NodeReport>;
+export {};

package/dist/api/site-reader.d.ts

@@ -0,0 +1,19 @@
+import { type DocsBundle } from '../model';
+/**
+ * Checks that parsed JSON has the parts of a bundle that queries read: `meta`, `nodes` and `edges`.
+ *
+ * @param value - Parsed JSON to check.
+ * @returns `true` when `value` has all three parts.
+ */
+export declare function isBundle(value: unknown): value is DocsBundle;
+/**
+ * @brief Reads the bundle back out of a site that `createDocs` wrote.
+ *
+ * The inverse of `HtmlSiteWriter.render`: parses the JSON in the data element of the site.
+ *
+ * @param html - Text of the site file.
+ * @param path - Path of the file, only for the error message.
+ * @returns The bundle the site holds.
+ * @throws {SourceError} When the file is no analyze site.
+ */
+export declare function readSite(html: string, path: string): DocsBundle;

package/dist/api/site-writer.d.ts

@@ -0,0 +1,43 @@
+import { type DocsBundle } from '../model';
+/** Writes a bundle as a documentation site. */
+export interface SiteWriter {
+    /**
+     * Writes the site for `bundle` to `path`.
+     *
+     * @param path - Where to write the site file.
+     * @param bundle - The bundle the site shows.
+     * @returns Size of the written site in bytes.
+     */
+    write(path: string, bundle: DocsBundle): Promise<number>;
+}
+/**
+ * @brief Fills the prebuilt single-file app with a bundle.
+ *
+ * Puts the title into `<title>` and the bundle as JSON into the data `<script>` element. Holds the template.
+ * `createDocs` creates one with `TEMPLATE_HTML` from `src/api/template.ts`; `readSite` reads the result back.
+ * Created with `new HtmlSiteWriter(TEMPLATE_HTML)`.
+ */
+export declare class HtmlSiteWriter implements SiteWriter {
+    private readonly template;
+    /**
+     * Creates a writer for one template.
+     *
+     * @param template - Page text with the title and data placeholders, each exactly once.
+     */
+    constructor(template: string);
+    /**
+     * Returns the template with the escaped title and the bundle as script-safe JSON in place of the placeholders.
+     *
+     * @param bundle - The bundle to put in the page.
+     * @returns The finished page text.
+     */
+    render(bundle: DocsBundle): string;
+    /**
+     * Writes the rendered site to `path`, creating its directory.
+     *
+     * @param path - Where to write the site file.
+     * @param bundle - The bundle to render.
+     * @returns Size of the written site in bytes.
+     */
+    write(path: string, bundle: DocsBundle): Promise<number>;
+}

package/dist/api/source.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { Retriever } from '../retrieval';
+import type { Reporter } from '../scanner';
+import { type ScanOptions } from './scan';
+/**
+ * Where a query gets its bundle: `site` is an HTML file that `createDocs` wrote; `scan` is a scan of the
+ * repository, whose result is kept in `analyze_out/cache` of the repository when `cache` is set.
+ */
+export type BundleSource = {
+    readonly kind: 'site';
+    readonly file: string;
+} | {
+    readonly kind: 'scan';
+    readonly scan: ScanOptions;
+    readonly cache: boolean;
+};
+/**
+ * The options that choose the bundle a query reads, as a caller passes them.
+ *
+ * @property from - An HTML file that `createDocs` wrote, read in place of the repository. Excludes the scan options.
+ * @property cache - `false` scans the repository again even when no file changed. Default: `true`.
+ */
+export declare const sourceShape: {
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    cache: z.ZodOptional<z.ZodBoolean>;
+};
+/** The source options after validation. */
+type SourceFields = z.output<z.ZodObject<typeof sourceShape>>;
+/**
+ * Adds an issue to the schema's refinement context for every scan option that comes with `from`.
+ *
+ * @param fields - Validated source options.
+ * @param context - Refinement context of the schema, which collects the issues.
+ */
+export declare function checkSource(fields: SourceFields, context: z.RefinementCtx): void;
+/**
+ * Turns validated source options into a bundle source.
+ *
+ * @param fields - Validated source options, checked by `checkSource` first.
+ * @returns The site file to read, with an absolute path, or the scan to run.
+ */
+export declare function sourceOf(fields: SourceFields): BundleSource;
+/**
+ * Loads the bundle of a source and opens it for queries, handing warnings of the load to `reporter`.
+ *
+ * @param source - Where the bundle comes from.
+ * @param reporter - Receives the warnings of the load.
+ * @returns The retriever that answers queries on the bundle.
+ * @throws {SourceError} When the site file or the repository cannot be read.
+ */
+export declare function openRetriever(source: BundleSource, reporter: Reporter): Promise<Retriever>;
+export {};

package/dist/api/target.d.ts

@@ -0,0 +1,12 @@
+import type { NodeRef } from '../model';
+import type { NodeFilter, Retriever } from '../retrieval';
+/**
+ * Finds the one node a caller means.
+ *
+ * @param retriever - Retriever the node is looked up in.
+ * @param target - An id, a path or a name.
+ * @param filter - Narrows the nodes that count.
+ * @returns The one node that fits.
+ * @throws {QueryError} When no node fits, or several do. The message lists the candidates with their ids.
+ */
+export declare function nodeOf(retriever: Retriever, target: string, filter: NodeFilter): NodeRef;

package/dist/api/template.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The web app as one HTML file, with placeholders for the title and the bundle. `HtmlSiteWriter` fills them in.
+ * Bun types every `.html` import as a page bundle. With `type: 'text'` the import is the file content.
+ */
+export declare const TEMPLATE_HTML: string;