lmgrep 0.1.18 → 0.2.0

package/dist/infrastructure/lancedb/VectorIndexPolicy.js

@@ -0,0 +1,72 @@
+/**
+ * Tuning for the LanceDB vector index. The numbers here were measured on a
+ * 43k-chunk / 3584-dimension index; the comments record what they bought so a
+ * later change can tell a tuned value from an arbitrary one.
+ */
+export const VectorIndexPolicy = {
+    /**
+     * Below this row count a brute-force scan is cheap enough that training an
+     * index costs more than it saves, and IVF-PQ has too few vectors to cluster
+     * well.
+     */
+    MIN_ROWS_FOR_ANN: 5_000,
+    /**
+     * Re-absorb new rows into the index once the unindexed tail passes this
+     * share of the indexed body. Rows outside the index are searched by flat
+     * scan, so the tail is exactly what needs bounding.
+     */
+    UNINDEXED_REINDEX_RATIO: 0.2,
+    /** ...but always tolerate a small tail, so a 3-chunk edit never retrains. */
+    UNINDEXED_REINDEX_FLOOR: 2_000,
+    /**
+     * Vector searches run without an explicit distance type, which LanceDB
+     * resolves to L2. The index has its own default, so it is pinned: an index
+     * built on a different metric would silently reorder every result.
+     */
+    DISTANCE_TYPE: "l2",
+    /**
+     * IVF-PQ stores compressed vectors, so its raw distances approximate the
+     * real ones. `refineFactor` makes LanceDB pull the uncompressed vectors for
+     * the top `limit * factor` candidates and re-score them exactly.
+     *
+     * It is not optional. Measured mean recall@20 against an exact scan:
+     *
+     *   off -> 53%   1 -> 75%   3 -> 86%   10 -> 91%   20 -> 94%   50 -> 94%
+     *
+     * and without it `_distance` is wrong by ~0.07, which matters because score
+     * is derived from it and users filter on `--min-score`. With refinement the
+     * scores match an exact scan to the digit.
+     *
+     * 20 sits at the knee: ~94% recall at ~11ms/query versus ~115ms for an
+     * exact scan. Beyond it recall flattens (the probed partitions run out of
+     * candidates) while latency keeps climbing. The refined set is bounded by
+     * the query limit, not by table size, so this costs a fixed few MB.
+     *
+     * Harmless on tables with no index: a flat scan already computes exact
+     * distances and returns identical rows.
+     */
+    REFINE_FACTOR: 20,
+};
+/**
+ * Columns a search reads off a result row.
+ *
+ * Selecting explicitly keeps the embedding out of the result set — without it
+ * LanceDB ships every over-fetched row's full vector back into JS for nothing.
+ *
+ * `_distance` is listed on purpose: LanceDB currently auto-projects it into any
+ * scoring query but warns that it will stop, so naming it pins the behaviour
+ * rather than relying on a deprecated default.
+ */
+export const SEARCH_COLUMNS = [
+    "id",
+    "filePath",
+    "startLine",
+    "endLine",
+    "type",
+    "name",
+    "content",
+    "context",
+    "fileHash",
+    "_distance",
+];
+//# sourceMappingURL=VectorIndexPolicy.js.map

package/dist/infrastructure/lancedb/VectorIndexPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorIndexPolicy.js","sourceRoot":"","sources":["../../../src/infrastructure/lancedb/VectorIndexPolicy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC;;;;OAIG;IACH,gBAAgB,EAAE,KAAK;IAEvB;;;;OAIG;IACH,uBAAuB,EAAE,GAAG;IAE5B,6EAA6E;IAC7E,uBAAuB,EAAE,KAAK;IAE9B;;;;OAIG;IACH,aAAa,EAAE,IAAI;IAEnB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,aAAa,EAAE,EAAE;CACR,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,IAAI;IACJ,UAAU;IACV,WAAW;IACX,SAAS;IACT,MAAM;IACN,MAAM;IACN,SAAS;IACT,SAAS;IACT,UAAU;IACV,WAAW;CACF,CAAC"}

package/dist/infrastructure/p2p/IndexShare.d.ts

