@g3nomaly/analyze 0.1.0 → 0.1.2

package/README.md

@@ -11,7 +11,11 @@ cd ~/code/my-repo
 bunx @g3nomaly/analyze create_docs
 ```
 
-This writes `analyze_out/index.html` in the repository. `analyze_out/` is the only place analyze writes, and the query commands keep their scan cache there as well. Add it to `.gitignore`. Nothing else in the repository is changed.
+This writes `analyze_out/index.html` in the repository, and the query commands keep their scan cache in `analyze_out/` as well. Add it to `.gitignore`. The one other file analyze writes is `.analyzeignore`, once, when the repository has none.
+
+## What it skips
+
+`.analyzeignore` at the repository root lists what the scan skips, on top of `.gitignore`, with the same patterns: `name/` skips a directory anywhere, `/name` only at the root, `*.ext` a file anywhere. analyze creates it with `node_modules/`, `dist/`, `build/`, `out/`, `target/`, `vendor/`, `coverage/`, `data/` and the like when it is absent. Edit it to change what is skipped. `--exclude` adds patterns for one run.
 
 `analyze` needs [Bun](https://bun.sh) 1.2.21 or newer.
 
@@ -19,11 +23,12 @@ This writes `analyze_out/index.html` in the repository. `analyze_out/` is the on
 
 | Section | Read from |
 |---|---|
-| Skills | Every `SKILL.md` and the files beside it |
-| Docs | Markdown, JSON, OpenAPI documents and JSON Schemas. `glossary.md` is read as terms, `decisions.md` as decisions |
-| Code | Classes and functions in 13 languages through tree-sitter, with their doc comments |
+| Skills | Every `SKILL.md` inside the directory of an AI tool (`.claude`, `.codex`, `.cursor`, `.gemini`, `.agents`, `.windsurf`, `.opencode`) and the files beside it. A `SKILL.md` elsewhere is a doc |
+| Docs | Markdown. `glossary.md` is read as terms, `decisions.md` as decisions |
+| Code | Classes and functions in 13 languages through tree-sitter, with their doc comments. JSON, TOML and YAML files, OpenAPI documents and JSON Schemas among them |
 | Database | `.sql` files. A file that creates tables becomes a schema diagram, any other a query catalog. No database is ever opened |
 | Tasks | The plans, phases and tasks that task-manager keeps, in `skills.settings.filetreeRoot` of `.g3n.config.json` (default `docs/task-manager`) |
+| Packages | A directory with a `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `composer.json`, `.csproj`, `.gemspec` or `Gemfile` is shown as a package: an app, a library or a workspace |
 
 Every page, entry, parameter and field is a node of one graph. Edges connect a type to where it is used, a term to the text that uses it, a decision to the code it affects, a table to its foreign keys and queries, and a task to the code, docs and decisions it names and to the tasks it depends on. One registry in `src/model/registry.ts` defines every kind of node and edge.
 
