@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/mcp/server.js

@@ -0,0 +1,132 @@
+import {
+  createToolHandlers
+} from "../chunk-SGGCSHAX.js";
+import "../chunk-EY5ZZUUA.js";
+import {
+  validateToolArguments
+} from "../chunk-HJEWO5EV.js";
+import "../chunk-VL52PL2T.js";
+import "../chunk-AHDWGM7Q.js";
+import "../chunk-BEIZZ73B.js";
+import "../chunk-3CTFIJJB.js";
+import {
+  PUBLIC_TOOL_DESCRIPTORS,
+  TOOL_DESCRIPTORS,
+  toMcpToolList
+} from "../chunk-HQSPJDHI.js";
+import "../chunk-22V37YTK.js";
+import "../chunk-DWKXZ6IF.js";
+import "../chunk-2RRBMNBQ.js";
+import "../chunk-UQNQZXHY.js";
+import "../chunk-ZETTGPAW.js";
+import "../chunk-4H22TLOT.js";
+import "../chunk-B5GEAAYF.js";
+import "../chunk-7AN7U5IZ.js";
+import "../chunk-UGR4QIGS.js";
+import "../chunk-GEFFO6O2.js";
+import "../chunk-NO3U3FJQ.js";
+import "../chunk-DYM4FQEE.js";
+import "../chunk-RM3PY6TG.js";
+import "../chunk-RCMTFSEF.js";
+import "../chunk-ENW4BTBA.js";
+import "../chunk-5BVAH26D.js";
+import {
+  getProjectId
+} from "../chunk-DIYAGQJL.js";
+import "../chunk-UUNHHX4M.js";
+import {
+  BACKBENCHER_BRAIN_VERSION
+} from "../chunk-WIG36E67.js";
+import "../chunk-QLK6ED4Q.js";
+import {
+  BrainDatabase
+} from "../chunk-QKTRECYS.js";
+import "../chunk-3ZTOHHSW.js";
+import "../chunk-BQ3OVQ3P.js";
+import "../chunk-SK6YVHFZ.js";
+import "../chunk-2BSKD7O3.js";
+import "../chunk-KAET47ZL.js";
+import "../chunk-KCDECRJY.js";
+import "../chunk-D2Q4Y47A.js";
+import "../chunk-SM7RFQRO.js";
+import "../chunk-L5TDYKYK.js";
+import "../chunk-ROMM6KMC.js";
+import "../chunk-MLKGABMK.js";
+
+// src/mcp/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+{
+  const toStderr = (...args) => {
+    try {
+      process.stderr.write(args.map((value) => typeof value === "string" ? value : String(value)).join(" ") + "\n");
+    } catch {
+    }
+  };
+  console.log = toStderr;
+  console.info = toStderr;
+  console.debug = toStderr;
+}
+var handlers = createToolHandlers();
+var descriptors = new Map(TOOL_DESCRIPTORS.map((descriptor) => [descriptor.name, descriptor]));
+async function ensureIndexed(context) {
+  try {
+    const raw = await BrainDatabase.getRawInstance(context.projectId, { readonly: true });
+    const files = raw.prepare("SELECT COUNT(*) c FROM brain_file WHERE project_id=?").get(context.projectId).c ?? 0;
+    if (files === 0) {
+      return `No index found for ${context.projectPath}. Run: bb index "${context.projectPath}" (or restart bb mcp after indexing).`;
+    }
+    return null;
+  } catch {
+    return `No index found for ${context.projectPath}. Run: bb index "${context.projectPath}".`;
+  }
+}
+async function indexRequirementRefusal(context, descriptor, args) {
+  if (!descriptor.requiresIndex) return null;
+  const free = descriptor.indexFreeModes ?? [];
+  const mode = typeof args.mode === "string" ? args.mode : void 0;
+  if (mode !== void 0 && free.includes(mode)) return null;
+  const notIndexed = await ensureIndexed(context);
+  if (notIndexed === null) return null;
+  if (free.length === 0) return notIndexed;
+  const blocked = descriptor.modes.filter((m) => !free.includes(m));
+  const names = (modes) => modes.map((m) => `\`${m}\``).join(", ");
+  return `${notIndexed} ${descriptor.name} needs that index for ${names(blocked)}; ${names(free)} ${free.length === 1 ? "does" : "do"} not need an index and ${free.length === 1 ? "works" : "work"} now.`;
+}
+async function startMcpServer(projectPath) {
+  const context = { projectPath, projectId: getProjectId(projectPath) };
+  const server = new Server(
+    { name: "backbencher-brain", version: BACKBENCHER_BRAIN_VERSION },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toMcpToolList(PUBLIC_TOOL_DESCRIPTORS) }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const descriptor = descriptors.get(request.params.name);
+    const handler = handlers[request.params.name];
+    if (!descriptor || !handler) {
+      return { content: [{ type: "text", text: `unknown tool: ${request.params.name}` }], isError: true };
+    }
+    try {
+      const argumentsObject = validateToolArguments(descriptor, request.params.arguments ?? {});
+      const notIndexed = await indexRequirementRefusal(context, descriptor, argumentsObject);
+      if (notIndexed !== null) return { content: [{ type: "text", text: notIndexed }], isError: true };
+      const result = await handler(argumentsObject, context);
+      return result;
+    } catch (error) {
+      return { content: [{ type: "text", text: `error: ${error?.message ?? String(error)}` }], isError: true };
+    }
+  });
+  await server.connect(new StdioServerTransport());
+}
+if (import.meta.main) {
+  const dirArg = process.argv.findIndex((argument) => argument === "--dir");
+  const directory = dirArg !== -1 ? process.argv[dirArg + 1] : process.cwd();
+  startMcpServer(directory).catch((error) => {
+    console.error("MCP server failed:", error?.message ?? String(error));
+    process.exit(1);
+  });
+}
+export {
+  startMcpServer
+};

