autonomous-sdlc-harness 0.1.0 → 0.2.0

package/dist/retrieval/chunk.js

@@ -0,0 +1,158 @@
+/**
+ * Splitting one Markdown document into the chunks docs retrieval embeds, indexes and cites.
+ *
+ * **The rule this module exists to enforce: a chunk's identity is its path and heading anchor, and
+ * its change signal is the hash of its text.** A refresh compares keys and hashes against the stored
+ * index and re-embeds only the chunks whose hash moved, so a key that shifted with an unrelated edit,
+ * or a hash over anything but the embedded text, would turn every refresh into a full rebuild or miss
+ * a change.
+ *
+ * A chunk starts at every `## ` or `### ` line outside a fenced code block, with two exceptions that
+ * exist to keep near-empty rows out of a fixed per-arm candidate budget: a `##` section with no body
+ * of its own that has at least one `###` child is folded into those children, and content before the
+ * first heading becomes the preamble chunk only when something but the title line is in it. A `###`
+ * section is otherwise its own chunk and is never folded into its parent `##`.
+ */
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+const ATX_HEADING = /^(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+/**
+ * GitHub's heading slug, as the `#anchor` in a `path#heading` citation an agent then opens — so it
+ * has to land on the heading GitHub renders, not merely be unique.
+ *
+ * Lower-cases the text, drops every character that is not a letter, a digit, a space, a hyphen or an
+ * underscore (backticks included), and turns each space into `-`. `seen` holds the slugs already
+ * issued in this file: a repeat gets `-1`, `-2`, … in order, skipping any suffixed form a literal
+ * heading already took, so every slug in one file is distinct.
+ */
+function headingSlug(text, seen) {
+    const base = text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N} _-]/gu, '')
+        .replace(/ /g, '-');
+    let slug = base;
+    if (seen.has(base)) {
+        let n = seen.get(base) ?? 0;
+        do {
+            n += 1;
+            slug = `${base}-${n}`;
+        } while (seen.has(slug));
+        seen.set(base, n);
+    }
+    seen.set(slug, 0);
+    return slug;
+}
+/** Trims blank lines from both ends and joins the rest. */
+function joinBody(lines) {
+    const isBlank = (line) => line.trim() === '';
+    const start = lines.findIndex((line) => !isBlank(line));
+    if (start === -1)
+        return '';
+    let end = lines.length;
+    while (isBlank(lines[end - 1] ?? ''))
+        end -= 1;
+    return lines.slice(start, end).join('\n');
+}
+/** `anchor` is `undefined` for the preamble alone: a heading whose slug is empty still keys as `path#`. */
+function makeChunk(path, anchor, heading, headingPath, title, body) {
+    const text = `${title}\n${headingPath}\n\n${body}`;
+    return {
+        key: anchor === undefined ? path : `${path}#${anchor}`,
+        path,
+        anchor: anchor ?? '',
+        heading,
+        text,
+        body,
+        hash: createHash('sha256').update(text).digest('hex'),
+    };
+}
+/**
+ * Splits `markdown`, read from the repo-relative `path`, into its chunks in document order.
+ *
+ * Every ATX heading outside a fence, at any level, consumes a slug, because GitHub numbers repeats
+ * across all levels; `##` and `###` start a chunk, except for the bodiless `##` wrapper the emission
+ * loop below folds into its `###` children. The title is the first `# ` line outside a fence, falling
+ * back to the file's basename.
+ */
+export function chunkMarkdown(path, markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const seen = new Map();
+    let current = { level: 0, heading: '', anchor: '', lines: [] };
+    const sections = [current];
+    let title;
+    let titleLineInPreamble = -1;
+    let fence;
+    for (const line of lines) {
+        if (fence !== undefined) {
+            const trimmed = line.trim();
+            if (trimmed.length >= fence.length && trimmed === fence.char.repeat(trimmed.length))
+                fence = undefined;
+            current.lines.push(line);
+            continue;
+        }
+        const open = FENCE_OPEN.exec(line);
+        if (open !== null) {
+            const marker = open[1] ?? '';
+            // A backtick fence's info string may not contain a backtick; such a line is not a fence.
+            if (!(marker.startsWith('`') && line.slice(line.indexOf(marker) + marker.length).includes('`'))) {
+                fence = { char: marker.charAt(0), length: marker.length };
+            }
+            current.lines.push(line);
+            continue;
+        }
+        const heading = ATX_HEADING.exec(line);
+        if (heading === null) {
+            current.lines.push(line);
+            continue;
+        }
+        const level = heading[1]?.length ?? 0;
+        const text = heading[2] ?? '';
+        const anchor = headingSlug(text, seen);
+        if (level === 2 || level === 3) {
+            current = { level, heading: text, anchor, lines: [] };
+            sections.push(current);
+            continue;
+        }
+        if (level === 1 && title === undefined) {
+            title = text;
+            if (sections.length === 1)
+                titleLineInPreamble = current.lines.length;
+        }
+        current.lines.push(line);
+    }
+    const resolvedTitle = title ?? posix.basename(path);
+    const chunks = [];
+    let parent;
+    for (const [index, section] of sections.entries()) {
+        if (section.level === 0) {
+            const own = section.lines.filter((_, index) => index !== titleLineInPreamble);
+            const body = joinBody(own);
+            if (body !== '')
+                chunks.push(makeChunk(path, undefined, '', resolvedTitle, resolvedTitle, body));
+            continue;
+        }
+        const body = joinBody(section.lines);
+        let headingPath;
+        if (section.level === 2) {
+            parent = `## ${section.heading}`;
+            headingPath = `${resolvedTitle} > ${parent}`;
+            // A `##` used only to group its `###` children carries no text of its own, so its row would be
+            // a near-duplicate of every other wrapper in the corpus while competing for the same fixed
+            // per-arm candidate budget. Folding it loses nothing: `headingPath` below spells the parent
+            // into each child, so the wrapper's words stay searchable through them.
+            //
+            // Decision, for the remaining case — an empty `##` or `###` with no child at all: it is still
+            // emitted. Unlike the wrapper, its words survive nowhere else in the index, so dropping it
+            // would make that heading unfindable; the fold above removes a duplicate, not merely a short row.
+            if (body === '' && sections[index + 1]?.level === 3)
+                continue;
+        }
+        else {
+            headingPath = parent === undefined ? `${resolvedTitle} > ### ${section.heading}` : `${resolvedTitle} > ${parent} > ### ${section.heading}`;
+        }
+        chunks.push(makeChunk(path, section.anchor, section.heading, headingPath, resolvedTitle, body));
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunk.js.map

package/dist/retrieval/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/corpus.js

@@ -0,0 +1,75 @@
+/**
+ * Enumerating the files docs retrieval indexes.
+ *
+ * **The rule this module exists to enforce: the corpus is exactly every Markdown file under
+ * `docs.root` plus every conventions document `layers[]` names — nothing else, and no copy of that
+ * list elsewhere.** The gate (`retrievalApplies` in `cli/src/config/model.ts`) is its callers' to
+ * check, not this module's.
+ *
+ * Nothing here throws on a missing path: the corpus is navigation, so an absent `docs.root`, a missing
+ * conventions document or a path resolving outside the repository becomes a warning line and the
+ * rest of the corpus is still returned.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { insideRepo } from '../core/paths.js';
+import { normalizeRepoDir } from '../core/repoPaths.js';
+function toRepoRelative(repoRoot, absolute) {
+    return relative(repoRoot, absolute).split(sep).join('/');
+}
+/** Every `*.md` under `dir`, recursively; a symlinked directory is not descended into. */
+function markdownUnder(dir, out) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            markdownUnder(full, out);
+            continue;
+        }
+        if (!entry.name.endsWith('.md'))
+            continue;
+        if (entry.isFile() || (entry.isSymbolicLink() && statSync(full, { throwIfNoEntry: false })?.isFile() === true)) {
+            out.push(full);
+        }
+    }
+}
+/** The corpus of `config` in the repository at `repoRoot`. Callers check `retrievalApplies` first. */
+export function corpusFiles(repoRoot, config) {
+    const absolute = [];
+    const warnings = [];
+    const root = config.docs?.root;
+    if (root === undefined) {
+        warnings.push('docs.root is not set, so no documentation directory is indexed');
+    }
+    else {
+        const dir = normalizeRepoDir(root);
+        const full = join(repoRoot, dir);
+        if (!insideRepo(repoRoot, full)) {
+            warnings.push(`docs.root ${dir} resolves outside the repository and was skipped`);
+        }
+        else if (statSync(full, { throwIfNoEntry: false })?.isDirectory() !== true) {
+            warnings.push(`docs.root ${dir} is not a directory, so no documentation directory is indexed`);
+        }
+        else {
+            markdownUnder(full, absolute);
+        }
+    }
+    for (const layer of config.layers ?? []) {
+        const conventions = layer.conventions;
+        if (typeof conventions !== 'string' || conventions === '')
+            continue;
+        const path = normalizeRepoDir(conventions);
+        const full = join(repoRoot, path);
+        if (!insideRepo(repoRoot, full)) {
+            warnings.push(`conventions document ${path} of layer ${layer.name} resolves outside the repository and was skipped`);
+        }
+        else if (statSync(full, { throwIfNoEntry: false })?.isFile() !== true) {
+            warnings.push(`conventions document ${path} of layer ${layer.name} is missing and was skipped`);
+        }
+        else {
+            absolute.push(full);
+        }
+    }
+    const files = [...new Set(absolute.map((path) => toRepoRelative(repoRoot, path)))].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    return { files, warnings };
+}
+//# sourceMappingURL=corpus.js.map