@@ -69,4 +74,4 @@ The web primitives in `src/web/components/shadcn/` are installed with the `g3nui
 
 ## License
 
-Elastic License 2.0. The word embedding table in `data/embedding/` was computed from all-MiniLM-L6-v2 (Apache-2.0) and potion (MIT). Its notice and licenses are kept beside it.
+Elastic License 2.0. The word embedding table in `assets/embedding/` was computed from all-MiniLM-L6-v2 (Apache-2.0) and potion (MIT). Its notice and licenses are kept beside it.

package/dist/api/bundle-builder.d.ts

@@ -2,27 +2,38 @@ import type { DocsBundle } from '../model';
 import { type FileLister, type Reporter, type RepositoryScanner, type Source, type TaskTreeSource } from '../scanner';
 import type { SemanticIndexer } from './embedding';
 import type { ScanOptions } from './scan';
-/** What a `BundleBuilder` works with. */
+/**
+ * What a `BundleBuilder` works with.
+ *
+ * @property files - Lists the files of a directory.
+ * @property scanner - Reads the files of a scan into graph nodes.
+ * @property semantic - Embeds the nodes for search by meaning. `null` leaves that search out of the bundle.
+ * @property generator - Recorded in the bundle as the tool that produced it.
+ * @property reporter - Receives the problems that do not stop a scan, such as a config file that is not valid.
+ */
 export interface BundleBuilderServices {
     readonly files: FileLister;
     readonly scanner: RepositoryScanner;
-    /** Embeds the nodes for search by meaning. `null` leaves that search out of the bundle. */
     readonly semantic: SemanticIndexer | null;
-    /** Recorded in the bundle as the tool that produced it. */
     readonly generator: string;
-    /** Receives the problems that do not stop a scan, such as a config file that is not valid. */
     readonly reporter: Reporter;
 }
-/** The directories of one scan, per section. */
+/**
+ * The directories of one scan, per section.
+ *
+ * @property skills - Directories the skills are read from.
+ * @property docs - Directories the docs are read from.
+ * @property code - Directories the code is read from.
+ * @property tasks - The task-manager tree of the repository. Empty when the repository has none.
+ */
 export interface ScanSources {
     readonly skills: readonly Source[];
     readonly docs: readonly Source[];
     readonly code: readonly Source[];
-    /** The task-manager tree of the repository. Empty when the repository has none. */
     readonly tasks: readonly TaskTreeSource[];
 }
 /**
- * Scans a repository into a bundle, with the file lister, scanner and embedder it holds.
+ * @brief Scans a repository into a bundle, with the file lister, scanner and embedder it holds.
  *
  * `createBuilder` in `src/api/services.ts` creates one per scan. `createDocs` writes its bundle into a site,
  * and `ScanLoader` hands it to the query functions. Both first call `sources` to list the files of the scan,
@@ -34,7 +45,11 @@ export interface ScanSources {
  */
 export declare class BundleBuilder {
     private readonly services;
-    /** Creates a builder from the file lister, the scanner, the embedder and the reporter to use. */
+    /**
+     * Creates a builder from the file lister, the scanner, the embedder and the reporter to use.
+     *
+     * @param services - What the builder works with.
+     */
     constructor(services: BundleBuilderServices);
     /**
      * Lists the files of a scan without reading them.
@@ -48,13 +63,16 @@ export declare class BundleBuilder {
      * Reads the files of a scan and links what they declare.
      *
      * @param sources - The directories of each section, from `sources`.
+     * @param title - Title of the bundle.
      * @returns The bundle, with a semantic index when the builder has an embedder.
      */
     build(sources: ScanSources, title: string): Promise<DocsBundle>;
     /**
-     * Finds the task-manager tree of a repository: the directory `skills.settings.filetreeRoot` of its
-     * `.g3n.config.json` names, `docs/task-manager` by default.
+     * @brief Finds the task-manager tree of a repository.
+     *
+     * The directory `skills.settings.filetreeRoot` of its `.g3n.config.json` names, `docs/task-manager` by default.
      *
+     * @param repository - The repository to look in.
      * @returns One tree with the files below its directory, or none when the directory does not exist.
      */
     private tasksIn;
@@ -68,6 +86,7 @@ export declare class BundleBuilder {
     /**
      * Picks the directories one section is read from.
      *
+     * @param repository - The repository source, read when no directories are given.
      * @param directories - Absolute directories the caller passed. Empty means the repository.
      * @returns The repository, or one source per directory.
      */

package/dist/api/bundle-cache.d.ts

@@ -19,15 +19,18 @@ export interface BundleCache {
     write(fingerprint: string, bundle: DocsBundle): Promise<void>;
 }
 /**
- * Names the cache entry of a scan. Two scans share an entry when they read
- * the same repository with the same options and the same version of the tool.
+ * @brief Names the cache entry of a scan.
  *
+ * Two scans share an entry when they read the same repository with the same options and the same version
+ * of the tool.
+ *
+ * @param scan - The options of the scan.
  * @param generator - Name and version of the tool, such as `GENERATOR` in `src/api/services.ts`.
  * @returns A file-name-safe key.
  */
 export declare function cacheKey(scan: ScanOptions, generator: string): string;
 /**
- * Fingerprints the files of a scan by path, size and modification time, and
+ * @brief Fingerprints the files of a scan by path, size and modification time, and
  * the directory of its task tree. The fingerprint changes when a file is
  * added, removed or saved, and when the config moves the task tree.
  *
@@ -36,7 +39,7 @@ export declare function cacheKey(scan: ScanOptions, generator: string): string;
  */
 export declare function fingerprintOf(sources: ScanSources): Promise<string>;
 /**
- * Keeps a bundle in one file of a cache directory. The first line of the
+ * @brief Keeps a bundle in one file of a cache directory. The first line of the
  * file is the fingerprint, the rest is the bundle as JSON.
  *
  * `openRetriever` creates one per query that scans a repository, in

package/dist/api/bundle-loader.d.ts

@@ -5,11 +5,15 @@ import { type BundleCache } from './bundle-cache';
 import type { ScanOptions } from './scan';
 /** Gets the bundle a query function reads. `loaderOf` in `src/api/source.ts` picks the implementation. */
 export interface BundleLoader {
-    /** Loads the bundle to query. */
+    /**
+     * Loads the bundle to query.
+     *
+     * @returns The bundle the queries read.
+     */
     load(): Promise<DocsBundle>;
 }
 /**
- * Loads the bundle of a site that `createDocs` wrote, from the HTML file alone, without the repository the
+ * @brief Loads the bundle of a site that `createDocs` wrote, from the HTML file alone, without the repository the
  * site was written from. `loaderOf` in `src/api/source.ts` creates one when a caller passes `from`
  * (`--from` on the CLI); `openRetriever` loads it.
  */
@@ -26,12 +30,13 @@ export declare class SiteLoader implements BundleLoader {
     /**
      * Reads the HTML file and takes the bundle out of it. Warns when its embeddings are of another format.
      *
+     * @returns The bundle the site holds.
      * @throws {SourceError} When the file is missing or is no analyze site.
      */
     load(): Promise<DocsBundle>;
 }
 /**
- * Loads the bundle of a repository: from the cache when no file changed
+ * @brief Loads the bundle of a repository: from the cache when no file changed
  * since the last scan, else from a new scan, which it then keeps.
  *
  * `loaderOf` in `src/api/source.ts` creates one when a caller passes no `from`; `openRetriever` loads it.
@@ -44,6 +49,8 @@ export declare class ScanLoader implements BundleLoader {
     /**
      * Creates a loader for one repository.
      *
+     * @param builder - Builds the bundle when the cache has none.
+     * @param scan - The repository to scan.
      * @param cache - Keeps the bundle between runs. `null` scans every time.
      * @param reporter - Receives a warning when the cache cannot be written.
      */

package/dist/api/create-docs.d.ts

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+import { type PackageRole } from '../model';
+/**
+ * Schema of the `createDocs` options.
+ *
+ * @property title - Site title. Default: the name of the repository directory.
+ */
 declare const createDocsSchema: z.ZodPipe<z.ZodObject<{
     onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
     repo: z.ZodOptional<z.ZodString>;
@@ -22,39 +28,52 @@ declare const createDocsSchema: z.ZodPipe<z.ZodObject<{
 }>>;
 /** Options of `createDocs`: what to scan and the title of the site. */
 export type CreateDocsOptions = z.input<typeof createDocsSchema>;
-/** Where `createDocs` wrote the site and what the site holds. */
+/**
+ * Where `createDocs` wrote the site and what the site holds.
+ *
+ * @property out - Absolute path of the site: `analyze_out/index.html` in the repository.
+ * @property bytes - Size of the site in bytes.
+ * @property skills - Skills of the bundle.
+ * @property docs - Pages of the docs section.
+ * @property files - Source files of the code section.
+ * @property configs - JSON, TOML and YAML files of the code section, OpenAPI documents and JSON Schemas included.
+ * @property packages - Packages of the code section, by role.
+ * @property symbols - Symbols of the source files.
+ * @property terms - Glossary terms.
+ * @property decisions - Decisions.
+ * @property operations - Operations of OpenAPI documents.
+ * @property definitions - Definitions of JSON Schemas and of OpenAPI documents.
+ * @property schemas - SQL files that create tables.
+ * @property tables - Tables of those files.
+ * @property catalogs - Directories of SQL files that create no table.
+ * @property queries - Queries and statements of those directories.
+ * @property plans - Plans of the task tree.
+ * @property tasks - Tasks of the task tree.
+ * @property completedTasks - Tasks with the status `completed`.
+ * @property links - Links between nodes: type references, mentions and the like.
+ * @property embedded - Nodes that search by meaning can find, and the model that embedded them. `null` without embeddings.
+ */
 export interface CreateDocsResult {
-    /** Absolute path of the site: `analyze_out/index.html` in the repository. */
     readonly out: string;
     readonly bytes: number;
     readonly skills: number;
     readonly docs: number;
     readonly files: number;
+    readonly configs: number;
+    readonly packages: Readonly<Record<PackageRole, number>>;
     readonly symbols: number;
-    /** Glossary terms. */
     readonly terms: number;
     readonly decisions: number;
-    /** Operations of OpenAPI documents. */
     readonly operations: number;
-    /** Definitions of JSON Schemas and of OpenAPI documents. */
     readonly definitions: number;
-    /** SQL files that create tables. */
     readonly schemas: number;
-    /** Tables of those files. */
     readonly tables: number;
-    /** Directories of SQL files that create no table. */
     readonly catalogs: number;
-    /** Queries and statements of those directories. */
     readonly queries: number;
-    /** Plans of the task tree. */
     readonly plans: number;
-    /** Tasks of the task tree. */
     readonly tasks: number;
-    /** Tasks with the status `completed`. */
     readonly completedTasks: number;
-    /** Links between nodes: type references, mentions and the like. */
     readonly links: number;
-    /** Nodes that search by meaning can find, and the model that embedded them. `null` without embeddings. */
     readonly embedded: {
         readonly nodes: number;
         readonly model: string;

package/dist/api/embedding.d.ts

@@ -4,17 +4,17 @@ export interface SemanticIndexer {
     /**
      * Embeds the searchable nodes of a scan.
      *
+     * @param nodes - Nodes of the scan to embed.
      * @returns The index for `DocsBundle.semantic`.
      */
     index(nodes: readonly GraphNode[]): Promise<SemanticIndex>;
 }
 /**
- * Embeds nodes with the model that ships with the package. Holds the word table of the model, read on first
- * use from two files: `vectors.bin` and `vocab.txt` in `build/embedding/` when run from source, or beside the
- * bundle when built.
+ * @brief Embeds nodes with the model that ships with the package.
  *
- * `shippedModel` in `src/api/services.ts` imports this module on first use and creates one for each scan with
- * embeddings, with its own directory as `baseDir`.
+ * Holds the word table of the model, read on first use from `vectors.bin` and `vocab.txt` in `build/embedding/`
+ * when run from source, or beside the bundle when built. `shippedModel` in `src/api/services.ts` imports this
+ * module on first use and creates one for each scan with embeddings, with its own directory as `baseDir`.
  */
 export declare class ShippedModelIndexer implements SemanticIndexer {
     private readonly baseDir;
@@ -25,8 +25,17 @@ export declare class ShippedModelIndexer implements SemanticIndexer {
      * @param baseDir - Absolute directory that relative paths of the bundled model files resolve against.
      */
     constructor(baseDir: string);
-    /** Reads the model on the first call, then embeds the searchable nodes into an index for `DocsBundle.semantic`. */
+    /**
+     * Reads the model on the first call, then embeds the searchable nodes.
+     *
+     * @param nodes - Nodes of the scan to embed.
+     * @returns The index for `DocsBundle.semantic`.
+     */
     index(nodes: readonly GraphNode[]): Promise<SemanticIndex>;
-    /** Reads the two files of the model and unpacks the four-bit vectors into a word table. */
+    /**
+     * Reads the two files of the model and unpacks the four-bit vectors.
+     *
+     * @returns The word table of the model, with its vectors unpacked.
+     */
     private load;
 }

package/dist/api/errors.d.ts

@@ -1,6 +1,9 @@
 /**
- * Options a caller passed that do not form a valid call. Holds one issue per problem.
- * Thrown by `parseOptions` in `src/api/options.ts`; `src/cli/index.ts` prints the usage and exits with 2 for it.
+ * @brief Options a caller passed that do not form a valid call.
+ *
+ * Holds one issue per problem in `issues`, and its message lists them all. Thrown by `parseOptions` in
+ * `src/api/options.ts`; `src/cli/index.ts` prints the usage and exits with 2 for it. Created with
+ * `new OptionsError(["limit: must be positive"])`.
  */
 export declare class OptionsError extends Error {
     readonly issues: readonly string[];
@@ -13,15 +16,19 @@ export declare class OptionsError extends Error {
     constructor(issues: readonly string[]);
 }
 /**
- * A query that cannot be answered, such as one for a node that does not exist. Thrown by `src/api/target.ts`
- * and `src/api/search.ts`; the CLI exits with 1 for it.
+ * @brief Error for a query that cannot be answered, such as one for a node that does not exist.
+ *
+ * Thrown by `src/api/target.ts` and `src/api/search.ts`; the CLI exits with 1 for it. Created with the
+ * message, e.g. `new QueryError('No node is called "x".')`.
  */
 export declare class QueryError extends Error {
     readonly name = "QueryError";
 }
 /**
- * A repository, a directory or a site file that is missing or cannot be read. Thrown by the bundle builder,
- * loader and site reader in `src/api/`; the CLI exits with 1 for it.
+ * @brief Error for a repository, a directory or a site file that is missing or cannot be read.
+ *
+ * Thrown by the bundle builder, loader and site reader in `src/api/`; the CLI exits with 1 for it. Created
+ * with the message, e.g. `new SourceError('Site not found: /path/site.html')`.
  */
 export declare class SourceError extends Error {
     readonly name = "SourceError";

package/dist/api/list.d.ts

@@ -1,38 +1,29 @@
 import { z } from 'zod';
 import type { NodeFilter, NodeSummary, Retriever } from '../retrieval';
+/**
+ * Schema of the `list` options.
+ *
+ * @property limit - Most rows. Absent lists everything.
+ */
 declare const listSchema: 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 listSchema: 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,19 +68,28 @@ declare const listSchema: z.ZodPipe<z.ZodObject<{
 }>>;
 /** Options of `list`: the filter, the limit, and the bundle to list. */
 export type ListOptions = z.input<typeof listSchema>;
-/** One `list` on a loaded bundle. */
+/**
+ * One `list` on a loaded bundle.
+ *
+ * @property filter - Narrows the nodes that count.
+ * @property limit - Most rows. `null` lists everything.
+ */
 export interface ListRequest {
     readonly filter: NodeFilter;
-    /** Most rows. `null` lists everything. */
     readonly limit: number | null;
 }
-/** What `list` finds. The CLI prints it with `list --json`. */
+/**
+ * What `list` finds. The CLI prints it with `list --json`.
+ *
+ * @property nodes - The nodes, in the order of the navigation.
+ */
 export interface ListResult {
     readonly nodes: readonly NodeSummary[];
 }
 /**
  * Lists the pages and entries of a loaded bundle.
  *
+ * @param retriever - The loaded bundle to list.
  * @param request - The filter and the limit.
  * @returns The nodes, in the order of the navigation.
  */

package/dist/api/options.d.ts

@@ -7,40 +7,30 @@ export type WarningHandler = (message: string) => void;
 export declare const warningShape: {
     onWarning: z.ZodOptional<z.ZodCustom<WarningHandler, WarningHandler>>;
 };
-/** The options that narrow the nodes a query looks at. */
+/**
+ * The options that narrow the nodes a query looks at.
+ *
+ * @property kinds - Only nodes of these kinds. Empty or absent keeps every kind.
+ * @property section - Only nodes of this section.
+ */
 export declare const filterShape: {
-    /** Only nodes of these kinds. Empty or absent keeps every kind. */
     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";
@@ -48,7 +38,6 @@ export declare const filterShape: {
         trait: "trait";
         type: "type";
     }>>>>;
-    /** Only nodes of this section. */
     section: z.ZodOptional<z.ZodEnum<{
         code: "code";
         database: "database";
@@ -57,20 +46,27 @@ export declare const filterShape: {
         tasks: "tasks";
     }>>;
 };
-/** The filter options after validation. */
+/** The filter options after validation: `kinds` and `section`, both optional. */
 type FilterFields = z.output<z.ZodObject<typeof filterShape>>;
 /**
  * Turns validated filter options into the filter the retriever takes.
  *
- * @returns The filter. Absent options keep every node.
+ * @param fields - Validated filter options, from `filterShape`.
+ * @returns The filter the retriever takes. Absent options keep every node.
  */
 export declare function filterOf(fields: FilterFields): NodeFilter;
-/** Turns the warning option into the reporter the services take: one that hands each warning to the handler, or drops it. */
+/**
+ * Turns the warning option into the reporter the services take.
+ *
+ * @param onWarning - The caller's handler, or `undefined` to drop the warnings.
+ * @returns A reporter that hands each warning to the handler, or drops it.
+ */
 export declare function reporterOf(onWarning: WarningHandler | undefined): Reporter;
 /**
  * Validates the options a caller passed against the schema of a function.
  *
  * @param schema - The schema of the options, with its transform.
+ * @param input - The options the caller passed, not yet validated.
  * @returns The options after the transform.
  * @throws {OptionsError} When the options do not fit the schema. Its `issues` name each problem.
  */

package/dist/api/refs.d.ts

@@ -1,38 +1,32 @@
 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<{
-        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";
@@ -84,7 +78,7 @@ declare const refsSchema: 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;
@@ -100,21 +94,30 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
 }>>;
 /** 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. */
+/**
+ * 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 {
-    /** Id, path or name of the node. */
     readonly target: string;
     readonly filter: NodeFilter;
     readonly references: ReferenceOptions;
 }
-/** What `refs` finds. The CLI prints it with `refs --json`. */
+/**
+ * What `refs` finds. The CLI prints it with `refs --json`.
+ *
+ * @property node - The node the references are of.
+ */
 export interface RefsResult extends References {
-    /** The node the references are of. */
     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.