@g3nomaly/analyze 0.1.0 → 0.1.1

package/dist/api/scan.d.ts

@@ -1,32 +1,44 @@
 import { z } from 'zod';
-/** What decides the content of a scan. */
+/**
+ * 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 {
-    /** 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. */
+/**
+ * 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: {
-    /** 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. */
+/**
+ * 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.

package/dist/api/search.d.ts

@@ -2,39 +2,32 @@ 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<{
-        agent: "agent";
-        api: "api";
-        asset: "asset";
-        catalog: "catalog";
         class: "class";
-        database: "database";
         decision: "decision";
-        decisions: "decisions";
         definition: "definition";
-        document: "document";
         enum: "enum";
         field: "field";
+        file: "file";
         folder: "folder";
         function: "function";
-        glossary: "glossary";
-        hook: "hook";
         interface: "interface";
-        json: "json";
-        method: "method";
         namespace: "namespace";
         operation: "operation";
+        package: "package";
         parameter: "parameter";
         phase: "phase";
         plan: "plan";
         query: "query";
-        reference: "reference";
-        schema: "schema";
-        section: "section";
-        skill: "skill";
-        source: "source";
         struct: "struct";
         table: "table";
         task: "task";
@@ -74,7 +67,7 @@ declare const searchSchema: z.ZodPipe<z.ZodObject<{
     };
 }, {
     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;
+    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;
@@ -89,25 +82,38 @@ declare const searchSchema: z.ZodPipe<z.ZodObject<{
 }>>;
 /** 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. */
+/**
+ * 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`. */
+/**
+ * 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;
-    /** 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 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.

package/dist/api/services.d.ts

@@ -3,5 +3,13 @@ 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`. */
+/**
+ * @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

@@ -1,38 +1,29 @@
 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<{
-        agent: "agent";
-        api: "api";
-        asset: "asset";
-        catalog: "catalog";
         class: "class";
-        database: "database";
         decision: "decision";
-        decisions: "decisions";
         definition: "definition";
-        document: "document";
         enum: "enum";
         field: "field";
+        file: "file";
         folder: "folder";
         function: "function";
-        glossary: "glossary";
-        hook: "hook";
         interface: "interface";
-        json: "json";
-        method: "method";
         namespace: "namespace";
         operation: "operation";
+        package: "package";
         parameter: "parameter";
         phase: "phase";
         plan: "plan";
         query: "query";
-        reference: "reference";
-        schema: "schema";
-        section: "section";
-        skill: "skill";
-        source: "source";
         struct: "struct";
         table: "table";
         task: "task";
@@ -64,7 +55,7 @@ declare const showSchema: z.ZodPipe<z.ZodObject<{
     };
 }, {
     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;
+    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;
@@ -77,15 +68,20 @@ declare const showSchema: z.ZodPipe<z.ZodObject<{
 }>>;
 /** 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. */
+/**
+ * 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 {
-    /** Id, path or name of the node. */
     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.

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

@@ -1,11 +1,19 @@
 import { type DocsBundle } from '../model';
-/** Checks that parsed JSON has the parts of a bundle that queries read: `meta`, `nodes` and `edges`. */
+/**
+ * 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;
 /**
- * Reads the bundle back out of a site that `createDocs` wrote. The inverse
- * of `HtmlSiteWriter.render`.
+ * @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

@@ -1,20 +1,43 @@
 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. */
+    /**
+     * 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>;
 }
 /**
- * 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.
+ * @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 a template that holds the title and data placeholders once each. */
+    /**
+     * 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. */
+    /**
+     * 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, and returns its size in bytes. */
+    /**
+     * 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

@@ -2,44 +2,55 @@ 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. */
-{
+/**
+ * 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;
-}
-/** 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. */
+/**
+ * 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>;
-    /** 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`. */
+/**
+ * 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, checked by `checkSource`, into a bundle source.
+ * 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>;

package/dist/api/target.d.ts

@@ -3,8 +3,10 @@ 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;