package/dist/retrieval/corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../src/retrieval/corpus.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/models.js

@@ -0,0 +1,175 @@
+/**
+ * The embedder and the reranker docs retrieval runs on: the two interfaces every consumer takes, the
+ * local Transformers.js models behind them, the files an offline load needs, and the deterministic
+ * stubs.
+ *
+ * **The rule this module exists to enforce: a model is downloaded only by `fetchModels`, at setup
+ * time. Every other load runs with remote models disabled, so a run never reaches the network.**
+ * `env.allowRemoteModels` is set in {@link loadModels} alone, from its caller's option, before any
+ * `from_pretrained`; `@huggingface/transformers` is reached only through `loadRetrievalModule`
+ * (`cli/src/retrieval/runtime.ts`), and this file takes its types with `import type`.
+ *
+ * **Why the stubs exist.** The suite drives the compiled CLI in a subprocess and has no mocking
+ * framework (`.claude/context/conventions.md` → `## The testing bar`), so a test cannot substitute a
+ * model in process. {@link RETRIEVAL_STUB_ENV} is the seam: set in the child's environment, it swaps
+ * both halves for hash-based stand-ins that never download or load a model.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError } from '../core/errors.js';
+import { loadRetrievalModule, retrievalModelCacheDir } from './runtime.js';
+/**
+ * ONNX port of `BAAI/bge-small-en-v1.5`, MIT; about 33M parameters, per the upstream model card.
+ * Loaded with `dtype: 'q8'`, CLS pooling and `normalize: true`, yielding {@link EMBEDDING_DIMENSIONS}
+ * dimensions.
+ */
+export const EMBEDDING_MODEL = 'Xenova/bge-small-en-v1.5';
+/** bge-v1.5's retrieval instruction, prepended to queries only. */
+const EMBEDDING_QUERY_PREFIX = 'Represent this sentence for searching relevant passages: ';
+/**
+ * ONNX port of `cross-encoder/ms-marco-MiniLM-L-6-v2`, Apache-2.0; about 23M parameters, per the
+ * upstream model card. Loaded with `dtype: 'q8'`; each score is the sigmoid of its single logit.
+ */
+export const RERANK_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
+/** Bumped by hand when any loading parameter above changes, so the embedder's `id` changes with it. */
+const MODEL_VERSION = 1;
+/** The vector width of {@link EMBEDDING_MODEL}, which the stub embedder matches. */
+const EMBEDDING_DIMENSIONS = 384;
+const MODEL_DTYPE = 'q8';
+const TRANSFORMERS_SPECIFIER = '@huggingface/transformers';
+/**
+ * The files, relative to `<retrievalModelCacheDir()>/<model id>/`, an offline load of each model
+ * needs. Read off `@huggingface/transformers` 4.3.0: `utils/hub.js` → `buildResourcePaths` keys a
+ * `FileCache` entry at `<model id>/<filename>` on the `main` revision, and `FileCache.match` joins that
+ * onto `env.cacheDir`; `utils/model_registry/get_model_files.js` → `get_model_files` lists
+ * `config.json` plus `onnx/<session><dtype suffix>.onnx` (`q8` → `_quantized`, `utils/dtypes.js`),
+ * with no external-data chunk for these configs; `get_tokenizer_files` lists `tokenizer.json` and
+ * `tokenizer_config.json`.
+ */
+export const MODEL_FILES = {
+    [EMBEDDING_MODEL]: ['config.json', 'tokenizer.json', 'tokenizer_config.json', 'onnx/model_quantized.onnx'],
+    [RERANK_MODEL]: ['config.json', 'tokenizer.json', 'tokenizer_config.json', 'onnx/model_quantized.onnx'],
+};
+/** File existence only: every {@link MODEL_FILES} entry under `cacheDir`, `missing` as `<model id>/<file>`. */
+export function modelFilesPresent(cacheDir) {
+    const missing = [];
+    for (const [modelId, files] of Object.entries(MODEL_FILES)) {
+        for (const file of files) {
+            if (!existsSync(join(cacheDir, modelId, file)))
+                missing.push(`${modelId}/${file}`);
+        }
+    }
+    return { present: missing.length === 0, missing };
+}
+/** The real models. Remote loading follows `options.allowRemote`, set before anything is loaded. */
+async function loadModels(options) {
+    const transformers = await loadRetrievalModule(TRANSFORMERS_SPECIFIER);
+    const { env } = transformers;
+    env.cacheDir = retrievalModelCacheDir();
+    env.allowRemoteModels = options.allowRemote;
+    const extractor = await transformers.pipeline('feature-extraction', EMBEDDING_MODEL, { dtype: MODEL_DTYPE });
+    const embed = async (texts) => {
+        const output = (await extractor(texts, { pooling: 'cls', normalize: true }));
+        return output.tolist();
+    };
+    const embedder = {
+        id: `${EMBEDDING_MODEL}:${MODEL_DTYPE}:cls:${EMBEDDING_DIMENSIONS}:v${MODEL_VERSION}`,
+        dimensions: EMBEDDING_DIMENSIONS,
+        async embedDocuments(texts) {
+            return texts.length === 0 ? [] : embed([...texts]);
+        },
+        async embedQuery(text) {
+            const [vector] = await embed([`${EMBEDDING_QUERY_PREFIX}${text}`]);
+            return vector ?? [];
+        },
+    };
+    const tokenizer = await transformers.AutoTokenizer.from_pretrained(RERANK_MODEL);
+    const model = await transformers.AutoModelForSequenceClassification.from_pretrained(RERANK_MODEL, {
+        dtype: MODEL_DTYPE,
+    });
+    const reranker = {
+        id: `${RERANK_MODEL}:${MODEL_DTYPE}:sigmoid:v${MODEL_VERSION}`,
+        async score(query, passages) {
+            if (passages.length === 0)
+                return [];
+            const inputs = tokenizer(passages.map(() => query), { text_pair: [...passages], padding: true, truncation: true });
+            const { logits } = (await model(inputs));
+            return logits.sigmoid().tolist().map((row) => row[0] ?? 0);
+        },
+    };
+    return { embedder, reranker };
+}
+/** The one place a download is allowed: load both models with remote loading on, and run each once. */
+export async function fetchModels() {
+    const { embedder, reranker } = await loadModels({ allowRemote: true });
+    await embedder.embedQuery('warm up');
+    await reranker.score('warm up', ['warm up']);
+}
+/** The environment variable that selects the stubs; this constant is its only spelling in `cli/src`. */
+export const RETRIEVAL_STUB_ENV = 'AUTONOMOUS_SDLC_HARNESS_RETRIEVAL_STUB';
+/** {@link RETRIEVAL_STUB_ENV}'s value, unset read as empty; the only read of the variable in `cli/src`. */
+function stubEnvValue() {
+    return process.env[RETRIEVAL_STUB_ENV] ?? '';
+}
+/** True when {@link RETRIEVAL_STUB_ENV} is set to a non-empty value — the one reading of "a stub run". */
+export function stubModelsSelected() {
+    return stubEnvValue() !== '';
+}
+const STUB_VERSIONS = ['hash-v1', 'hash-v2'];
+/** Lower-cased alphanumeric runs of at least `minLength` characters. */
+function stubTokens(text, minLength) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length >= minLength);
+}
+function stubEmbedder(version) {
+    const salt = version === 'hash-v2' ? 'v2' : '';
+    const embed = (text) => {
+        const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
+        for (const token of stubTokens(text, 2)) {
+            const bucket = createHash('sha256').update(salt).update(token).digest().readUInt32BE(0) % EMBEDDING_DIMENSIONS;
+            vector[bucket] = (vector[bucket] ?? 0) + 1;
+        }
+        const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+        return norm === 0 ? vector : vector.map((value) => value / norm);
+    };
+    return {
+        id: `stub-hash:${version}`,
+        dimensions: EMBEDDING_DIMENSIONS,
+        async embedDocuments(texts) {
+            return texts.map(embed);
+        },
+        async embedQuery(text) {
+            return embed(text);
+        },
+    };
+}
+const STUB_RERANKER = {
+    id: 'stub-overlap',
+    async score(query, passages) {
+        const queryTokens = [...new Set(stubTokens(query, 3))];
+        return passages.map((passage) => {
+            if (queryTokens.length === 0)
+                return 0;
+            const passageTokens = new Set(stubTokens(passage, 2));
+            return queryTokens.filter((token) => passageTokens.has(token)).length / queryTokens.length;
+        });
+    },
+};
+/**
+ * The stubs when {@link RETRIEVAL_STUB_ENV} names one of {@link STUB_VERSIONS}, a refusal for any other
+ * non-empty value, and otherwise {@link loadModels}.
+ */
+export async function resolveModels(options) {
+    if (!stubModelsSelected())
+        return loadModels(options);
+    const value = stubEnvValue();
+    const version = STUB_VERSIONS.find((candidate) => candidate === value);
+    if (version === undefined) {
+        throw new HarnessError(`${RETRIEVAL_STUB_ENV} is set to ${JSON.stringify(value)}; its legal values are ${STUB_VERSIONS.join(' and ')}, or unset it to load the real models`);
+    }
+    return { embedder: stubEmbedder(version), reranker: STUB_RERANKER };
+}
+//# sourceMappingURL=models.js.map

