lmgrep 0.1.18 → 0.2.1

package/dist/application/operations/StatusService.js

@@ -0,0 +1,171 @@
+import { Deadline } from "./Deadline.js";
+/**
+ * Reports what the index holds and whether it actually works.
+ *
+ * The two liveness checks are deliberately shallow and time-boxed: `status`
+ * must stay responsive even when the embedder is wedged, since diagnosing that
+ * is exactly why someone runs it.
+ */
+export class StatusService {
+    chunks;
+    maintenance;
+    embedder;
+    locator;
+    metadata;
+    location;
+    config;
+    cwd;
+    configSources;
+    alternatives;
+    static PROBE_TIMEOUT_MS = 3000;
+    /** A word generic enough to match something in any codebase. */
+    static SMOKE_QUERY = "code";
+    constructor(chunks, maintenance, embedder, locator, metadata, location, config, cwd, configSources, alternatives) {
+        this.chunks = chunks;
+        this.maintenance = maintenance;
+        this.embedder = embedder;
+        this.locator = locator;
+        this.metadata = metadata;
+        this.location = location;
+        this.config = config;
+        this.cwd = cwd;
+        this.configSources = configSources;
+        this.alternatives = alternatives;
+    }
+    async status() {
+        // A manually targeted database is flat — no ancestor or prefix walking.
+        const ancestor = this.location.isGitAware
+            ? this.locator.findIndexedAncestor(this.cwd)
+            : undefined;
+        const projectRoot = this.location.manual
+            ? this.location.root
+            : (ancestor?.root ?? this.cwd);
+        const filesByPath = await this.chunks.hashesByFile();
+        const hashes = await this.chunks.allHashes();
+        let chunkCount = 0;
+        for (const [, list] of filesByPath)
+            chunkCount += list.length;
+        const probe = await this.probe(filesByPath.size > 0);
+        const meta = this.metadata.read(this.location.manual
+            ? this.location.path
+            : this.locator.databasePathFor(projectRoot));
+        const vectorIndex = await this.maintenance.vectorIndexState();
+        const info = {
+            projectRoot,
+            prefix: ancestor?.prefix ?? "",
+            databasePath: this.location.path,
+            config: this.config,
+            configSources: this.configSources,
+            fileCount: filesByPath.size,
+            chunkCount,
+            uniqueHashes: hashes.size,
+            ...probe,
+            vectorIndex,
+            indexModel: meta?.model,
+            indexDimensions: meta?.dimensions,
+        };
+        return { ...info, verdict: this.judge(info) };
+    }
+    /**
+     * Reduce the probes to one answer, in the order a user would care.
+     *
+     * A missing vector index is a note rather than a failure: search works, it
+     * is just answering by reading every embedding, which nothing else would
+     * tell you.
+     */
+    judge(info) {
+        if (info.fileCount === 0) {
+            // An empty database for the configured model usually means the
+            // model changed, not that the project was never indexed.
+            const absence = this.alternatives.explainAbsence();
+            return absence
+                ? { searchable: false, reason: absence.reason, fix: absence.fix }
+                : {
+                    searchable: false,
+                    reason: "This project is not indexed.",
+                    fix: "lmgrep index",
+                };
+        }
+        if (!info.embeddingOk) {
+            return {
+                searchable: false,
+                reason: `The embedding provider is unreachable — ${info.embeddingError ?? "no response"}`,
+                fix: `Start the server at ${this.config.baseURL ?? "your configured baseURL"}, then retry.`,
+            };
+        }
+        if (!info.searchOk) {
+            // Manifests are per branch while chunks are shared by content, so
+            // a checkout that has never been indexed searches an empty scope
+            // over a full database. That is an ordinary state on a new
+            // worktree or branch, and telling someone to `--reset` over it
+            // would throw away a working index for no reason.
+            return info.anyBranchOk
+                ? {
+                    searchable: false,
+                    reason: "This branch has not been indexed yet.",
+                    fix: "lmgrep index",
+                }
+                : {
+                    searchable: false,
+                    reason: "The index holds files but answered a test query with nothing — it is likely stale or was built with a different model.",
+                    fix: "lmgrep index --reset",
+                };
+        }
+        if (!info.vectorIndex.built && info.vectorIndex.worthBuilding) {
+            return {
+                searchable: true,
+                note: `Every search reads all ${info.vectorIndex.rows} embeddings — slow, and roughly the ` +
+                    "index's size in memory per query. `lmgrep index` builds the vector index.",
+            };
+        }
+        return { searchable: true };
+    }
+    /**
+     * Embed once and reuse the vector for the search check — one roundtrip
+     * covers both, which keeps `status` cheap against a billed provider.
+     */
+    async probe(hasFiles) {
+        const deadline = Deadline.after(StatusService.PROBE_TIMEOUT_MS);
+        let vector;
+        let embeddingLatencyMs;
+        try {
+            const started = Date.now();
+            vector = await deadline.enforce(this.embedder.embedQuery(StatusService.SMOKE_QUERY));
+            embeddingLatencyMs = Date.now() - started;
+        }
+        catch (err) {
+            return {
+                embeddingOk: false,
+                searchOk: false,
+                embeddingError: err instanceof Error ? err.message : String(err),
+            };
+        }
+        if (!hasFiles) {
+            return { embeddingOk: true, embeddingLatencyMs, searchOk: false };
+        }
+        try {
+            const started = Date.now();
+            const hits = await deadline.enforce(this.chunks.search({ vector, limit: 1, scopeToBranch: true }));
+            // Only when the scoped query found nothing: the unscoped one is a
+            // second query, and it is worth running solely to tell an
+            // unindexed branch apart from a broken index.
+            const anyBranchOk = hits.length > 0
+                ? true
+                : (await deadline.enforce(this.chunks.search({ vector, limit: 1, scopeToBranch: false }))).length > 0;
+            return {
+                embeddingOk: true,
+                embeddingLatencyMs,
+                searchOk: hits.length > 0,
+                searchResultCount: hits.length,
+                searchLatencyMs: Date.now() - started,
+                anyBranchOk,
+            };
+        }
+        catch {
+            // The embedder works; the index does not answer. That is a
+            // meaningful distinction the caller reports differently.
+            return { embeddingOk: true, embeddingLatencyMs, searchOk: false };
+        }
+    }
+}
+//# sourceMappingURL=StatusService.js.map

