lmgrep 0.1.18 → 0.2.0

package/dist/infrastructure/p2p/ShareCode.js

@@ -0,0 +1,304 @@
+import { hkdfSync, randomBytes } from "node:crypto";
+/**
+ * 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 class ShareCode {
+    value;
+    static WORDS = [
+        "acid",
+        "acme",
+        "aged",
+        "also",
+        "arch",
+        "area",
+        "army",
+        "away",
+        "back",
+        "bail",
+        "bake",
+        "band",
+        "bank",
+        "barn",
+        "base",
+        "bath",
+        "beam",
+        "bean",
+        "bear",
+        "beat",
+        "beef",
+        "beer",
+        "bell",
+        "belt",
+        "bend",
+        "bike",
+        "bird",
+        "bite",
+        "blow",
+        "blue",
+        "boat",
+        "body",
+        "bolt",
+        "bomb",
+        "bond",
+        "bone",
+        "book",
+        "boot",
+        "born",
+        "boss",
+        "bowl",
+        "bulk",
+        "bull",
+        "burn",
+        "cage",
+        "cake",
+        "calm",
+        "came",
+        "camp",
+        "cape",
+        "card",
+        "care",
+        "cart",
+        "case",
+        "cash",
+        "cast",
+        "cave",
+        "chef",
+        "chip",
+        "city",
+        "clan",
+        "clay",
+        "clip",
+        "club",
+        "clue",
+        "coal",
+        "coat",
+        "code",
+        "coil",
+        "coin",
+        "cold",
+        "come",
+        "cook",
+        "cool",
+        "cope",
+        "copy",
+        "cord",
+        "core",
+        "corn",
+        "cost",
+        "crew",
+        "crop",
+        "crow",
+        "cure",
+        "curl",
+        "cute",
+        "dame",
+        "damp",
+        "dare",
+        "dark",
+        "dash",
+        "data",
+        "dawn",
+        "deal",
+        "dean",
+        "deck",
+        "deep",
+        "deer",
+        "demo",
+        "desk",
+        "dial",
+        "dice",
+        "diet",
+        "dirt",
+        "disk",
+        "dock",
+        "door",
+        "dose",
+        "down",
+        "draw",
+        "drop",
+        "drum",
+        "dual",
+        "duck",
+        "dull",
+        "dump",
+        "dune",
+        "dust",
+        "duty",
+        "each",
+        "earl",
+        "earn",
+        "ease",
+        "east",
+        "edge",
+        "else",
+        "epic",
+        "even",
+        "ever",
+        "exam",
+        "exit",
+        "face",
+        "fact",
+        "fade",
+        "fail",
+        "fair",
+        "fall",
+        "fame",
+        "farm",
+        "fast",
+        "fate",
+        "fawn",
+        "feed",
+        "feel",
+        "file",
+        "film",
+        "find",
+        "fine",
+        "fire",
+        "firm",
+        "fish",
+        "flag",
+        "flat",
+        "fled",
+        "flip",
+        "flow",
+        "foam",
+        "fold",
+        "folk",
+        "fond",
+        "food",
+        "fool",
+        "fork",
+        "form",
+        "fort",
+        "foul",
+        "four",
+        "free",
+        "frog",
+        "fuel",
+        "full",
+        "fund",
+        "fury",
+        "fuse",
+        "gain",
+        "gale",
+        "game",
+        "gang",
+        "gate",
+        "gave",
+        "gaze",
+        "gear",
+        "gene",
+        "gift",
+        "glad",
+        "glow",
+        "glue",
+        "goat",
+        "gold",
+        "golf",
+        "gone",
+        "good",
+        "grab",
+        "gray",
+        "grid",
+        "grip",
+        "grow",
+        "gulf",
+        "guru",
+        "gust",
+        "hack",
+        "half",
+        "hall",
+        "halt",
+        "hand",
+        "hang",
+        "hare",
+        "harm",
+        "harp",
+        "hash",
+        "hate",
+        "haul",
+        "have",
+        "hawk",
+        "haze",
+        "head",
+        "heap",
+        "heat",
+        "held",
+        "helm",
+        "help",
+        "herb",
+        "herd",
+        "here",
+        "hero",
+        "hide",
+        "high",
+        "hike",
+        "hill",
+        "hilt",
+        "hint",
+        "hire",
+        "hold",
+        "hole",
+        "holy",
+        "home",
+        "hood",
+        "hook",
+        "hope",
+        "horn",
+        "host",
+        "hour",
+        "huge",
+        "hull",
+        "hung",
+        "hunt",
+        "hurt",
+        "icon",
+        "idea",
+        "inch",
+        "info",
+        "iron",
+        "isle",
+        "item",
+        "jack",
+        "jade",
+    ];
+    static PATTERN = /^lmgrep[a-z]+[0-9a-f]{10}$/;
+    constructor(value) {
+        this.value = value;
+    }
+    static generate() {
+        const bytes = randomBytes(16);
+        const words = [
+            ShareCode.WORDS[bytes[0]],
+            ShareCode.WORDS[bytes[1]],
+            ShareCode.WORDS[bytes[2]],
+        ].join("");
+        return new ShareCode(`lmgrep${words}${bytes.subarray(3, 8).toString("hex")}`);
+    }
+    static parse(value) {
+        return ShareCode.looksLikeCode(value) ? new ShareCode(value) : undefined;
+    }
+    static looksLikeCode(value) {
+        return ShareCode.PATTERN.test(value);
+    }
+    toString() {
+        return this.value;
+    }
+    /** Rendezvous topic for peer discovery. Public by nature. */
+    toTopic() {
+        return Buffer.from(hkdfSync("sha256", this.value, "lmgrep-topic", "topic", 32));
+    }
+    /** AES-256 key for the payload. Never derivable from the topic. */
+    toEncryptionKey() {
+        return Buffer.from(hkdfSync("sha256", this.value, "lmgrep-key", "encryption", 32));
+    }
+}
+//# sourceMappingURL=ShareCode.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShareCode.js","sourceRoot":"","sources":["../../../src/infrastructure/p2p/ShareCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IAsQQ;IArQrB,MAAM,CAAU,KAAK,GAAG;QAC/B,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;KACN,CAAC;IAEF,MAAM,CAAU,OAAO,GAAG,4BAA4B,CAAC;IAEvD,YAA6B,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAE9C,MAAM,CAAC,QAAQ;QACd,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG;YACb,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACzB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACX,OAAO,IAAI,SAAS,CACnB,SAAS,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CACvD,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,KAAa;QACzB,OAAO,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1E,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,KAAa;QACjC,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,QAAQ;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,6DAA6D;IAC7D,OAAO;QACN,OAAO,MAAM,CAAC,IAAI,CACjB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,CAAC,CAC3D,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,eAAe;QACd,OAAO,MAAM,CAAC,IAAI,CACjB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,EAAE,CAAC,CAC9D,CAAC;IACH,CAAC"}