@@ -0,0 +1,45 @@
+import type { IndexMetadata } from "../../domain/project/IndexMetadata.js";
+import type { RowReplication } from "../lancedb/RowReplication.js";
+import { ShareCode } from "./ShareCode.js";
+export interface ShareProgress {
+    onProgress?: (done: number, total: number) => void;
+}
+export interface ReceiveOptions extends ShareProgress {
+    onMeta?: (meta: {
+        model?: string;
+        dimensions?: number;
+        chunkCount: number;
+        remote?: string;
+    }) => void;
+    onWarning?: (message: string) => void;
+}
+export interface ReceiveResult {
+    chunks: number;
+    files: number;
+}
+/**
+ * Sends and receives a whole index between two machines.
+ *
+ * The transfer copies rows verbatim, embeddings included: re-embedding a large
+ * repository is the expensive thing, and avoiding it is the entire reason to
+ * share. That makes model compatibility the receiver's responsibility to check
+ * — vectors from a different model are silently meaningless, so a mismatch is
+ * warned about explicitly.
+ */
+export declare class IndexShare {
+    private readonly rows;
+    private static readonly BATCH_SIZE;
+    private static readonly PEER_TIMEOUT_MS;
+    constructor(rows: RowReplication);
+    /**
+     * Publish the index and return the code a peer needs. `done` resolves once
+     * a peer has taken the whole transfer.
+     */
+    send(metadata: IndexMetadata | undefined, options?: ShareProgress): Promise<{
+        code: string;
+        done: Promise<void>;
+    }>;
+    /** Connect to a sharer and write everything it sends into this database. */
+    receive(code: ShareCode, localMetadata: IndexMetadata | undefined, options?: ReceiveOptions): Promise<ReceiveResult>;
+    private warnOnModelMismatch;
+}

package/dist/infrastructure/p2p/IndexShare.js