package/dist/application/operations/StatusService.js.map

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

package/dist/application/operations/WatchService.d.ts

@@ -0,0 +1,67 @@
+import type { LmgrepConfig } from "../../domain/config/LmgrepConfig.js";
+import type { LockPort } from "../../domain/ports/LockPort.js";
+import type { LoggerPort } from "../../domain/ports/LoggerPort.js";
+import type { WorkspacePort } from "../../domain/ports/WorkspacePort.js";
+import type { IndexBuilder } from "../indexing/IndexBuilder.js";
+/**
+ * Keeps an index current while the process runs.
+ *
+ * Two mechanisms, because neither suffices alone: filesystem events give a
+ * fast path for ordinary edits, and a periodic full reconcile is the backstop
+ * for what recursive `fs.watch` misses on Linux — new subdirectories, editor
+ * atomic saves, event bursts. The reconcile also retries files that failed
+ * while the embedder was down, which is what removes the need to re-run
+ * `lmgrep index` by hand.
+ */
+export declare class WatchService {
+    private readonly builder;
+    private readonly workspace;
+    private readonly config;
+    private readonly cwd;
+    private readonly logger;
+    private readonly locks;
+    /** How often the backstop reconcile runs. */
+    private static readonly RECONCILE_MS;
+    /** Window for coalescing a burst of filesystem events. */
+    private static readonly DEBOUNCE_MS;
+    private indexing;
+    /** Whether anything arrived while a run was in flight. */
+    private queuedWork;
+    /**
+     * Paths queued mid-run, or undefined when the queued work is a full
+     * rebuild. A full rebuild is a superset, so once one is queued no file list
+     * may narrow it back down.
+     */
+    private queuedFiles;
+    private timer;
+    private watcher;
+    private holdsLock;
+    /** The catch-up build is the one allowed to train a vector index. */
+    private caughtUp;
+    constructor(builder: IndexBuilder, workspace: WorkspacePort, config: LmgrepConfig, cwd: string, logger: LoggerPort, locks: LockPort);
+    /**
+     * Begin watching. Returns a function that stops it.
+     *
+     * Acquiring the maintainer lock is what makes exactly one process
+     * responsible for a database; it also registers this process so
+     * `lmgrep status` can report who is watching. Losing the race is normal —
+     * another server already has it — and simply means not watching.
+     */
+    start(): () => void;
+    private beginWatching;
+    stop(): void;
+    /**
+     * Run an index pass, coalescing anything that arrives while one is in
+     * flight. A queued full rebuild wins over queued file lists: it is the
+     * superset, and narrowing it would skip work.
+     */
+    private reindex;
+    /**
+     * Merge incoming work into whatever is already queued.
+     *
+     * The previous implementation used `undefined` both for "nothing queued"
+     * and for "a full rebuild is queued", so a reconcile that landed mid-run
+     * was silently dropped. The two states are now distinct.
+     */
+    private enqueue;
+}

