@zenera/rag 1.1.5 → 1.1.6

package/README.md

@@ -59,6 +59,22 @@ 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
@@ -79,6 +95,22 @@ 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
 
 ```
@@ -96,10 +128,14 @@ 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
+`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.
 

package/dist/command.js

@@ -6,8 +6,10 @@ import { isEmpty, parseQuery, QueryError } from "./query.js";
 import { repl } from "./repl.js";
 import { buildIndex } from "./schema/build.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 { select, stitch } from "./schema/subgraph.js";
 // ---------------------------------------------------------------------------
@@ -33,7 +35,6 @@ 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.',
     usage: USAGE,
@@ -54,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.'),
@@ -78,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.')],
@@ -90,6 +94,7 @@ 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.')],
@@ -99,17 +104,22 @@ export const command = {
         ...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.')],
+            ['  list properties', dim('Fields and parameters. Filter with --name and --path.')],
             ['  grep <pattern>', dim('Substring over every node; --regex for a regex.')],
-            ['  --case-sensitive', dim('grep: match the capitals too.')],
+            ['  --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.'),
+        dim('  a substring, so --name password finds ResetPasswordPayload. With'),
+        dim('  --regex it is a regex either way, so --path "^/(users|teams)/" works.'),
         '',
         'Show',
         ...table([
@@ -117,9 +127,13 @@ export const command = {
             ['  --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) {
@@ -156,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();
@@ -250,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.
@@ -381,6 +400,9 @@ async function list(args, ctx) {
         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);
@@ -392,11 +414,12 @@ async function list(args, ctx) {
     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 how = { regex: values.regex, caseSensitive: values['case-sensitive'] };
+    const index = await openIndex(indexDir(ctx, values.dir));
     const found = listNodes(index.graph, {
         kind,
-        name: globs(values.name, '--name'),
-        path: globs(values.path, '--path'),
+        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'),
@@ -406,7 +429,7 @@ async function list(args, ctx) {
         json({ found: found.found, truncated: found.truncated, rows: found.rows });
         return;
     }
-    const lines = rowLines(index.graph, kind, found.rows);
+    const lines = rowLines(index.graph, kind, found.rows, values['show-source']);
     if (lines.length > 0) {
         write(lines.join('\n'));
     }
@@ -414,21 +437,24 @@ async function list(args, ctx) {
         note(dim(`  ${found.found} ${subject}${shown(found.found, found.rows.length)}`));
     }
 }
-function rowLines(graph, kind, rows) {
+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, doc(r.doc)]));
+        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),
     ]));
 }
@@ -438,7 +464,10 @@ async function grep(args, ctx) {
         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' },
@@ -450,13 +479,18 @@ async function grep(args, ctx) {
         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));
+    // 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) {
@@ -470,7 +504,11 @@ async function grep(args, ctx) {
     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))]));
+            : 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']) {
@@ -479,11 +517,22 @@ async function grep(args, ctx) {
 }
 // ---------------------------------------------------------------------------
 const shown = (found, kept) => (kept < found ? `, showing ${kept}` : '');