package/dist/infrastructure/process/ProcessRegistry.d.ts

@@ -0,0 +1,50 @@
+import type { StateDirectoryPort } from "../../domain/ports/StateDirectoryPort.js";
+/** What kind of lmgrep invocation a process is. */
+export type ProcessKind = "mcp" | "serve" | "cli";
+/** A live lmgrep process holding a database's maintainer lock. */
+export interface RunningProcess {
+    pid: number;
+    /** Process title from /proc/<pid>/comm (e.g. "lmgrep-mcp"). */
+    processName: string;
+    cmdline: string;
+    kind: ProcessKind;
+    /** Working tree this process watches. */
+    projectRoot?: string;
+    /** Database it holds. */
+    databasePath?: string;
+    /** Whether this process is watching the index for changes. */
+    watching: boolean;
+}
+/**
+ * Discovers which lmgrep processes are alive and what they hold.
+ *
+ * Maintainer lock files double as the registry: each records its owner's pid,
+ * worktree and database, so scanning them and testing liveness gives an
+ * accurate picture without any separate bookkeeping that could drift from
+ * reality.
+ */
+export declare class ProcessRegistry {
+    private readonly state;
+    private static readonly LOCK_SUFFIX;
+    constructor(state: StateDirectoryPort);
+    discoverRunning(): RunningProcess[];
+    /**
+     * Lock files, from the locks directory and from the state root.
+     *
+     * The root is scanned too because a watcher started before locks moved is
+     * still running and still holds its database — reporting "no running
+     * processes" right after an upgrade would be wrong in exactly the moment
+     * someone is most likely to check.
+     */
+    private lockFiles;
+    private inspect;
+    /**
+     * What kind of process this is, from its title.
+     *
+     * The title is the only reliable signal: `process.title` rewrites the argv
+     * buffer, so /proc/<pid>/cmdline reads back as the title alone and carries
+     * no subcommand. The MCP entry point titles itself distinctly; anything
+     * else holding a maintainer lock reached it through `lmgrep serve`.
+     */
+    private classify;
+}