package/dist/onboard-DIQZV2NW.js

@@ -0,0 +1,161 @@
+import {
+  PUBLIC_TOOL_DESCRIPTORS
+} from "./chunk-HQSPJDHI.js";
+import "./chunk-MLKGABMK.js";
+
+// src/cli/onboard.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+var GUIDANCE_START = "<!-- bb:onboard:start -->";
+var GUIDANCE_END = "<!-- bb:onboard:end -->";
+var BB_TOOL_NAME_RE = /\bbb_[a-z0-9_]+\b/g;
+var RETIRED_GHOST_TOOL_NAMES = [
+  "bb_select",
+  "bb_update",
+  "bb_delete",
+  "bb_insert",
+  "bb_write",
+  "bb_refresh",
+  "bb_refactor",
+  "bb_relationships"
+];
+function oneLine(summary) {
+  const flat = summary.replace(/\s+/g, " ").trim();
+  const stop = flat.indexOf(". ");
+  return stop > 0 ? flat.slice(0, stop + 1) : flat;
+}
+var TASK_DISAMBIGUATION = {
+  bb_search: "Find a symbol, its exact source, or a file \u2014 exact/lexical lookup.",
+  bb_ask: "Ask a natural-language question about behavior and get scored semantic matches.",
+  bb_graph: "Who calls this symbol, and what does it call \u2014 per-symbol callers/callees, depth-bounded.",
+  bb_impact: "What breaks if this symbol changes \u2014 reverse dependencies with a declared budget.",
+  bb_visualize: "Show the dependency overview for a whole project/file/module at once, not one symbol.",
+  bb_annotate: "Write a note on a symbol (agent-authored annotation).",
+  bb_annotations: "Read notes back \u2014 all annotations, or one symbol's.",
+  bb_analyze: "Typed per-mode analysis: callers/callees/stats/complexity/tests.",
+  bb_patterns: "Find dead code, orphans, and anti-patterns.",
+  bb_security: "Find taint flows and injection findings.",
+  bb_health: "Is the index complete, fresh, and healthy.",
+  bb_index: "Reindex just-written or changed files/directories.",
+  bb_edit: "Change source code safely (preview, validate, rollback, reindex).",
+  bb_doc: "Write cited documentation for a symbol, file, module, feature, or API.",
+  bb_migrate: "Plan a cross-language migration with ordering and unsupported mappings.",
+  bb_cross_language: "Show stored cross-language facts for one symbol (declared absent when none)."
+};
+function renderGuidanceBody() {
+  const names = PUBLIC_TOOL_DESCRIPTORS.map((d) => d.name);
+  for (const name of names) {
+    if (!/^bb_[a-z0-9_]+$/.test(name)) throw new Error(`bb onboard: registry name is not a public tool name: ${name}`);
+  }
+  const rows = PUBLIC_TOOL_DESCRIPTORS.map((d) => {
+    const whenToUse = TASK_DISAMBIGUATION[d.name] ?? oneLine(d.documentation.summary);
+    return `| \`${d.name}\` | ${whenToUse} | ${d.mutability === "read" ? "no" : "**yes**"} |`;
+  });
+  const writeTools = PUBLIC_TOOL_DESCRIPTORS.filter((d) => d.mutability !== "read").map((d) => `\`${d.name}\``);
+  return [
+    "# Backbencher Brain (bb)",
+    "",
+    "This project is indexed by bb. Use the bb MCP tools below for code questions \u2014 they read the",
+    "indexed AST (symbols, relationships, taint, embeddings) and report staleness instead of guessing.",
+    "",
+    "| Tool | Use when | Mutates files? |",
+    "|---|---|---|",
+    ...rows,
+    "",
+    `These are the only bb tools (${names.length} total). A name that is not in this table does not exist \u2014`,
+    'if you call it you will get "unavailable tool" and learn nothing.',
+    "",
+    "Read tools answer from the index and declare staleness (`fresh`/`stale`/`missing`); reads that find stale",
+    "files refresh them within budget and say so in the answer.",
+    writeTools.length > 0 ? `Write tools (${writeTools.join(", ")}) change the index or source \u2014 call them only when the user asks for that change.` : "All registered tools are read-only."
+  ].join("\n");
+}
+function renderGuidanceSection() {
+  return `${GUIDANCE_START}
+${renderGuidanceBody()}
+${GUIDANCE_END}
+`;
+}
+function extractGuidanceSection(text) {
+  const start = text.indexOf(GUIDANCE_START);
+  const end = text.indexOf(GUIDANCE_END);
+  if (start === -1 || end === -1 || end < start) return null;
+  return text.slice(start, end + GUIDANCE_END.length + 1);
+}
+function applyGuidanceSection(existing, section) {
+  const current = extractGuidanceSection(existing);
+  if (current !== null) {
+    if (current === section) return { text: existing, action: "replaced" };
+    return { text: existing.replace(current, section), action: "replaced" };
+  }
+  if (existing.trim() === "") return { text: section, action: "inserted" };
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+  return { text: `${existing}${sep}${section}`, action: "appended" };
+}
+function toolNamesIn(text) {
+  return text.match(BB_TOOL_NAME_RE) ?? [];
+}
+function ghostToolNames(text, registryNames = PUBLIC_TOOL_DESCRIPTORS.map((d) => d.name)) {
+  const known = new Set(registryNames);
+  return [...new Set(toolNamesIn(text).filter((n) => !known.has(n)))].sort();
+}
+function missingToolNames(section, registryNames = PUBLIC_TOOL_DESCRIPTORS.map((d) => d.name)) {
+  const mentioned = new Set(toolNamesIn(section));
+  return registryNames.filter((n) => !mentioned.has(n)).sort();
+}
+function guidanceFile(dir) {
+  return path.join(dir, "AGENTS.md");
+}
+function onboard(dir, opts = {}) {
+  const file = opts.file ?? guidanceFile(dir);
+  const section = renderGuidanceSection();
+  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const current = extractGuidanceSection(existing);
+  const ghosts = ghostToolNames(current ?? "");
+  const missing = missingToolNames(current ?? "");
+  if (opts.print) return { dir, file, action: "would-write", changed: false, ghosts, missing };
+  if (opts.check) {
+    if (current === null) return { dir, file, action: "missing", changed: true, ghosts, missing };
+    const conformant = current === section && ghosts.length === 0 && missing.length === 0;
+    return { dir, file, action: conformant ? "unchanged" : "drift", changed: !conformant, ghosts, missing };
+  }
+  const { text, action } = applyGuidanceSection(existing, section);
+  if (text === existing) return { dir, file, action: "unchanged", changed: false, ghosts, missing };
+  writeFileSync(file, text);
+  return { dir, file, action, changed: true, ghosts, missing };
+}
+function renderOnboardResult(r) {
+  switch (r.action) {
+    case "unchanged":
+      return `\u2713 ${r.file} is current (${PUBLIC_TOOL_DESCRIPTORS.length} tools, no ghosts)`;
+    case "drift":
+      return [
+        `\u2717 ${r.file} guidance is out of date`,
+        r.ghosts.length > 0 ? `  ghost tool names: ${r.ghosts.join(", ")}` : "",
+        r.missing.length > 0 ? `  registry tools not mentioned: ${r.missing.join(", ")}` : "",
+        "  run: bb onboard <dir>"
+      ].filter(Boolean).join("\n");
+    case "missing":
+      return `\u2717 ${r.file} has no bb guidance section \u2014 run: bb onboard <dir>`;
+    case "would-write":
+      return renderGuidanceSection();
+    default:
+      return `\u2713 ${r.file} guidance ${r.action} (${PUBLIC_TOOL_DESCRIPTORS.length} tools)`;
+  }
+}
+export {
+  BB_TOOL_NAME_RE,
+  GUIDANCE_END,
+  GUIDANCE_START,
+  RETIRED_GHOST_TOOL_NAMES,
+  TASK_DISAMBIGUATION,
+  applyGuidanceSection,
+  extractGuidanceSection,
+  ghostToolNames,
+  missingToolNames,
+  onboard,
+  renderGuidanceBody,
+  renderGuidanceSection,
+  renderOnboardResult,
+  toolNamesIn
+};