package/dist/application/operations/WatchService.js

@@ -0,0 +1,145 @@
+/**
+ * Keeps an index current while the process runs.
+ *
+ * Two mechanisms, because neither suffices alone: filesystem events give a
+ * fast path for ordinary edits, and a periodic full reconcile is the backstop
+ * for what recursive `fs.watch` misses on Linux — new subdirectories, editor
+ * atomic saves, event bursts. The reconcile also retries files that failed
+ * while the embedder was down, which is what removes the need to re-run
+ * `lmgrep index` by hand.
+ */
+export class WatchService {
+    builder;
+    workspace;
+    config;
+    cwd;
+    logger;
+    locks;
+    /** How often the backstop reconcile runs. */
+    static RECONCILE_MS = 30_000;
+    /** Window for coalescing a burst of filesystem events. */
+    static DEBOUNCE_MS = 2000;
+    indexing = false;
+    /** Whether anything arrived while a run was in flight. */
+    queuedWork = false;
+    /**
+     * Paths queued mid-run, or undefined when the queued work is a full
+     * rebuild. A full rebuild is a superset, so once one is queued no file list
+     * may narrow it back down.
+     */
+    queuedFiles;
+    timer;
+    watcher;
+    holdsLock = false;
+    /** The catch-up build is the one allowed to train a vector index. */
+    caughtUp = false;
+    constructor(builder, workspace, config, cwd, logger, locks) {
+        this.builder = builder;
+        this.workspace = workspace;
+        this.config = config;
+        this.cwd = cwd;
+        this.logger = logger;
+        this.locks = locks;
+    }
+    /**
+     * Begin watching. Returns a function that stops it.
+     *
+     * Acquiring the maintainer lock is what makes exactly one process
+     * responsible for a database; it also registers this process so
+     * `lmgrep status` can report who is watching. Losing the race is normal —
+     * another server already has it — and simply means not watching.
+     */
+    start() {
+        if (!this.locks.acquireMaintainer()) {
+            this.logger.info("Another process is already watching this index.");
+            return () => { };
+        }
+        this.holdsLock = true;
+        return this.beginWatching();
+    }
+    beginWatching() {
+        // Catch up first, so a branch checked out while this was not running
+        // gets its manifest bootstrapped before any event arrives.
+        void this.reindex();
+        this.watcher = this.workspace.watch(this.cwd, this.config.ignore, (changed) => void this.reindex(changed), WatchService.DEBOUNCE_MS, this.config.extensions);
+        this.timer = setInterval(() => void this.reindex(), WatchService.RECONCILE_MS);
+        // Never keep the host process alive on the timer alone.
+        this.timer.unref?.();
+        this.logger.info("Watching for changes...");
+        return () => this.stop();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.watcher?.close();
+        this.watcher = undefined;
+        if (this.holdsLock) {
+            this.locks.releaseMaintainer();
+            this.holdsLock = false;
+        }
+    }
+    /**
+     * Run an index pass, coalescing anything that arrives while one is in
+     * flight. A queued full rebuild wins over queued file lists: it is the
+     * superset, and narrowing it would skip work.
+     */
+    async reindex(changedFiles) {
+        if (this.indexing) {
+            this.enqueue(changedFiles);
+            return;
+        }
+        this.indexing = true;
+        try {
+            this.logger.info(changedFiles?.length
+                ? `Changes detected in ${changedFiles.length} file(s), re-indexing...`
+                : "Changes detected, re-indexing...");
+            // Train the vector index on the catch-up build only.
+            //
+            // Without an index every search brute-force scans the table, which
+            // costs roughly the index's own size in peak memory *per query* —
+            // measured at ~1GB a search against a 759MB index, versus ~200MB
+            // once indexed. Training spikes higher (~2.5GB) but does so once,
+            // so for a process that will serve many queries it is the cheaper
+            // option as well as the faster one. Incremental ticks stay off it
+            // and only absorb the tail.
+            await this.builder.build({
+                files: changedFiles,
+                createIndex: !this.caughtUp,
+            });
+            this.caughtUp = true;
+        }
+        catch (err) {
+            this.logger.error(`Index error: ${err instanceof Error ? err.message : err}`);
+        }
+        finally {
+            this.indexing = false;
+            if (this.queuedWork) {
+                const next = this.queuedFiles;
+                this.queuedWork = false;
+                this.queuedFiles = undefined;
+                void this.reindex(next);
+            }
+        }
+    }
+    /**
+     * Merge incoming work into whatever is already queued.
+     *
+     * The previous implementation used `undefined` both for "nothing queued"
+     * and for "a full rebuild is queued", so a reconcile that landed mid-run
+     * was silently dropped. The two states are now distinct.
+     */
+    enqueue(changedFiles) {
+        if (!changedFiles) {
+            this.queuedWork = true;
+            this.queuedFiles = undefined;
+            return;
+        }
+        // A queued full rebuild already covers these paths.
+        if (this.queuedWork && this.queuedFiles === undefined)
+            return;
+        this.queuedWork = true;
+        this.queuedFiles = [...(this.queuedFiles ?? []), ...changedFiles];
+    }
+}
+//# sourceMappingURL=WatchService.js.map