package/dist/infrastructure/process/ProcessRegistry.js

@@ -0,0 +1,109 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PidFileLock } from "../fs/PidFileLock.js";
+/**
+ * Discovers which lmgrep processes are alive and what they hold.
+ *
+ * Maintainer lock files double as the registry: each records its owner's pid,
+ * worktree and database, so scanning them and testing liveness gives an
+ * accurate picture without any separate bookkeeping that could drift from
+ * reality.
+ */
+export class ProcessRegistry {
+    state;
+    static LOCK_SUFFIX = ".lock";
+    constructor(state) {
+        this.state = state;
+    }
+    discoverRunning() {
+        const results = [];
+        // One process can hold several databases; report it once.
+        const seen = new Set();
+        for (const path of this.lockFiles()) {
+            const owner = new PidFileLock(path).read();
+            if (owner === undefined)
+                continue;
+            if (!PidFileLock.isAlive(owner.pid) || seen.has(owner.pid))
+                continue;
+            seen.add(owner.pid);
+            const info = this.inspect(owner.pid);
+            if (!info)
+                continue;
+            results.push({
+                pid: owner.pid,
+                processName: info.name,
+                cmdline: info.cmdline,
+                kind: this.classify(info),
+                // The lock records the worktree its owner actually watches,
+                // which is what the user wants to see — several worktrees can
+                // share one database, so the database's own recorded root
+                // would name the wrong tree.
+                projectRoot: owner.root,
+                databasePath: owner.database,
+                // Every lock in this scan is a maintainer lock, and only a
+                // watcher ever takes one — so holding it *is* watching. This
+                // used to be inferred from the command line, which cannot
+                // work: setting process.title overwrites that buffer, so the
+                // subcommand a process was launched with is no longer there
+                // to match against.
+                watching: true,
+            });
+        }
+        return results;
+    }
+    /**
+     * Lock files, from the locks directory and from the state root.
+     *
+     * The root is scanned too because a watcher started before locks moved is
+     * still running and still holds its database — reporting "no running
+     * processes" right after an upgrade would be wrong in exactly the moment
+     * someone is most likely to check.
+     */
+    lockFiles() {
+        const out = [];
+        for (const directory of [this.state.locksDirectory(), this.state.root()]) {
+            let entries;
+            try {
+                entries = readdirSync(directory);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.endsWith(ProcessRegistry.LOCK_SUFFIX)) {
+                    out.push(join(directory, entry));
+                }
+            }
+        }
+        return out;
+    }
+    inspect(pid) {
+        try {
+            return {
+                name: readFileSync(`/proc/${pid}/comm`, "utf-8").trim(),
+                cmdline: readFileSync(`/proc/${pid}/cmdline`, "utf-8")
+                    .replace(/\0/g, " ")
+                    .trim(),
+            };
+        }
+        catch {
+            // No procfs (macOS) or the process exited mid-scan.
+            return undefined;
+        }
+    }
+    /**
+     * What kind of process this is, from its title.
+     *
+     * The title is the only reliable signal: `process.title` rewrites the argv
+     * buffer, so /proc/<pid>/cmdline reads back as the title alone and carries
+     * no subcommand. The MCP entry point titles itself distinctly; anything
+     * else holding a maintainer lock reached it through `lmgrep serve`.
+     */
+    classify(info) {
+        if (info.name === "lmgrep-mcp" || info.cmdline.includes("mcp")) {
+            return "mcp";
+        }
+        return "serve";
+    }
+}
+//# sourceMappingURL=ProcessRegistry.js.map

