@indigoai-us/hq-cli 5.111.2 → 5.113.0

package/dist/lib/search-index/max-doc-bytes.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Document size cap for the local HQ search index.
+ *
+ * WHY THIS EXISTS
+ *
+ * qmd indexes a collection by globbing its mask and reading every match — there
+ * is no size check anywhere on that path (`reindexCollection` in @tobilu/qmd
+ * 2.5.3 goes straight from the glob to `readFileSync`). HQ's project
+ * collections are registered with a `md`/`json` mask, which sweeps in build
+ * artifacts nobody would ever search as prose: browser trace dumps, perf
+ * captures, scraped datasets, lockfiles.
+ *
+ * Embedding is the consumer that makes this expensive. `qmd embed` runs under a
+ * hard 30-minute session cap; once the corpus stops fitting inside that budget
+ * the run aborts and discards its work, so an oversized corpus does not merely
+ * cost CPU — it stops the index ever converging.
+ *
+ * HOW IT WORKS
+ *
+ * qmd has no size option, but it does honour a per-collection `ignore` list of
+ * globs, applied at glob time, so an ignored file is never read, never chunked
+ * and never embedded. That list is not reachable through `qmd collection add`
+ * (there is no flag) and qmd's own YAML writer drops the key — but qmd's READER
+ * passes the parsed YAML collection object straight through to the store, and
+ * `syncConfigToDb` treats external config as authoritative ("External config
+ * always wins"). Writing an `ignore:` key into qmd's `index.yml` is therefore a
+ * durable way to express the cap, and it survives qmd's config resync.
+ *
+ * So: resolve the configured cap, walk each collection the way qmd would, and
+ * rewrite its `ignore` list to the files currently over the cap. The list is
+ * recomputed every run, so a file that shrinks or is deleted stops being
+ * ignored with no manual cleanup.
+ *
+ * OWNERSHIP
+ *
+ * The `ignore` list is shared with whatever an operator hand-wrote into
+ * `index.yml`. We therefore never treat "looks like our output" as proof of
+ * provenance: entries this module INTRODUCED are recorded in
+ * `<hqRoot>/.hq/index-size-ignores.json`, and only entries named in that record
+ * are removed on a later run. Anything else in `ignore` is left untouched.
+ *
+ * "Introduced" is doing real work in that sentence. An operator who already
+ * wrote `big.md` by hand keeps owning it even when our scan independently finds
+ * the same file oversized, so lowering the cap later can never delete their
+ * line. The record is also written BEFORE the config: an entry whose provenance
+ * failed to persist would read as foreign forever, which is to say permanently
+ * un-removable, and skipping the change is the cheaper mistake.
+ */
+import * as fs from "node:fs";
+/**
+ * Default cap: 100 KB. Chosen against a real HQ corpus where the median indexed
+ * document is ~1.2 KB — a 100 KB document is three orders of magnitude off the
+ * median and is, in practice, always generated output rather than prose.
+ */
+export declare const DEFAULT_INDEX_MAX_DOC_BYTES: number;
+/** Where this module records the ignore entries it generated. */
+export declare function sizeIgnoreRecordPath(hqRoot: string): string;
+/**
+ * qmd's config file, resolved the way qmd's own CLI resolves it.
+ *
+ * Mirrors `dist/cli/qmd.js`: with no `--index` flag, a project-local
+ * `.qmd/index.yaml` (then `.qmd/index.yml`), found by walking up from the
+ * directory qmd runs in, overrides the global config entirely. Otherwise the
+ * global ladder applies: `QMD_CONFIG_DIR`, then `XDG_CONFIG_HOME/qmd`, then
+ * `$HOME/.config/qmd`.
+ *
+ * Getting this wrong fails silently in the worst way: we would write a correct
+ * `ignore` list into a file qmd never reads, every test asserting the key would
+ * pass, and nothing would actually be skipped. A `$HOME`-only version of this
+ * function shipped to CI and did exactly that, because GitHub runners set
+ * `XDG_CONFIG_HOME` — the e2e positive control is what caught it.
+ *
+ * Returns undefined when no rung resolves, which callers treat as "no config to
+ * update" rather than inventing a path.
+ */
+export declare function resolveQmdConfigPath(opts: {
+    env: NodeJS.ProcessEnv;
+    /** Directory qmd will run in; hq-cli always invokes it with cwd = hqRoot. */
+    startDir?: string;
+    existsFile?: (p: string) => boolean;
+}): string | undefined;
+/**
+ * Resolve the per-document size cap in bytes. Precedence, first match wins:
+ *
+ *   1. `HQ_INDEX_MAX_DOC_BYTES` env var (integer bytes),
+ *   2. `<hqRoot>/.hq/config.json` → `indexMaxDocBytes` (integer bytes),
+ *   3. `DEFAULT_INDEX_MAX_DOC_BYTES` (100 KB).
+ *
+ * `0` disables the cap — and is honoured rather than ignored, so turning the
+ * setting off also clears any ignore entries a previous run wrote.
+ *
+ * A negative, non-integer or otherwise unparseable override falls through to
+ * the next source rather than throwing: this is operator-facing config and a
+ * typo must not break an index run.
+ */
+export declare function resolveIndexMaxDocBytes(opts?: {
+    hqRoot?: string;
+    /** Test seam — defaults to `process.env.HQ_INDEX_MAX_DOC_BYTES`. */
+    envValue?: string | undefined;
+    readFile?: (p: string) => string;
+    existsFile?: (p: string) => boolean;
+}): number;
+/**
+ * Extensions a qmd mask selects, lowercased and without the dot.
+ *
+ * HQ registers exactly two mask shapes today (see `deriveCollections`), but an
+ * operator's own collection may carry anything. An unrecognised mask returns
+ * `null`, meaning "match every file" — the cap then applies to the whole
+ * collection, which is the safe direction: we may ignore a file qmd would not
+ * have indexed (a no-op) rather than miss one it would.
+ */
+export declare function maskExtensions(mask: string): Set<string> | null;
+/** Injected filesystem seam, so the walk is testable without a real tree. */
+export type OversizedScanIo = {
+    readdirSync: (directory: string) => fs.Dirent[];
+    statSync: (file: string) => {
+        size: number;
+    };
+};
+/**
+ * Escape a relative path so qmd's glob matcher treats it as a literal filename.
+ *
+ * Without this, a file genuinely named `reports/[final].json` becomes a
+ * character class: it fails to ignore itself (so the oversized document is
+ * still indexed) while matching unrelated paths like `reports/f.json` (so a
+ * small document silently disappears from search). Both halves of that are
+ * worse than not having the cap.
+ */
+export declare function escapeGlobLiteral(relativePath: string): string;
+/** Outcome of walking one collection for oversized files. */
+export type OversizedScan = {
+    /** Escaped, sorted glob literals for files over the cap. */
+    oversized: string[];
+    /**
+     * Escaped literals for every file the walk POSITIVELY evaluated, over the cap
+     * or under it. An owned ignore entry missing from this set was not observed,
+     * which is only proof the file is gone when `complete` is true.
+     */
+    evaluated: Set<string>;
+    /** False when any directory or file could not be read, so the walk has gaps. */
+    complete: boolean;
+};
+/**
+ * Walk `collectionPath` for files the mask selects whose size exceeds `maxBytes`.
+ *
+ * Mirrors qmd's own walk: excluded directories are skipped, dot-prefixed files
+ * and directories are skipped at every level, and symlinks are never followed.
+ *
+ * `prunePrefixes` carries directory prefixes already excluded by the
+ * collection's own ignore globs. Descending into them would burn exactly the
+ * CPU this cap exists to save, and qmd is not going to read them anyway.
+ *
+ * A failure to read a directory or stat a file sets `complete = false` rather
+ * than being silently treated as "not oversized". The difference matters: an
+ * unreadable file that is still on disk must keep its existing ignore entry,
+ * because dropping it would let the next update read the very document the cap
+ * was protecting against.
+ */
+export declare function findOversizedFiles(collectionPath: string, mask: string, maxBytes: number, io?: OversizedScanIo, prunePrefixes?: readonly string[]): OversizedScan;
+/**
+ * Directory prefixes an operator's own ignore globs already exclude.
+ *
+ * Only the `dir/**` and `dir/**\/*` shapes are recognised. Any other glob stays
+ * unpruned, which costs a walk we did not need but never changes the result —
+ * the conservative direction for a heuristic whose only job is saving work.
+ */
+export declare function prunablePrefixes(patterns: readonly string[]): string[];
+/** What a single collection ended up ignoring on account of the size cap. */
+export type CappedCollection = {
+    name: string;
+    ignored: string[];
+};
+export type IndexSizeLimitResult = {
+    /** The cap that was applied. `0` means the cap is disabled. */
+    maxBytes: number;
+    /** qmd's config file, or undefined when there was none to update. */
+    configPath?: string;
+    /** Per-collection oversized files, only for collections that have any. */
+    collections: CappedCollection[];
+    /** True when qmd's config was actually rewritten. */
+    changed: boolean;
+};
+export type ApplyIndexSizeLimitOptions = {
+    /** Test seam — defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    maxBytes?: number;
+    scanIo?: OversizedScanIo;
+    readFile?: (p: string) => string;
+    writeFile?: (p: string, contents: string) => void;
+    existsFile?: (p: string) => boolean;
+    mkdir?: (p: string) => void;
+};
+/**
+ * Apply the size cap to every collection in qmd's config.
+ *
+ * Runs BEFORE `qmd update`, so the update that follows never reads an oversized
+ * file. Rewrites the config only when the resulting ignore lists differ from
+ * what is already on disk, so a steady-state HQ does no config churn.
+ *
+ * ## Concurrency
+ *
+ * qmd's config is shared with `qmd collection add` and with any other HQ
+ * process running an index pass. A naive read, long scan, then full-file dump
+ * would erase a collection registered while the scan was running.
+ *
+ * The order here is read, scan, RE-READ, then write. That re-read is the part
+ * that matters: the scan is slow (it walks every collection), so the config can
+ * easily move while it runs, and comparing the fresh bytes against the ones the
+ * merge was computed from catches exactly that. On a mismatch the whole merge is
+ * recomputed against the newer config, up to {@link CONFIG_WRITE_ATTEMPTS}
+ * times, after which we decline to write rather than guess. The write itself is
+ * a temp-file rename, so no reader ever sees a half-written config.
+ *
+ * This narrows the window to the microseconds between the re-read and the
+ * rename; it is not a mutex. A writer that lands inside that gap still loses.
+ * A lockfile would not close it either, because qmd's own writers would not
+ * take the lock, so the residual race is documented rather than papered over.
+ */
+export declare function applyIndexSizeLimit(hqRoot: string, options?: ApplyIndexSizeLimitOptions): IndexSizeLimitResult;
+//# sourceMappingURL=max-doc-bytes.d.ts.map

package/dist/lib/search-index/max-doc-bytes.js

@@ -0,0 +1,463 @@
+/**
+ * Document size cap for the local HQ search index.
+ *
+ * WHY THIS EXISTS
+ *
+ * qmd indexes a collection by globbing its mask and reading every match — there
+ * is no size check anywhere on that path (`reindexCollection` in @tobilu/qmd
+ * 2.5.3 goes straight from the glob to `readFileSync`). HQ's project
+ * collections are registered with a `md`/`json` mask, which sweeps in build
+ * artifacts nobody would ever search as prose: browser trace dumps, perf
+ * captures, scraped datasets, lockfiles.
+ *
+ * Embedding is the consumer that makes this expensive. `qmd embed` runs under a
+ * hard 30-minute session cap; once the corpus stops fitting inside that budget
+ * the run aborts and discards its work, so an oversized corpus does not merely
+ * cost CPU — it stops the index ever converging.
+ *
+ * HOW IT WORKS
+ *
+ * qmd has no size option, but it does honour a per-collection `ignore` list of
+ * globs, applied at glob time, so an ignored file is never read, never chunked
+ * and never embedded. That list is not reachable through `qmd collection add`
+ * (there is no flag) and qmd's own YAML writer drops the key — but qmd's READER
+ * passes the parsed YAML collection object straight through to the store, and
+ * `syncConfigToDb` treats external config as authoritative ("External config
+ * always wins"). Writing an `ignore:` key into qmd's `index.yml` is therefore a
+ * durable way to express the cap, and it survives qmd's config resync.
+ *
+ * So: resolve the configured cap, walk each collection the way qmd would, and
+ * rewrite its `ignore` list to the files currently over the cap. The list is
+ * recomputed every run, so a file that shrinks or is deleted stops being
+ * ignored with no manual cleanup.
+ *
+ * OWNERSHIP
+ *
+ * The `ignore` list is shared with whatever an operator hand-wrote into
+ * `index.yml`. We therefore never treat "looks like our output" as proof of
+ * provenance: entries this module INTRODUCED are recorded in
+ * `<hqRoot>/.hq/index-size-ignores.json`, and only entries named in that record
+ * are removed on a later run. Anything else in `ignore` is left untouched.
+ *
+ * "Introduced" is doing real work in that sentence. An operator who already
+ * wrote `big.md` by hand keeps owning it even when our scan independently finds
+ * the same file oversized, so lowering the cap later can never delete their
+ * line. The record is also written BEFORE the config: an entry whose provenance
+ * failed to persist would read as foreign forever, which is to say permanently
+ * un-removable, and skipping the change is the cheaper mistake.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import YAML from "js-yaml";
+/**
+ * Default cap: 100 KB. Chosen against a real HQ corpus where the median indexed
+ * document is ~1.2 KB — a 100 KB document is three orders of magnitude off the
+ * median and is, in practice, always generated output rather than prose.
+ */
+export const DEFAULT_INDEX_MAX_DOC_BYTES = 100 * 1024;
+/**
+ * Directories qmd's own reindex never descends into. Mirrored here so our scan
+ * sees exactly the files qmd would index — an ignore entry for a file qmd never
+ * reads is harmless, but it makes the generated list misleading to read.
+ */
+const EXCLUDED_DIRECTORIES = new Set([
+    "node_modules",
+    ".git",
+    ".cache",
+    "vendor",
+    "dist",
+    "build",
+]);
+/** Where this module records the ignore entries it generated. */
+export function sizeIgnoreRecordPath(hqRoot) {
+    return path.join(hqRoot, ".hq", "index-size-ignores.json");
+}
+/** qmd's default index name; the config file and store are both named after it. */
+const QMD_INDEX_NAME = "index";
+/**
+ * qmd's config file, resolved the way qmd's own CLI resolves it.
+ *
+ * Mirrors `dist/cli/qmd.js`: with no `--index` flag, a project-local
+ * `.qmd/index.yaml` (then `.qmd/index.yml`), found by walking up from the
+ * directory qmd runs in, overrides the global config entirely. Otherwise the
+ * global ladder applies: `QMD_CONFIG_DIR`, then `XDG_CONFIG_HOME/qmd`, then
+ * `$HOME/.config/qmd`.
+ *
+ * Getting this wrong fails silently in the worst way: we would write a correct
+ * `ignore` list into a file qmd never reads, every test asserting the key would
+ * pass, and nothing would actually be skipped. A `$HOME`-only version of this
+ * function shipped to CI and did exactly that, because GitHub runners set
+ * `XDG_CONFIG_HOME` — the e2e positive control is what caught it.
+ *
+ * Returns undefined when no rung resolves, which callers treat as "no config to
+ * update" rather than inventing a path.
+ */
+export function resolveQmdConfigPath(opts) {
+    const exists = opts.existsFile ?? fs.existsSync;
+    if (opts.startDir) {
+        const local = findLocalQmdConfig(path.resolve(opts.startDir), exists);
+        if (local)
+            return local;
+    }
+    const configDir = opts.env.QMD_CONFIG_DIR?.trim();
+    if (configDir)
+        return path.join(configDir, `${QMD_INDEX_NAME}.yml`);
+    const xdg = opts.env.XDG_CONFIG_HOME?.trim();
+    if (xdg)
+        return path.join(xdg, "qmd", `${QMD_INDEX_NAME}.yml`);
+    const home = opts.env.HOME?.trim();
+    if (home)
+        return path.join(home, ".config", "qmd", `${QMD_INDEX_NAME}.yml`);
+    return undefined;
+}
+/** Nearest `.qmd/index.{yaml,yml}` at or above `startDir`, matching qmd's walk. */
+function findLocalQmdConfig(startDir, exists) {
+    let dir = startDir;
+    for (;;) {
+        for (const name of ["index.yaml", "index.yml"]) {
+            const candidate = path.join(dir, ".qmd", name);
+            if (exists(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Resolve the per-document size cap in bytes. Precedence, first match wins:
+ *
+ *   1. `HQ_INDEX_MAX_DOC_BYTES` env var (integer bytes),
+ *   2. `<hqRoot>/.hq/config.json` → `indexMaxDocBytes` (integer bytes),
+ *   3. `DEFAULT_INDEX_MAX_DOC_BYTES` (100 KB).
+ *
+ * `0` disables the cap — and is honoured rather than ignored, so turning the
+ * setting off also clears any ignore entries a previous run wrote.
+ *
+ * A negative, non-integer or otherwise unparseable override falls through to
+ * the next source rather than throwing: this is operator-facing config and a
+ * typo must not break an index run.
+ */
+export function resolveIndexMaxDocBytes(opts = {}) {
+    const fromEnv = parseNonNegativeInt(opts.envValue !== undefined ? opts.envValue : process.env.HQ_INDEX_MAX_DOC_BYTES);
+    if (fromEnv !== null)
+        return fromEnv;
+    if (opts.hqRoot) {
+        const configPath = path.join(opts.hqRoot, ".hq", "config.json");
+        const exists = opts.existsFile ?? fs.existsSync;
+        const read = opts.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+        if (exists(configPath)) {
+            try {
+                const cfg = JSON.parse(read(configPath));
+                const fromCfg = parseNonNegativeInt(cfg.indexMaxDocBytes);
+                if (fromCfg !== null)
+                    return fromCfg;
+            }
+            catch {
+                // Malformed config → fall through to the default.
+            }
+        }
+    }
+    return DEFAULT_INDEX_MAX_DOC_BYTES;
+}
+/** A finite, non-negative integer parsed from a string/number, else null. */
+function parseNonNegativeInt(value) {
+    if (typeof value === "number") {
+        return Number.isInteger(value) && value >= 0 ? value : null;
+    }
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const n = Number(trimmed);
+    return Number.isSafeInteger(n) ? n : null;
+}
+/**
+ * Extensions a qmd mask selects, lowercased and without the dot.
+ *
+ * HQ registers exactly two mask shapes today (see `deriveCollections`), but an
+ * operator's own collection may carry anything. An unrecognised mask returns
+ * `null`, meaning "match every file" — the cap then applies to the whole
+ * collection, which is the safe direction: we may ignore a file qmd would not
+ * have indexed (a no-op) rather than miss one it would.
+ */
+export function maskExtensions(mask) {
+    const braced = /^\*\*\/\*\.\{([^}]+)\}$/.exec(mask);
+    if (braced) {
+        return new Set(braced[1].split(",").map((ext) => ext.trim().toLowerCase()).filter(Boolean));
+    }
+    const single = /^\*\*\/\*\.([A-Za-z0-9]+)$/.exec(mask);
+    if (single)
+        return new Set([single[1].toLowerCase()]);
+    return null;
+}
+const defaultScanIo = {
+    readdirSync: (directory) => fs.readdirSync(directory, { withFileTypes: true }),
+    statSync: (file) => fs.statSync(file),
+};
+/**
+ * Characters picomatch (via fast-glob, which is what qmd globs with) treats as
+ * pattern syntax rather than literal text. `^` and `$` are deliberately absent:
+ * they are regex syntax, not glob syntax, and escaping them would be a guess.
+ */
+const GLOB_META = /[\\*?[\]{}()!+@|]/g;
+/** Same set, without the `g` flag, so `.test()` carries no `lastIndex` state. */
+const HAS_GLOB_META = /[\\*?[\]{}()!+@|]/;
+/**
+ * Escape a relative path so qmd's glob matcher treats it as a literal filename.
+ *
+ * Without this, a file genuinely named `reports/[final].json` becomes a
+ * character class: it fails to ignore itself (so the oversized document is
+ * still indexed) while matching unrelated paths like `reports/f.json` (so a
+ * small document silently disappears from search). Both halves of that are
+ * worse than not having the cap.
+ */
+export function escapeGlobLiteral(relativePath) {
+    return relativePath.replace(GLOB_META, (character) => `\\${character}`);
+}
+/**
+ * Walk `collectionPath` for files the mask selects whose size exceeds `maxBytes`.
+ *
+ * Mirrors qmd's own walk: excluded directories are skipped, dot-prefixed files
+ * and directories are skipped at every level, and symlinks are never followed.
+ *
+ * `prunePrefixes` carries directory prefixes already excluded by the
+ * collection's own ignore globs. Descending into them would burn exactly the
+ * CPU this cap exists to save, and qmd is not going to read them anyway.
+ *
+ * A failure to read a directory or stat a file sets `complete = false` rather
+ * than being silently treated as "not oversized". The difference matters: an
+ * unreadable file that is still on disk must keep its existing ignore entry,
+ * because dropping it would let the next update read the very document the cap
+ * was protecting against.
+ */
+export function findOversizedFiles(collectionPath, mask, maxBytes, io = defaultScanIo, prunePrefixes = []) {
+    const evaluated = new Set();
+    if (maxBytes <= 0)
+        return { oversized: [], evaluated, complete: true };
+    const extensions = maskExtensions(mask);
+    const pruned = new Set(prunePrefixes);
+    const found = [];
+    let complete = true;
+    const walk = (directory, relative) => {
+        let entries;
+        try {
+            entries = io.readdirSync(directory);
+        }
+        catch {
+            complete = false; // A gap, not an absence.
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIRECTORIES.has(entry.name))
+                    continue;
+                if (pruned.has(childRelative))
+                    continue;
+                walk(path.join(directory, entry.name), childRelative);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (extensions) {
+                const ext = path.extname(entry.name).slice(1).toLowerCase();
+                if (!extensions.has(ext))
+                    continue;
+            }
+            const literal = escapeGlobLiteral(childRelative);
+            try {
+                const { size } = io.statSync(path.join(directory, entry.name));
+                evaluated.add(literal);
+                if (size > maxBytes)
+                    found.push(literal);
+            }
+            catch {
+                complete = false; // Unreadable now; it may still be oversized.
+            }
+        }
+    };
+    walk(collectionPath, "");
+    return {
+        oversized: found.sort((left, right) => left.localeCompare(right)),
+        evaluated,
+        complete,
+    };
+}
+/**
+ * Directory prefixes an operator's own ignore globs already exclude.
+ *
+ * Only the `dir/**` and `dir/**\/*` shapes are recognised. Any other glob stays
+ * unpruned, which costs a walk we did not need but never changes the result —
+ * the conservative direction for a heuristic whose only job is saving work.
+ */
+export function prunablePrefixes(patterns) {
+    const prefixes = [];
+    for (const pattern of patterns) {
+        const match = /^(.+?)\/\*\*(?:\/\*)?$/.exec(pattern);
+        if (match && !HAS_GLOB_META.test(match[1]))
+            prefixes.push(match[1]);
+    }
+    return prefixes;
+}
+/** How many times to re-read and re-merge when the config moves under us. */
+const CONFIG_WRITE_ATTEMPTS = 3;
+/**
+ * Apply the size cap to every collection in qmd's config.
+ *
+ * Runs BEFORE `qmd update`, so the update that follows never reads an oversized
+ * file. Rewrites the config only when the resulting ignore lists differ from
+ * what is already on disk, so a steady-state HQ does no config churn.
+ *
+ * ## Concurrency
+ *
+ * qmd's config is shared with `qmd collection add` and with any other HQ
+ * process running an index pass. A naive read, long scan, then full-file dump
+ * would erase a collection registered while the scan was running.
+ *
+ * The order here is read, scan, RE-READ, then write. That re-read is the part
+ * that matters: the scan is slow (it walks every collection), so the config can
+ * easily move while it runs, and comparing the fresh bytes against the ones the
+ * merge was computed from catches exactly that. On a mismatch the whole merge is
+ * recomputed against the newer config, up to {@link CONFIG_WRITE_ATTEMPTS}
+ * times, after which we decline to write rather than guess. The write itself is
+ * a temp-file rename, so no reader ever sees a half-written config.
+ *
+ * This narrows the window to the microseconds between the re-read and the
+ * rename; it is not a mutex. A writer that lands inside that gap still loses.
+ * A lockfile would not close it either, because qmd's own writers would not
+ * take the lock, so the residual race is documented rather than papered over.
+ */
+export function applyIndexSizeLimit(hqRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const maxBytes = options.maxBytes ?? resolveIndexMaxDocBytes({ hqRoot, envValue: env.HQ_INDEX_MAX_DOC_BYTES });
+    const exists = options.existsFile ?? fs.existsSync;
+    const read = options.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+    const write = options.writeFile ?? atomicWrite;
+    const mkdir = options.mkdir ?? ((p) => fs.mkdirSync(p, { recursive: true }));
+    const configPath = resolveQmdConfigPath({ env, startDir: hqRoot, existsFile: exists });
+    if (!configPath)
+        return { maxBytes, collections: [], changed: false };
+    if (!exists(configPath))
+        return { maxBytes, configPath, collections: [], changed: false };
+    const previouslyOwned = readIgnoreRecord(hqRoot, { exists, read });
+    for (let attempt = 0; attempt < CONFIG_WRITE_ATTEMPTS; attempt++) {
+        let original;
+        let config;
+        try {
+            original = read(configPath);
+            config = YAML.load(original) ?? {};
+        }
+        catch {
+            // A config we cannot parse is a config we must not rewrite.
+            return { maxBytes, configPath, collections: [], changed: false };
+        }
+        const collections = config.collections;
+        if (!collections || typeof collections !== "object") {
+            return { maxBytes, configPath, collections: [], changed: false };
+        }
+        const nowOwned = {};
+        const capped = [];
+        for (const [name, entry] of Object.entries(collections)) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const collectionPath = typeof entry.path === "string" ? entry.path : undefined;
+            if (!collectionPath)
+                continue;
+            const mask = typeof entry.pattern === "string" ? entry.pattern : "**/*.md";
+            const existing = Array.isArray(entry.ignore)
+                ? entry.ignore.filter((value) => typeof value === "string")
+                : [];
+            // Provenance: an entry is ours only if a previous run recorded writing it.
+            const ours = new Set(previouslyOwned[name] ?? []);
+            const foreign = existing.filter((value) => !ours.has(value));
+            const foreignSet = new Set(foreign);
+            const scan = exists(collectionPath)
+                ? findOversizedFiles(collectionPath, mask, maxBytes, options.scanIo, prunablePrefixes(foreign))
+                : { oversized: [], evaluated: new Set(), complete: false };
+            // Keep an owned entry the scan could not positively re-evaluate. Dropping
+            // it on an incomplete walk would silently re-expose an oversized file.
+            const unverified = scan.complete
+                ? []
+                : [...ours].filter((value) => !scan.evaluated.has(value));
+            const mine = [...new Set([...scan.oversized, ...unverified])]
+                // Never claim an entry the operator already had: if we recorded it as
+                // ours, a later shrink would delete their line, not ours.
+                .filter((value) => !foreignSet.has(value))
+                .sort((left, right) => left.localeCompare(right));
+            const merged = [...new Set([...foreign, ...scan.oversized, ...unverified])].sort((left, right) => left.localeCompare(right));
+            if (merged.length > 0)
+                entry.ignore = merged;
+            else
+                delete entry.ignore;
+            if (mine.length > 0)
+                nowOwned[name] = mine;
+            if (scan.oversized.length > 0)
+                capped.push({ name, ignored: scan.oversized });
+        }
+        const updated = YAML.dump(config, { lineWidth: 0 });
+        if (updated === original)
+            return { maxBytes, configPath, collections: capped, changed: false };
+        // Provenance first. A config mutation whose record is lost leaves entries
+        // that look foreign forever, so neither a shrinking file nor `0` can clear
+        // them. Better to skip the mutation than to strand it.
+        if (!writeIgnoreRecord(hqRoot, nowOwned, { mkdir, write })) {
+            return { maxBytes, configPath, collections: capped, changed: false };
+        }
+        // Re-read immediately before writing: if another writer landed since the
+        // read above, recompute against their version rather than erasing it.
+        let current;
+        try {
+            current = read(configPath);
+        }
+        catch {
+            return { maxBytes, configPath, collections: capped, changed: false };
+        }
+        if (current !== original)
+            continue;
+        write(configPath, updated);
+        return { maxBytes, configPath, collections: capped, changed: true };
+    }
+    return { maxBytes, configPath, collections: [], changed: false };
+}
+/** Write via temp file + rename, so a concurrent reader never sees a partial config. */
+function atomicWrite(target, contents) {
+    const temporary = `${target}.hq-${process.pid}.tmp`;
+    fs.writeFileSync(temporary, contents, "utf-8");
+    fs.renameSync(temporary, target);
+}
+function readIgnoreRecord(hqRoot, io) {
+    const recordPath = sizeIgnoreRecordPath(hqRoot);
+    if (!io.exists(recordPath))
+        return {};
+    try {
+        const parsed = JSON.parse(io.read(recordPath));
+        const result = {};
+        for (const [name, value] of Object.entries(parsed)) {
+            if (Array.isArray(value)) {
+                result[name] = value.filter((v) => typeof v === "string");
+            }
+        }
+        return result;
+    }
+    catch {
+        return {}; // A corrupt record means we claim nothing, and clobber nothing.
+    }
+}
+/** True when the record landed; false tells the caller not to mutate the config. */
+function writeIgnoreRecord(hqRoot, owned, io) {
+    const recordPath = sizeIgnoreRecordPath(hqRoot);
+    try {
+        io.mkdir(path.dirname(recordPath));
+        io.write(recordPath, `${JSON.stringify(owned, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=max-doc-bytes.js.map