@zenera/rag 1.1.4 → 1.1.5

package/README.md

@@ -46,6 +46,24 @@ 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
+```
+
+`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.
@@ -66,7 +84,9 @@ JSON
 ```
 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 +96,18 @@ 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` takes `--name` and `--path`, `grep` takes `--regex`, `--case-sensitive`,
+`--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. `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 +121,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,11 @@ 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 { fields, grepNodes, listNodes, propertyCount } from "./schema/lookup.js";
+import { isGlob, loose, matcher, PatternError, wildcard } from "./schema/match.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,10 +20,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 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>]';
 const DEFAULT_DIR = './schema-db';
 export const command = {
     summary: 'Search an openapi/swagger document as a graph.',
@@ -31,7 +42,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.')],
         ]),
         '',
@@ -82,6 +95,31 @@ export const command = {
             ['  --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.')],
+            ['  grep <pattern>', dim('Substring over every node; --regex for a regex.')],
+            ['  --case-sensitive', dim('grep: match the capitals too.')],
+            ['  --kind <k>', dim('grep: method | type | property. Repeatable.')],
+            ['  --ids-only', dim('grep: bare ids, to pipe into show.')],
+            ['  --source <name>', dim('Only this document, as `stats` names it.')],
+            ['  --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.'),
+        '',
+        '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.')],
+            ['  --exact', dim('Only what was named, without the neighbours.')],
+        ]),
+        '',
         dim(`Credentials come from the ${cyan('zen')} keyring — try ${cyan('zen key ls')}.`),
     ],
     async run(ctx) {
@@ -94,6 +132,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':
@@ -317,33 +359,248 @@ 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' },
+        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 index = await openIndex(resolve(ctx.cwd, values.dir ?? DEFAULT_DIR));
+    const found = listNodes(index.graph, {
+        kind,
+        name: globs(values.name, '--name'),
+        path: globs(values.path, '--path'),
+        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);
+    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) {
+    if (kind === 'method') {
+        return table(rows.map((r) => [`${r.httpMethod} ${r.path}`, r.name, 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})`),
+            doc(r.doc),
+        ]));
+    }
+    return table(rows.map((r) => [
+        `${r.parent ? `${r.parent}.` : ''}${r.name}${r.required ? '' : '?'}`,
+        `: ${r.signature || 'unknown'}`,
+        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,
+        source: { type: 'string' },
+        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'));
+    const index = await openIndex(resolve(ctx.cwd, values.dir ?? DEFAULT_DIR));
+    const result = pattern(() => grepNodes(index.graph, matcher(positionals[0], {
+        regex: values.regex,
+        caseSensitive: values['case-sensitive'],
+    }), {
+        kinds,
+        source: values.source,
+        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, 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}` : '');
+function globs(patterns, flag) {
+    if (!patterns || patterns.length === 0) {
+        return undefined;
+    }
+    return patterns.map((p) => pattern(() => loose(p), 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' },
+        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 = resolve(ctx.cwd, values.dir ?? DEFAULT_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 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'] });
     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);

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export * from './schema/entities.ts';
 export * from './schema/files.ts';
 export * from './schema/graph.ts';
 export * from './schema/hydrate.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,8 @@ export * from "./schema/entities.js";
 export * from "./schema/files.js";
 export * from "./schema/graph.js";
 export * from "./schema/hydrate.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

package/dist/schema/files.js

@@ -60,6 +60,23 @@ function once(load) {
     let pending;
     return () => (pending ??= load());
 }
+/**
+ * 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 async function readSource(dir, name) {
+    const manifest = await readManifest(dir);
+    const record = manifest.sources.find((s) => s.name === name);
+    if (!record) {
+        throw new CliError(`${dir} holds no document called ${name}`, EXIT.failed, `it has: ${manifest.sources.map((s) => s.name).join(', ')}`);
+    }
+    if (!record.path) {
+        return undefined;
+    }
+    return await readFile(join(dir, record.path), 'utf8');
+}
 export async function readManifest(dir) {
     let text;
     try {

package/dist/schema/lookup.d.ts

@@ -0,0 +1,44 @@
+import type { ApiGraph, NodeAttrs, NodeKind } from './graph.ts';
+import { type Matcher } from './match.ts';
+export interface Row extends NodeAttrs {
+    id: string;
+}
+export interface ListFilter {
+    kind: NodeKind;
+    /** any one matching is enough; none means every name passes */
+    name?: readonly Matcher[];
+    path?: readonly Matcher[];
+    source?: string;
+    methodType?: string;
+    direction?: string;
+    limit?: number;
+}
+export interface Listing {
+    /** how many matched, whatever was kept */
+    found: number;
+    rows: Row[];
+    truncated: boolean;
+}
+export interface Match {
+    id: string;
+    attributes: NodeAttrs;
+    /** the indexed text this matched against */
+    text: string;
+}
+export interface GrepFilter {
+    kinds?: readonly string[];
+    source?: string;
+    limit?: number;
+}
+export interface Grep {
+    found: number;
+    matches: Match[];
+    truncated: boolean;
+}
+export declare function listNodes(graph: ApiGraph, filter: ListFilter): Listing;
+export declare function grepNodes(graph: ApiGraph, match: Matcher, filter?: GrepFilter): Grep;
+/** How many fields a type carries, which is most of what a listing wants to say. */
+export declare function propertyCount(graph: ApiGraph, id: string): number;
+/** That count, said properly, in the one phrasing the CLI and the tools share. */
+export declare const fields: (n: number) => string;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/schema/lookup.js

@@ -0,0 +1,83 @@
+import { textOf } from "./entities.js";
+import { PatternError } from "./match.js";
+/** A scan is bounded, because a pattern may have come from a model. */
+const DEADLINE_MS = 2000;
+const DEADLINE_EVERY = 500;
+export function listNodes(graph, filter) {
+    const rows = [];
+    graph.forEachNode((id, a) => {
+        if (a.kind !== filter.kind || !passes(a, filter)) {
+            return;
+        }
+        if (filter.name && !filter.name.some((match) => match(a.name))) {
+            return;
+        }
+        if (filter.path && !filter.path.some((match) => match(a.path))) {
+            return;
+        }
+        rows.push({ ...a, id });
+    });
+    rows.sort(order(filter.kind));
+    return cut(rows, filter.limit);
+}
+export function grepNodes(graph, match, filter = {}) {
+    const kinds = filter.kinds?.length ? new Set(filter.kinds) : undefined;
+    const matches = [];
+    const until = Date.now() + DEADLINE_MS;
+    let seen = 0;
+    for (const id of graph.nodes()) {
+        if (++seen % DEADLINE_EVERY === 0 && Date.now() > until) {
+            throw new PatternError(`the pattern is still running after ${DEADLINE_MS / 1000}s — it is too expensive to be useful`);
+        }
+        const a = graph.getNodeAttributes(id);
+        if (kinds && !kinds.has(a.kind)) {
+            continue;
+        }
+        if (filter.source && a.source !== filter.source) {
+            continue;
+        }
+        const text = textOf(graph, id);
+        if (match(text)) {
+            matches.push({ id, attributes: a, text });
+        }
+    }
+    matches.sort((a, b) => a.id.localeCompare(b.id));
+    const kept = cut(matches, filter.limit);
+    return { found: kept.found, matches: kept.rows, truncated: kept.truncated };
+}
+/** How many fields a type carries, which is most of what a listing wants to say. */
+export function propertyCount(graph, id) {
+    return graph
+        .outEdges(id)
+        .filter((e) => graph.getEdgeAttribute(e, 'relation') === 'HAS_PROPERTY').length;
+}
+/** That count, said properly, in the one phrasing the CLI and the tools share. */
+export const fields = (n) => `${n} ${n === 1 ? 'field' : 'fields'}`;
+// ---------------------------------------------------------------------------
+function passes(a, filter) {
+    if (filter.source && a.source !== filter.source) {
+        return false;
+    }
+    if (filter.methodType && a.methodType !== filter.methodType) {
+        return false;
+    }
+    if (filter.direction && a.direction !== filter.direction && a.direction !== 'both') {
+        return false;
+    }
+    return true;
+}
+/** Operations read as a table of routes; everything else reads as a list of names. */
+function order(kind) {
+    if (kind !== 'method') {
+        return (a, b) => a.id.localeCompare(b.id);
+    }
+    return (a, b) => a.path.localeCompare(b.path) || a.httpMethod.localeCompare(b.httpMethod);
+}
+function cut(rows, limit) {
+    const found = rows.length;
+    if (!limit || limit >= found) {
+        return { found, rows, truncated: false };
+    }
+    return { found, rows: rows.slice(0, limit), truncated: true };
+}
+//# sourceMappingURL=lookup.js.map

package/dist/schema/match.d.ts

@@ -0,0 +1,36 @@
+/** Long enough for any honest pattern, short enough to bound a bad one. */
+export declare const MAX_PATTERN = 200;
+export declare class PatternError extends Error {
+}
+export interface MatchOptions {
+    /** read the pattern as a regular expression rather than as a literal */
+    regex?: boolean;
+    caseSensitive?: boolean;
+}
+export type Matcher = (text: string) => boolean;
+/**
+ * A predicate over a string. Literal by default: someone typing `user.id` means
+ * those seven characters, and a dot that quietly matched anything would be a
+ * worse answer than no answer.
+ */
+export declare function matcher(pattern: string, options?: MatchOptions): Matcher;
+/**
+ * A glob, matched against the whole string. Globs rather than regexes because
+ * these are for naming things — a path, a schema — and a star is what everyone
+ * reaches for first.
+ */
+export declare function wildcard(pattern: string, options?: {
+    caseSensitive?: boolean;
+}): Matcher;
+/** Whether a pattern is asking to be read as a glob at all. */
+export declare const isGlob: (pattern: string) => boolean;
+/**
+ * What someone means when they type a name into a filter. With a star in it,
+ * a glob; without one, a substring — because `password` typed into `--name` is
+ * a search for the word, and a whole-string match would answer nothing and
+ * look like the field does not exist.
+ */
+export declare function loose(pattern: string, options?: MatchOptions): Matcher;
+/** True when any of the patterns matches; no patterns means no opinion. */
+export declare function anyOf(matchers: readonly Matcher[]): Matcher | undefined;
+//# sourceMappingURL=match.d.ts.map

package/dist/schema/match.js

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// Matching, with nothing learned in between
+//
+// Everything here is exact. A glob matches the characters it names and a
+// substring is a substring, which is the whole point of the surfaces built on
+// it: a vector index answers "what is near this", and near is a ranking, so it
+// can only ever return the top of a list. When the question is "does the word
+// `password` appear anywhere at all", a ranking is the wrong instrument and no
+// amount of tuning makes it the right one.
+//
+// A pattern may arrive from a model, so a regex is a bounded promise: the
+// length is capped here and the scan that uses it keeps a deadline.
+// ---------------------------------------------------------------------------
+/** Long enough for any honest pattern, short enough to bound a bad one. */
+export const MAX_PATTERN = 200;
+export class PatternError extends Error {
+}
+/**
+ * A predicate over a string. Literal by default: someone typing `user.id` means
+ * those seven characters, and a dot that quietly matched anything would be a
+ * worse answer than no answer.
+ */
+export function matcher(pattern, options = {}) {
+    guard(pattern);
+    if (!options.regex) {
+        if (options.caseSensitive) {
+            return (text) => text.includes(pattern);
+        }
+        const needle = pattern.toLowerCase();
+        return (text) => text.toLowerCase().includes(needle);
+    }
+    const expression = compile(pattern, options.caseSensitive ? '' : 'i');
+    // `lastIndex` is not carried between calls: the flags never include `g`.
+    return (text) => expression.test(text);
+}
+/**
+ * A glob, matched against the whole string. Globs rather than regexes because
+ * these are for naming things — a path, a schema — and a star is what everyone
+ * reaches for first.
+ */
+export function wildcard(pattern, options = {}) {
+    guard(pattern);
+    const source = [...pattern]
+        .map((char) => (char === '*' ? '.*' : char === '?' ? '.' : escape(char)))
+        .join('');
+    const expression = compile(`^${source}$`, options.caseSensitive ? '' : 'i');
+    return (text) => expression.test(text);
+}
+/** Whether a pattern is asking to be read as a glob at all. */
+export const isGlob = (pattern) => /[*?]/.test(pattern);
+/**
+ * What someone means when they type a name into a filter. With a star in it,
+ * a glob; without one, a substring — because `password` typed into `--name` is
+ * a search for the word, and a whole-string match would answer nothing and
+ * look like the field does not exist.
+ */
+export function loose(pattern, options = {}) {
+    return isGlob(pattern) ? wildcard(pattern, options) : matcher(pattern, options);
+}
+/** True when any of the patterns matches; no patterns means no opinion. */
+export function anyOf(matchers) {
+    if (matchers.length === 0) {
+        return undefined;
+    }
+    return (text) => matchers.some((match) => match(text));
+}
+// ---------------------------------------------------------------------------
+function guard(pattern) {
+    if (pattern.length === 0) {
+        throw new PatternError('the pattern is empty');
+    }
+    if (pattern.length > MAX_PATTERN) {
+        throw new PatternError(`the pattern is longer than ${MAX_PATTERN} characters`);
+    }
+}
+function compile(source, flags) {
+    try {
+        return new RegExp(source, flags);
+    }
+    catch (err) {
+        throw new PatternError(`invalid pattern: ${err.message}`);
+    }
+}
+const escape = (char) => char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+//# sourceMappingURL=match.js.map

package/dist/schema/subgraph.d.ts

@@ -37,6 +37,12 @@ export interface StitchOptions {
 export declare const DEFAULT_MAX_HOPS = 3;
 export declare const DEFAULT_MAX_NODES = 200;
 export declare function stitch(graph: ApiGraph, seeds: readonly Seed[], options?: StitchOptions): Subgraph[];
+/**
+ * Exactly the nodes named, and only the edges between them. The counterpart to
+ * `stitch`: no neighbours are gathered, because the caller is not asking what
+ * this is connected to — they already know what they want and want it whole.
+ */
+export declare function select(graph: ApiGraph, ids: readonly string[]): Subgraph;
 /** Breadth-first, ignoring edge direction, giving up past `maxHops`. */
 export declare function path(graph: ApiGraph, from: string, to: string, maxHops: number): string[] | undefined;
 //# sourceMappingURL=subgraph.d.ts.map

package/dist/schema/subgraph.js

@@ -150,6 +150,33 @@ function connect(graph, seeds, maxHops) {
     }
     return out;
 }
+/**
+ * Exactly the nodes named, and only the edges between them. The counterpart to
+ * `stitch`: no neighbours are gathered, because the caller is not asking what
+ * this is connected to — they already know what they want and want it whole.
+ */
+export function select(graph, ids) {
+    const kept = new Set(ids.filter((id) => graph.hasNode(id)));
+    const nodes = [...kept].map((id) => ({
+        id,
+        kind: graph.getNodeAttribute(id, 'kind'),
+        attributes: graph.getNodeAttributes(id),
+        hit: true,
+        score: 1,
+    }));
+    const edges = [];
+    for (const id of kept) {
+        for (const edge of graph.outEdges(id)) {
+            const target = graph.target(edge);
+            if (!kept.has(target)) {
+                continue;
+            }
+            const a = graph.getEdgeAttributes(edge);
+            edges.push({ source: id, target, relation: a.relation, status: a.status, in: a.in });
+        }
+    }
+    return { nodes, edges, hits: [...kept], score: kept.size, truncated: false };
+}
 /** Breadth-first, ignoring edge direction, giving up past `maxHops`. */
 export function path(graph, from, to, maxHops) {
     if (from === to) {

package/dist/schema/tools.js

@@ -2,22 +2,32 @@ import { tool } from '@zenera/neo';
 import { FORMATS, isFormat, present } from "../present.js";
 import { isEmpty, parseQuery, QueryError } from "../query.js";
 import { toTypeScript } from "./hydrate.js";
+import { fields, grepNodes, listNodes, propertyCount } from "./lookup.js";
+import { loose, matcher, PatternError } from "./match.js";
 import { stitch } from "./subgraph.js";
 // ---------------------------------------------------------------------------
 // The same index, given to an agent
 //
-// Four tools over one engine. Three of them search, and the fourth deliberately
-// does not: `find_types_with_property` is a graph lookup, for the moment after
-// the compiler says `'password' does not exist in type 'PublicUserProfile'`.
-// At that point the model does not need to be reminded what a password is —
-// it needs the list of types that have one, and an embedding of the word will
-// only rank the guess it already made near the top again.
+// Five tools over one engine, and only one of them ranks anything. `search_api`
+// is the way in when the question is vague; the other four are exact, because
+// a model that has been 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 for the moment after the compiler says
+// `'password' does not exist in type 'PublicUserProfile'`. At that point the
+// model does not need to be reminded what a password is — it needs the list of
+// types that have one. `grep_api` is the same instinct widened: every literal
+// occurrence, counted in full, so "it is not there" can actually be concluded.
 // ---------------------------------------------------------------------------
 const GROUP = 'schema';
 /** Kept small on purpose: a tool result is prompt, and the model asked for one thing. */
 const DEFAULT_LIMIT = 4;
 const DEFAULT_MAX_NODES = 60;
 const MAX_CANDIDATES = 25;
+/** A listing is lines rather than subgraphs, so it can afford more of them. */
+const DEFAULT_ROWS = 50;
+const MAX_ROWS = 200;
 export function schemaTools(index, options = {}) {
     const fallback = options.format ?? 'text';
     const docs = options.docs ?? true;
@@ -178,43 +188,145 @@ export function schemaTools(index, options = {}) {
                 : { found: candidates.length, candidates: candidates.slice(0, MAX_CANDIDATES) };
         },
     });
-    const listMethods = tool({
-        name: 'list_methods',
+    const listApi = tool({
+        name: 'list_api',
         group: GROUP,
-        description: 'Lists operations by path, with no searching. Use it to see the shape of the API ' +
-            'before deciding what to ask for.',
+        description: 'Lists operations, schemas or fields by name, with no searching and no ranking. ' +
+            'The answer is complete: every match is counted, so `found` tells you how many ' +
+            'exist even when the list was shortened. Use it to see the shape of the API ' +
+            'before deciding what to ask for, and to settle whether something exists at all — ' +
+            'search can only ever return its best guesses, so it cannot answer that.',
         parameters: {
             type: 'object',
             properties: {
-                contains: { type: 'string', description: 'Only paths holding this text.' },
+                kind: {
+                    type: 'string',
+                    enum: ['methods', 'types', 'properties'],
+                    description: 'What to list. Default methods.',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Match the name. A plain word matches anywhere in it; use * and ? ' +
+                        'to match the whole name, e.g. "*Password*".',
+                },
+                path: { type: 'string', description: 'Match the route, e.g. "/users*".' },
                 method_type: {
                     type: 'string',
                     enum: ['read_only', 'read_write', 'any'],
                 },
+                direction: { type: 'string', enum: ['input', 'output', 'any'] },
+                limit: {
+                    type: 'integer',
+                    description: `Rows to return. Default ${DEFAULT_ROWS}.`,
+                },
             },
             additionalProperties: false,
         },
-        execute: async ({ contains, method_type }) => {
-            const needle = contains?.toLowerCase();
-            const rows = [];
-            index.graph.forEachNode((_id, a) => {
-                if (a.kind !== 'method') {
-                    return;
-                }
-                if (needle && !a.path.toLowerCase().includes(needle)) {
-                    return;
-                }
-                if (method_type && method_type !== 'any' && a.methodType !== method_type) {
-                    return;
-                }
-                rows.push(`${a.httpMethod} ${a.path}  ${a.name}${a.doc ? ` — ${a.doc}` : ''}`);
-            });
-            return { found: rows.length, methods: rows.sort() };
+        execute: async ({ kind, name, path, method_type, direction, limit }) => {
+            const subject = SUBJECTS[kind ?? 'methods'];
+            if (!subject) {
+                return { error: `cannot list "${kind}"`, hint: 'kind is methods, types or fields' };
+            }
+            let result;
+            try {
+                result = listNodes(index.graph, {
+                    kind: subject,
+                    name: name ? [loose(name)] : undefined,
+                    path: path ? [loose(path)] : undefined,
+                    methodType: enumerated(method_type),
+                    direction: enumerated(direction),
+                    limit: Math.min(limit ?? DEFAULT_ROWS, MAX_ROWS),
+                });
+            }
+            catch (err) {
+                return { error: err instanceof PatternError ? err.message : String(err) };
+            }
+            return {
+                found: result.found,
+                truncated: result.truncated,
+                [PLURALS[subject]]: result.rows.map((r) => line(index.graph, subject, r)),
+            };
         },
     });
-    return [searchApi, describeTypes, findTypesWithProperty, listMethods];
+    const grepApi = tool({
+        name: 'grep_api',
+        group: GROUP,
+        description: 'Finds every literal occurrence of a string across the whole API description — ' +
+            'operations, schemas and fields alike. No embeddings and no ranking, so ' +
+            'nothing is missed for being an unusual word or an odd spelling. This is the ' +
+            'tool for "does X exist anywhere", and for checking that a search which ' +
+            'returned nothing really means there is nothing.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: 'The text to find. Matched anywhere, ignoring case.',
+                },
+                regex: {
+                    type: 'boolean',
+                    description: 'Read the pattern as a regular expression instead.',
+                },
+                kind: { type: 'string', enum: ['method', 'type', 'property'] },
+                limit: {
+                    type: 'integer',
+                    description: `Matches to return. Default ${DEFAULT_ROWS}. \`found\` always counts them all.`,
+                },
+            },
+            required: ['pattern'],
+            additionalProperties: false,
+        },
+        execute: async ({ pattern, regex, kind, limit }) => {
+            let result;
+            try {
+                result = grepNodes(index.graph, matcher(pattern, { regex }), {
+                    kinds: kind ? [kind] : undefined,
+                    limit: Math.min(limit ?? DEFAULT_ROWS, MAX_ROWS),
+                });
+            }
+            catch (err) {
+                return { error: err instanceof PatternError ? err.message : String(err) };
+            }
+            if (result.found === 0) {
+                return {
+                    found: 0,
+                    hint: 'nothing in the description contains it — it is not there under this name',
+                };
+            }
+            return {
+                found: result.found,
+                truncated: result.truncated,
+                matches: result.matches.map((m) => ({ id: m.id, text: m.text })),
+            };
+        },
+    });
+    return [searchApi, describeTypes, findTypesWithProperty, listApi, grepApi];
 }
 // ---------------------------------------------------------------------------
+const SUBJECTS = {
+    methods: 'method',
+    types: 'type',
+    properties: 'property',
+    fields: 'property',
+};
+const PLURALS = {
+    method: 'methods',
+    type: 'types',
+    property: 'properties',
+};
+/** One row, as the line a model reads rather than an object it has to walk. */
+function line(graph, kind, row) {
+    if (kind === 'method') {
+        return `${row.httpMethod} ${row.path}  ${row.name}${row.doc ? ` — ${row.doc}` : ''}`;
+    }
+    if (kind === 'type') {
+        const side = row.direction === 'none' ? '' : ` (${row.direction})`;
+        return `${row.name}${side}  ${fields(propertyCount(graph, row.id))}${row.doc ? ` — ${row.doc}` : ''}`;
+    }
+    const owner = row.parent ? `${row.parent}.` : '';
+    return `${owner}${row.name}${row.required ? '' : '?'}: ${row.signature || 'unknown'}`;
+}
+const enumerated = (value) => value && value !== 'any' ? value : undefined;
 function list(description) {
     return { type: 'array', items: { type: 'string' }, description };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/rag",
-    "version": "1.1.4",
+    "version": "1.1.5",
     "description": "Retrieval over API descriptions: openapi/swagger documents as a searchable graph.",
     "keywords": [
         "agents",
@@ -53,7 +53,7 @@
         "@apidevtools/swagger-parser": "^12.0.0",
         "@lancedb/lancedb": "^0.38.0",
         "graphology": "^0.26.0",
-        "@zenera/cli": "^1.1.4",
-        "@zenera/neo": "^1.1.4"
+        "@zenera/cli": "^1.1.5",
+        "@zenera/neo": "^1.1.5"
     }
 }