@loopover/engine 1.0.0

package/dist/miner/local-write-tools.d.ts

@@ -0,0 +1,81 @@
+/** A minimal, self-contained JSON-value type (mirrors src/types.ts's own JsonValue) -- kept local rather than
+ *  imported so this module has zero cross-package type dependency beyond what it already needs. */
+export type LocalWriteJsonValue = string | number | boolean | null | LocalWriteJsonValue[] | {
+    [key: string]: LocalWriteJsonValue;
+};
+export declare const LOCAL_WRITE_BOUNDARY = "Run this locally with your OWN GitHub credentials (e.g. an authenticated `gh`/`git`). Gittensory supplies the content but never performs the write \u2014 your code and the action both stay on your machine.";
+export type LocalWriteActionSpec = {
+    action: string;
+    description: string;
+    inputs: Record<string, LocalWriteJsonValue>;
+    command: string;
+    boundary: string;
+};
+/** Open a PR from a local branch (content typically taken from gittensory's prepare_pr_packet). */
+export declare function buildOpenPrSpec(input: {
+    repoFullName: string;
+    base: string;
+    head: string;
+    title: string;
+    body: string;
+    draft?: boolean | undefined;
+}): LocalWriteActionSpec;
+/** Close a pull request the miner itself opened (e.g. it lost a claim-conflict adjudication to an earlier
+ *  claimant, #4848) -- never used against a PR the miner does not own. The close runs FIRST and
+ *  unconditionally -- it's the safety-critical action (never leave a known-losing PR open); `comment`, when
+ *  supplied, is a best-effort follow-up posted only once the close itself succeeds (`gh pr close` has no
+ *  comment-body flag of its own, and a transient `gh pr comment` failure must never mask or block the close
+ *  it's explaining). */
+export declare function buildClosePrSpec(input: {
+    repoFullName: string;
+    number: number;
+    comment?: string | undefined;
+}): LocalWriteActionSpec;
+/** File an issue (e.g. an issue-discovery proposal). */
+export declare function buildFileIssueSpec(input: {
+    repoFullName: string;
+    title: string;
+    body: string;
+    labels?: string[] | undefined;
+}): LocalWriteActionSpec;
+/** Add labels to an issue or PR (gh issue edit also targets PRs). */
+export declare function buildApplyLabelsSpec(input: {
+    repoFullName: string;
+    number: number;
+    labels: string[];
+}): LocalWriteActionSpec;
+/** Post an eligibility/context comment on an issue or PR. */
+export declare function buildPostEligibilityCommentSpec(input: {
+    repoFullName: string;
+    number: number;
+    body: string;
+}): LocalWriteActionSpec;
+/** Create a local branch off an optional base. */
+export declare function buildCreateBranchSpec(input: {
+    branch: string;
+    base?: string | undefined;
+}): LocalWriteActionSpec;
+/** Delete a branch locally, and optionally on the remote. */
+export declare function buildDeleteBranchSpec(input: {
+    branch: string;
+    remote?: boolean | undefined;
+}): LocalWriteActionSpec;
+export declare function buildTestGenSpec(input: {
+    repoFullName: string;
+    targetFiles: string[];
+    framework: string;
+    testDir?: string | null | undefined;
+    criteria?: string[] | undefined;
+}): LocalWriteActionSpec;
+/** Build a LOCAL-execution spec to file a follow-up issue for a review finding a maintainer wants TRACKED
+ *  rather than blocked on this PR. Composes a bounded, public-safe title/body from the finding and delegates to
+ *  {@link buildFileIssueSpec}'s exact "file_issue" spec shape — no new write path. `label` is optional: when the
+ *  caller supplies a point-bearing label (e.g. "gittensor:bug"), the follow-up carries it so the tracked issue
+ *  is itself a scored, actionable contribution target; omitted ⇒ no labels at all (empty-label branch). */
+export declare function buildFollowUpIssueSpec(input: {
+    repoFullName: string;
+    path: string;
+    line?: number | undefined;
+    finding: string;
+    label?: string | null | undefined;
+}): LocalWriteActionSpec;

package/dist/miner/local-write-tools.js