package/dist/infrastructure/process/ProcessRegistry.js.map

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

package/dist/infrastructure/treesitter/ChunkContextBuilder.d.ts

@@ -0,0 +1,45 @@
+import type { Node } from "web-tree-sitter";
+import type { LanguageConfig } from "./LanguageCatalog.js";
+/** What kind of thing a chunk is, structurally. */
+export type StructuralRole = "definition" | "orchestration" | "implementation";
+/** One enclosing scope, e.g. `class Foo`. */
+export interface ScopeEntry {
+    kind: string;
+    name: string;
+}
+/**
+ * Builds the context header prepended to a chunk before embedding.
+ *
+ * The header is what makes an isolated function retrievable: on its own,
+ * `async function handle(req)` shares little vocabulary with "how are webhooks
+ * authenticated", but stamped with its file, enclosing class and doc comment
+ * it does. Retrieval quality depends on this at least as much as on the text.
+ */
+export declare class ChunkContextBuilder {
+    /** How far above a node to look for its doc comment. */
+    private static readonly MAX_COMMENT_LOOKBACK;
+    /** AST node type -> the word used for it in the header. */
+    private static readonly SCOPE_KINDS;
+    /** Node types that declare a shape rather than behaviour. */
+    private static readonly DEFINITION_TYPES;
+    /** Node types that wire things together rather than implement them. */
+    private static readonly ORCHESTRATION_TYPES;
+    /** The full header for one chunk. */
+    build(node: Node, filePath: string, source: string, language: LanguageConfig): string;
+    /** The minimal header for a file with no parsed structure. */
+    buildFileOnly(filePath: string): string;
+    /** Walk up from a node collecting the named scopes that enclose it. */
+    extractScope(node: Node, language: LanguageConfig): ScopeEntry[];
+    /**
+     * Collect the comment block or decorators immediately above a node.
+     *
+     * A blank line ends the block only once something has been collected, so a
+     * comment separated from its node by whitespace is still picked up, while
+     * unrelated code above it is not.
+     */
+    extractLeadingComment(node: Node, source: string): string | null;
+    classifyRole(node: Node): StructuralRole;
+    /** Comment syntax across every supported language, plus decorators. */
+    private looksLikeCommentOrDecorator;
+    private nodeName;
+}

package/dist/infrastructure/treesitter/ChunkContextBuilder.js