package/dist/retrieval/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/retrieval/models.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/queryLog.js

@@ -0,0 +1,68 @@
+/**
+ * The `search_docs` query log: the environment variable that turns it on, the shape of one JSONL
+ * record, and the append that writes it.
+ *
+ * **The rule this module exists to enforce: failing to log never fails a call, and nothing here ever
+ * reaches stdout.** {@link logQuery} absorbs its own failure into a `Reporter` warning on stderr and
+ * returns, so `cli/src/retrieval/server.ts` → `answer` has nothing to catch and returns its result
+ * unchanged. Stdout belongs to the MCP transport, where a stray byte is a malformed frame for the
+ * client (`cli/templates/scripts/docs-search-server.sh`, its stdout paragraph).
+ *
+ * **Why the record shape lives here rather than in its one caller.** {@link QueryLogRecord} and
+ * {@link QueryOutcome} are the input contract the `feat_docs_retrieval_eval` branch reads: the feature
+ * ships opt-in and not yet measured against the index-first navigation agents use today, and this file
+ * is what distinguishes a tool no agent reaches for from one agents reach for and get nothing from. A
+ * contract inlined into its first caller has no owner file a later reader can find, so `server.ts`
+ * holds no field list, no outcome spelling and no `fs` call of its own.
+ *
+ * **One key set, always.** Every record carries every key, the outcome included; a field a failed exit
+ * cannot fill is `null` rather than absent, so a consumer never infers the outcome from which other
+ * fields are missing.
+ *
+ * **No locking, deliberately.** `cli/src/retrieval/server.ts` → `serveDocs` serializes calls through
+ * its `queue`, so two appends cannot interleave. Do not add any.
+ *
+ * **No shipped template mirrors {@link RETRIEVAL_LOG_ENV}, and that is deliberate.** The agent runner
+ * starts the server from `.mcp.json` and passes only the MCP SDK's fixed inherited set —
+ * `getDefaultEnvironment()` in `@modelcontextprotocol/sdk/client/stdio.js` is `HOME`, `LOGNAME`,
+ * `PATH`, `SHELL` and `USER` on POSIX — so an exported variable does not reach the child. The route is
+ * an `env` entry the operator adds by hand to the `harness-docs` server in their own `.mcp.json`,
+ * which `init` merges rather than overwrites. `init` must not generate the key: generating it would
+ * make this a surface an adopter who wants nothing has to read. So the spelling lives here and in the
+ * adopter's own hand-edited file only, never under `cli/templates/`, and there is no mirror for this
+ * header to declare under `.claude/context/conventions.md` → `## What accompanies a new unit of each
+ * kind` (row *A persisted machine-state key*).
+ *
+ * The write itself is outside the write engine's monopoly; `cli/src/core/writer.ts`'s header
+ * enumerates it as the third such exception.
+ */
+import { appendFileSync } from 'node:fs';
+/**
+ * The environment variable that turns the log on; this constant is its only spelling in `cli/src`.
+ * Its value is a path to a file: set and non-empty, one JSON line is appended per `search_docs` call;
+ * unset or empty, nothing is opened, nothing is written and no code path changes. It is deliberately
+ * not a `harness.config.json` key — an adopter who does not set it gains no new surface, so there is
+ * nothing for `config`, `doctor` or the config check to grow.
+ */
+export const RETRIEVAL_LOG_ENV = 'AUTONOMOUS_SDLC_HARNESS_RETRIEVAL_LOG';
+/** {@link RETRIEVAL_LOG_ENV}'s value, unset read as empty; the only read of the variable in `cli/src`. */
+function logPath() {
+    return process.env[RETRIEVAL_LOG_ENV] ?? '';
+}
+/**
+ * Append `record` as one JSON line to the file {@link RETRIEVAL_LOG_ENV} names, or do nothing when the
+ * variable is unset or empty. Never throws: an unwritable path, a missing parent directory or a full
+ * disk becomes one `report.warn` and a return.
+ */
+export function logQuery(record, report) {
+    const path = logPath();
+    if (path === '')
+        return;
+    try {
+        appendFileSync(path, `${JSON.stringify(record)}\n`, 'utf8');
+    }
+    catch (error) {
+        report.warn(`${RETRIEVAL_LOG_ENV}: appending to ${path} failed: ${error instanceof Error ? error.message : String(error)}; the query was answered and nothing was logged`);
+    }
+}
+//# sourceMappingURL=queryLog.js.map

