@g3nomaly/analyze 0.0.0-stage → 0.1.0

package/dist/api/scan.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/** What decides the content of a scan. */
+export interface ScanOptions {
+    /** Absolute path of the repository to document. */
+    readonly repo: string;
+    /** Absolute skill directories. Empty means: find every `SKILL.md` in the repository. */
+    readonly skillDirs: readonly string[];
+    /** Absolute docs directories. Empty means: every markdown, JSON and YAML file in the repository. */
+    readonly docDirs: readonly string[];
+    readonly excludes: readonly string[];
+    /** Whether the bundle gets the embedding model and search by meaning. */
+    readonly embeddings: boolean;
+}
+/** The options that choose what to scan, as a caller passes them. Relative paths resolve against the working directory. */
+export declare const scanShape: {
+    /** Repository to read. Default: the working directory. */
+    repo: z.ZodOptional<z.ZodString>;
+    /** Read skills from these directories instead of the repository. */
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    /** Read docs from these directories instead of the repository. */
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    /** Glob patterns of paths to skip, such as `src/legacy/**`. */
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    /** `false` leaves out search by meaning. Default: `true`. */
+    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. */
+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,126 @@
+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;
+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<{
+        agent: "agent";
+        api: "api";
+        asset: "asset";
+        catalog: "catalog";
+        class: "class";
+        database: "database";
+        decision: "decision";
+        decisions: "decisions";
+        definition: "definition";
+        document: "document";
+        enum: "enum";
+        field: "field";
+        folder: "folder";
+        function: "function";
+        glossary: "glossary";
+        hook: "hook";
+        interface: "interface";
+        json: "json";
+        method: "method";
+        namespace: "namespace";
+        operation: "operation";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        reference: "reference";
+        schema: "schema";
+        section: "section";
+        skill: "skill";
+        source: "source";
+        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 ("agent" | "api" | "asset" | "catalog" | "class" | "database" | "decision" | "decisions" | "definition" | "document" | "enum" | "field" | "folder" | "function" | "glossary" | "hook" | "interface" | "json" | "method" | "namespace" | "operation" | "parameter" | "phase" | "plan" | "query" | "reference" | "schema" | "section" | "skill" | "source" | "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. */
+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`. */
+export interface SearchResult {
+    readonly query: string;
+    readonly mode: SearchMode;
+    /** Name of the embedding model of the bundle. `null` when the bundle has none. */
+    readonly model: string | null;
+    /** Hits, best first. */
+    readonly hits: readonly SearchHit[];
+}
+/**
+ * Searches a loaded bundle.
+ *
+ * @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,7 @@
+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;
+/** Wires the services that scan one repository into a builder, which hands warnings of the scan to `reporter`. */
+export declare function createBuilder(scan: ScanOptions, reporter: Reporter): BundleBuilder;

package/dist/api/show.d.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import type { NodeFilter, NodeReport, Retriever } from '../retrieval';
+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<{
+        agent: "agent";
+        api: "api";
+        asset: "asset";
+        catalog: "catalog";
+        class: "class";
+        database: "database";
+        decision: "decision";
+        decisions: "decisions";
+        definition: "definition";
+        document: "document";
+        enum: "enum";
+        field: "field";
+        folder: "folder";
+        function: "function";
+        glossary: "glossary";
+        hook: "hook";
+        interface: "interface";
+        json: "json";
+        method: "method";
+        namespace: "namespace";
+        operation: "operation";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        reference: "reference";
+        schema: "schema";
+        section: "section";
+        skill: "skill";
+        source: "source";
+        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 ("agent" | "api" | "asset" | "catalog" | "class" | "database" | "decision" | "decisions" | "definition" | "document" | "enum" | "field" | "folder" | "function" | "glossary" | "hook" | "interface" | "json" | "method" | "namespace" | "operation" | "parameter" | "phase" | "plan" | "query" | "reference" | "schema" | "section" | "skill" | "source" | "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. */
+export interface ShowRequest {
+    /** Id, path or name of the node. */
+    readonly target: string;
+    readonly filter: NodeFilter;
+}
+/**
+ * Describes one node of a loaded bundle.
+ *
+ * @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,11 @@
+import { type DocsBundle } from '../model';
+/** Checks that parsed JSON has the parts of a bundle that queries read: `meta`, `nodes` and `edges`. */
+export declare function isBundle(value: unknown): value is DocsBundle;
+/**
+ * Reads the bundle back out of a site that `createDocs` wrote. The inverse
+ * of `HtmlSiteWriter.render`.
+ *
+ * @param path - Path of the file, only for the error message.
+ * @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,20 @@
+import { type DocsBundle } from '../model';
+/** Writes a bundle as a documentation site. */
+export interface SiteWriter {
+    /** Writes the site for `bundle` to `path` and returns its size in bytes. */
+    write(path: string, bundle: DocsBundle): Promise<number>;
+}
+/**
+ * Fills the prebuilt single-file app with a bundle: the title into `<title>`, 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.
+ */
+export declare class HtmlSiteWriter implements SiteWriter {
+    private readonly template;
+    /** Creates a writer for a template that holds the title and data placeholders once each. */
+    constructor(template: string);
+    /** Returns the template with the escaped title and the bundle as script-safe JSON in place of the placeholders. */
+    render(bundle: DocsBundle): string;
+    /** Writes the rendered site to `path`, creating its directory, and returns its size in bytes. */
+    write(path: string, bundle: DocsBundle): Promise<number>;
+}

package/dist/api/source.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { Retriever } from '../retrieval';
+import type { Reporter } from '../scanner';
+import { type ScanOptions } from './scan';
+/** Where a query gets its bundle. */
+export type BundleSource = 
+/** An HTML file that `createDocs` wrote. */
+{
+    readonly kind: 'site';
+    readonly file: string;
+}
+/** A scan of the repository. With `cache`, its result is kept in `analyze_out/cache` of the repository. */
+ | {
+    readonly kind: 'scan';
+    readonly scan: ScanOptions;
+    readonly cache: boolean;
+};
+/** The options that choose the bundle a query reads, as a caller passes them. */
+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>;
+    /** An HTML file that `createDocs` wrote, read in place of the repository. Excludes the scan options. */
+    from: z.ZodOptional<z.ZodString>;
+    /** `false` scans the repository again even when no file changed. Default: `true`. */
+    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`. */
+export declare function checkSource(fields: SourceFields, context: z.RefinementCtx): void;
+/**
+ * Turns validated source options, checked by `checkSource`, into a bundle source.
+ *
+ * @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`.
+ *
+ * @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,10 @@
+import type { NodeRef } from '../model';
+import type { NodeFilter, Retriever } from '../retrieval';
+/**
+ * Finds the one node a caller means.
+ *
+ * @param target - An id, a path or a name.
+ * @param filter - Narrows the nodes that count.
+ * @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;