package/dist/application/operations/WatchService.js.map

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

package/dist/application/operations/WorkingTreeDiff.d.ts

@@ -0,0 +1,19 @@
+import type { FileManifest } from "../../domain/corpus/SourceFile.js";
+import type { WorkspacePort } from "../../domain/ports/WorkspacePort.js";
+/** How the working tree differs from what the manifest recorded. */
+export interface TreeChanges {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+}
+/**
+ * Compares the working tree against the manifest, without changing anything.
+ *
+ * This is what `lmgrep status --changes` reports: a read-only preview of what
+ * the next index run would do, so a user can see whether it is worth running.
+ */
+export declare class WorkingTreeDiff {
+    private readonly workspace;
+    constructor(workspace: WorkspacePort);
+    compute(projectRoot: string, manifest: FileManifest): TreeChanges;
+}

package/dist/application/operations/WorkingTreeDiff.js

@@ -0,0 +1,36 @@
+/**
+ * Compares the working tree against the manifest, without changing anything.
+ *
+ * This is what `lmgrep status --changes` reports: a read-only preview of what
+ * the next index run would do, so a user can see whether it is worth running.
+ */
+export class WorkingTreeDiff {
+    workspace;
+    constructor(workspace) {
+        this.workspace = workspace;
+    }
+    compute(projectRoot, manifest) {
+        const added = [];
+        const modified = [];
+        const deleted = [];
+        const seen = new Set();
+        for (const file of this.workspace.listFiles(projectRoot)) {
+            seen.add(file);
+            const hash = this.workspace.hashOf(projectRoot, file);
+            // Unreadable right now: not a reportable change either way.
+            if (!hash)
+                continue;
+            const stored = manifest.versionOf(file);
+            if (!stored)
+                added.push(file);
+            else if (!stored.equals(hash))
+                modified.push(file);
+        }
+        for (const path of manifest.paths()) {
+            if (!seen.has(path))
+                deleted.push(path);
+        }
+        return { added, modified, deleted };
+    }
+}
+//# sourceMappingURL=WorkingTreeDiff.js.map