package/dist/override-companion-pass-XR7MHTP7.js

@@ -0,0 +1,117 @@
+import {
+  buildOverrideCompanion
+} from "./chunk-OWISBAOF.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/override-companion-pass.ts
+var OVERRIDES = "overrides";
+var CONFIDENCE_FLOOR = 0.7;
+async function populateOverrideCompanion(opts) {
+  const stats = {
+    owners: 0,
+    refiles: 0,
+    reapplied: 0,
+    confirmed: 0,
+    confirmedKeys: [],
+    confirmedIds: [],
+    confirmedIdsMissed: 0,
+    confirmedIdsDuplicates: 0,
+    confirmedNewInReparse: 0,
+    stillGuessKeys: [],
+    stillGuessIds: [],
+    stillGuessIdsMissed: 0,
+    stillGuess: 0,
+    failed: 0
+  };
+  const language = opts.language ?? "perl";
+  const firstParseKeys = /* @__PURE__ */ new WeakMap();
+  const results = opts.results;
+  const reparse = opts.reparse;
+  if (!reparse) return stats;
+  const symbols = results.flatMap((r) => r.success && r.language === language ? r.symbols ?? [] : []);
+  const companion = buildOverrideCompanion(symbols);
+  stats.owners = companion.size;
+  if (companion.size === 0) return stats;
+  const affected = results.filter(
+    (r) => r.success && r.language === language && (r.relationships ?? []).some((x) => x.type === OVERRIDES)
+  );
+  stats.refiles = affected.length;
+  for (const result of affected) {
+    let again;
+    try {
+      again = await reparse(result.filePath, opts.projectPath, { overrideCompanion: companion });
+    } catch {
+      stats.failed++;
+      continue;
+    }
+    if (!again || !again.success || !Array.isArray(again.relationships)) {
+      stats.failed++;
+      continue;
+    }
+    if (Array.isArray(result.relationships)) {
+      const first = /* @__PURE__ */ new Set();
+      for (const r of result.relationships) {
+        if (r?.type !== OVERRIDES) continue;
+        first.add(`${String(r?.target ?? "")}\0${r?.line_number ?? "?"}`);
+      }
+      firstParseKeys.set(result, first);
+    }
+    result.symbols = again.symbols ?? result.symbols;
+    result.relationships = again.relationships;
+    result.imports = again.imports ?? result.imports;
+    stats.reapplied++;
+  }
+  const spansByResult = /* @__PURE__ */ new WeakMap();
+  const relIdOf = (result, rel) => {
+    if (!opts.projectId || !opts.buildSpans || !opts.enclosingSpanId || !opts.fileIdOf) return null;
+    try {
+      let spans = spansByResult.get(result);
+      if (!spans) {
+        if (!result.filePath) return null;
+        const isStoreable = opts.makeStoreableName ? opts.makeStoreableName(!!result.fallback, result.language).isStoreable : () => true;
+        spans = opts.buildSpans(result.symbols ?? [], opts.fileIdOf(result.filePath), isStoreable);
+        spansByResult.set(result, spans);
+      }
+      const line = rel.line_number ?? null;
+      const sourceId = opts.enclosingSpanId(spans, line);
+      if (!sourceId) return null;
+      return `${opts.projectId}:rel:${sourceId}:${String(rel.target ?? "")}:${String(rel.type ?? "")}:${line ?? "?"}`;
+    } catch {
+      return null;
+    }
+  };
+  for (const result of affected) {
+    for (const rel of result.relationships ?? []) {
+      if (rel.type !== OVERRIDES) continue;
+      if (Number(rel.confidence ?? 0) >= CONFIDENCE_FLOOR) {
+        stats.confirmed++;
+        stats.confirmedKeys.push({
+          target: String(rel.target ?? ""),
+          line: rel.line_number ?? null,
+          confidence: Number(rel.confidence ?? 0)
+        });
+        const key = relIdOf(result, rel);
+        if (key) stats.confirmedIds.push({ id: key, confidence: Number(rel.confidence ?? 0) });
+        else stats.confirmedIdsMissed++;
+        const fp = firstParseKeys.get(result);
+        if (fp && !fp.has(`${String(rel.target ?? "")}\0${rel.line_number ?? "?"}`)) {
+          stats.confirmedNewInReparse++;
+        }
+      } else {
+        stats.stillGuess++;
+        stats.stillGuessKeys.push({
+          target: String(rel.target ?? ""),
+          line: rel.line_number ?? null
+        });
+        const skey = relIdOf(result, rel);
+        if (skey) stats.stillGuessIds.push({ id: skey, line: rel.line_number ?? null });
+        else stats.stillGuessIdsMissed++;
+      }
+    }
+  }
+  stats.confirmedIdsDuplicates = stats.confirmedIds.length - new Set(stats.confirmedIds.map((x) => x.id)).size;
+  return stats;
+}
+export {
+  populateOverrideCompanion
+};

