@g3nomaly/analyze 0.1.5 → 0.1.7

package/README.md

@@ -11,7 +11,7 @@ cd ~/code/my-repo
 bunx @g3nomaly/analyze create_docs
 ```
 
-This writes `analyze_out/index.html` in the repository, and the query commands keep their scan cache in `analyze_out/` as well. analyze puts a `.gitignore` holding `*` in `analyze_out/`, so git skips the directory. It writes nothing else in the repository.
+This writes `analyze_out/index.html` in the repository, and the query commands keep their scan cache in `analyze_out/` as well. analyze puts a `.gitignore` holding `*` in `analyze_out/`, so git skips the directory. It writes nothing else in the repository. `--out <file>` writes the site to that file instead, and then `create_docs` writes nothing in the repository.
 
 ## What it skips
 
@@ -30,34 +30,50 @@ On top of `.gitignore`, the scan skips `node_modules/`, `dist/`, `build/`, `out/
 | 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`, `Gemfile`, `vcpkg.json` or `CMakeLists.txt` is shown as a package: an app, a library or a workspace. A `CMakeLists.txt` counts when it calls `project(`, builds a library or an executable (`add_library`, `add_executable`, or a macro whose name holds `library` or `executable`), or sits beside an `include/` folder. In a `src/`, `test/`, `tests/`, `cmake/` or `examples/` directory only `project(` counts, so `libs/<lib>/src/CMakeLists.txt` stays part of `libs/<lib>` |
 
-Every page, entry, parameter and field is a node of one graph. Edges connect a type to where it is used, a source file to the files it includes or imports, a function to the functions it calls, 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.
+Every page, entry, parameter and field is a node of one graph. Edges connect a type to where it is used, a source file to the files it includes or imports, a function to the functions it calls and to those it passes on as values, 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.
 
 ## Querying
 
 ```sh
-g3n-analyze search how are routes chosen     # by words and by meaning
+g3n-analyze search how are routes chosen     # by words and by meaning, per section
 g3n-analyze show choose_route                # one page or entry in full
 g3n-analyze refs Sailing --kind term         # what it links to, and what links to it
+g3n-analyze refs Rates.find --incoming --depth 3   # what links to it, and what links to those
+g3n-analyze path Rates.price LineItem.perTeu # the shortest chain of edges from one to the other
 g3n-analyze list --kind task                 # every task with its status
 g3n-analyze graph --level packages --json    # which package uses which, as nodes and edges
 g3n-analyze list --community 3               # every page and entry of one community
 g3n-analyze show TASK-002 --json             # a task, as JSON
 ```
 
+`search` searches each section on its own and lists the hits under one heading per section, so the docs of a repository never crowd out its code. `-n` is the most hits per section, 5 by default, and `--section` keeps to one section. In the JSON the hits come in the same order, each with its `section`. Hits are best first in each section. `score` is set only for a match by meaning, from 0 to 1; a match by words has `score: null`, and its place in the list is its rank.
+
+Hits that match the same way, with the same kind, type, title, summary, score and matched member, such as nine `hooks.json` files that say nothing, are one hit. It says how many nodes it stands for and lists the path of each, in `duplicates` in the JSON. A hit found through a parameter, field, operation or definition names it, as in `interface InstallerIO (field hashFile)`, and so does the message for a name that fits several nodes. A name that fits no node suggests the closest names.
+
 When nothing matches, `search` lists up to three weak matches by meaning instead, under a note and with `weak: true` in the JSON. Rewording the query often finds a better one. Output is markdown, or JSON with `--json`. `--from analyze_out/index.html` queries a built site without the repository. `g3n-analyze --help` lists every option, node kind, section and edge kind.
 
+`refs --depth <n>` follows the edges `n` hops, one hop at a time in each direction, and prints each hop indented under the reference it follows. A node is listed once. `--edge`, `--incoming` and `--outgoing` apply at every hop; `--kind` and `--section` only pick the node to start from. `refs` lists at most 50 references over every hop, or `-n`, and says how many more it left out. `path <from> <to>` follows edges the way they point, so `path a b` and `path b a` differ; `--edge` keeps it to some kinds. Without `--edge` it follows every kind but `mentions`, the links descriptions make; `--include-mentions` follows those too, and of equally short chains the one with the fewest `mentions` steps still wins. A name with spaces goes in quotes.
+
+A call, a function passed on and an import say where they are made: `calls (add.ts:86, 112)` is a call on lines 86 and 112 of `add.ts`, the file of the node the edge starts at. In the JSON, such a reference has `location`, with the `path` of that file and its `lines`; any other reference has `location: null`. The links to one node print on one line, `calls (app.ts:7), passes (app.ts:9): function run`, and a heading counts the lines under it.
+
+`refs --level files` lists the links between the file of the node and other files, the way the files level of the graph page draws them: every link of the file or of an entry in it, to another file or an entry in it, counts for that file. These are no links of their own. The default, `--level entries`, lists the links as they are stored.
+
+The commands exit with 0 when they answer, also for a search that finds nothing, with 1 for a node that does not exist, a name that fits several nodes, a `path` with no chain, or a repository or site that cannot be read, and with 2 for a call that is not valid, such as an unknown flag.
+
 `graph` exports the whole graph in one call. `--level` picks how much of it: `files`, `entries` and `all` are the levels of the graph page of the site, and `packages` and `communities` sum the edges between packages or communities. `--kind`, `--section`, `--community` and `--edge` narrow the nodes and edges. An edge of a node the level leaves out, such as a call at the `files` level, counts for the node that holds it, such as its file.
 
 ### Communities
 
-A **community** is a group of nodes that link to each other more than to the rest, such as the classes and functions of one feature. Each scan splits the graph once, with the Louvain method, over every page and entry; a parameter or field is in the community of its entry, and a folder or package is in none. The community is a value of the node: `graph --level communities` lists them with their ids, `--community <id>` narrows `list`, `search`, `show`, `refs` and `graph` to one, and every node of a `graph` export carries its id. On the graph page of the site, dots can be colored by community and one community can be shown on its own.
+A **community** is a group of nodes that link to each other more than to the rest, such as the classes and functions of one feature. Each scan splits the graph once, with the Louvain method, over every page and entry; a parameter or field is in the community of its entry, and a folder or package is in none, nor is a page or entry that would be alone in one. The community is a value of the node: `graph --level communities` lists them with their ids, their size in pages and entries (a parameter or field counts with its entry) and their five best-linked pages and entries, `--community <id>` narrows `list`, `search`, `show`, `refs` and `graph` to one, and every node of a `graph` export carries its id. On the graph page of the site, dots can be colored by community and one community can be shown on its own.
 
 ### How code links
 
-- **Imports**: C and C++ `#include`, JavaScript and TypeScript imports, and Python imports link to the file of the repository they name. An include resolves next to the including file, then against every file whose path ends with it, the closest winning. A TypeScript import resolves a relative path, a package of the repository by name (`@scope/core`), or a path alias (`@/lib/api`). A header or package from outside the repository links to nothing.
+- **Imports**: an import of a whole file links to that file: a C or C++ `#include`, a Python `import a.b`, and in JavaScript and TypeScript `import './x'`, `import * as x`, a default import, `export * from` and `require`. An import by name links to each class, function or type it names, through any `export … from` files in between, and not to the file: `import { recordedHashes } from "../../installer"` links to `recordedHashes` in `installer/classify.ts`, which `installer/index.ts` re-exports. Python's `from a import b` does the same for a `b` that is no module. A name that is no node, such as a constant, links to the file the import names. An include resolves next to the including file, then against every file whose path ends with it, the closest winning. A TypeScript import resolves a relative path, a package of the repository by name (`@scope/core`), or a path alias (`@/lib/api`). A header or package from outside the repository links to nothing. The files level of the graph page and of `graph` draws the links of a file to the entries of another file as one arrow between the files.
 - **What a file sees**: in C, C++, JavaScript, TypeScript and Python, a file sees itself and the files it imports, directly or through other files. A type name or a call only links to a declaration in a file it sees, so a common name never links across the repository. In the other languages every file is seen, and a type name links to the closest declaration of that name.
 - **Types**: a qualified C++ name such as `geo::Point` only links to a `Point` inside `geo`. A type declared in a C or C++ source file is seen only in that file.
-- **Calls**: a call links when it names one function: by name, through a namespace or type (`geo::distance()`, `Timer.once()`), through `this` or `self`, or through a parameter or field whose declared type is known. A call through a local variable, a module alias such as `helpers.go()`, or any other expression links nowhere, since its type is unknown. A bare call inside a JavaScript, TypeScript or Python method never means a method of its own class. A C++ method declared in a header and defined in a source file is called at its declaration.
+- **Calls**: a call links when it names one function: by name, through a namespace or type (`geo::distance()`, `Timer.once()`), through `this` or `self`, or through a parameter or field whose declared type is known. A call through a local variable, a module alias such as `helpers.go()`, or any other expression links nowhere, since its type is unknown. A bare call inside a JavaScript, TypeScript or Python method never means a method of its own class. A C++ method declared in a header and defined in a source file is called at its declaration. Only the calls inside a function or method link: code at the top level of a file, such as the callbacks a CLI registers there, belongs to no function.
+- **Values**: a function handed on without a call, such as the callback in `run(onDone)`, the entry of `{ add: addCommand }`, an element of `[first, second]` or `this.flush`, links as `passes`. It links the way a call of that name would. A name the function binds itself, as a parameter, a local, a loop variable or a lambda parameter, links nowhere, and nor does a getter or setter, which reading runs.
+- **Examples**: the generated example of a JavaScript or TypeScript symbol imports it the way code outside its package does: from the package name, or from a subpath of its `exports` such as `@scope/core/hash`, under the name the entry file there exports it as, through `export … from`. A symbol no package exports has no import line.
 
 ## From hooks
 
@@ -80,20 +96,22 @@ const callers = await refs({
 });
 ```
 
-`createDocs`, `search`, `show`, `refs`, `list` and `graph` take the options of the CLI as fields.
+`createDocs`, `search`, `show`, `refs`, `path`, `list` and `graph` take the options of the CLI as fields. `path` takes its two nodes as `start` and `end`, since `from` names a site to read.
 
 ## Development
 
 Run every command from this directory.
 
 ```sh
-bun run build              # web app, CLI and library into dist/
+bun run build              # web app, CLI and library into dist/, examples into build/
 bun run typecheck
 bun test                   # unit tests
 bun run test:integration   # builds first
 bun run analyze -- --help  # the CLI from source, after one build
 ```
 
+The build also runs a set of queries on the g3n monorepo and writes what each prints, as text and as JSON, to `build/examples/`, beside the site it queries. Its `README.md` lists them. `build/` is gitignored and never ships. The queries are in `scripts/examples.ts`.
+
 The web primitives in `src/web/components/shadcn/` are installed with `@g3nomaly/ui`. The reasons behind the design are in [`decisions.md`](decisions.md).
 
 ## License

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

@@ -4,6 +4,8 @@ import { type PackageRole } from '../model';
  * Schema of the `createDocs` options.
  *
  * @property title - Site title. Default: the name of the repository directory.
+ * @property out - Path of the site file, relative to the working directory. Default: `analyze_out/index.html` in the
+ *   repository.
  */
 declare const createDocsSchema: z.ZodPipe<z.ZodObject<{
     onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
@@ -13,9 +15,11 @@ declare const createDocsSchema: z.ZodPipe<z.ZodObject<{
     excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     embeddings: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
+    out: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodTransform<{
     scan: import("./scan").ScanOptions;
     title: string;
+    out: string | null;
     reporter: import("../scanner").Reporter;
 }, {
     onWarning?: import("./options").WarningHandler | undefined;
@@ -25,13 +29,14 @@ declare const createDocsSchema: z.ZodPipe<z.ZodObject<{
     excludes?: readonly string[] | undefined;
     embeddings?: boolean | undefined;
     title?: string | undefined;
+    out?: string | undefined;
 }>>;
-/** Options of `createDocs`: what to scan and the title of the site. */
+/** Options of `createDocs`: what to scan, the title of the site and where to write it. */
 export type CreateDocsOptions = z.input<typeof createDocsSchema>;
 /**
  * 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 out - Absolute path of the site: the `out` option, else `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.
@@ -80,9 +85,10 @@ export interface CreateDocsResult {
     } | null;
 }
 /**
- * Scans a repository and writes its documentation site to `analyze_out/index.html` in the repository.
+ * @brief Scans a repository and writes its documentation site to `out`, or to `analyze_out/index.html` in the
+ * repository. With `out`, it writes nothing in the repository.
  *
- * @param options - What to scan and the title. Default: the working directory.
+ * @param options - What to scan, the title and where to write. Default: the working directory.
  * @returns Where the site was written and what it holds.
  * @throws {OptionsError} When the options are not valid.
  * @throws {SourceError} When the repository or one of the directories does not exist.

package/dist/api/graph.d.ts

@@ -65,6 +65,7 @@ declare const graphSchema: z.ZodPipe<z.ZodObject<{
         imports: "imports";
         mentions: "mentions";
         names: "names";
+        passes: "passes";
         reads: "reads";
         references: "references";
         returns: "returns";
@@ -79,7 +80,7 @@ declare const graphSchema: z.ZodPipe<z.ZodObject<{
     request: {
         level: "all" | "communities" | "entries" | "files" | "packages";
         filter: NodeFilter;
-        edges: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+        edges: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
     };
 }, {
     onWarning?: import("./options").WarningHandler | undefined;
@@ -94,7 +95,7 @@ declare const graphSchema: z.ZodPipe<z.ZodObject<{
     from?: string | undefined;
     cache?: boolean | undefined;
     level?: "all" | "communities" | "entries" | "files" | "packages" | undefined;
-    edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+    edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
 }>>;
 /** Options of `graph`: the level, the nodes and edges to keep, and the bundle to read. */
 export type GraphOptions = z.input<typeof graphSchema>;

package/dist/api/path.d.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { type EdgeKind } from '../model';
+import type { NodeFilter, NodeSummary, Reference, Retriever } from '../retrieval';
+/**
+ * Schema of the `path` options.
+ *
+ * @property start - Id, path or name of the node the chain starts at. Not `from`, which names a site to read.
+ * @property end - Id, path or name of the node the chain ends at.
+ * @property edges - Only edges of these kinds. Empty or absent follows every kind but `mentions`.
+ * @property includeMentions - Also follow `mentions`, the links descriptions make, when `edges` is empty. Of the
+ *   chains that are equally short, the one with the fewest `mentions` steps still wins.
+ */
+declare const pathSchema: 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";
+    }>>;
+    communities: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodNumber>>>;
+    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>;
+    start: z.ZodString;
+    end: z.ZodString;
+    edges: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        affects: "affects";
+        calls: "calls";
+        depends: "depends";
+        extends: "extends";
+        imports: "imports";
+        mentions: "mentions";
+        names: "names";
+        passes: "passes";
+        reads: "reads";
+        references: "references";
+        returns: "returns";
+        throws: "throws";
+        type: "type";
+        uses: "uses";
+        writes: "writes";
+    }>>>>;
+    includeMentions: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodTransform<{
+    source: import("./source").BundleSource;
+    reporter: import("../scanner").Reporter;
+    request: {
+        start: string;
+        end: string;
+        filter: NodeFilter;
+        kinds: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+        includeMentions: boolean;
+    };
+}, {
+    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;
+    communities?: readonly number[] | 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;
+    start: string;
+    end: string;
+    edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+    includeMentions?: boolean | undefined;
+}>>;
+/** Options of `path`: the two nodes, the edges to follow, and the bundle to read. */
+export type PathOptions = z.input<typeof pathSchema>;
+/**
+ * One `path` on a loaded bundle.
+ *
+ * @property start - Id, path or name of the node the chain starts at.
+ * @property end - Id, path or name of the node the chain ends at.
+ * @property filter - Narrows both names to one node each.
+ * @property kinds - Edge kinds to follow. Empty follows every kind but `mentions`, unless `includeMentions` is set.
+ * @property includeMentions - Whether an empty `kinds` follows `mentions` too.
+ */
+export interface PathRequest {
+    readonly start: string;
+    readonly end: string;
+    readonly filter: NodeFilter;
+    readonly kinds: readonly EdgeKind[];
+    readonly includeMentions: boolean;
+}
+/**
+ * What `path` finds. The CLI prints it with `path --json`.
+ *
+ * @property start - The node the chain starts at.
+ * @property end - The node the chain ends at.
+ * @property steps - Each edge of the chain in order, with the node it leads to. The last leads to `end`.
+ */
+export interface PathResult {
+    readonly start: NodeSummary;
+    readonly end: NodeSummary;
+    readonly steps: readonly Reference[];
+}
+/**
+ * @brief Finds the shortest chain of edges between two nodes of a loaded bundle, following edges the way they point.
+ *
+ * @param retriever - The loaded bundle to read.
+ * @param request - The two nodes, the filter that narrows their names, and the edge kinds to follow.
+ * @returns Both nodes and the chain between them.
+ * @throws {QueryError} When no node fits a name, several do, or no chain leads from one node to the other.
+ */
+export declare function pathIn(retriever: Retriever, request: PathRequest): PathResult;
+/**
+ * @brief Finds the shortest chain of edges from one node to another, such as the calls from a command to a helper.
+ *
+ * @param options - The two nodes, the edges to follow, and the repository or site to read.
+ * @returns Both nodes and the chain between them.
+ * @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 a name, several do, or no chain leads from one node to the other.
+ */
+export declare function path(options: PathOptions): Promise<PathResult>;
+export {};

