@zenera/rag 1.1.4 → 1.1.6

package/README.md

@@ -46,6 +46,40 @@ zen rag schema stats                  # what is in the index, and what built it
 zen rag schema show Type:Invoice      # a named node, with no search in between
 ```
 
+Search ranks, which means it returns the top of a list — useful when the
+question is vague, and no use at all when the question is whether something
+exists. For that there is exact matching, which needs no embedder, no
+credential and no network:
+
+```sh
+zen rag schema list methods --path "*/users*"   # every route under /users
+zen rag schema list types --name "*Password*"   # every schema so named
+zen rag schema grep password                    # every literal occurrence
+zen rag schema grep "pass(word|phrase)" --regex
+zen rag schema show --method GetCurrentUserInfo --format openapi --exact
+```
+
+Patterns are globs by default and regular expressions under `--regex`, on
+`list` as well as `grep`, which is the only way to say "one of these prefixes":
+
+```sh
+zen rag schema list methods --regex --path "^/(users|teams)/"
+zen rag schema grep status --path "/invoices/*" --kind property
+```
+
+`grep` takes the same `--name` and `--path` constraints `list` takes, so a
+common word can be narrowed to one corner of the API instead of being read out
+of every document at once.
+
+When an index holds more than one document, `--show-source` names the one each
+row came from — `[source: billing_api_v2]` — on `list`, `grep`, `search` and
+`show` alike, so the document does not have to be recovered from `--json`.
+
+`list` and `grep` report `found` as the true total even when `--limit` cuts the
+printed rows, so a shortened answer still tells you how much there is. Nothing
+matching exits 0 — an empty answer is an answer, and here it is a trustworthy
+one: if `grep` finds nothing, the word is not in the description.
+
 Non-interactive search is a machine interface: every field is a flag, the whole
 query can arrive as one JSON object, the `--json` output keeps the same
 structure from run to run, no terminal is required, and an empty result exits 0.
@@ -61,12 +95,30 @@ zen rag schema search --query - --format ts <<'JSON'
 JSON
 ```
 
+## Which index
+
+Every reading command takes `-d, --dir`. Without one, `$ZEN_SCHEMA_DB` is used
+if it is set; without that, the nearest index to the working directory is found
+and named on stderr as it is used.
+
+Nearest means what it says: this directory, then a short way down into it, then
+up a level and again, stopping at your home directory. What is looked for is a
+`manifest.json` — an index is self-describing, so nothing here searches for a
+directory called `schema-db`, and an index called anything else is found just
+the same. `schema-db` is only the name a new one is given.
+
+Two indexes the same distance away is a question, not a tie to break, and it is
+refused: the wrong index does not fail, it answers confidently about a
+different API. Name one with `--dir`, or set `ZEN_SCHEMA_DB`.
+
 ## Commands
 
 ```
 zen rag schema index <spec...>   Read the documents and write a searchable index.
 zen rag schema search            Ask it something. --interactive for a prompt.
-zen rag schema show <id...>      Print named nodes, with no search in between.
+zen rag schema list <what>       Every method, type or property. No ranking.
+zen rag schema grep <pattern>    Every literal match across the whole index.
+zen rag schema show [id...]      Print named nodes, with no search in between.
 zen rag schema stats             What is in an index, and what built it.
 ```
 
@@ -76,6 +128,22 @@ by `--direction`, `--method-type`, `--limit`, `--max-hops`, `--max-nodes` and
 the four `--exclude-*` filters, and rendered by `--format text | mermaid |
 mermaid-flowchart | ts | openapi`. `zen help rag` prints the full table.
 
+`list` and `grep` share `--name`, `--path`, `--regex`, `--case-sensitive`,
+`--source`, `--show-source` and `--limit`; `grep` adds `--kind` and
+`--ids-only`. A pattern with `*` or `?` in it is a glob matched against the
+whole name; a plain word is a substring, so `--name password` finds
+`ResetPasswordPayload` rather than nothing; under `--regex` it is a regular
+expression either way. `--path` selects on the route an operation sits on, and
+on the route a parameter's operation sits on — a schema belongs to no one
+route, so `--path` never selects one. `show` takes ids, or `--method` and
+`--type` by name, or `--source` for a whole document, and `--exact` to print
+only what was named instead of its neighbourhood.
+
+```sh
+# Everything that mentions a token, rendered as TypeScript.
+zen rag schema grep token --ids-only | xargs zen rag schema show --format ts
+```
+
 ## From an agent
 
 ```ts
@@ -89,18 +157,23 @@ const index = await SchemaIndex.open(
 const project = await loadProject('./my-project', { tools: schemaTools(index) });
 ```
 