package/dist/parallel-indexer-FK2XKZXY.js

@@ -0,0 +1,88 @@
+import {
+  CROSS_SYMBOL_TAINT_QUERY,
+  ParallelIndexerConfig,
+  admitsShellShebang,
+  backfillEmbeddingBlobs,
+  backgroundEmbedMetrics,
+  buildStoreableSpans,
+  calculateGravityScores,
+  collectDirChanges,
+  describePoolWorkerUnavailable,
+  discoverIndexableFiles,
+  embeddingDrainPending,
+  enclosingNonContainerId,
+  enclosingSpanId,
+  enclosingSpanIdByName,
+  flushBackgroundEmbeddings,
+  getIndexingStats,
+  hasValidExtension,
+  indexProjectParallel,
+  makeStoreableName,
+  parallelIndexerCliSkipPatterns,
+  pendingEmbeddingCount,
+  processWithWorkerPool,
+  purgeDeletedFiles,
+  reindexFilesParallel,
+  repairInEdges,
+  resolveCrossSymbolTaints,
+  runBoundedPostProcessing,
+  runPostProcessing,
+  shouldSkipCli,
+  snapshotInEdges,
+  storeResults,
+  surveyEmbeddingIntegrity,
+  surveyEmbeddingModels,
+  wipeProjectData
+} from "./chunk-ZETTGPAW.js";
+import "./chunk-4H22TLOT.js";
+import "./chunk-GEFFO6O2.js";
+import "./chunk-NO3U3FJQ.js";
+import "./chunk-DYM4FQEE.js";
+import "./chunk-QKTRECYS.js";
+import "./chunk-3ZTOHHSW.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-D2Q4Y47A.js";
+import "./chunk-SM7RFQRO.js";
+import "./chunk-L5TDYKYK.js";
+import "./chunk-ROMM6KMC.js";
+import "./chunk-MLKGABMK.js";
+export {
+  CROSS_SYMBOL_TAINT_QUERY,
+  ParallelIndexerConfig,
+  admitsShellShebang,
+  backfillEmbeddingBlobs,
+  backgroundEmbedMetrics,
+  buildStoreableSpans,
+  calculateGravityScores,
+  collectDirChanges,
+  describePoolWorkerUnavailable,
+  discoverIndexableFiles,
+  embeddingDrainPending,
+  enclosingNonContainerId,
+  enclosingSpanId,
+  enclosingSpanIdByName,
+  flushBackgroundEmbeddings,
+  getIndexingStats,
+  hasValidExtension,
+  indexProjectParallel,
+  makeStoreableName,
+  parallelIndexerCliSkipPatterns,
+  pendingEmbeddingCount,
+  processWithWorkerPool,
+  purgeDeletedFiles,
+  reindexFilesParallel,
+  repairInEdges,
+  resolveCrossSymbolTaints,
+  runBoundedPostProcessing,
+  runPostProcessing,
+  shouldSkipCli,
+  snapshotInEdges,
+  storeResults,
+  surveyEmbeddingIntegrity,
+  surveyEmbeddingModels,
+  wipeProjectData
+};