package/dist/retrieval/queryLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryLog.js","sourceRoot":"","sources":["../../src/retrieval/queryLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAIzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,uCAAuC,CAAC;AA8BzE,0GAA0G;AAC1G,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAsB,EAAE,MAAgB;IAC/D,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO;IACxB,IAAI,CAAC;QACH,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CACT,GAAG,iBAAiB,kBAAkB,IAAI,YAAY,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAC9J,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/retrieval/refresh.js

@@ -0,0 +1,55 @@
+/**
+ * Bringing the docs-retrieval index in line with the corpus, incrementally.
+ *
+ * **The rule this module exists to enforce: the Markdown is the source of truth and the index is
+ * always rebuildable from it, so nothing stored here is authoritative.** A refresh never keeps a chunk
+ * the corpus no longer has, and an embedder change discards every stored vector rather than mixing
+ * two models' vectors in one index.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chunkMarkdown } from './chunk.js';
+import { corpusFiles } from './corpus.js';
+import { EMBEDDER_META_KEY } from './store.js';
+const EMBED_BATCH_SIZE = 32;
+/**
+ * Refreshes `store` from the corpus of `config`: (1) an embedder id differing from the stored one,
+ * or none stored, clears the index and records the new id; (2) every corpus file is chunked; (3) every
+ * stored key not in that set is deleted; (4) chunks whose key is new or whose hash moved are embedded
+ * in batches of 32 and upserted; (5) the rest count as unchanged.
+ *
+ * Expected cost: a document whose title changed re-embeds every one of its chunks, because the title
+ * is part of each chunk's embedded `text`.
+ */
+export async function refreshIndex(options) {
+    const { repoRoot, config, store, embedder } = options;
+    let rebuilt = false;
+    const storedEmbedder = await store.readMeta(EMBEDDER_META_KEY);
+    if (storedEmbedder !== embedder.id) {
+        await store.clear();
+        await store.writeMeta(EMBEDDER_META_KEY, embedder.id);
+        rebuilt = storedEmbedder !== undefined;
+    }
+    const corpus = corpusFiles(repoRoot, config);
+    const chunks = corpus.files.flatMap((path) => chunkMarkdown(path, readFileSync(join(repoRoot, path), 'utf8')));
+    const stored = await store.listChunkHashes();
+    const current = new Set(chunks.map((chunk) => chunk.key));
+    const gone = [...stored.keys()].filter((key) => !current.has(key));
+    await store.deleteChunks(gone);
+    const changed = chunks.filter((chunk) => stored.get(chunk.key) !== chunk.hash);
+    for (let start = 0; start < changed.length; start += EMBED_BATCH_SIZE) {
+        const batch = changed.slice(start, start + EMBED_BATCH_SIZE);
+        const embeddings = await embedder.embedDocuments(batch.map((chunk) => chunk.text));
+        await store.upsertChunks(batch, embeddings);
+    }
+    return {
+        files: corpus.files.length,
+        chunks: chunks.length,
+        embedded: changed.length,
+        unchanged: chunks.length - changed.length,
+        deleted: gone.length,
+        rebuilt,
+        warnings: corpus.warnings,
+    };
+}
+//# sourceMappingURL=refresh.js.map

package/dist/retrieval/refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.js","sourceRoot":"","sources":["../../src/retrieval/refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,iBAAiB,EAAiB,MAAM,YAAY,CAAC;AAe9D,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAKlC;IACC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAEtD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,cAAc,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAC/D,IAAI,cAAc,KAAK,QAAQ,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,KAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QACtD,OAAO,GAAG,cAAc,KAAK,SAAS,CAAC;IACzC,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAe,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAE3H,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,eAAe,EAAE,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,MAAM,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/E,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,gBAAgB,EAAE,CAAC;QACtE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACnF,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;QAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,OAAO,CAAC,MAAM;QACxB,SAAS,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM;QACzC,OAAO,EAAE,IAAI,CAAC,MAAM;QACpB,OAAO;QACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC"}