@zenera/rag 1.1.24 → 1.1.25

package/README.md

@@ -313,7 +313,7 @@ zen rag docs ready               Can this index answer? Exit 0 if it can, 3 if i
 zen rag docs search [text]       Ask it something. --interactive for a prompt.
 zen rag docs list <what>         Every document, section or table. No ranking.
 zen rag docs grep <pattern>      Every matching line, with the section it sits in.
-zen rag docs show <file>         A document, a section of one, or a line range.
+zen rag docs show <target...>    Documents, sections or line ranges, several in one call.
 zen rag docs stats               What is in an index, and what built it.
 ```
 
@@ -377,11 +377,19 @@ zen rag docs list tables                     # every table, with its columns
 zen rag docs grep "Retry-After"              # every matching line, and its section
 zen rag docs show api/routing.md --section "Rate limits"
 zen rag docs show api/routing.md --lines 40-80
+zen rag docs show "api/routing.md:24-31" "api/errors.md#Retries"
 ```
 
 `grep` counts every match, not the top of a list, so unlike a search it can
 answer whether a string appears at all.
 
+`show` takes any number of targets written the way a citation is -
+`<document>:<a>-<b>`, `<document>:<a>`, `<document>#<heading>`, or a bare name -
+and prints each under a header that is itself a target, so reading every
+passage an answer cites costs one call. Overlapping ranges print once, a
+missing target is reported in place, and `--max-lines` (default 400) is shared
+between them, each cut block naming the target that continues it.
+
 <details>
 <summary>Every flag</summary>
 
@@ -559,12 +567,12 @@ Only the first ranks. `find_types_with_property` is the one for the repair loop
 
 Four tools in the group `docs`, selectable as `docs:*`:
 
-| Tool          | For                                                          |
-| ------------- | ------------------------------------------------------------ |
-| `search_docs` | the passages that match, quoted with their line numbers      |
-| `list_docs`   | the documents, their headings, or their tables - no search   |
-| `grep_docs`   | every matching line, counted in full - no search             |
-| `read_docs`   | a section or a line range, verbatim and with nothing omitted |
+| Tool          | For                                                              |
+| ------------- | ---------------------------------------------------------------- |
+| `search_docs` | the passages that match, quoted with their line numbers          |
+| `list_docs`   | the documents, their headings, or their tables - no search       |
+| `grep_docs`   | every matching line, counted in full - no search                 |
+| `read_docs`   | a section or a line range, verbatim; several at once via `reads` |
 
 `search_docs` is the way in when the question is vague; `grep_docs` is how "it
 is not in here" can actually be concluded. Every answer carries line numbers and

package/dist/common/progress.js

@@ -1,6 +1,6 @@
 import { CliError, EXIT } from '@zenera/cli/lib';
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { hostname } from 'node:os';
+import { claimLock, ownLock } from '@zenera/neo';
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 // ---------------------------------------------------------------------------
 // A build that says what it is doing
@@ -32,14 +32,12 @@ export const INTERVAL_MS = 5000;
 export function beginBuild(plan) {
     const documents = plan.files.map((file) => basename(file));
     const started = Date.now();
-    const lock = {
-        pid: process.pid,
-        host: hostname(),
+    const lock = ownLock({
         startedAt: new Date(started).toISOString(),
         indexer: plan.indexer,
         embedding: plan.embedding,
         documents,
-    };
+    });
     mkdirSync(plan.dir, { recursive: true });
     claim(join(plan.dir, LOCK_FILE), lock);
     let phase = Object.keys(plan.phases)[0];
@@ -140,48 +138,8 @@ export function beginBuild(plan) {
         },
     };
 }