@@ -0,0 +1,159 @@
+/**
+ * Builds the context header prepended to a chunk before embedding.
+ *
+ * The header is what makes an isolated function retrievable: on its own,
+ * `async function handle(req)` shares little vocabulary with "how are webhooks
+ * authenticated", but stamped with its file, enclosing class and doc comment
+ * it does. Retrieval quality depends on this at least as much as on the text.
+ */
+export class ChunkContextBuilder {
+    /** How far above a node to look for its doc comment. */
+    static MAX_COMMENT_LOOKBACK = 10;
+    /** AST node type -> the word used for it in the header. */
+    static SCOPE_KINDS = {
+        // TypeScript / JavaScript
+        class_declaration: "class",
+        class_body: "class",
+        interface_declaration: "interface",
+        module: "module",
+        namespace_declaration: "namespace",
+        // Python
+        class_definition: "class",
+        // Rust
+        impl_item: "impl",
+        trait_item: "trait",
+        mod_item: "mod",
+        // Go
+        type_declaration: "type",
+        // Ruby
+        class: "class",
+        // C / C++
+        struct_specifier: "struct",
+        class_specifier: "class",
+        namespace_definition: "namespace",
+        // Swift
+        struct_declaration: "struct",
+        extension_declaration: "extension",
+        // Scala
+        object_definition: "object",
+        trait_definition: "trait",
+        // Generic
+        ContainerDecl: "container",
+    };
+    /** Node types that declare a shape rather than behaviour. */
+    static DEFINITION_TYPES = new Set([
+        "class_declaration",
+        "class_definition",
+        "interface_declaration",
+        "type_alias_declaration",
+        "enum_declaration",
+        "struct_item",
+        "enum_item",
+        "trait_item",
+        "type_item",
+        "type_declaration",
+        "struct_specifier",
+        "class_specifier",
+        "enum_specifier",
+        "type_definition",
+        "struct_declaration",
+        "protocol_declaration",
+        "trait_definition",
+        "ContainerDecl",
+    ]);
+    /** Node types that wire things together rather than implement them. */
+    static ORCHESTRATION_TYPES = new Set([
+        "export_statement",
+        "decorated_definition",
+    ]);
+    /** The full header for one chunk. */
+    build(node, filePath, source, language) {
+        const lines = [
+            `[file: ${filePath}]`,
+            `[role: ${this.classifyRole(node)}]`,
+        ];
+        const scope = this.extractScope(node, language);
+        if (scope.length > 0) {
+            lines.push(`[scope: ${scope.map((s) => `${s.kind} ${s.name}`).join(" > ")}]`);
+        }
+        const comment = this.extractLeadingComment(node, source);
+        if (comment)
+            lines.push(`[doc: ${comment}]`);
+        return lines.join("\n");
+    }
+    /** The minimal header for a file with no parsed structure. */
+    buildFileOnly(filePath) {
+        return `[file: ${filePath}]`;
+    }
+    /** Walk up from a node collecting the named scopes that enclose it. */
+    extractScope(node, language) {
+        const scopes = [];
+        let current = node.parent;
+        while (current) {
+            if (language.scopeTypes.includes(current.type)) {
+                const name = this.nodeName(current);
+                if (name) {
+                    scopes.unshift({
+                        kind: ChunkContextBuilder.SCOPE_KINDS[current.type] ?? current.type,
+                        name,
+                    });
+                }
+            }
+            current = current.parent;
+        }
+        return scopes;
+    }
+    /**
+     * Collect the comment block or decorators immediately above a node.
+     *
+     * A blank line ends the block only once something has been collected, so a
+     * comment separated from its node by whitespace is still picked up, while
+     * unrelated code above it is not.
+     */
+    extractLeadingComment(node, source) {
+        const lines = source.split("\n");
+        const start = node.startPosition.row;
+        const collected = [];
+        for (let i = start - 1; i >= 0 && i >= start - ChunkContextBuilder.MAX_COMMENT_LOOKBACK; i--) {
+            const line = lines[i].trim();
+            if (this.looksLikeCommentOrDecorator(line)) {
+                collected.unshift(lines[i]);
+            }
+            else if (line === "") {
+                if (collected.length > 0)
+                    break;
+            }
+            else {
+                break;
+            }
+        }
+        return collected.length === 0 ? null : collected.join("\n").trim();
+    }
+    classifyRole(node) {
+        if (ChunkContextBuilder.DEFINITION_TYPES.has(node.type)) {
+            return "definition";
+        }
+        if (ChunkContextBuilder.ORCHESTRATION_TYPES.has(node.type)) {
+            return "orchestration";
+        }
+        return "implementation";
+    }
+    /** Comment syntax across every supported language, plus decorators. */
+    looksLikeCommentOrDecorator(line) {
+        return (line.startsWith("//") ||
+            line.startsWith("#") ||
+            line.startsWith("*") ||
+            line.startsWith("/*") ||
+            line.startsWith("*/") ||
+            line.startsWith("///") ||
+            line.startsWith("--") ||
+            line.startsWith("@") ||
+            line.startsWith('"""') ||
+            line.startsWith("'''"));
+    }
+    nodeName(node) {
+        return (node.childForFieldName("name") ??
+            node.children.find((c) => c.type === "identifier" || c.type === "type_identifier"))?.text;
+    }
+}
+//# sourceMappingURL=ChunkContextBuilder.js.map