-function globs(patterns, flag) {
-    if (!patterns || patterns.length === 0) {
+/**
+ * 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 patterns.map((p) => pattern(() => loose(p), flag));
+    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) {
@@ -526,10 +575,11 @@ async function show(args, ctx) {
         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 dir = resolve(ctx.cwd, values.dir ?? DEFAULT_DIR);
+    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)) {
@@ -551,7 +601,10 @@ async function show(args, ctx) {
                 ? count(values['max-nodes'], '--max-nodes')
                 : undefined,
         });
-    const text = await present(index, subgraphs, format, { docs: !values['no-docs'] });
+    const text = await present(index, subgraphs, format, {
+        docs: !values['no-docs'],
+        source: values['show-source'],
+    });
     if (ctx.json) {
         json({ ids, subgraphs, rendered: text });
     }
@@ -603,7 +656,7 @@ function resolveIds(graph, ids, values) {
 }
 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,7 @@ 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';

package/dist/index.js

@@ -5,6 +5,7 @@ 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";

package/dist/schema/files.js

@@ -83,7 +83,7 @@ export async function readManifest(dir) {
         text = await readFile(join(dir, MANIFEST_FILE), 'utf8');
     }
     catch {
-        throw new CliError(`${dir} does not hold an index`, EXIT.invalid, 'build one first with `zen rag schema index`');
+        throw new CliError(`${dir} does not hold an index`, EXIT.invalid, 'build one with `zen rag schema index`, or name an existing one with --dir or $ZEN_SCHEMA_DB');
     }
     const manifest = JSON.parse(text);
     if (manifest.version !== INDEX_VERSION) {

package/dist/schema/locate.d.ts

@@ -0,0 +1,20 @@
+/** The name a new index is given. Nothing searches for it; only `index --out` writes it. */
+export declare const DEFAULT_DIR = "./schema-db";
+export declare const DIR_ENV = "ZEN_SCHEMA_DB";
+/** How the directory was arrived at, which is what decides whether to say so. */
+export type DirSource = 'flag' | 'env' | 'found' | 'default';
+export interface Located {
+    dir: string;
+    from: DirSource;
+}
+export interface LocateOptions {
+    env?: NodeJS.ProcessEnv;
+    /** do not climb above this; the home directory, or the root, by default */
+    ceiling?: string;
+}
+export declare function locateIndex(cwd: string, flag?: string, options?: LocateOptions): Located;
+/** Where a new index goes: the same environment variable, minus the search. */
+export declare function outputDir(cwd: string, flag?: string, env?: NodeJS.ProcessEnv): string;
+/** An index is a directory with a manifest in it; nothing else is asserted here. */
+export declare function isIndex(dir: string): boolean;
+//# sourceMappingURL=locate.d.ts.map

package/dist/schema/locate.js

@@ -0,0 +1,141 @@
+import { CliError, EXIT } from '@zenera/cli/lib';
+import { readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+import { MANIFEST_FILE } from "./files.js";
+// ---------------------------------------------------------------------------
+// Which index, when nobody said
+//
+// `--dir` and `$ZEN_SCHEMA_DB` are taken as written, missing or not: naming a
+// directory that turns out not to hold an index has to fail saying so, because
+// quietly using a different one would be a worse answer than an error.
+//
+// With neither, the directory is looked for. There is no list of blessed names
+// here and there should not be — an index is self-describing, so what is being
+// looked for is a `manifest.json`, not a directory called `schema-db`.
+// `schema-db` is only the name a *new* index is given, and nothing reads it
+// back. The search is nearest-first: this directory, then what is under it,
+// then up a level and again, so `/assets/…/whatever` is reachable from
+// `/workspace` because the two meet at a shared root on the way up.
+//
+// Three things bound it, and each is bounding a different kind of mistake.
+// Depth and a visit budget bound the cost. The ceiling — the home directory,
+// or the filesystem root when the search began outside it — bounds the
+// blast radius, because an index in someone else's tree is not yours. And two
+// indexes at the same distance is an ambiguity rather than a tie to break:
+// choosing one silently is the one failure worth ruling out entirely, since
+// the wrong index does not error, it answers confidently about another API.
+// ---------------------------------------------------------------------------
+/** The name a new index is given. Nothing searches for it; only `index --out` writes it. */
+export const DEFAULT_DIR = './schema-db';
+export const DIR_ENV = 'ZEN_SCHEMA_DB';
+/** Far enough to climb out of a package into its workspace, not far enough to roam. */
+const MAX_LEVELS = 6;
+/** How far below a directory an index may sit and still count as being in it. */
+const MAX_DEPTH = 3;
+/** A directory with more entries than this is a data store, not a place to keep an index. */
+const MAX_ENTRIES = 128;
+/** Directories the whole search may read, however it is shaped. */
+const MAX_VISITS = 400;
+export function locateIndex(cwd, flag, options = {}) {
+    const env = options.env ?? process.env;
+    if (flag) {
+        return { dir: resolve(cwd, flag), from: 'flag' };
+    }
+    const named = env[DIR_ENV]?.trim();
+    if (named) {
+        return { dir: resolve(cwd, named), from: 'env' };
+    }
+    const found = search(resolve(cwd), options.ceiling ?? ceilingFor(cwd));
+    // Nothing found still answers with the default, so the error names the
+    // directory everyone expects rather than the last place that was searched.
+    return found
+        ? { dir: found, from: 'found' }
+        : { dir: resolve(cwd, DEFAULT_DIR), from: 'default' };
+}
+/** Where a new index goes: the same environment variable, minus the search. */
+export function outputDir(cwd, flag, env = process.env) {
+    return resolve(cwd, flag ?? env[DIR_ENV]?.trim() ?? DEFAULT_DIR);
+}
+/** An index is a directory with a manifest in it; nothing else is asserted here. */
+export function isIndex(dir) {
+    try {
+        return statSync(join(dir, MANIFEST_FILE)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function search(cwd, ceiling) {
+    const budget = { left: MAX_VISITS, seen: new Set() };
+    let dir = cwd;
+    for (let level = 0; level < MAX_LEVELS; level++) {
+        const found = nearest(dir, budget);
+        if (found.length === 1) {
+            return found[0];
+        }
+        if (found.length > 1) {
+            throw new CliError(`more than one index is equally close to here: ${found.join(', ')}`, EXIT.usage, `say which with --dir, or set ${DIR_ENV}`);
+        }
+        budget.seen.add(dir);
+        const up = dirname(dir);
+        if (up === dir || dir === ceiling) {
+            break;
+        }
+        dir = up;
+    }
+    return undefined;
+}
+/** Every index at the shallowest depth that has any, so a tie can be reported as one. */
+function nearest(root, budget) {
+    let frontier = [root];
+    for (let depth = 0; depth <= MAX_DEPTH && frontier.length > 0; depth++) {
+        const found = frontier.filter(isIndex);
+        if (found.length > 0) {
+            return found;
+        }
+        const next = [];
+        for (const dir of frontier) {
+            if (budget.left <= 0) {
+                return [];
+            }
+            budget.left--;
+            next.push(...children(dir).filter((child) => !budget.seen.has(child)));
+        }
+        frontier = next;
+    }
+    return [];
+}
+/**
+ * The subdirectories of one directory. Hidden directories and `node_modules`
+ * are skipped: an index kept out of sight is not one anybody meant to be found
+ * by looking.
+ */
+function children(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    if (entries.length > MAX_ENTRIES) {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+        .map((e) => join(dir, e.name));
+}
+/**
+ * Home is the ceiling for anyone working inside it. Starting outside it —
+ * a container whose workspace is `/workspace`, a CI checkout — there is no
+ * home to stay within, so the root is the only stop.
+ */
+function ceilingFor(cwd) {
+    const home = homedir();
+    const below = relative(home, resolve(cwd));
+    return below === '' || (!below.startsWith('..') && !isAbsolute(below))
+        ? home
+        : parse(resolve(cwd)).root;
+}
+//# sourceMappingURL=locate.js.map

package/dist/schema/lookup.d.ts

@@ -1,4 +1,4 @@
-import type { ApiGraph, NodeAttrs, NodeKind } from './graph.ts';
+import { type ApiGraph, type NodeAttrs, type NodeKind } from './graph.ts';
 import { type Matcher } from './match.ts';
 export interface Row extends NodeAttrs {
     id: string;
@@ -28,6 +28,9 @@ export interface Match {
 export interface GrepFilter {
     kinds?: readonly string[];
     source?: string;
+    /** the same two constraints `list` takes, so one question has one spelling */
+    name?: readonly Matcher[];
+    path?: readonly Matcher[];
     limit?: number;
 }
 export interface Grep {
@@ -41,4 +44,11 @@ export declare function grepNodes(graph: ApiGraph, match: Matcher, filter?: Grep
 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;
+/**
+ * The route a node sits on. An operation carries its own; a parameter carries
+ * the operation's name instead, so it is looked up. A schema has no route at
+ * all and never will — the same DTO is returned by half the API — which is
+ * why a `--path` filter is a filter on the operations and what hangs off them.
+ */
+export declare function routeOf(graph: ApiGraph, id: string, a: NodeAttrs): string;
 //# sourceMappingURL=lookup.d.ts.map

package/dist/schema/lookup.js

@@ -1,4 +1,5 @@
 import { textOf } from "./entities.js";
+import { methodId } from "./graph.js";
 import { PatternError } from "./match.js";
 /** A scan is bounded, because a pattern may have come from a model. */
 const DEADLINE_MS = 2000;
@@ -12,7 +13,7 @@ export function listNodes(graph, filter) {
         if (filter.name && !filter.name.some((match) => match(a.name))) {
             return;
         }
-        if (filter.path && !filter.path.some((match) => match(a.path))) {
+        if (filter.path && !matchesRoute(graph, id, a, filter.path)) {
             return;
         }
         rows.push({ ...a, id });
@@ -36,6 +37,12 @@ export function grepNodes(graph, match, filter = {}) {
         if (filter.source && a.source !== filter.source) {
             continue;
         }
+        if (filter.name && !filter.name.some((match) => match(a.name))) {
+            continue;
+        }
+        if (filter.path && !matchesRoute(graph, id, a, filter.path)) {
+            continue;
+        }
         const text = textOf(graph, id);
         if (match(text)) {
             matches.push({ id, attributes: a, text });
@@ -53,7 +60,27 @@ export function propertyCount(graph, id) {
 }
 /** That count, said properly, in the one phrasing the CLI and the tools share. */
 export const fields = (n) => `${n} ${n === 1 ? 'field' : 'fields'}`;
+/**
+ * The route a node sits on. An operation carries its own; a parameter carries
+ * the operation's name instead, so it is looked up. A schema has no route at
+ * all and never will — the same DTO is returned by half the API — which is
+ * why a `--path` filter is a filter on the operations and what hangs off them.
+ */
+export function routeOf(graph, id, a) {
+    if (a.path) {
+        return a.path;
+    }
+    if (a.kind !== 'property' || !a.parent) {
+        return '';
+    }
+    const owner = methodId(a.parent);
+    return graph.hasNode(owner) ? graph.getNodeAttribute(owner, 'path') : '';
+}
 // ---------------------------------------------------------------------------
+function matchesRoute(graph, id, a, patterns) {
+    const route = routeOf(graph, id, a);
+    return route !== '' && patterns.some((match) => match(route));
+}
 function passes(a, filter) {
     if (filter.source && a.source !== filter.source) {
         return false;

package/dist/schema/match.d.ts

@@ -29,6 +29,10 @@ export declare const isGlob: (pattern: string) => boolean;
  * 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.
+ *
+ * `regex` settles it outright, and has to: a star is punctuation in both
+ * languages, so `^/(users|teams)/.*` read as a glob would match nothing and
+ * never say why.
  */
 export declare function loose(pattern: string, options?: MatchOptions): Matcher;
 /** True when any of the patterns matches; no patterns means no opinion. */

package/dist/schema/match.js

@@ -53,8 +53,15 @@ export const isGlob = (pattern) => /[*?]/.test(pattern);
  * 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.
+ *
+ * `regex` settles it outright, and has to: a star is punctuation in both
+ * languages, so `^/(users|teams)/.*` read as a glob would match nothing and
+ * never say why.
  */
 export function loose(pattern, options = {}) {
+    if (options.regex) {
+        return matcher(pattern, options);
+    }
     return isGlob(pattern) ? wildcard(pattern, options) : matcher(pattern, options);
 }
 /** True when any of the patterns matches; no patterns means no opinion. */

package/dist/schema/render.d.ts

@@ -3,7 +3,15 @@ export type RenderFormat = 'text' | 'mermaid' | 'mermaid-flowchart';
 export interface RenderOptions {
     docs?: boolean;
     maxDoc?: number;
+    /** name the document each operation and schema came from */
+    source?: boolean;
 }
+/**
+ * Which document something came from, spelled one way everywhere. An index
+ * over four revisions of one API has four `GET /infra/tier-0s`, and a listing
+ * that does not say which is which is a listing you have to go and check.
+ */
+export declare const sourceTag: (source: string) => string;
 export declare function render(sub: Subgraph, format: RenderFormat, options?: RenderOptions): string;
 export declare function toText(sub: Subgraph, options?: RenderOptions): string;
 export declare function toMermaid(sub: Subgraph, options?: RenderOptions): string;

package/dist/schema/render.js

@@ -1,4 +1,10 @@
 const HIT = '»';
+/**
+ * Which document something came from, spelled one way everywhere. An index
+ * over four revisions of one API has four `GET /infra/tier-0s`, and a listing
+ * that does not say which is which is a listing you have to go and check.
+ */
+export const sourceTag = (source) => (source ? `[source: ${source}]` : '');
 export function render(sub, format, options = {}) {
     switch (format) {
         case 'mermaid':
@@ -44,7 +50,7 @@ export function toText(sub, options = {}) {
 function methodLines(view, method, options) {
     const a = method.attributes;
     const out = [
-        `  ${mark(method)}${a.httpMethod} ${a.path}  ${a.name}${doc(method, options, ' —')}`,
+        `  ${mark(method)}${a.httpMethod} ${a.path}  ${a.name}${from(method, options)}${doc(method, options, ' —')}`,
     ];
     for (const edge of view.out(method.id, 'HAS_PARAM')) {
         const node = view.node(edge.target);
@@ -62,7 +68,7 @@ function methodLines(view, method, options) {
 }
 function typeLines(view, type, options) {
     const out = [
-        `  ${mark(type)}${type.attributes.name}${side(type.attributes)}${doc(type, options, ' —')}`,
+        `  ${mark(type)}${type.attributes.name}${side(type.attributes)}${from(type, options)}${doc(type, options, ' —')}`,
     ];
     const composes = view.out(type.id, 'COMPOSES').map((e) => view.name(e.target));
     if (composes.length > 0) {
@@ -96,6 +102,10 @@ function doc(node, options, lead) {
     }
     return `${lead} ${clip(node.attributes.doc, options.maxDoc ?? 120)}`;
 }
+function from(node, options) {
+    const tag = options.source ? sourceTag(node.attributes.source) : '';
+    return tag ? `  ${tag}` : '';
+}
 // ---------------------------------------------------------------------------
 // Mermaid
 // ---------------------------------------------------------------------------

package/dist/schema/tools.d.ts

@@ -5,6 +5,8 @@ export interface SchemaToolOptions {
     /** what `format` defaults to when the model does not say */
     format?: Format;
     docs?: boolean;
+    /** name the document each answer came from; on by default past one document */
+    source?: boolean;
 }
 export declare function schemaTools<TCtx = unknown>(index: SchemaIndex, options?: SchemaToolOptions): AnyTool<TCtx>[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/schema/tools.js

@@ -4,6 +4,7 @@ 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 { sourceTag } from "./render.js";
 import { stitch } from "./subgraph.js";
 // ---------------------------------------------------------------------------
 // The same index, given to an agent
@@ -31,6 +32,10 @@ const MAX_ROWS = 200;
 export function schemaTools(index, options = {}) {
     const fallback = options.format ?? 'text';
     const docs = options.docs ?? true;
+    // With one document there is nothing to disambiguate and naming it on every
+    // line is prompt spent saying the same word; with several it is the only
+    // way to tell two revisions of one API apart.
+    const source = options.source ?? index.manifest.sources.length > 1;
     const searchApi = tool({
         name: 'search_api',
         group: GROUP,
@@ -107,7 +112,10 @@ export function schemaTools(index, options = {}) {
                 found: result.subgraphs.length,
                 ids: result.subgraphs.flatMap((s) => s.hits),
                 truncated: result.subgraphs.some((s) => s.truncated),
-                api: await present(index, result.subgraphs, chosen(format, fallback), { docs }),
+                api: await present(index, result.subgraphs, chosen(format, fallback), {
+                    docs,
+                    source,
+                }),
             };
         },
     });
@@ -209,12 +217,24 @@ export function schemaTools(index, options = {}) {
                     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*".' },
+                path: {
+                    type: 'string',
+                    description: 'Match the route, e.g. "/users*". Keeps operations and their ' +
+                        'parameters; a schema sits on no one route, so it is left out.',
+                },
+                regex: {
+                    type: 'boolean',
+                    description: 'Read `name` and `path` as regular expressions instead.',
+                },
                 method_type: {
                     type: 'string',
                     enum: ['read_only', 'read_write', 'any'],
                 },
                 direction: { type: 'string', enum: ['input', 'output', 'any'] },
+                source: {
+                    type: 'string',
+                    description: 'Only this document, when the index holds more than one.',
+                },
                 limit: {
                     type: 'integer',
                     description: `Rows to return. Default ${DEFAULT_ROWS}.`,
@@ -222,7 +242,7 @@ export function schemaTools(index, options = {}) {
             },
             additionalProperties: false,
         },
-        execute: async ({ kind, name, path, method_type, direction, limit }) => {
+        execute: async ({ kind, name, path, regex, method_type, direction, source: only, limit, }) => {
             const subject = SUBJECTS[kind ?? 'methods'];
             if (!subject) {
                 return { error: `cannot list "${kind}"`, hint: 'kind is methods, types or fields' };
@@ -231,8 +251,9 @@ export function schemaTools(index, options = {}) {
             try {
                 result = listNodes(index.graph, {
                     kind: subject,
-                    name: name ? [loose(name)] : undefined,
-                    path: path ? [loose(path)] : undefined,
+                    name: name ? [loose(name, { regex })] : undefined,
+                    path: path ? [loose(path, { regex })] : undefined,
+                    source: only,
                     methodType: enumerated(method_type),
                     direction: enumerated(direction),
                     limit: Math.min(limit ?? DEFAULT_ROWS, MAX_ROWS),
@@ -244,7 +265,7 @@ export function schemaTools(index, options = {}) {
             return {
                 found: result.found,
                 truncated: result.truncated,
-                [PLURALS[subject]]: result.rows.map((r) => line(index.graph, subject, r)),
+                [PLURALS[subject]]: result.rows.map((r) => line(index.graph, subject, r, source)),
             };
         },
     });
@@ -255,7 +276,8 @@ export function schemaTools(index, options = {}) {
             '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.',
+            'returned nothing really means there is nothing. Narrow it with `path` or ' +
+            '`name` when the word is common and only one corner of the API is meant.',
         parameters: {
             type: 'object',
             properties: {
@@ -268,6 +290,18 @@ export function schemaTools(index, options = {}) {
                     description: 'Read the pattern as a regular expression instead.',
                 },
                 kind: { type: 'string', enum: ['method', 'type', 'property'] },
+                name: {
+                    type: 'string',
+                    description: 'Only nodes whose own name matches this. * and ? allowed.',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Only what sits on a matching route, e.g. "/users*".',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Only this document, when the index holds more than one.',
+                },
                 limit: {
                     type: 'integer',
                     description: `Matches to return. Default ${DEFAULT_ROWS}. \`found\` always counts them all.`,
@@ -276,11 +310,14 @@ export function schemaTools(index, options = {}) {
             required: ['pattern'],
             additionalProperties: false,
         },
-        execute: async ({ pattern, regex, kind, limit }) => {
+        execute: async ({ pattern, regex, kind, name, path, source: only, limit }) => {
             let result;
             try {
                 result = grepNodes(index.graph, matcher(pattern, { regex }), {
                     kinds: kind ? [kind] : undefined,
+                    name: name ? [loose(name)] : undefined,
+                    path: path ? [loose(path)] : undefined,
+                    source: only,
                     limit: Math.min(limit ?? DEFAULT_ROWS, MAX_ROWS),
                 });
             }
@@ -296,7 +333,11 @@ export function schemaTools(index, options = {}) {
             return {
                 found: result.found,
                 truncated: result.truncated,
-                matches: result.matches.map((m) => ({ id: m.id, text: m.text })),
+                matches: result.matches.map((m) => ({
+                    id: m.id,
+                    ...(source ? { source: m.attributes.source } : {}),
+                    text: m.text,
+                })),
             };
         },
     });
@@ -315,16 +356,17 @@ const PLURALS = {
     property: 'properties',
 };
 /** One row, as the line a model reads rather than an object it has to walk. */
-function line(graph, kind, row) {
+function line(graph, kind, row, source = false) {
+    const from = source ? `  ${sourceTag(row.source)}` : '';
     if (kind === 'method') {
-        return `${row.httpMethod} ${row.path}  ${row.name}${row.doc ? ` — ${row.doc}` : ''}`;
+        return `${row.httpMethod} ${row.path}  ${row.name}${from}${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}` : ''}`;
+        return `${row.name}${side}  ${fields(propertyCount(graph, row.id))}${from}${row.doc ? ` — ${row.doc}` : ''}`;
     }
     const owner = row.parent ? `${row.parent}.` : '';
-    return `${owner}${row.name}${row.required ? '' : '?'}: ${row.signature || 'unknown'}`;
+    return `${owner}${row.name}${row.required ? '' : '?'}: ${row.signature || 'unknown'}${from}`;
 }
 const enumerated = (value) => value && value !== 'any' ? value : undefined;
 function list(description) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/rag",
-    "version": "1.1.5",
+    "version": "1.1.6",
     "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.5",
-        "@zenera/neo": "^1.1.5"
+        "@zenera/cli": "^1.1.6",
+        "@zenera/neo": "^1.1.6"
     }
 }