-/**
- * `wx` makes the create and the check one operation, so two builds racing for
- * the same directory cannot both win. A lock whose process is gone is stale by
- * definition and is taken rather than respected — a crashed build must not make
- * a directory permanently unbuildable.
- */
+/** Two builds writing one index would interleave their store writes. */
 function claim(path, lock) {
-    const body = `${JSON.stringify(lock, null, 4)}\n`;
-    try {
-        writeFileSync(path, body, { flag: 'wx' });
-        return;
-    }
-    catch (err) {
-        if (err.code !== 'EEXIST') {
-            throw err;
-        }
-    }
-    const held = readLock(path);
-    if (held && held.host === hostname() && alive(held.pid)) {
-        throw new CliError(`this index is already being built (pid ${held.pid}, since ${held.startedAt})`, EXIT.failed, `wait for it, or build elsewhere with --out`);
-    }
-    writeFileSync(path, body);
-}
-function readLock(path) {
-    try {
-        return JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * `kill(pid, 0)` sends no signal and only asks whether the process exists.
- * EPERM means it exists and belongs to someone else, which still counts.
- */
-function alive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
+    claimLock(path, lock, (held) => new CliError(`this index is already being built (pid ${held.pid}, since ${held.startedAt})`, EXIT.failed, `wait for it, or build elsewhere with --out`));
 }
 //# sourceMappingURL=progress.js.map

package/dist/docs/command.js

@@ -1,10 +1,10 @@
 import { bold, CliError, cyan, dim, EXIT, isInteractive, json, note, parse, paths, table, usageError, write, } from '@zenera/cli/lib';
+import { PatternError } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { resolveEmbedder } from "../common/embedder.js";
 import { locateIndex, outputDir } from "../common/locate.js";
 import { assertSameEmbedding, inspectIndex } from "../common/manifest.js";
-import { PatternError } from "../common/match.js";
 import { INTERVAL_MS } from "../common/progress.js";
 import { breakdown, grid, indexing } from "../common/prose.js";
 import { announce, reportReady, stagingFor, swapIn } from "../common/restore.js";
@@ -13,11 +13,12 @@ import { buildIndex } from "./build.js";
 import { CHUNK_KINDS } from "./chunk.js";
 import { DOCS_INDEX, readManifest, SOURCES_DIR } from "./files.js";
 import { DOC_EXTENSIONS } from "./load.js";
-import { grepLines, listFiles, listSections, listTables, readRange, readSection, } from "./lookup.js";
-import { MATCH_HEADERS, matchRows, renderAssembly } from "./render.js";
+import { grepLines, isFailure, listFiles, listSections, listTables, readMany, readRange, readSection, spanOf, } from "./lookup.js";
+import { MATCH_HEADERS, matchRows, renderAssembly, renderReads } from "./render.js";
 import { repl } from "./repl.js";
 import { DEFAULT_LIMIT, DocsIndex, legsOf, SEARCH_MODES, } from "./search.js";
 import { ChunkStore } from "./store.js";
+import { parseTarget, selects, TargetError } from "./targets.js";
 const { defaultDir: DEFAULT_DIR, envName: DIR_ENV } = DOCS_INDEX;
 // ---------------------------------------------------------------------------
 // zen rag docs — a pile of documents, as something to search
@@ -49,7 +50,7 @@ const READY_USAGE = 'zen rag docs ready [--dir <dir>] [--quiet]';
 const SEARCH_USAGE = 'zen rag docs search [--dir <dir>] [query... | --text-query <text> --vector-query <text>]';
 const LIST_USAGE = 'zen rag docs list <files|sections|tables> [--dir <dir>]';
 const GREP_USAGE = 'zen rag docs grep <pattern> [--dir <dir>]';
-const SHOW_USAGE = 'zen rag docs show <file> [--section <name>] [--lines <from-to>]';
+const SHOW_USAGE = 'zen rag docs show <file> [--section <name>] [--lines <from-to>] | <target>... [--max-lines <n>]';
 export const command = {
     summary: 'Search a pile of markdown and text documents.',
     usage: USAGE,
@@ -78,8 +79,8 @@ export const command = {
                 dim('Find every literal or regex line match; use it to prove whether text exists.'),
             ],
             [
-                '  show <file>',
-                dim('Read a document, heading or line range verbatim after finding its location.'),
+                '  show <target...>',
+                dim('Read documents, headings or line ranges verbatim, several in one call.'),
             ],
             ['  stats', dim('Inspect the index contents, size and embedding configuration.')],
         ]),
@@ -197,9 +198,20 @@ export const command = {
             ['  <file>', dim('A document name, as `list files` prints it.')],
             ['  --section <name>', dim('Just that heading and what nests under it.')],
             ['  --lines <from-to>', dim('Just those lines, e.g. --lines 40-80.')],
+            ['  <doc>:<a>-<b>', dim('Lines a to b. <doc>:<a> is one line.')],
+            ['  <doc>#<heading>', dim('A heading and what nests under it.')],
+            [
+                '  --max-lines <n>',
+                dim(`A ceiling shared by every target. Default ${DEFAULT_MAX_LINES}.`),
+            ],
             ['  --no-numbers', dim('Without the line-number gutter.')],
         ]),
         '',
+        dim('  Name every passage you will read in one call, as the search printed them:'),
+        dim(`  ${cyan('zen rag docs show "api/routing.md:24-60" "api/limits.md#Rate limits"')}`),
+        dim('  Each prints under a header that is itself a target, in the order given;'),
+        dim('  overlapping ranges print once. --section and --lines take one document.'),
+        '',
         dim(`Without --dir, the index is the nearest one at or above the working`),
         dim(`directory; ${cyan(DIR_ENV)} names it outright.`),
         '',