@@ -0,0 +1,160 @@
+import { ModelIdentity } from "../../domain/project/ModelIdentity.js";
+import { PeerSwarm } from "./PeerSwarm.js";
+import { SecureChannel, } from "./SecureChannel.js";
+import { ShareCode } from "./ShareCode.js";
+/**
+ * Sends and receives a whole index between two machines.
+ *
+ * The transfer copies rows verbatim, embeddings included: re-embedding a large
+ * repository is the expensive thing, and avoiding it is the entire reason to
+ * share. That makes model compatibility the receiver's responsibility to check
+ * — vectors from a different model are silently meaningless, so a mismatch is
+ * warned about explicitly.
+ */
+export class IndexShare {
+    rows;
+    static BATCH_SIZE = 200;
+    static PEER_TIMEOUT_MS = 5 * 60 * 1000;
+    constructor(rows) {
+        this.rows = rows;
+    }
+    /**
+     * Publish the index and return the code a peer needs. `done` resolves once
+     * a peer has taken the whole transfer.
+     */
+    async send(metadata, options = {}) {
+        const swarm = await PeerSwarm.create();
+        const code = ShareCode.generate();
+        const channel = new SecureChannel(code.toEncryptionKey());
+        const chunkCount = await this.rows.chunkCount();
+        const done = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                void swarm.destroy();
+                reject(new Error("Timed out waiting for peer (5 minutes)."));
+            }, IndexShare.PEER_TIMEOUT_MS);
+            swarm.onConnection(async (socket) => {
+                clearTimeout(timeout);
+                try {
+                    channel.send(socket, {
+                        type: "meta",
+                        model: metadata?.model,
+                        dimensions: metadata?.dimensions,
+                        chunkCount,
+                        branch: metadata?.branch ?? "main",
+                        remote: metadata?.remote,
+                    });
+                    // Wait for the receiver to accept before streaming — it may
+                    // refuse on an incompatible model.
+                    await channel.await(socket, "ready");
+                    let sent = 0;
+                    for await (const batch of this.rows.streamChunkRows(IndexShare.BATCH_SIZE)) {
+                        channel.send(socket, { type: "chunks", batch });
+                        sent += batch.length;
+                        options.onProgress?.(sent, chunkCount);
+                    }
+                    const files = await this.rows.allManifestRows();
+                    if (files.length > 0) {
+                        channel.send(socket, { type: "files", batch: files });
+                    }
+                    channel.send(socket, { type: "done" });
+                    // Wait for the ack so the socket is not torn down before
+                    // the receiver has committed.
+                    await channel.await(socket, "ack");
+                    socket.end();
+                    await swarm.destroy();
+                    resolve();
+                }
+                catch (err) {
+                    await swarm.destroy();
+                    reject(err);
+                }
+            });
+            swarm.join(code.toTopic(), "server").catch(reject);
+        });
+        return { code: code.toString(), done };
+    }
+    /** Connect to a sharer and write everything it sends into this database. */
+    async receive(code, localMetadata, options = {}) {
+        const swarm = await PeerSwarm.create();
+        const channel = new SecureChannel(code.toEncryptionKey());
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                void swarm.destroy();
+                reject(new Error("Timed out waiting for peer (5 minutes)."));
+            }, IndexShare.PEER_TIMEOUT_MS);
+            const fail = (err) => {
+                void swarm.destroy().then(() => reject(err));
+            };
+            swarm.onConnection((socket) => {
+                clearTimeout(timeout);
+                let expected = 0;
+                let chunks = 0;
+                let files = 0;
+                let accepted = false;
+                const handle = (message) => {
+                    switch (message.type) {
+                        case "meta": {
+                            expected = message.chunkCount;
+                            options.onMeta?.({
+                                model: message.model,
+                                dimensions: message.dimensions,
+                                chunkCount: message.chunkCount,
+                                remote: message.remote,
+                            });
+                            this.warnOnModelMismatch(localMetadata, message, options.onWarning);
+                            channel.send(socket, { type: "ready" });
+                            accepted = true;
+                            break;
+                        }
+                        case "chunks": {
+                            // Ignore anything arriving before the handshake.
+                            if (!accepted)
+                                break;
+                            chunks += message.batch.length;
+                            options.onProgress?.(chunks, expected);
+                            this.rows.addChunkRows(message.batch).catch(fail);
+                            break;
+                        }
+                        case "files": {
+                            if (!accepted)
+                                break;
+                            files += message.batch.length;
+                            this.rows.addManifestRows(message.batch).catch(fail);
+                            break;
+                        }
+                        case "done": {
+                            channel.send(socket, { type: "ack" });
+                            void swarm.destroy().then(() => resolve({ chunks, files }));
+                            break;
+                        }
+                    }
+                };
+                const read = channel.reader((message) => {
+                    try {
+                        handle(message);
+                    }
+                    catch (err) {
+                        fail(new Error(`Protocol error: ${err}`));
+                    }
+                });
+                socket.on("data", read);
+                socket.on("error", fail);
+            });
+            swarm.join(code.toTopic(), "client").catch(reject);
+        });
+    }
+    warnOnModelMismatch(local, remote, onWarning) {
+        if (!local?.model || !remote.model)
+            return;
+        const localFamily = ModelIdentity.of(local.model).family;
+        const remoteFamily = ModelIdentity.of(remote.model).family;
+        if (localFamily === remoteFamily &&
+            local.dimensions === remote.dimensions) {
+            return;
+        }
+        onWarning?.(`Warning: source uses "${remote.model}" (${remote.dimensions} dims) ` +
+            `but local index uses "${local.model}" (${local.dimensions} dims). ` +
+            "Imported vectors may not be compatible.");
+    }
+}
+//# sourceMappingURL=IndexShare.js.map

package/dist/infrastructure/p2p/IndexShare.js.map

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

package/dist/infrastructure/p2p/PeerSwarm.d.ts