package/dist/api/refs.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { NodeFilter, NodeSummary, ReferenceOptions, References, Retriever } from '../retrieval';
+import { type NodeFilter, type NodeSummary, type Retriever, type Walk, type WalkOptions } from '../retrieval';
 /**
  * Schema of the `refs` options.
  *
@@ -7,6 +7,10 @@ import type { NodeFilter, NodeSummary, ReferenceOptions, References, Retriever }
  * @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.
+ * @property depth - Hops to follow from the node. Default: 1, the node's own references.
+ * @property limit - Most references to list, every hop and both directions together. Default: 50.
+ * @property level - `entries` for the stored links, `files` for the links between the files that hold their ends,
+ *   from the file of the node. Default: `entries`.
  */
 declare const refsSchema: z.ZodPipe<z.ZodObject<{
     onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
@@ -60,6 +64,7 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
         imports: "imports";
         mentions: "mentions";
         names: "names";
+        passes: "passes";
         reads: "reads";
         references: "references";
         returns: "returns";
@@ -68,15 +73,24 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
         uses: "uses";
         writes: "writes";
     }>>>>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    level: z.ZodOptional<z.ZodEnum<{
+        entries: "entries";
+        files: "files";
+    }>>;
 }, z.core.$strict>, z.ZodTransform<{
     source: import("./source").BundleSource;
     reporter: import("../scanner").Reporter;
     request: {
         target: string;
         filter: NodeFilter;
-        references: {
+        walk: {
             direction: "both" | "in" | "out";
-            kinds: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+            kinds: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+            depth: number;
+            limit: number;
+            level: "entries" | "files";
         };
     };
 }, {
@@ -94,43 +108,46 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
     target: string;
     incoming?: boolean | undefined;
     outgoing?: boolean | undefined;
-    edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+    edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+    depth?: number | undefined;
+    limit?: number | undefined;
+    level?: "entries" | "files" | undefined;
 }>>;
-/** Options of `refs`: the node, which links to follow, and the bundle to read. */
+/** Options of `refs`: the node, which links to follow and how far, 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.
+ * @property filter - Narrows a name to one node. The references themselves are not narrowed by it.
+ * @property walk - Which links to follow: direction, edge kinds, depth and limit.
  */
 export interface RefsRequest {
     readonly target: string;
     readonly filter: NodeFilter;
-    readonly references: ReferenceOptions;
+    readonly walk: WalkOptions;
 }
 /**
  * What `refs` finds. The CLI prints it with `refs --json`.
  *
- * @property node - The node the references are of.
+ * @property node - The node the references are of: the file of the target at the `files` level.
  */
-export interface RefsResult extends References {
+export interface RefsResult extends Walk {
     readonly node: NodeSummary;
 }
 /**
- * Lists the references of one node of a loaded bundle.
+ * @brief Lists the references of one node of a loaded bundle, followed for some hops.
  *
  * @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.
+ * @param request - The node, the filter that narrows a name, and the walk to make.
+ * @returns The node with what it links to and what links to it, and how many references the limit left out.
  * @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.
+ * @brief Lists what a node links to and what links to it, and with `depth` what those link to in turn.
  *
- * @param options - The node, which links to follow, and the repository or site to read.
+ * @param options - The node, which links to follow and how far, 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.

package/dist/api/search.d.ts

@@ -1,13 +1,13 @@
 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;
+/** Most hits per section of a search without a limit. */
+export declare const DEFAULT_SEARCH_LIMIT = 5;
 /**
  * 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.
+ * @property limit - Most hits per section. Default: 5.
  */
 declare const searchSchema: z.ZodPipe<z.ZodObject<{
     onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
@@ -89,8 +89,8 @@ export type SearchOptions = z.input<typeof searchSchema>;
  *
  * @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.
+ * @property limit - Most hits per section.
+ * @property filter - Narrows the nodes that count. With a section, only that section is searched.
  */
 export interface SearchRequest {
     readonly query: string;
@@ -104,7 +104,8 @@ export interface SearchRequest {
  * @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. When nothing matched, the few closest by meaning, each marked `weak`.
+ * @property hits - Hits grouped by section, the sections in the order the site lists them, and best first in each.
+ *   When nothing matched, the few closest by meaning in all of them, each marked `weak`, in the same order.
  */
 export interface SearchResult {
     readonly query: string;
@@ -113,12 +114,13 @@ export interface SearchResult {
     readonly hits: readonly SearchHit[];
 }
 /**
- * @brief Searches a loaded bundle. When nothing clears the cut-off, it returns the few closest hits by meaning
- * below it instead, each marked `weak`.
+ * @brief Searches a loaded bundle, each section on its own, so the hits of one section never crowd out another.
+ * When nothing clears the cut-off in any section, it returns the few closest hits by meaning below it instead, each
+ * marked `weak`.
  *
  * @param retriever - The loaded bundle to search.
- * @param request - The words, the mode, the limit and the filter.
- * @returns The hits, best first.
+ * @param request - The words, the mode, the limit per section and the filter.
+ * @returns The hits, grouped by section and best first in each.
  * @throws {QueryError} When the search is by meaning and the bundle has no embeddings.
  */
 export declare function searchIn(retriever: Retriever, request: SearchRequest): SearchResult;

package/dist/api/target.d.ts

@@ -1,12 +1,13 @@
 import type { NodeRef } from '../model';
 import type { NodeFilter, Retriever } from '../retrieval';
 /**
- * Finds the one node a caller means.
+ * @brief 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.
+ * @throws {QueryError} When no node fits, or several do. For no node, the message names the closest names. For
+ *   several, it lists the candidates with their ids, and the field or parameter a candidate matched by.
  */
 export declare function nodeOf(retriever: Retriever, target: string, filter: NodeFilter): NodeRef;