package/dist/application/operations/WorkingTreeDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkingTreeDiff.js","sourceRoot":"","sources":["../../../src/application/operations/WorkingTreeDiff.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACE;IAA7B,YAA6B,SAAwB;QAAxB,cAAS,GAAT,SAAS,CAAe;IAAG,CAAC;IAEzD,OAAO,CAAC,WAAmB,EAAE,QAAsB;QAClD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAE/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YACtD,4DAA4D;YAC5D,IAAI,CAAC,IAAI;gBAAE,SAAS;YAEpB,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,CAAC,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;iBACzB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACrC,CAAC;CACD"}

package/dist/application/research/ResearchAgent.d.ts

@@ -0,0 +1,68 @@
+import type { LmgrepConfig } from "../../domain/config/LmgrepConfig.js";
+import type { ChatModelPort } from "../../domain/ports/ChatModelPort.js";
+import { type Source } from "../../domain/research/Citation.js";
+import { type TraceEntry } from "../../domain/research/ResearchTrace.js";
+import type { HitList } from "../../domain/retrieval/HitList.js";
+import { SearchCriteria } from "../search/SearchCriteria.js";
+export interface ResearchResult {
+    question: string;
+    answer: string;
+    /** Sources the answer actually cited, in citation order. */
+    sources: Source[];
+    trace: TraceEntry[];
+    steps: number;
+    elapsedMs: number;
+    /**
+     * True when synthesis was unavailable and the result fell back to raw
+     * search hits, so the caller knows not to over-trust the answer.
+     */
+    degraded: boolean;
+}
+/** How the agent reaches the index. */
+export interface ResearchSearcher {
+    search(query: string, criteria: SearchCriteria): Promise<HitList>;
+}
+/**
+ * Answers a question by searching the codebase and synthesizing a cited answer.
+ *
+ * Robustness is layered, because a local model fails in several distinct ways
+ * and none of them should hard-fail the caller:
+ *
+ *  1. Happy path — the model self-terminates with a cited answer.
+ *  2. It cannot self-terminate (step cap, timeout, or the transcript overflows
+ *     its context) — synthesize from a budgeted digest in a fresh context.
+ *  3. It answered without ever searching — discard that, since it is ungrounded
+ *     by construction, search directly and synthesize.
+ *  4. The model is unreachable — degrade to raw search hits.
+ */
+export declare class ResearchAgent {
+    private readonly searcher;
+    private readonly chat;
+    private readonly config;
+    private static readonly DEFAULT_MAX_STEPS;
+    /**
+     * Wall clock is only a backstop against a wedged run; the search and step
+     * budgets bound the real work. A local model doing a few steps plus a cold
+     * load can need minutes, so this stays generous.
+     */
+    private static readonly DEFAULT_TIMEOUT_MS;
+    private static readonly MAX_SEARCHES;
+    private static readonly DEFAULT_SEARCH_LIMIT;
+    /** The model tends to ask for 10+, which bloats the transcript. */
+    private static readonly MAX_SEARCH_LIMIT;
+    /** After this many searches, nudge it to wrap up. */
+    private static readonly NUDGE_AFTER;
+    constructor(searcher: ResearchSearcher, chat: ChatModelPort, config: LmgrepConfig);
+    research(question: string, onTrace?: (entry: TraceEntry) => void): Promise<ResearchResult>;
+    private runSearch;
+    /**
+     * One-shot synthesis over a budgeted digest, in a fresh context with no
+     * tool transcript to replay — which is what makes it work even when the
+     * agentic loop overflowed the window.
+     */
+    private synthesize;
+    /** Ask the model to insert markers into its own answer, wording unchanged. */
+    private addCitations;
+    /** Last resort: return the raw hits, clearly marked as un-synthesized. */
+    private degrade;
+}