@@ -615,32 +627,56 @@ async function show(args, ctx) {
         dir: { type: 'string', short: 'd' },
         section: { type: 'string', short: 's' },
         lines: { type: 'string' },
+        'max-lines': { type: 'string' },
         'no-numbers': { type: 'boolean' },
         quiet: { type: 'boolean' },
     }, SHOW_USAGE);
-    const [name] = positionals;
-    if (!name) {
+    if (positionals.length === 0) {
         throw usageError('no document named', SHOW_USAGE);
     }
+    const flagged = values.section !== undefined || values.lines !== undefined;
+    if (flagged && positionals.length > 1) {
+        throw usageError('--section and --lines read one document', 'name each part instead: <document>:<a>-<b> or <document>#<heading>');
+    }
+    const span = values.lines ? range(values.lines) : undefined;
+    const maxLines = values['max-lines'] ? count(values['max-lines'], '--max-lines') : undefined;
     const found = await open(ctx, values.dir);
     try {
+        const names = new Set(found.manifest.sources.map((s) => s.name));
+        const several = !flagged && (positionals.length > 1 || targeted(() => selects(positionals[0], names)));
+        if (several) {
+            const reads = targeted(() => positionals.map((raw) => parseTarget(raw, names)));
+            await showMany(ctx, found, reads, values, maxLines ?? DEFAULT_MAX_LINES);
+            return;
+        }
+        const name = positionals[0];
         const file = found.resolveFiles([name])[0];
         if (!file) {
             throw new CliError(`no document called ${name}`, EXIT.failed, 'list them with `zen rag docs list files`');
         }
-        const span = values.lines ? range(values.lines) : undefined;
-        const excerpt = values.section
+        const whole = values.section
             ? await readSection(found, file, values.section)
             : await readRange(found, file, span?.[0] ?? 1, span?.[1] ?? Infinity);
+        // Uncapped unless asked: this form printed whole documents before the cap existed.
+        const cut = maxLines !== undefined && whole.lines.length > maxLines;
+        const excerpt = cut
+            ? { ...whole, lines: whole.lines.slice(0, maxLines), end: whole.start + maxLines - 1 }
+            : whole;
         if (ctx.json) {
-            json(excerpt);
+            json(cut ? { ...excerpt, truncated: true } : excerpt);
             return;
         }
-        const width = String(excerpt.end).length;
+        const width = String(whole.end).length;
         write(excerpt.lines
             .map((line, at) => values['no-numbers']
             ? line
             : `${dim(String(excerpt.start + at).padStart(width))} ${dim('|')} ${line}`)
+            .concat(cut
+            ? [
+                dim(`... truncated at line ${excerpt.end} of ${whole.end} - read ` +
+                    `${spanOf(file, excerpt.end + 1, whole.end)} to continue`),
+            ]
+            : [])
             .join('\n'));
         if (!values.quiet) {
             note(dim(`  ${file} · lines ${excerpt.start}-${excerpt.end} of ${excerpt.total}`));
@@ -650,6 +686,51 @@ async function show(args, ctx) {
         found.close();
     }
 }
+async function showMany(ctx, found, reads, values, maxLines) {
+    const read = await patterned(() => readMany(found, reads, { maxLines }));
+    if (ctx.json) {
+        json({
+            results: read.results.map((result) => isFailure(result)
+                ? result
+                : {
+                    target: result.target,
+                    file: result.file,
+                    from: result.from,
+                    to: result.to,
+                    section: result.section ?? null,
+                    text: result.lines.join('\n'),
+                    truncated: result.truncated,
+                    ...(result.continue ? { continue: result.continue } : {}),
+                }),
+            printed: read.printed,
+            failed: read.failed,
+        });
+    }
+    else {
+        write(renderReads(read, { numbers: !values['no-numbers'] }));
+        if (!values.quiet) {
+            const lines = read.results.reduce((sum, r) => sum + (isFailure(r) ? 0 : r.lines.length), 0);
+            const cut = read.results.some((r) => !isFailure(r) && r.truncated);
+            note(dim(`  ${read.printed} of ${read.results.length} target(s) · ${lines} line(s)` +
+                (cut ? ` · cut to --max-lines ${maxLines}` : '')));
+        }
+    }
+    if (read.printed === 0) {
+        throw new CliError('none of the targets could be read', EXIT.failed, '`zen rag docs list files` lists the document names');
+    }
+}
+/** A malformed target is a bad invocation, so nothing is printed for any of them. */
+function targeted(run) {
+    try {
+        return run();
+    }
+    catch (err) {
+        if (err instanceof TargetError) {
+            throw usageError(err.message, SHOW_USAGE);
+        }
+        throw err;
+    }
+}
 async function stats(args, ctx) {
     const { values } = parse(args, { dir: { type: 'string', short: 'd' } }, 'zen rag docs stats [--dir <dir>]');
     const dir = indexDir(ctx, values.dir);

package/dist/docs/load.js

@@ -1,8 +1,8 @@
 import { CliError, EXIT } from '@zenera/cli/lib';
+import { isGlob, wildcard } from '@zenera/neo';
 import { createHash } from 'node:crypto';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { isGlob, wildcard } from "../common/match.js";
 import { NO_PARSE_CACHE, openParseCache, parseKey } from "./parse-cache.js";
 import { normalize } from "./parse.js";
 import { parseAll } from "./pool.js";

package/dist/docs/lookup.d.ts

@@ -1,4 +1,4 @@
-import { type MatchOptions } from '../common/match.ts';
+import { type MatchOptions } from '@zenera/neo';
 import type { DocsIndex } from './search.ts';
 export interface Listing<T> {
     found: number;
@@ -77,4 +77,57 @@ export interface Verbatim {
 /** A named section, verbatim: heading line to the line before the next peer. */
 export declare function readSection(index: DocsIndex, file: string, section: string): Promise<Verbatim>;
 export declare function readRange(index: DocsIndex, file: string, from: number, to: number): Promise<Verbatim>;
+export interface Read {
+    /** what the caller wrote, so a failure can be put back next to it */
+    target: string;
+    file: string;
+    /** a heading title, id or path; wins over from/to */
+    section?: string;
+    from?: number;
+    to?: number;
+}
+export interface ReadBlock {
+    /** what was printed, as a read that would print it again */
+    target: string;
+    file: string;
+    /** first line printed */
+    from: number;
+    /** last line printed; `from - 1` when the budget left none */
+    to: number;
+    /** last line that was asked for, after clamping to the document */
+    end: number;
+    total: number;
+    /** the heading, when the block is exactly one section */
+    section?: string;
+    /** the range asked for, when it ran past the end of the document */
+    asked?: string;
+    lines: string[];
+    truncated: boolean;
+    /** the read that prints the rest of a cut block */
+    continue?: string;
+}
+export interface ReadFailure {
+    target: string;
+    file: string;
+    error: string;
+    hint: string;
+}
+export type ReadResult = ReadBlock | ReadFailure;
+export interface ReadMany {
+    results: ReadResult[];
+    printed: number;
+    failed: number;
+}
+export interface ReadHints {
+    document: (file: string) => string;
+    section: (file: string) => string;
+    range: (file: string, total: number) => string;
+}
+export interface ReadManyOptions {
+    maxLines?: number;
+    hints?: Partial<ReadHints>;
+}
+export declare const isFailure: <T extends object>(result: T | ReadFailure) => result is ReadFailure;
+export declare const spanOf: (file: string, from: number, to: number) => string;
+export declare function readMany(index: DocsIndex, reads: readonly Read[], options?: ReadManyOptions): Promise<ReadMany>;
 //# sourceMappingURL=lookup.d.ts.map

package/dist/docs/lookup.js

@@ -1,5 +1,5 @@
 import { CliError, EXIT } from '@zenera/cli/lib';
-import { loose } from "../common/match.js";
+import { loose } from '@zenera/neo';
 import { under } from "./search.js";
 export const DEFAULT_ROWS = 50;
 export const MAX_ROWS = 500;
@@ -120,6 +120,125 @@ export async function readRange(index, file, from, to) {
         total: lines.length,
     };
 }
+const CLI_HINTS = {
+    document: (file) => `\`zen rag docs list files --file "*${file.split('/').at(-1)}*"\` lists close names`,
+    section: (file) => `\`zen rag docs list sections --file "${file}"\` lists its headings`,
+    range: (file, total) => `read ${spanOf(file, 1, total)}`,
+};
+export const isFailure = (result) => 'error' in result;
+export const spanOf = (file, from, to) => from === to ? `${file}:${from}` : `${file}:${from}-${to}`;
+export async function readMany(index, reads, options = {}) {
+    const hints = { ...CLI_HINTS, ...options.hints };
+    const slots = [];
+    for (const read of reads) {
+        const span = await spanFor(index, read, hints);
+        if (isFailure(span)) {
+            slots.push(span);
+            continue;
+        }
+        // Everything it overlaps or touches folds into the first of them, so a
+        // line is printed once however many reads named it.
+        const touching = slots.filter((slot) => !isFailure(slot) &&
+            slot.file === span.file &&
+            span.from <= slot.end + 1 &&
+            span.end >= slot.from - 1);
+        if (touching.length === 0) {
+            slots.push(span);
+            continue;
+        }
+        const [first, ...rest] = touching;
+        const all = [first, ...rest, span];
+        const from = Math.min(...all.map((s) => s.from));
+        const end = Math.max(...all.map((s) => s.end));
+        const same = all.every((s) => s.from === from && s.end === end);
+        Object.assign(first, {
+            from,
+            end,
+            section: same && all.every((s) => s.section === first.section) ? first.section : undefined,
+            asked: same ? first.asked : undefined,
+        });
+        for (const gone of rest) {
+            slots.splice(slots.indexOf(gone), 1);
+        }
+    }
+    const spans = slots.filter((slot) => !isFailure(slot));
+    const grants = share(spans.map((s) => s.end - s.from + 1), options.maxLines ?? Infinity);
+    const results = [];
+    for (const slot of slots) {
+        if (isFailure(slot)) {
+            results.push(slot);
+            continue;
+        }
+        const granted = grants[spans.indexOf(slot)];
+        const to = slot.from + granted - 1;
+        const lines = (await index.lines(slot.file)).slice(slot.from - 1, to);
+        const truncated = to < slot.end;
+        results.push({
+            target: spanOf(slot.file, slot.from, granted > 0 ? to : slot.end),
+            file: slot.file,
+            from: slot.from,
+            to,
+            end: slot.end,
+            total: slot.total,
+            ...(slot.section ? { section: slot.section } : {}),
+            ...(slot.asked ? { asked: slot.asked } : {}),
+            lines,
+            truncated,
+            ...(truncated ? { continue: spanOf(slot.file, to + 1, slot.end) } : {}),
+        });
+    }
+    const failed = results.filter(isFailure).length;
+    return { results, printed: results.length - failed, failed };
+}
+async function spanFor(index, read, hints) {
+    const fail = (error, hint) => ({
+        target: read.target,
+        file: read.file,
+        error,
+        hint,
+    });
+    const outline = index.file(read.file);
+    if (!outline) {
+        return fail('no document by that name', hints.document(read.file));
+    }
+    const total = (await index.lines(read.file)).length;
+    const base = { target: read.target, file: read.file, total };
+    if (read.section !== undefined) {
+        const found = index.resolveSections([read.section], [read.file]);
+        const wanted = read.section.toLowerCase();
+        const heading = found.find((h) => h.title.toLowerCase() === wanted) ?? found[0];
+        if (!heading) {
+            return fail(`no section called ${read.section}`, hints.section(read.file));
+        }
+        return { ...base, from: heading.line, end: heading.end, section: heading.title };
+    }
+    const from = read.from ?? 1;
+    const to = read.to ?? total;
+    if (from > total) {
+        return fail(`line ${from} is past the end; the document has ${total} lines`, hints.range(read.file, total));
+    }
+    return {
+        ...base,
+        from,
+        end: Math.min(to, total),
+        ...(to > total && read.to !== undefined ? { asked: `${from}-${to}` } : {}),
+    };
+}
+/**
+ * Divides a budget so no request can starve the rest: an even share each, and
+ * what a short one does not use is shared again among those still wanting.
+ */
+function share(sizes, budget) {
+    const grants = sizes.map(() => 0);
+    const order = sizes.map((_, at) => at).sort((a, b) => sizes[a] - sizes[b]);
+    let left = budget;
+    for (const [rank, at] of order.entries()) {
+        const fair = Math.floor(left / (order.length - rank));
+        grants[at] = Math.min(sizes[at], fair === Infinity ? sizes[at] : fair);
+        left -= grants[at];
+    }
+    return grants;
+}
 // ---------------------------------------------------------------------------
 function cut(rows, limit) {
     const take = Math.min(Math.max(1, limit ?? DEFAULT_ROWS), MAX_ROWS);

package/dist/docs/render.d.ts

@@ -1,4 +1,5 @@
 import type { Assembly, Excerpt } from './assemble.ts';
+import { type ReadMany } from './lookup.ts';
 import type { Match } from './search.ts';
 export interface RenderOptions {
     /** the line-number gutter; on unless something else is going to eat this */
@@ -7,6 +8,11 @@ export interface RenderOptions {
 }
 export declare function renderAssembly(assembly: Assembly, options?: RenderOptions): string;
 export declare function renderExcerpt(file: Excerpt, options?: RenderOptions): string[];
+/**
+ * Each read under a header that is itself a read, so a citation copied from
+ * the header, or the line that continues a cut block, pastes straight back.
+ */
+export declare function renderReads(read: ReadMany, options?: RenderOptions): string;
 /** The one-line-per-match view, for `--quiet` and for the prompt loop. */
 export declare const matchRows: (matches: readonly Match[]) => string[][];
 export declare const MATCH_HEADERS: readonly ["id", "kind", "lines", "score", "vec / txt", "heading"];

package/dist/docs/render.js

@@ -1,4 +1,5 @@
 import { bold, dim } from '@zenera/cli/lib';
+import { isFailure } from "./lookup.js";
 export function renderAssembly(assembly, options = {}) {
     const out = [];
     for (const file of assembly.files) {
@@ -30,6 +31,38 @@ function renderPiece(piece, width, options, faint) {
         : `${faint(String(piece.start + at).padStart(width))} ${faint('|')} ${line}`);
     return [...lines, ''];
 }
+/**
+ * Each read under a header that is itself a read, so a citation copied from
+ * the header, or the line that continues a cut block, pastes straight back.
+ */
+export function renderReads(read, options = {}) {
+    const paint = options.colour === false ? (s) => s : undefined;
+    const strong = paint ?? bold;
+    const faint = paint ?? dim;
+    const blocks = read.results.map((result) => isFailure(result)
+        ? [`## ${strong(result.target)}`, `error: ${result.error} - ${result.hint}`]
+        : renderBlock(result, options, strong, faint));
+    return blocks.map((lines) => lines.join('\n')).join('\n\n');
+}
+function renderBlock(block, options, strong, faint) {
+    const notes = [
+        block.section ? `(#${block.section})` : '',
+        block.asked ? `(asked ${block.asked}; the document ends at ${block.total})` : '',
+    ].filter(Boolean);
+    const width = String(block.end).length;
+    const out = [`## ${strong(block.target)}${notes.length ? ` ${faint(notes.join(' '))}` : ''}`];
+    for (const [at, line] of block.lines.entries()) {
+        out.push(options.numbers === false
+            ? line
+            : `${faint(String(block.from + at).padStart(width))} ${faint('|')} ${line}`);
+    }
+    if (block.continue) {
+        out.push(faint(block.lines.length > 0
+            ? `... truncated at line ${block.to} of ${block.end} - read ${block.continue} to continue`
+            : `... the line budget ran out before this one - read ${block.continue}`));
+    }
+    return out;
+}
 /** The one-line-per-match view, for `--quiet` and for the prompt loop. */
 export const matchRows = (matches) => matches.map((m) => [
     m.id,

package/dist/docs/search.d.ts

@@ -1,4 +1,4 @@
-import type { Embedder } from '@zenera/neo';
+import { type Embedder } from '@zenera/neo';
 import { type FileOutline, type HeadingRecord, type Manifest, type OpenDocs, type Outline } from './files.ts';
 import { ChunkStore } from './store.ts';
 export type SearchMode = 'hybrid' | 'vector' | 'text';

package/dist/docs/search.js

@@ -1,5 +1,5 @@
+import { loose, PatternError } from '@zenera/neo';
 import { assertSameEmbedding } from "../common/manifest.js";
-import { loose, PatternError } from "../common/match.js";
 import { CHUNK_KINDS, parseLines } from "./chunk.js";
 import { openIndex, readLines, } from "./files.js";
 import { ChunkStore } from "./store.js";

package/dist/docs/targets.d.ts

@@ -0,0 +1,7 @@
+import type { Read } from './lookup.ts';
+export declare class TargetError extends Error {
+}
+export declare function parseTarget(raw: string, names: ReadonlySet<string>): Read;
+/** Does this argument name a part of a document the index holds? */
+export declare function selects(raw: string, names: ReadonlySet<string>): boolean;
+//# sourceMappingURL=targets.d.ts.map

package/dist/docs/targets.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// A read, written as its citation
+//
+// `<document>:<a>-<b>`, `<document>:<a>`, `<document>#<heading>`, or a bare
+// document name — the form an answer cites a passage in, so a citation pastes
+// back unchanged.
+//
+// Splitting at the last `:` or `#` would be wrong both ways: a heading may hold
+// a colon (`#Step 1: Install`) and a document name is any relative path. So the
+// split is wherever the text before it is a document the index holds, longest
+// first, and only a name nobody holds is split by guesswork.
+// ---------------------------------------------------------------------------
+export class TargetError extends Error {
+}
+export function parseTarget(raw, names) {
+    if (names.has(raw)) {
+        return { target: raw, file: raw };
+    }
+    for (let at = raw.length - 1; at > 0; at--) {
+        if ((raw[at] === ':' || raw[at] === '#') && names.has(raw.slice(0, at))) {
+            return selector(raw, raw.slice(0, at), raw[at], raw.slice(at + 1));
+        }
+    }
+    // A name the index does not hold: a heading is likelier to carry a colon
+    // than a document name a hash, so the first `#` wins over the last `:`.
+    const hash = raw.indexOf('#');
+    const at = hash > 0 ? hash : raw.lastIndexOf(':');
+    return at > 0
+        ? selector(raw, raw.slice(0, at), raw[at], raw.slice(at + 1))
+        : { target: raw, file: raw };
+}
+/** Does this argument name a part of a document the index holds? */
+export function selects(raw, names) {
+    const read = parseTarget(raw, names);
+    return names.has(read.file) && read.file !== raw;
+}
+function selector(raw, file, mark, rest) {
+    if (mark === '#') {
+        if (!rest.trim()) {
+            throw new TargetError(`"${raw}" names no heading after the #`);
+        }
+        return { target: raw, file, section: rest };
+    }
+    const found = /^(\d+)(?:-(\d+))?$/.exec(rest);
+    const from = Number(found?.[1]);
+    const to = found?.[2] === undefined ? from : Number(found[2]);
+    if (!found || from < 1 || to < from) {
+        throw new TargetError(`"${raw}" is not a line range - expected <document>:<a>-<b>`);
+    }
+    return { target: raw, file, from, to };
+}
+//# sourceMappingURL=targets.js.map

package/dist/docs/tools.js

@@ -1,8 +1,7 @@
-import { tool } from '@zenera/neo';
-import { PatternError } from "../common/match.js";
+import { PatternError, tool } from '@zenera/neo';
 import { assemble } from "./assemble.js";
 import { CHUNK_KINDS } from "./chunk.js";
-import { grepLines, listFiles, listSections, listTables, readRange, readSection, } from "./lookup.js";
+import { grepLines, isFailure, listFiles, listSections, listTables, readMany, readRange, readSection, } from "./lookup.js";
 import { renderAssembly } from "./render.js";
 import { SEARCH_MODES } from "./search.js";
 // ---------------------------------------------------------------------------
@@ -248,7 +247,8 @@ export function docsTools(index, options = {}) {
         group: GROUP,
         description: 'Reads a document verbatim: a whole named section, or a line range as printed by ' +
             'search_docs or grep_docs. Use it when a passage was found and the lines around ' +
-            'it are needed in full, with nothing omitted and nothing summarised.',
+            'it are needed in full, with nothing omitted and nothing summarised. To read ' +
+            'several passages, name them all in `reads` in one call instead of calling again.',
         parameters: {
             type: 'object',
             properties: {
@@ -262,11 +262,38 @@ export function docsTools(index, options = {}) {
                 },
                 from: { type: 'integer', description: 'First line, 1-based. Default 1.' },
                 to: { type: 'integer', description: 'Last line. Default the end of the document.' },
+                reads: {
+                    type: 'array',
+                    description: 'Instead of file: every passage to read, each as {file, section} or ' +
+                        `{file, from, to}. They share a ceiling of ${MAX_LINES} lines.`,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            file: { type: 'string' },
+                            section: { type: 'string' },
+                            from: { type: 'integer' },
+                            to: { type: 'integer' },
+                        },
+                        required: ['file'],
+                        additionalProperties: false,
+                    },
+                },
             },
-            required: ['file'],
             additionalProperties: false,
         },
         execute: async (args) => {
+            if (args.reads !== undefined) {
+                if (args.file !== undefined || args.reads.length === 0) {
+                    return {
+                        error: args.file ? 'send `file` or `reads`, not both' : '`reads` is empty',
+                        hint: 'put every passage in `reads`, one {file, section} or {file, from, to} each',
+                    };
+                }
+                return await readSeveral(args.reads);
+            }
+            if (!args.file) {
+                return { error: 'nothing to read', hint: 'send `file`, or `reads` for several' };
+            }
             const file = index.resolveFiles([args.file])[0];
             if (!file) {
                 return {
@@ -293,6 +320,43 @@ export function docsTools(index, options = {}) {
         },
     });
     return [searchDocs, listDocs, grepDocs, readDocs];
+    async function readSeveral(reads) {
+        const names = new Set(index.manifest.sources.map((s) => s.name));
+        const resolved = await guard(() => reads.map((r) => ({
+            target: r.file,
+            file: names.has(r.file) ? r.file : (index.resolveFiles([r.file])[0] ?? r.file),
+            section: r.section,
+            from: r.from,
+            to: r.to,
+        })));
+        if ('error' in resolved) {
+            return resolved;
+        }
+        const read = await readMany(index, resolved, {
+            maxLines: MAX_LINES,
+            hints: {
+                document: () => 'call list_docs for the names',
+                section: () => 'call list_docs with what "sections" for its headings',
+                range: (_, total) => `it has ${total} lines`,
+            },
+        });
+        return {
+            printed: read.printed,
+            failed: read.failed,
+            results: read.results.map((r) => isFailure(r)
+                ? { file: r.file, error: r.error, hint: r.hint }
+                : {
+                    file: r.file,
+                    ...(r.section ? { section: r.section } : {}),
+                    start: r.from,
+                    end: r.to,
+                    total: r.total,
+                    truncated: r.truncated,
+                    ...(r.continue ? { continue: r.continue } : {}),
+                    text: r.lines.map((line, at) => `${r.from + at} | ${line}`).join('\n'),
+                }),
+        };
+    }
 }
 // ---------------------------------------------------------------------------
 const strings = (description) => ({

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+export { anyOf, isGlob, loose, matcher, MAX_PATTERN, PatternError, wildcard, type Matcher, type MatchOptions, } from '@zenera/neo';
 export * from './common/locate.ts';
 export * from './common/manifest.ts';
-export * from './common/match.ts';
 export * as docs from './docs/index.ts';
 export * from './schema/build.ts';
 export * from './schema/entities.ts';

package/dist/index.js

@@ -1,6 +1,6 @@
+export { anyOf, isGlob, loose, matcher, MAX_PATTERN, PatternError, wildcard, } from '@zenera/neo';
 export * from "./common/locate.js";
 export * from "./common/manifest.js";
-export * from "./common/match.js";
 // A namespace rather than a re-export: both subjects have a `Manifest`, a
 // `writeIndex` and a `search`, and flattening them would collide on every one.
 export * as docs from "./docs/index.js";

package/dist/schema/command.js

@@ -1,10 +1,10 @@
 import { bold, CliError, cyan, dim, EXIT, isInteractive, json, note, parse, paths, table, usageError, write, } from '@zenera/cli/lib';
+import { isGlob, loose, matcher, PatternError, wildcard } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { resolveEmbedder } from "../common/embedder.js";
 import { locateIndex, outputDir } from "../common/locate.js";
 import { assertSameEmbedding, inspectIndex } from "../common/manifest.js";
-import { isGlob, loose, matcher, PatternError, wildcard } from "../common/match.js";
 import { breakdown, indexing } from "../common/prose.js";
 import { announce, reportReady, stagingFor, swapIn } from "../common/restore.js";
 import { buildIndex } from "./build.js";

package/dist/schema/lookup.d.ts

@@ -1,4 +1,4 @@
-import { type Matcher } from '../common/match.ts';
+import { type Matcher } from '@zenera/neo';
 import { type ApiGraph, type NodeAttrs, type NodeKind } from './graph.ts';
 export interface Row extends NodeAttrs {
     id: string;

package/dist/schema/lookup.js

@@ -1,4 +1,4 @@
-import { PatternError } from "../common/match.js";
+import { PatternError } from '@zenera/neo';
 import { textOf } from "./entities.js";
 import { methodId } from "./graph.js";
 /** A scan is bounded, because a pattern may have come from a model. */

package/dist/schema/tools.js

@@ -1,5 +1,4 @@
-import { tool } from '@zenera/neo';
-import { loose, matcher, PatternError } from "../common/match.js";
+import { loose, matcher, PatternError, tool } from '@zenera/neo';
 import { toTypeScript } from "./hydrate.js";
 import { fields, grepNodes, listNodes, propertyCount } from "./lookup.js";
 import { FORMATS, isFormat, present } from "./present.js";

package/dist/schema/trace.d.ts

@@ -1,4 +1,4 @@
-import type { Matcher } from '../common/match.ts';
+import type { Matcher } from '@zenera/neo';
 import type { ApiGraph, NodeAttrs, NodeKind } from './graph.ts';
 export type Side = 'input' | 'output' | 'both';
 export interface Route {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/rag",
-    "version": "1.1.24",
+    "version": "1.1.25",
     "description": "Retrieval over a corpus: openapi/swagger documents as a searchable graph, markdown and text as searchable passages.",
     "keywords": [
         "agents",
@@ -61,8 +61,8 @@
     "dependencies": {
         "@apidevtools/swagger-parser": "^12.0.0",
         "@lancedb/lancedb": "^0.38.0",
-        "@zenera/cli": "^1.1.24",
-        "@zenera/neo": "^1.1.24",
+        "@zenera/cli": "^1.1.25",
+        "@zenera/neo": "^1.1.25",
         "graphology": "^0.26.0",
         "remark-frontmatter": "^5.0.0",
         "remark-gfm": "^4.0.1",

package/dist/common/match.d.ts

@@ -1,40 +0,0 @@
-/** 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.
- *
- * `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. */
-export declare function anyOf(matchers: readonly Matcher[]): Matcher | undefined;
-//# sourceMappingURL=match.d.ts.map

package/dist/common/match.js

@@ -1,92 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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.
- *
- * `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. */
-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