-Four tools in the group `schema`, selectable as `schema:*`:
+Five tools in the group `schema`, selectable as `schema:*`:
 
 | Tool                       | For                                                     |
 | -------------------------- | ------------------------------------------------------- |
 | `search_api`               | the connected piece of the API that matches an intent   |
 | `describe_types`           | named schemas as declarations that compile on their own |
 | `find_types_with_property` | which types have a field of this name — no search       |
-| `list_methods`             | the shape of the API, by path                           |
+| `list_api`                 | the shape of the API: methods, types or fields          |
+| `grep_api`                 | every literal occurrence of a string — no search        |
 
-`find_types_with_property` is the one for the repair loop: when `tsc` says
+Only the first of those ranks anything. The rest are exact, because a model
+told "no results" by a vector search has learned nothing: a ranking returns the
+top of a list, so an empty answer and an absent thing look identical.
+`find_types_with_property` is the one for the repair loop — when `tsc` says
 `'password' does not exist in type 'PublicUserProfile'`, the model does not
 need the word explained again, it needs the list of types that have one.
+`grep_api` is the same instinct widened to the whole description.
 
 ## What an index is
 

package/dist/command.js

@@ -5,9 +5,13 @@ import { isFormat, present } from "./present.js";
 import { isEmpty, parseQuery, QueryError } from "./query.js";
 import { repl } from "./repl.js";
 import { buildIndex } from "./schema/build.js";
-import { assertSameEmbedding, openIndex, readManifest } from "./schema/files.js";
+import { assertSameEmbedding, openIndex, readManifest, readSource, } from "./schema/files.js";
+import { DEFAULT_DIR, DIR_ENV, locateIndex, outputDir } from "./schema/locate.js";
+import { fields, grepNodes, listNodes, propertyCount } from "./schema/lookup.js";
+import { isGlob, loose, matcher, PatternError, wildcard } from "./schema/match.js";
+import { sourceTag } from "./schema/render.js";
 import { SchemaIndex } from "./schema/search.js";
-import { stitch } from "./schema/subgraph.js";
+import { select, stitch } from "./schema/subgraph.js";
 // ---------------------------------------------------------------------------
 // zen rag — an api description, as something to search
 //
@@ -18,11 +22,19 @@ import { stitch } from "./schema/subgraph.js";
 // required, and exit 0 when nothing matched — an empty answer is an answer, and
 // a caller that has to tell "no results" from "the index is missing" by parsing
 // stderr will get it wrong.
+//
+// `list`, `grep` and `show` are the other half, and they are deliberately not
+// searches. A ranking can only ever hand back the top of a list, so it cannot
+// answer "is there a field called `password` anywhere" — the honest answer to
+// that question is every match or none, and these three give it without asking
+// a model or a credential for permission.
 // ---------------------------------------------------------------------------
-const USAGE = 'zen rag schema <index|search|show|stats> [spec...]';
+const USAGE = 'zen rag schema <index|search|list|grep|show|stats> [spec...]';
 const INDEX_USAGE = 'zen rag schema index --embedding <ref> [--out <dir>] <spec...>';
 const SEARCH_USAGE = 'zen rag schema search [--dir <dir>] [query...]';