@@ -0,0 +1,16 @@
+import type { DuplexSocket } from "./SecureChannel.js";
+/**
+ * Peer discovery over Hyperswarm.
+ *
+ * Imported lazily and treated as optional: sharing is a side feature, and its
+ * native dependency should not be required to run a search.
+ */
+export declare class PeerSwarm {
+    private readonly swarm;
+    private constructor();
+    static create(): Promise<PeerSwarm>;
+    onConnection(handler: (socket: DuplexSocket) => void): void;
+    /** Announce as a server (sharer) or dial as a client (receiver). */
+    join(topic: Buffer, role: "server" | "client"): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/infrastructure/p2p/PeerSwarm.js

@@ -0,0 +1,41 @@
+/**
+ * Peer discovery over Hyperswarm.
+ *
+ * Imported lazily and treated as optional: sharing is a side feature, and its
+ * native dependency should not be required to run a search.
+ */
+export class PeerSwarm {
+    swarm;
+    constructor(swarm) {
+        this.swarm = swarm;
+    }
+    static async create() {
+        let module;
+        try {
+            // @ts-expect-error -- no type declarations for hyperswarm
+            module = await import("hyperswarm");
+        }
+        catch {
+            throw new Error("hyperswarm is not installed. Run: pnpm add hyperswarm");
+        }
+        const Constructor = (module.default ??
+            module);
+        return new PeerSwarm(new Constructor());
+    }
+    onConnection(handler) {
+        this.swarm.on("connection", handler);
+    }
+    /** Announce as a server (sharer) or dial as a client (receiver). */
+    async join(topic, role) {
+        await this.swarm
+            .join(topic, {
+            server: role === "server",
+            client: role === "client",
+        })
+            .flushed();
+    }
+    async destroy() {
+        await this.swarm.destroy().catch(() => { });
+    }
+}
+//# sourceMappingURL=PeerSwarm.js.map

package/dist/infrastructure/p2p/PeerSwarm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeerSwarm.js","sourceRoot":"","sources":["../../../src/infrastructure/p2p/PeerSwarm.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IACgB;IAArC,YAAqC,KAAyB;QAAzB,UAAK,GAAL,KAAK,CAAoB;IAAG,CAAC;IAElE,MAAM,CAAC,KAAK,CAAC,MAAM;QAClB,IAAI,MAAkD,CAAC;QACvD,IAAI,CAAC;YACJ,0DAA0D;YAC1D,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACR,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC1E,CAAC;QACD,MAAM,WAAW,GAAG,CAAC,MAAM,CAAC,OAAO;YAClC,MAAM,CAAiC,CAAC;QACzC,OAAO,IAAI,SAAS,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,YAAY,CAAC,OAAuC;QACnD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAyB;QAClD,MAAM,IAAI,CAAC,KAAK;aACd,IAAI,CAAC,KAAK,EAAE;YACZ,MAAM,EAAE,IAAI,KAAK,QAAQ;YACzB,MAAM,EAAE,IAAI,KAAK,QAAQ;SACzB,CAAC;aACD,OAAO,EAAE,CAAC;IACb,CAAC;IAED,KAAK,CAAC,OAAO;QACZ,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;CACD"}

package/dist/infrastructure/p2p/SecureChannel.d.ts

@@ -0,0 +1,60 @@
+/** Messages exchanged during a share. */
+export type ShareMessage = {
+    type: "meta";
+    model?: string;
+    dimensions?: number;
+    chunkCount: number;
+    branch: string;
+    remote?: string;
+} | {
+    type: "ready";
+} | {
+    type: "chunks";
+    batch: Record<string, unknown>[];
+} | {
+    type: "files";
+    batch: Array<{
+        filePath: string;
+        fileHash: string;
+        branch: string;
+    }>;
+} | {
+    type: "done";
+} | {
+    type: "ack";
+};
+/** The transport a share runs over. */
+export interface DuplexSocket {
+    write(data: Buffer): boolean;
+    on(event: "data", cb: (chunk: Buffer) => void): void;
+    on(event: "end" | "close" | "error", cb: (err?: Error) => void): void;
+    end(): void;
+    destroy(): void;
+}
+/**
+ * Authenticated encryption and message framing over a raw peer socket.
+ *
+ * AES-256-GCM, so a tampered payload fails to decrypt rather than being parsed
+ * — a peer discovered over a public DHT is not trusted. Frames carry an
+ * explicit length prefix because a stream socket splits and merges writes
+ * arbitrarily, and JSON alone gives no way to find a message boundary.
+ */
+export declare class SecureChannel {
+    private readonly key;
+    private static readonly IV_BYTES;
+    private static readonly TAG_BYTES;
+    private static readonly LENGTH_PREFIX_BYTES;
+    constructor(key: Buffer);
+    send(socket: {
+        write(data: Buffer): boolean;
+    }, message: ShareMessage): void;
+    /**
+     * A stateful reader: feed it raw socket chunks, and it emits whole
+     * messages as their frames complete.
+     */
+    reader(onMessage: (message: ShareMessage) => void): (chunk: Buffer) => void;
+    /** Resolve once a message of the expected type arrives. */
+    await(socket: DuplexSocket, expected: ShareMessage["type"]): Promise<ShareMessage>;
+    private encrypt;
+    private decrypt;
+}

package/dist/infrastructure/p2p/SecureChannel.js

@@ -0,0 +1,71 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+/**
+ * Authenticated encryption and message framing over a raw peer socket.
+ *
+ * AES-256-GCM, so a tampered payload fails to decrypt rather than being parsed
+ * — a peer discovered over a public DHT is not trusted. Frames carry an
+ * explicit length prefix because a stream socket splits and merges writes
+ * arbitrarily, and JSON alone gives no way to find a message boundary.
+ */
+export class SecureChannel {
+    key;
+    static IV_BYTES = 12;
+    static TAG_BYTES = 16;
+    static LENGTH_PREFIX_BYTES = 4;
+    constructor(key) {
+        this.key = key;
+    }
+    send(socket, message) {
+        const encrypted = this.encrypt(Buffer.from(JSON.stringify(message)));
+        const frame = Buffer.alloc(SecureChannel.LENGTH_PREFIX_BYTES + encrypted.length);
+        frame.writeUInt32BE(encrypted.length, 0);
+        encrypted.copy(frame, SecureChannel.LENGTH_PREFIX_BYTES);
+        socket.write(frame);
+    }
+    /**
+     * A stateful reader: feed it raw socket chunks, and it emits whole
+     * messages as their frames complete.
+     */
+    reader(onMessage) {
+        let buffered = Buffer.alloc(0);
+        return (chunk) => {
+            buffered = Buffer.concat([buffered, chunk]);
+            while (buffered.length >= SecureChannel.LENGTH_PREFIX_BYTES) {
+                const length = buffered.readUInt32BE(0);
+                if (buffered.length < SecureChannel.LENGTH_PREFIX_BYTES + length) {
+                    break;
+                }
+                const frame = buffered.subarray(SecureChannel.LENGTH_PREFIX_BYTES, SecureChannel.LENGTH_PREFIX_BYTES + length);
+                buffered = buffered.subarray(SecureChannel.LENGTH_PREFIX_BYTES + length);
+                onMessage(JSON.parse(this.decrypt(frame).toString()));
+            }
+        };
+    }
+    /** Resolve once a message of the expected type arrives. */
+    await(socket, expected) {
+        return new Promise((resolve, reject) => {
+            const read = this.reader((message) => {
+                if (message.type === expected)
+                    resolve(message);
+            });
+            socket.on("data", read);
+            socket.on("error", reject);
+            socket.on("close", () => reject(new Error("Connection closed")));
+        });
+    }
+    encrypt(plaintext) {
+        const iv = randomBytes(SecureChannel.IV_BYTES);
+        const cipher = createCipheriv("aes-256-gcm", this.key, iv);
+        const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        return Buffer.concat([iv, cipher.getAuthTag(), body]);
+    }
+    decrypt(data) {
+        const iv = data.subarray(0, SecureChannel.IV_BYTES);
+        const tag = data.subarray(SecureChannel.IV_BYTES, SecureChannel.IV_BYTES + SecureChannel.TAG_BYTES);
+        const body = data.subarray(SecureChannel.IV_BYTES + SecureChannel.TAG_BYTES);
+        const decipher = createDecipheriv("aes-256-gcm", this.key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(body), decipher.final()]);
+    }
+}
+//# sourceMappingURL=SecureChannel.js.map

package/dist/infrastructure/p2p/SecureChannel.js.map

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

package/dist/infrastructure/p2p/ShareCode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A human-transcribable one-time code that both names a rendezvous topic and
+ * derives the encryption key for a share.
+ *
+ * Three words plus hex: short enough to read aloud, with 40 bits of entropy in
+ * the suffix so a code cannot be guessed within its lifetime.
+ *
+ * Topic and key are derived from the code by *separate* HKDF labels. That
+ * separation is the point — peer discovery necessarily publishes the topic, and
+ * it must not leak anything about the key protecting the payload.
+ */
+export declare class ShareCode {
+    readonly value: string;
+    private static readonly WORDS;
+    static readonly PATTERN: RegExp;
+    private constructor();
+    static generate(): ShareCode;
+    static parse(value: string): ShareCode | undefined;
+    static looksLikeCode(value: string): boolean;
+    toString(): string;
+    /** Rendezvous topic for peer discovery. Public by nature. */
+    toTopic(): Buffer;
+    /** AES-256 key for the payload. Never derivable from the topic. */
+    toEncryptionKey(): Buffer;
+}