@@ -0,0 +1,113 @@
+// #780 miner write-tools. These build ACTION SPECS — gittensory supplies the content; the miner's OWN local
+// harness runs the command with its OWN GitHub credentials. Gittensory NEVER performs the write, so source code
+// and the write both stay on the miner's machine: the no-cloud-write boundary holds. Pure + deterministic: every
+// builder returns a self-contained, shell-safe spec and touches nothing.
+//
+// MOVED HERE FROM src/mcp/local-write-tools.ts (#2337): this module has zero root-specific dependencies (it only
+// ever needed a generic JSON-value type), so it belongs in the shared "brain" layer alongside the rest of the
+// portable engine, not root-only. This is what lets packages/gittensory-miner's own real driving-loop entrypoint
+// construct the EXACT SAME open_pr command gittensory's MCP server would return, with zero network round-trip
+// and zero duplicated/drifting logic: both consumers import the same functions from this one place. Root's
+// src/mcp/local-write-tools.ts is now a thin re-export preserving every existing import path unchanged.
+export const LOCAL_WRITE_BOUNDARY = "Run this locally with your OWN GitHub credentials (e.g. an authenticated `gh`/`git`). Gittensory supplies the content but never performs the write — your code and the action both stay on your machine.";
+// POSIX single-quote escaping: wrap in single quotes and escape embedded single quotes. Safe against injection
+// when the harness runs `command` verbatim.
+function sq(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function spec(action, description, inputs, command) {
+    return { action, description, inputs, command, boundary: LOCAL_WRITE_BOUNDARY };
+}
+/** Open a PR from a local branch (content typically taken from gittensory's prepare_pr_packet). */
+export function buildOpenPrSpec(input) {
+    const draft = input.draft === true;
+    const command = `gh pr create --repo ${sq(input.repoFullName)} --base ${sq(input.base)} --head ${sq(input.head)} --title ${sq(input.title)} --body ${sq(input.body)}${draft ? " --draft" : ""}`;
+    return spec("open_pr", "Open a pull request from your local branch.", { repoFullName: input.repoFullName, base: input.base, head: input.head, title: input.title, body: input.body, draft }, command);
+}
+/** Close a pull request the miner itself opened (e.g. it lost a claim-conflict adjudication to an earlier
+ *  claimant, #4848) -- never used against a PR the miner does not own. The close runs FIRST and
+ *  unconditionally -- it's the safety-critical action (never leave a known-losing PR open); `comment`, when
+ *  supplied, is a best-effort follow-up posted only once the close itself succeeds (`gh pr close` has no
+ *  comment-body flag of its own, and a transient `gh pr comment` failure must never mask or block the close
+ *  it's explaining). */
+export function buildClosePrSpec(input) {
+    const closeCommand = `gh pr close ${input.number} --repo ${sq(input.repoFullName)}`;
+    const command = input.comment
+        ? `${closeCommand} && gh pr comment ${input.number} --repo ${sq(input.repoFullName)} --body ${sq(input.comment)}`
+        : closeCommand;
+    return spec("close_pr", "Close a pull request you opened.", { repoFullName: input.repoFullName, number: input.number, ...(input.comment ? { comment: input.comment } : {}) }, command);
+}
+/** File an issue (e.g. an issue-discovery proposal). */
+export function buildFileIssueSpec(input) {
+    const labels = input.labels ?? [];
+    const labelArgs = labels.map((label) => ` --label ${sq(label)}`).join("");
+    const command = `gh issue create --repo ${sq(input.repoFullName)} --title ${sq(input.title)} --body ${sq(input.body)}${labelArgs}`;
+    return spec("file_issue", "File a new issue.", { repoFullName: input.repoFullName, title: input.title, body: input.body, labels }, command);
+}
+/** Add labels to an issue or PR (gh issue edit also targets PRs). */
+export function buildApplyLabelsSpec(input) {
+    const labelArgs = input.labels.map((label) => ` --add-label ${sq(label)}`).join("");
+    const command = `gh issue edit ${input.number} --repo ${sq(input.repoFullName)}${labelArgs}`;
+    return spec("apply_labels", "Add labels to an issue or pull request.", { repoFullName: input.repoFullName, number: input.number, labels: input.labels }, command);
+}
+/** Post an eligibility/context comment on an issue or PR. */
+export function buildPostEligibilityCommentSpec(input) {
+    const command = `gh issue comment ${input.number} --repo ${sq(input.repoFullName)} --body ${sq(input.body)}`;
+    return spec("post_eligibility_comment", "Post an eligibility/context comment on an issue or pull request.", { repoFullName: input.repoFullName, number: input.number, body: input.body }, command);
+}
+/** Create a local branch off an optional base. */
+export function buildCreateBranchSpec(input) {
+    const command = input.base ? `git switch -c ${sq(input.branch)} ${sq(input.base)}` : `git switch -c ${sq(input.branch)}`;
+    return spec("create_branch", "Create a local branch.", { branch: input.branch, ...(input.base ? { base: input.base } : {}) }, command);
+}
+/** Delete a branch locally, and optionally on the remote. */
+export function buildDeleteBranchSpec(input) {
+    const local = `git branch -D ${sq(input.branch)}`;
+    const command = input.remote === true ? `${local} && git push origin --delete ${sq(input.branch)}` : local;
+    return spec("delete_branch", "Delete a branch (locally, and optionally on origin).", { branch: input.branch, remote: input.remote === true }, command);
+}
+// #2188 (boundary-safe test-generation slice of #1972). Unlike the write-tools above, there is no single CLI
+// verb that "scaffolds a test file" across vitest/jest/pytest/go test/rspec/cargo test — so `command` here is a
+// safe, informative `echo` of the plan (target files + boundary criteria) rather than a real write, and the
+// actual scaffolding is left to the contributor's OWN agent reading the structured `inputs`. This keeps the same
+// no-cloud-write guarantee as every other spec in this file: gittensory supplies WHAT test cases should exist at
+// which boundaries, never the test file content or its execution.
+export function buildTestGenSpec(input) {
+    const criteria = input.criteria ?? [];
+    const testDir = input.testDir ?? null;
+    const targetList = input.targetFiles.join(", ");
+    const criteriaList = criteria.length > 0 ? ` Boundary-safe criteria: ${criteria.join("; ")}.` : "";
+    const location = testDir ? ` under ${testDir}` : " co-located with the source it covers";
+    const description = `Scaffold ${input.framework} tests${location} for: ${targetList}.${criteriaList}`;
+    const command = `echo ${sq(description)}`;
+    return spec("generate_tests", description, { repoFullName: input.repoFullName, targetFiles: input.targetFiles, framework: input.framework, testDir, criteria }, command);
+}
+// #2177 (follow-up-issue slice of #1962). Reuses buildFileIssueSpec's exact spec shape ("file_issue") — a
+// deferred review finding is just another issue-worth-filing content source, so there is no new spec verb or
+// no-cloud-write boundary here, only a deterministic title/body composer in front of the SAME builder.
+const FOLLOW_UP_ISSUE_TITLE_MAX = 200;
+const FOLLOW_UP_ISSUE_BODY_MAX = 4000;
+// Strip any machine-readable marker (e.g. fix-handoff's HTML comment marker, or a stray fenced block) before
+// the finding's text becomes issue content — a follow-up issue is read by a HUMAN triaging a backlog, not a
+// harness, so it should read as prose, not carry an internal marker meant for a different consumer.
+function stripMachineMarkers(text) {
+    return text
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/```[\s\S]*?```/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Build a LOCAL-execution spec to file a follow-up issue for a review finding a maintainer wants TRACKED
+ *  rather than blocked on this PR. Composes a bounded, public-safe title/body from the finding and delegates to
+ *  {@link buildFileIssueSpec}'s exact "file_issue" spec shape — no new write path. `label` is optional: when the
+ *  caller supplies a point-bearing label (e.g. "gittensor:bug"), the follow-up carries it so the tracked issue
+ *  is itself a scored, actionable contribution target; omitted ⇒ no labels at all (empty-label branch). */
+export function buildFollowUpIssueSpec(input) {
+    const safePath = stripMachineMarkers(input.path);
+    const location = input.line && input.line > 0 ? `${safePath}:${input.line}` : safePath;
+    const safeFinding = stripMachineMarkers(input.finding).slice(0, FOLLOW_UP_ISSUE_BODY_MAX);
+    const title = `Follow up: ${location}`.slice(0, FOLLOW_UP_ISSUE_TITLE_MAX);
+    const body = `Deferred review finding at \`${location}\`:\n\n${safeFinding}`.slice(0, FOLLOW_UP_ISSUE_BODY_MAX);
+    const labels = input.label ? [input.label] : [];
+    return buildFileIssueSpec({ repoFullName: input.repoFullName, title, body, labels });
+}

package/dist/miner/loop-reentry-policy.d.ts

@@ -0,0 +1,36 @@
+import { type MinerKillSwitchScope } from "../governor/kill-switch.js";
+/** The terminal outcome that just resolved for the repo the caller is considering re-entering on. */
+export type LoopReentryOutcome = "merged" | "disengaged" | "other";
+export declare const DEFAULT_MAX_CONSECUTIVE_DISENGAGEMENTS = 3;
+export declare const DEFAULT_MAX_REENTRIES_PER_HOUR = 4;
+export declare const DEFAULT_MAX_REENTRIES_PER_SESSION = 20;
+export type LoopReentryCandidate = {
+    /** Checked FIRST, before any other field below -- see the module doc comment's KILL-SWITCH section. */
+    killSwitchScope: MinerKillSwitchScope;
+    repoFullName: string;
+    outcome: LoopReentryOutcome;
+    /** Caller-computed count of CONSECUTIVE `"disengaged"` outcomes for this repo, ending with (and including,
+     *  when `outcome === "disengaged"`) this one. Any non-disengaged outcome resets this to 0 -- the caller owns
+     *  that computation, this policy only consumes the resulting integer (mirrors `reputation-throttle.ts`'s
+     *  caller-supplied `RepoOutcomeHistory`). */
+    consecutiveDisengagements: number;
+    maxConsecutiveDisengagements?: number | undefined;
+    /** Caller-tracked re-entry counters for the hard rate/session cap -- independent of the per-repo circuit
+     *  breaker above. */
+    reentriesThisHour: number;
+    maxReentriesPerHour?: number | undefined;
+    reentriesThisSession: number;
+    maxReentriesPerSession?: number | undefined;
+};
+export type LoopReentryDecision = {
+    reenter: boolean;
+    /** Always populated when `reenter` is `false`; every ceiling that was hit, not just the first. */
+    reasons: string[];
+};
+/**
+ * Decide whether the loop may re-enter discovery for this repo. Pure; identical inputs always yield the
+ * identical decision. `outcome === "merged"` alone never bypasses the rate/session cap -- a healthy repo can
+ * still be rate-limited if the operator-wide ceiling is already spent. The kill-switch is checked FIRST and
+ * short-circuits everything else -- an active kill-switch blocks unconditionally.
+ */
+export declare function shouldReenter(candidate: LoopReentryCandidate): LoopReentryDecision;

package/dist/miner/loop-reentry-policy.js

@@ -0,0 +1,53 @@
+// Closed-loop discovery re-entry policy (#2338): the pure decision half of "on a resolved outcome (merged, or
+// rejected-and-disengaged), automatically re-invoke discovery to select the next candidate." Deliberately split
+// from the miner-side orchestrator (packages/gittensory-miner/lib/loop-reentry.js), which owns the REAL IO --
+// reading recent event-ledger history to compute the tallies this policy consumes, dequeuing the next
+// candidate, and transitioning run-state -- mirroring this session's established engine (pure) / miner-lib
+// (stateful) split for every other governor primitive.
+//
+// TOP SLOP-AT-SCALE RISK: this issue's own framing calls out "a bug here (re-entering too fast, ignoring a
+// circuit-breaker, or looping on a permanently-rejected repo) is the top slop-at-scale risk for the whole miner
+// subsystem." Both failure modes get an INDEPENDENT hard ceiling here, neither one masking the other:
+//   - A per-repo circuit breaker: N consecutive disengaged (rejected) outcomes on the SAME repo pauses further
+//     re-entry for that repo, regardless of how much of the hour/session rate budget remains.
+//   - A hard rate/session cap: independent of any repo's own history, a conservative ceiling on how many
+//     re-entries may fire in a rolling hour or across the whole session.
+// Both reasons are collected (not short-circuited) so a caller logging the decision sees every ceiling that
+// was hit, not just the first one checked.
+//
+// KILL-SWITCH (#2339): checked FIRST, before any other logic -- flipping the kill-switch must halt any pending
+// re-entry immediately, the same way it halts the Governor chokepoint (#2340). Reuses
+// `isMinerKillSwitchActive` (kill-switch.ts, #2341) directly -- the identical shared helper
+// `submission-gate.ts`'s `shouldSubmit` consults, per #2339's own "single shared helper, not duplicated per
+// call site" deliverable. Unlike the reasons above, the kill-switch check DOES short-circuit (an active kill-
+// switch is the only reason reported) -- "as their FIRST guard, before any other logic" reads as "don't even
+// evaluate the rest," not "collect this alongside the rest."
+import { isMinerKillSwitchActive } from "../governor/kill-switch.js";
+export const DEFAULT_MAX_CONSECUTIVE_DISENGAGEMENTS = 3;
+export const DEFAULT_MAX_REENTRIES_PER_HOUR = 4;
+export const DEFAULT_MAX_REENTRIES_PER_SESSION = 20;
+/**
+ * Decide whether the loop may re-enter discovery for this repo. Pure; identical inputs always yield the
+ * identical decision. `outcome === "merged"` alone never bypasses the rate/session cap -- a healthy repo can
+ * still be rate-limited if the operator-wide ceiling is already spent. The kill-switch is checked FIRST and
+ * short-circuits everything else -- an active kill-switch blocks unconditionally.
+ */
+export function shouldReenter(candidate) {
+    if (isMinerKillSwitchActive(candidate.killSwitchScope)) {
+        return { reenter: false, reasons: [`${candidate.killSwitchScope}_kill_switch_active`] };
+    }
+    const reasons = [];
+    const maxConsecutiveDisengagements = candidate.maxConsecutiveDisengagements ?? DEFAULT_MAX_CONSECUTIVE_DISENGAGEMENTS;
+    const maxReentriesPerHour = candidate.maxReentriesPerHour ?? DEFAULT_MAX_REENTRIES_PER_HOUR;
+    const maxReentriesPerSession = candidate.maxReentriesPerSession ?? DEFAULT_MAX_REENTRIES_PER_SESSION;
+    if (candidate.outcome === "disengaged" && candidate.consecutiveDisengagements >= maxConsecutiveDisengagements) {
+        reasons.push(`repo_paused_after_consecutive_disengagements:${candidate.consecutiveDisengagements}>=${maxConsecutiveDisengagements}`);
+    }
+    if (candidate.reentriesThisHour >= maxReentriesPerHour) {
+        reasons.push(`hourly_reentry_cap_reached:${candidate.reentriesThisHour}>=${maxReentriesPerHour}`);
+    }
+    if (candidate.reentriesThisSession >= maxReentriesPerSession) {
+        reasons.push(`session_reentry_cap_reached:${candidate.reentriesThisSession}>=${maxReentriesPerSession}`);
+    }
+    return { reenter: reasons.length === 0, reasons };
+}

package/dist/miner/repo-map.d.ts

@@ -0,0 +1,51 @@
+import Parser from "web-tree-sitter";
+export type RepoMapSymbolKind = "function" | "class" | "method" | "interface" | "type";
+export type RepoMapSymbol = {
+    kind: RepoMapSymbolKind;
+    name: string;
+    signature: string;
+    line: number;
+};
+export type RepoMapSkipReason = "unsupported_language" | "grammar_unavailable" | "resource_limit";
+export type RepoMapFileEntry = {
+    path: string;
+    language: string | null;
+    symbols: readonly RepoMapSymbol[];
+    skipped?: RepoMapSkipReason;
+};
+export type RepoMapSourceFile = {
+    path: string;
+    sourceText: string;
+};
+/** Pure: map a file path to the grammar name that would parse it, or null if unsupported. */
+export declare function resolveRepoMapLanguage(path: string): string | null;
+/** Test/injection seam for loading a compiled grammar -- real WASM-file IO lives only in the default
+ *  implementation, so a test can inject a failing loader to exercise `grammar_unavailable` without needing an
+ *  actually-broken WASM file. */
+export type LoadRepoMapLanguageFn = (languageName: string) => Promise<Parser.Language>;
+export type ExtractRepoMapSymbolsOptions = {
+    maxSignatureChars?: number | undefined;
+    maxAstNodes?: number | undefined;
+    maxSymbols?: number | undefined;
+};
+/** Walk a parsed tree collecting one `RepoMapSymbol` per matched node kind (function/class/method/interface/
+ *  type declarations). Pure given an already-parsed tree. Returns `null` when extraction exceeds its work budget. */
+export declare function extractRepoMapSymbols(tree: Parser.Tree, maxSignatureChars?: number): RepoMapSymbol[] | null;
+export declare function extractRepoMapSymbols(tree: Parser.Tree, sourceText: string, options?: ExtractRepoMapSymbolsOptions): RepoMapSymbol[] | null;
+export type BuildRepoMapOptions = {
+    loadLanguage?: LoadRepoMapLanguageFn | undefined;
+    maxSignatureChars?: number | undefined;
+    maxFiles?: number | undefined;
+    maxSourceBytes?: number | undefined;
+    maxTotalSourceBytes?: number | undefined;
+    maxAstNodes?: number | undefined;
+    maxSymbols?: number | undefined;
+};
+/** Build one `RepoMapFileEntry` per source file: unsupported extensions and grammar/parse failures are caught
+ *  and reported via `skipped`, never thrown -- see module header. A language's grammar is only loaded once per
+ *  call even across many files of the same language. */
+export declare function buildRepoMap(files: readonly RepoMapSourceFile[], options?: BuildRepoMapOptions): Promise<RepoMapFileEntry[]>;
+/** Render entries into a bounded plain-text outline: one line per symbol (`kind name (line N): signature`),
+ *  skipped/empty files noted with a one-line placeholder. Stops once `maxOutputChars` would be exceeded and
+ *  appends a truncation marker, so a caller/prompt-builder can tell the map is partial rather than complete. */
+export declare function renderRepoMap(entries: readonly RepoMapFileEntry[], maxOutputChars?: number): string;

package/dist/miner/repo-map.js

@@ -0,0 +1,268 @@
+// Tree-sitter-based repo map builder (#4280): gives a coding-agent driver (or the acceptance-criteria/prompt-
+// packet builders upstream of it) a compact, structural view of a target repository -- function/class/method
+// signatures -- without paying the token cost of dumping full file contents into a prompt. Uses `web-tree-sitter`
+// (the WASM binding) with prebuilt grammars from `tree-sitter-wasms`, not a native addon: this package also ships
+// a Cloudflare Workers deployment target where native Node addons are not an option. This module only ever runs
+// in the local miner/CLI process, but the WASM binding keeps that door open and needs no native build step.
+//
+// Supported today: JavaScript/TypeScript/TSX (this repo's own dominant languages). A file whose extension has no
+// mapped grammar is skipped (not crashed on) with `skipped: "unsupported_language"`; a grammar that fails to load
+// or a parse that throws is caught the same way, with `skipped: "grammar_unavailable"` -- this module's contract
+// is "extract what it safely can," never "block the whole driver invocation."
+//
+// Known scope limit: only `function`/`class` declarations and expressions, `method_definition`, `interface`, and
+// `type` alias nodes are extracted -- an arrow function or class expression bound via a `const foo = ...`
+// declarator is not walked up to its binding identifier, so it is either missed (arrow functions aren't matched
+// at all yet) or reported as "<anonymous>" (a bare class/function expression). Good enough for a compact outline
+// today; resolving binding names is a reasonable follow-up, not attempted here.
+import { Buffer } from "node:buffer";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import Parser from "web-tree-sitter";
+// Lazy, not module-scope: this file is reachable from the Cloudflare Workers bundle (barrel-exported via
+// `@loopover/engine`) even though nothing there ever calls `buildRepoMap`. `import.meta.url` is
+// undefined in that bundle's startup-validation context, so an eager `createRequire(import.meta.url)` at
+// module scope would crash the Worker's deploy before any request is served. Deferring construction to
+// first real use keeps this module import-safe everywhere while still working for its actual CLI callers.
+let cachedRequire = null;
+function requireFromHere() {
+    return (cachedRequire ??= createRequire(import.meta.url));
+}
+/** File extension (including the leading dot) -> tree-sitter grammar name in `tree-sitter-wasms`. */
+const LANGUAGE_BY_EXTENSION = Object.freeze({
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".tsx": "tsx",
+});
+const SYMBOL_NODE_KIND = Object.freeze({
+    function_declaration: "function",
+    // `function_expression`/`class` (bare, unnamed) cover `export default function() {}` / `export default class {}`
+    // and other expression positions -- these have no `name` field, so `nameOf` reports them as "<anonymous>"
+    // rather than skipping them outright.
+    function_expression: "function",
+    class_declaration: "class",
+    class: "class",
+    method_definition: "method",
+    interface_declaration: "interface",
+    type_alias_declaration: "type",
+});
+function extensionOf(path) {
+    const dot = path.lastIndexOf(".");
+    return dot === -1 ? "" : path.slice(dot);
+}
+/** Pure: map a file path to the grammar name that would parse it, or null if unsupported. */
+export function resolveRepoMapLanguage(path) {
+    return LANGUAGE_BY_EXTENSION[extensionOf(path)] ?? null;
+}
+let parserInitialized = null;
+async function defaultLoadRepoMapLanguage(languageName) {
+    parserInitialized ??= Parser.init();
+    await parserInitialized;
+    const wasmPath = requireFromHere().resolve(`tree-sitter-wasms/out/tree-sitter-${languageName}.wasm`);
+    return Parser.Language.load(readFileSync(wasmPath));
+}
+const DEFAULT_MAX_FILES = 200;
+const DEFAULT_MAX_SOURCE_BYTES = 1_000_000;
+const DEFAULT_MAX_TOTAL_SOURCE_BYTES = 5_000_000;
+const DEFAULT_MAX_AST_NODES = 50_000;
+const DEFAULT_MAX_SYMBOLS = 5_000;
+const MAX_NAME_CHARS = 200;
+function boundedNodeText(sourceText, node, maxChars) {
+    return sourceText.slice(node.startIndex, Math.min(node.endIndex, node.startIndex + maxChars));
+}
+/** First line of a symbol node's own text, trimmed and bounded to `maxChars` (with an ellipsis marker when cut),
+ *  so one huge one-line minified function can't blow out the rendered output on its own. */
+function signatureOf(sourceText, node, maxChars) {
+    const end = Math.min(node.endIndex, node.startIndex + maxChars + 1);
+    const newline = sourceText.indexOf("\n", node.startIndex);
+    const sliceEnd = newline === -1 || newline > end ? end : newline;
+    const firstLine = sourceText.slice(node.startIndex, sliceEnd).trim();
+    return node.endIndex - node.startIndex > maxChars &&
+        firstLine.length >= maxChars
+        ? `${firstLine.slice(0, maxChars)}…`
+        : firstLine;
+}
+function nameOf(sourceText, node) {
+    const nameNode = node.childForFieldName("name");
+    if (!nameNode)
+        return "<anonymous>";
+    const name = boundedNodeText(sourceText, nameNode, MAX_NAME_CHARS + 1);
+    return name.length > MAX_NAME_CHARS
+        ? `${name.slice(0, MAX_NAME_CHARS)}…`
+        : name;
+}
+export function extractRepoMapSymbols(tree, sourceTextOrMaxSignatureChars = tree.rootNode.text, options = {}) {
+    const sourceText = typeof sourceTextOrMaxSignatureChars === "string"
+        ? sourceTextOrMaxSignatureChars
+        : tree.rootNode.text;
+    const maxSignatureChars = typeof sourceTextOrMaxSignatureChars === "number"
+        ? sourceTextOrMaxSignatureChars
+        : (options.maxSignatureChars ?? 120);
+    const maxAstNodes = options.maxAstNodes ?? DEFAULT_MAX_AST_NODES;
+    const maxSymbols = options.maxSymbols ?? DEFAULT_MAX_SYMBOLS;
+    const symbols = [];
+    const stack = [tree.rootNode];
+    let visited = 0;
+    while (stack.length > 0) {
+        const node = stack.pop();
+        visited += 1;
+        if (visited > maxAstNodes)
+            return null;
+        const kind = SYMBOL_NODE_KIND[node.type];
+        if (kind) {
+            if (symbols.length >= maxSymbols)
+                return null;
+            symbols.push({
+                kind,
+                name: nameOf(sourceText, node),
+                signature: signatureOf(sourceText, node, maxSignatureChars),
+                line: node.startPosition.row + 1,
+            });
+        }
+        for (let index = node.namedChildCount - 1; index >= 0; index -= 1) {
+            stack.push(node.namedChild(index));
+        }
+    }
+    return symbols;
+}
+/** Build one `RepoMapFileEntry` per source file: unsupported extensions and grammar/parse failures are caught
+ *  and reported via `skipped`, never thrown -- see module header. A language's grammar is only loaded once per
+ *  call even across many files of the same language. */
+export async function buildRepoMap(files, options = {}) {
+    const loadLanguage = options.loadLanguage ?? defaultLoadRepoMapLanguage;
+    const maxSignatureChars = options.maxSignatureChars ?? 120;
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxSourceBytes = options.maxSourceBytes ?? DEFAULT_MAX_SOURCE_BYTES;
+    const maxTotalSourceBytes = options.maxTotalSourceBytes ?? DEFAULT_MAX_TOTAL_SOURCE_BYTES;
+    const maxAstNodes = options.maxAstNodes ?? DEFAULT_MAX_AST_NODES;
+    const maxSymbols = options.maxSymbols ?? DEFAULT_MAX_SYMBOLS;
+    const languageCache = new Map();
+    async function resolveLanguage(name) {
+        const cached = languageCache.get(name);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const language = await loadLanguage(name);
+            languageCache.set(name, language);
+            return language;
+        }
+        catch {
+            languageCache.set(name, null);
+            return null;
+        }
+    }
+    const entries = [];
+    let totalSourceBytes = 0;
+    for (const [index, file] of files.entries()) {
+        if (index >= maxFiles) {
+            entries.push({
+                path: file.path,
+                language: resolveRepoMapLanguage(file.path),
+                symbols: [],
+                skipped: "resource_limit",
+            });
+            continue;
+        }
+        const languageName = resolveRepoMapLanguage(file.path);
+        const sourceBytes = Buffer.byteLength(file.sourceText, "utf8");
+        totalSourceBytes += sourceBytes;
+        if (sourceBytes > maxSourceBytes ||
+            totalSourceBytes > maxTotalSourceBytes) {
+            entries.push({
+                path: file.path,
+                language: languageName,
+                symbols: [],
+                skipped: "resource_limit",
+            });
+            continue;
+        }
+        if (!languageName) {
+            entries.push({
+                path: file.path,
+                language: null,
+                symbols: [],
+                skipped: "unsupported_language",
+            });
+            continue;
+        }
+        const language = await resolveLanguage(languageName);
+        if (!language) {
+            entries.push({
+                path: file.path,
+                language: languageName,
+                symbols: [],
+                skipped: "grammar_unavailable",
+            });
+            continue;
+        }
+        try {
+            const parser = new Parser();
+            parser.setLanguage(language);
+            const tree = parser.parse(file.sourceText);
+            const symbols = extractRepoMapSymbols(tree, file.sourceText, {
+                maxSignatureChars,
+                maxAstNodes,
+                maxSymbols,
+            });
+            entries.push({
+                path: file.path,
+                language: languageName,
+                symbols: symbols ?? [],
+                ...(symbols === null ? { skipped: "resource_limit" } : {}),
+            });
+        }
+        catch {
+            entries.push({
+                path: file.path,
+                language: languageName,
+                symbols: [],
+                skipped: "grammar_unavailable",
+            });
+        }
+    }
+    return entries;
+}
+/** Render entries into a bounded plain-text outline: one line per symbol (`kind name (line N): signature`),
+ *  skipped/empty files noted with a one-line placeholder. Stops once `maxOutputChars` would be exceeded and
+ *  appends a truncation marker, so a caller/prompt-builder can tell the map is partial rather than complete. */
+export function renderRepoMap(entries, maxOutputChars = 20_000) {
+    const lines = [];
+    let length = 0;
+    let truncated = false;
+    function pushLine(line) {
+        const addedLength = length === 0 ? line.length : line.length + 1; // +1 for the joining newline
+        if (length + addedLength > maxOutputChars) {
+            truncated = true;
+            return false;
+        }
+        lines.push(line);
+        length += addedLength;
+        return true;
+    }
+    outer: for (const entry of entries) {
+        if (entry.skipped) {
+            if (!pushLine(`${entry.path}: (skipped: ${entry.skipped})`))
+                break outer;
+        }
+        else if (entry.symbols.length === 0) {
+            if (!pushLine(`${entry.path}: (no symbols)`))
+                break outer;
+        }
+        else {
+            if (!pushLine(`${entry.path}:`))
+                break outer;
+            for (const symbol of entry.symbols) {
+                if (!pushLine(`  ${symbol.kind} ${symbol.name} (line ${symbol.line}): ${symbol.signature}`))
+                    break outer;
+            }
+        }
+    }
+    if (truncated)
+        lines.push("… (repo map truncated to fit the output budget)");
+    return lines.join("\n");
+}