-const DEFAULT_DIR = './schema-db';
+const LIST_USAGE = 'zen rag schema list <methods|types|properties> [--dir <dir>]';
+const GREP_USAGE = 'zen rag schema grep <pattern> [--dir <dir>]';
+const SHOW_USAGE = 'zen rag schema show [id...] [--method <name>] [--type <name>]';
 export const command = {
     summary: 'Search an openapi/swagger document as a graph.',
     usage: USAGE,
@@ -31,7 +43,9 @@ export const command = {
         ...table([
             ['  index <spec...>', dim('Read the documents and write a searchable index.')],
             ['  search', dim('Ask it something. --interactive for a prompt.')],
-            ['  show <id...>', dim('Print named nodes, with no search in between.')],
+            ['  list <what>', dim('Every method, type or property matching a pattern.')],
+            ['  grep <pattern>', dim('Every literal match, ranked by nothing.')],
+            ['  show [id...]', dim('Print named nodes, with no search in between.')],
             ['  stats', dim('What is in an index, and what built it.')],
         ]),
         '',
@@ -41,7 +55,10 @@ export const command = {
                 '  --embedding <ref>',
                 dim('Which embedder makes the vectors. Omit it to be shown the choices.'),
             ],
-            ['  -o, --out <dir>', dim(`Where the index goes. Default ${DEFAULT_DIR}.`)],
+            [
+                '  -o, --out <dir>',
+                dim(`Where the index goes. Default ${DEFAULT_DIR}, or ${DIR_ENV}.`),
+            ],
             [
                 '  --batch <n>',
                 dim('Texts per embedding request, and how often progress prints. Default 96.'),
@@ -65,7 +82,7 @@ export const command = {
         '',
         'Search filters and shape',
         ...table([
-            ['  -d, --dir <dir>', dim(`Which index. Default ${DEFAULT_DIR}.`)],
+            ['  -d, --dir <dir>', dim(`Which index. Found from here if unset; see ${DIR_ENV}.`)],
             ['  --embedding <ref>', dim('Must be the one the index was built with.')],
             ['  --direction <d>', dim('input | output | any. Default any.')],
             ['  --method-type <t>', dim('read_only | read_write | any. Default any.')],
@@ -77,11 +94,46 @@ export const command = {
             ['  --max-hops <n>', dim('How far apart two hits may be. Default 3.')],
             ['  --max-nodes <n>', dim('Nodes per result. Default 200.')],
             ['  --format <f>', dim('text | mermaid | mermaid-flowchart | ts | openapi.')],
+            ['  --show-source', dim('Name the document each operation and schema came from.')],
             ['  --no-docs', dim('Leave the descriptions out.')],
             ['  --interactive', dim('Prompt, search, refine. Needs a terminal.')],
             ['  --quiet', dim('No narration.')],
         ]),
         '',
+        'Exact listing — no embedder, no credential',
+        ...table([
+            ['  list methods', dim('Operations. Filter with --path and --name.')],
+            ['  list types', dim('Schemas. Filter with --name.')],
+            ['  list properties', dim('Fields and parameters. Filter with --name and --path.')],
+            ['  grep <pattern>', dim('Substring over every node; --regex for a regex.')],
+            ['  --regex', dim('Read every pattern as a regex, list and grep alike.')],
+            ['  --case-sensitive', dim('Match the capitals too.')],
+            ['  --kind <k>', dim('grep: method | type | property. Repeatable.')],
+            ['  --name <p>', dim('grep too: only nodes whose name matches. Repeatable.')],
+            ['  --path <p>', dim('grep too: only what sits on a matching route.')],
+            ['  --ids-only', dim('grep: bare ids, to pipe into show.')],
+            ['  --source <name>', dim('Only this document, as `stats` names it.')],
+            ['  --show-source', dim('Print which document each row came from.')],
+            ['  --limit <n>', dim('Keep at most n; the count still reports them all.')],
+        ]),
+        '',
+        dim('  A pattern with * or ? is a glob over the whole name; otherwise it is'),
+        dim('  a substring, so --name password finds ResetPasswordPayload. With'),
+        dim('  --regex it is a regex either way, so --path "^/(users|teams)/" works.'),
+        '',
+        'Show',
+        ...table([
+            ['  <id...>', dim('Node ids, e.g. Type:User or Property:User.email.')],
+            ['  --method <name>', dim('An operation by name. * to take more. Repeatable.')],
+            ['  --type <name>', dim('A schema by name. * to take more. Repeatable.')],
+            ['  --source <name>', dim('A whole document, as it was indexed.')],
+            ['  --show-source', dim('Name the document each node came from.')],
+            ['  --exact', dim('Only what was named, without the neighbours.')],
+        ]),
+        '',
+        dim(`Without --dir, the index is the nearest one at or above the working`),
+        dim(`directory; ${cyan(DIR_ENV)} names it outright.`),
+        '',
         dim(`Credentials come from the ${cyan('zen')} keyring — try ${cyan('zen key ls')}.`),
     ],
     async run(ctx) {
@@ -94,6 +146,10 @@ export const command = {
                 return await index(tail, ctx);
             case 'search':
                 return await search(tail, ctx);
+            case 'list':
+                return await list(tail, ctx);
+            case 'grep':
+                return await grep(tail, ctx);
             case 'show':
                 return await show(tail, ctx);
             case 'stats':
@@ -114,7 +170,7 @@ async function index(args, ctx) {
     if (positionals.length === 0) {
         throw usageError('no document given', INDEX_USAGE);
     }
-    const out = resolve(ctx.cwd, values.out ?? DEFAULT_DIR);
+    const out = outputDir(ctx.cwd, values.out);
     const loud = !values.quiet && !ctx.json;
     const chosen = await embedder(values.embedding);
     const started = Date.now();
@@ -208,14 +264,19 @@ const SEARCH_OPTIONS = {
     format: { type: 'string' },
     'no-docs': { type: 'boolean' },
     'only-hits': { type: 'boolean' },
+    'show-source': { type: 'boolean' },
     interactive: { type: 'boolean' },
     quiet: { type: 'boolean' },
 };
 async function search(args, ctx) {
     const { values, positionals } = parse(args, SEARCH_OPTIONS, SEARCH_USAGE);
-    const dir = resolve(ctx.cwd, values.dir ?? DEFAULT_DIR);
+    const dir = indexDir(ctx, values.dir);
     const format = formatOf(values.format);
-    const options = { docs: !values['no-docs'], onlyHits: values['only-hits'] };
+    const options = {
+        docs: !values['no-docs'],
+        onlyHits: values['only-hits'],
+        source: values['show-source'],
+    };
     const query = { ...(await fromStdin(values.query)), ...fromFlags(values, positionals) };
     // Everything that can be wrong about the invocation is settled before a
     // credential is asked for, so a typo is a usage error and not a login.
@@ -317,36 +378,285 @@ function check(value) {
     }
 }
 // ---------------------------------------------------------------------------
-// show, stats
+// list, grep
+//
+// The deterministic half. Neither takes an embedder, because neither ranks
+// anything: `list` filters on the attributes a node already has and `grep`
+// reads the same materialized string the index was built from. What comes back
+// is every match, and where a limit cut the list the count still reports the
+// total — being shown three of three hundred is only useful if you are told
+// which of the two happened.
+// ---------------------------------------------------------------------------
+const SUBJECTS = {
+    methods: 'method',
+    types: 'type',
+    properties: 'property',
+};
+async function list(args, ctx) {
+    const { values, positionals } = parse(args, {
+        dir: { type: 'string', short: 'd' },
+        name: MANY,
+        path: MANY,
+        source: { type: 'string' },
+        'method-type': { type: 'string' },
+        direction: { type: 'string' },
+        regex: { type: 'boolean' },
+        'case-sensitive': { type: 'boolean' },
+        'show-source': { type: 'boolean' },
+        limit: { type: 'string' },
+        quiet: { type: 'boolean' },
+    }, LIST_USAGE);
+    const subject = positionals[0];
+    const kind = subject ? SUBJECTS[subject] : undefined;
+    if (!kind) {
+        throw usageError(subject ? `cannot list "${subject}"` : 'nothing named to list', `expected one of ${Object.keys(SUBJECTS).join(', ')}`);
+    }
+    if (positionals.length > 1) {
+        throw usageError('one subject at a time', LIST_USAGE);
+    }
+    const how = { regex: values.regex, caseSensitive: values['case-sensitive'] };
+    const index = await openIndex(indexDir(ctx, values.dir));
+    const found = listNodes(index.graph, {
+        kind,
+        name: patterns(values.name, '--name', how),
+        path: patterns(values.path, '--path', how),
+        source: values.source,
+        methodType: oneOf(values['method-type'], ['read_only', 'read_write'], '--method-type'),
+        direction: oneOf(values.direction, ['input', 'output'], '--direction'),
+        limit: values.limit ? count(values.limit, '--limit') : undefined,
+    });
+    if (ctx.json) {
+        json({ found: found.found, truncated: found.truncated, rows: found.rows });
+        return;
+    }
+    const lines = rowLines(index.graph, kind, found.rows, values['show-source']);
+    if (lines.length > 0) {
+        write(lines.join('\n'));
+    }
+    if (!values.quiet) {
+        note(dim(`  ${found.found} ${subject}${shown(found.found, found.rows.length)}`));
+    }
+}
+function rowLines(graph, kind, rows, showSource = false) {
+    const from = (r) => (showSource ? [dim(sourceTag(r.source))] : []);
+    if (kind === 'method') {
+        return table(rows.map((r) => [`${r.httpMethod} ${r.path}`, r.name, ...from(r), doc(r.doc)]));
+    }
+    if (kind === 'type') {
+        return table(rows.map((r) => [
+            r.name,
+            dim(fields(propertyCount(graph, r.id))),
+            dim(r.direction === 'none' ? '' : `(${r.direction})`),
+            ...from(r),
+            doc(r.doc),
+        ]));
+    }
+    return table(rows.map((r) => [
+        `${r.parent ? `${r.parent}.` : ''}${r.name}${r.required ? '' : '?'}`,
+        `: ${r.signature || 'unknown'}`,
+        ...from(r),
+        doc(r.doc),
+    ]));
+}
+async function grep(args, ctx) {
+    const { values, positionals } = parse(args, {
+        dir: { type: 'string', short: 'd' },
+        regex: { type: 'boolean' },
+        'case-sensitive': { type: 'boolean' },
+        kind: MANY,
+        name: MANY,
+        path: MANY,
+        source: { type: 'string' },
+        'show-source': { type: 'boolean' },
+        limit: { type: 'string' },
+        'ids-only': { type: 'boolean' },
+        quiet: { type: 'boolean' },
+    }, GREP_USAGE);
+    if (positionals.length === 0) {
+        throw usageError('no pattern given', GREP_USAGE);
+    }
+    if (positionals.length > 1) {
+        throw usageError('one pattern at a time — quote it if it has spaces', GREP_USAGE);
+    }
+    const kinds = (values.kind ?? []).map((k) => oneOf(k, ['method', 'type', 'property'], '--kind'));
+    // The pattern is read as the flags say; the constraints are always names,
+    // so they stay globs-or-substrings even under --regex on the pattern.
+    const how = { caseSensitive: values['case-sensitive'] };
+    const index = await openIndex(indexDir(ctx, values.dir));
+    const result = pattern(() => grepNodes(index.graph, matcher(positionals[0], {
+        regex: values.regex,
+        caseSensitive: values['case-sensitive'],
+    }), {
+        kinds,
+        source: values.source,
+        name: patterns(values.name, '--name', how),
+        path: patterns(values.path, '--path', how),
+        limit: values.limit ? count(values.limit, '--limit') : undefined,
+    }));
+    if (ctx.json) {
+        json({
+            found: result.found,
+            truncated: result.truncated,
+            matches: result.matches.map((m) => ({ id: m.id, ...m.attributes, text: m.text })),
+        });
+        return;
+    }
+    if (result.matches.length > 0) {
+        const lines = values['ids-only']
+            ? result.matches.map((m) => m.id)
+            : table(result.matches.map((m) => [
+                m.id,
+                ...(values['show-source'] ? [dim(sourceTag(m.attributes.source))] : []),
+                dim(clip(m.text, 140)),
+            ]));
+        write(lines.join('\n'));
+    }
+    if (!values.quiet && !values['ids-only']) {
+        note(dim(`  ${result.found} match(es)${shown(result.found, result.matches.length)}`));
+    }
+}
 // ---------------------------------------------------------------------------
+const shown = (found, kept) => (kept < found ? `, showing ${kept}` : '');
+/**
+ * Where the index is, said out loud when nobody named it. Finding one and not
+ * saying which would make every answer here unattributable.
+ */
+function indexDir(ctx, flag) {
+    const { dir, from } = locateIndex(ctx.cwd, flag);
+    if (from === 'found' && !ctx.json) {
+        note(dim(`  using ${relative(ctx.cwd, dir) || dir}`));
+    }
+    return dir;
+}
+function patterns(values, flag, options = {}) {
+    if (!values || values.length === 0) {
+        return undefined;
+    }
+    return values.map((p) => pattern(() => loose(p, options), flag));
+}
+/** A bad pattern is a bad invocation, not a failure of the index. */
+function pattern(run, flag) {
+    try {
+        return run();
+    }
+    catch (err) {
+        if (err instanceof PatternError) {
+            throw usageError(`${flag ? `${flag}: ` : ''}${err.message}`, USAGE);
+        }
+        throw err;
+    }
+}
+function oneOf(value, allowed, flag) {
+    if (value === undefined || value === 'any') {
+        return undefined;
+    }
+    if (!allowed.includes(value)) {
+        throw usageError(`${flag} cannot be "${value}"`, `expected ${allowed.join(' or ')}`);
+    }
+    return value;
+}
+const doc = (text) => (text ? dim(`— ${clip(text.replace(/\s+/g, ' '), 90)}`) : '');
+const clip = (text, max) => text.length <= max ? text : `${text.slice(0, max - 1)}…`;
 /**
  * No embedder and no store: naming a node is a graph lookup, and asking for a
  * credential to print something already on disk would be theatre.
+ *
+ * Ids are the precise way in, and `--method`/`--type` are the way in for
+ * someone who has a name rather than an id — which, with `--format openapi
+ * --exact`, is how a resolved slice of the document is got out.
  */
 async function show(args, ctx) {
-    const usage = 'zen rag schema show <id...>';
-    const { values, positionals } = parse(args, SEARCH_OPTIONS, usage);
-    if (positionals.length === 0) {
-        throw usageError('no node named', usage);
-    }
+    const { values, positionals } = parse(args, {
+        dir: { type: 'string', short: 'd' },
+        method: MANY,
+        type: MANY,
+        source: { type: 'string' },
+        exact: { type: 'boolean' },
+        format: { type: 'string' },
+        'max-nodes': { type: 'string' },
+        'no-docs': { type: 'boolean' },
+        'show-source': { type: 'boolean' },
+        quiet: { type: 'boolean' },
+    }, SHOW_USAGE);
     const format = formatOf(values.format);
-    const index = await openIndex(resolve(ctx.cwd, values.dir ?? DEFAULT_DIR));
-    const missing = positionals.filter((id) => !index.graph.hasNode(id));
-    if (missing.length > 0) {
-        throw new CliError(`no such node: ${missing.join(', ')}`, EXIT.failed, 'ids look like `Type:User` or `Property:User.email`');
+    const dir = indexDir(ctx, values.dir);
+    // A whole document, verbatim: the copy kept at index time is the resolved
+    // original, and anything rebuilt from the graph would be a paraphrase.
+    if (values.source && format === 'openapi' && positionals.length === 0 && !named(values)) {
+        const document = await readSource(dir, values.source);
+        if (document) {
+            write(document);
+            return;
+        }
+        if (!values.quiet) {
+            note(dim('  this index kept no copy of the documents — rebuilding it from the graph'));
+        }
     }
-    const subgraphs = stitch(index.graph, positionals.map((id) => ({ id, term: id, field: 'show', score: 1 })), { maxNodes: values['max-nodes'] ? count(values['max-nodes'], '--max-nodes') : undefined });
-    const text = await present(index, subgraphs, format, { docs: !values['no-docs'] });
+    const index = await openIndex(dir);
+    const ids = resolveIds(index.graph, positionals, values);
+    const subgraphs = values.exact
+        ? [select(index.graph, ids)]
+        : stitch(index.graph, ids.map((id) => ({ id, term: id, field: 'show', score: 1 })), {
+            maxNodes: values['max-nodes']
+                ? count(values['max-nodes'], '--max-nodes')
+                : undefined,
+        });
+    const text = await present(index, subgraphs, format, {
+        docs: !values['no-docs'],
+        source: values['show-source'],
+    });
     if (ctx.json) {
-        json({ subgraphs, rendered: text });
+        json({ ids, subgraphs, rendered: text });
     }
     else if (text) {
         write(text);
     }
 }
+const named = (values) => Boolean(values.method?.length || values.type?.length);
+/** Ids as given, plus whatever the name selectors resolve to. */
+function resolveIds(graph, ids, values) {
+    if (ids.length === 0 && !named(values) && !values.source) {
+        throw usageError('no node named', SHOW_USAGE);
+    }
+    const missing = ids.filter((id) => !graph.hasNode(id));
+    if (missing.length > 0) {
+        throw new CliError(`no such node: ${missing.join(', ')}`, EXIT.failed, 'ids look like `Type:User` or `Property:User.email`');
+    }
+    const out = new Set(ids);
+    for (const kind of ['method', 'type']) {
+        for (const wanted of values[kind] ?? []) {
+            // Selecting, not searching: a bare name means that name. A star is
+            // the way to ask for more than one.
+            const match = isGlob(wanted)
+                ? pattern(() => wildcard(wanted), `--${kind}`)
+                : (name) => name === wanted;
+            const rows = listNodes(graph, { kind, name: [match], source: values.source });
+            // A selector that matched nothing is a wrong answer, not an empty
+            // one: the caller named something they believe is there.
+            if (rows.found === 0) {
+                throw new CliError(`no ${kind} called ${wanted}`, EXIT.failed, `try: zen rag schema list ${kind}s --name "${wanted}"`);
+            }
+            for (const row of rows.rows) {
+                out.add(row.id);
+            }
+        }
+    }
+    // `--source` on its own means the whole document.
+    if (out.size === 0 && values.source) {
+        for (const kind of ['method', 'type']) {
+            for (const row of listNodes(graph, { kind, source: values.source }).rows) {
+                out.add(row.id);
+            }
+        }
+        if (out.size === 0) {
+            throw new CliError(`nothing in this index came from ${values.source}`, EXIT.failed);
+        }
+    }
+    return [...out];
+}
 async function stats(args, ctx) {
     const { values } = parse(args, { dir: { type: 'string', short: 'd' } }, 'zen rag schema stats [--dir <dir>]');
-    const dir = resolve(ctx.cwd, values.dir ?? DEFAULT_DIR);
+    const dir = indexDir(ctx, values.dir);
     const manifest = await readManifest(dir);
     if (ctx.json) {
         json(manifest);

package/dist/index.d.ts

@@ -5,6 +5,9 @@ export * from './schema/entities.ts';
 export * from './schema/files.ts';
 export * from './schema/graph.ts';
 export * from './schema/hydrate.ts';
+export * from './schema/locate.ts';
+export * from './schema/lookup.ts';
+export * from './schema/match.ts';
 export * from './schema/render.ts';
 export * from './schema/schema.ts';
 export * from './schema/search.ts';

package/dist/index.js

@@ -5,6 +5,9 @@ export * from "./schema/entities.js";
 export * from "./schema/files.js";
 export * from "./schema/graph.js";
 export * from "./schema/hydrate.js";
+export * from "./schema/locate.js";
+export * from "./schema/lookup.js";
+export * from "./schema/match.js";
 export * from "./schema/render.js";
 export * from "./schema/schema.js";
 export * from "./schema/search.js";

package/dist/schema/entities.d.ts

@@ -15,4 +15,6 @@ export interface EntityRecord {
     text: string;
 }
 export declare function toEntities(graph: ApiGraph): EntityRecord[];
+/** Exported so a literal search reads the same string the index was built from. */
+export declare function textOf(graph: ApiGraph, id: string): string;
 //# sourceMappingURL=entities.d.ts.map

package/dist/schema/entities.js

@@ -22,7 +22,8 @@ export function toEntities(graph) {
     }
     return out.sort((a, b) => a.id.localeCompare(b.id));
 }
-function textOf(graph, id) {
+/** Exported so a literal search reads the same string the index was built from. */
+export function textOf(graph, id) {
     const a = graph.getNodeAttributes(id);
     const parts = [];
     if (a.kind === 'method') {

package/dist/schema/files.d.ts

@@ -68,6 +68,13 @@ export interface OpenIndex {
 export declare const lancePath: (dir: string) => string;
 export declare function writeIndex(dir: string, index: WrittenIndex): Promise<void>;
 export declare function openIndex(dir: string): Promise<OpenIndex>;
+/**
+ * The bundled document as it was indexed. Kept only when the index was built
+ * with sources, which is why the manifest is asked first: the difference
+ * between "no such document" and "this index did not keep them" is the whole
+ * of what the caller can do next.
+ */
+export declare function readSource(dir: string, name: string): Promise<string | undefined>;
 export declare function readManifest(dir: string): Promise<Manifest>;
 /**
  * A store answers with the neighbours of a vector, and a vector means nothing