vibecop 0.4.0 → 0.4.1

package/README.md

@@ -64,7 +64,26 @@ Agent writes code → vibecop hook fires → Findings? Agent fixes → Clean? Co
 }
 ```
 
-Three tools: `vibecop_scan`, `vibecop_check`, `vibecop_explain`.
+Four tools: `vibecop_scan`, `vibecop_check`, `vibecop_explain`, `vibecop_context_benchmark`.
+
+## Context Optimization
+
+Reduce token consumption by ~35% on Read tool re-reads. When Claude Code reads a file it's already seen, vibecop intercepts the Read and serves a compact AST skeleton instead of the full file. Unchanged files get smart-limited to 30 lines + skeleton context.
+
+**Requires bun runtime** (uses `bun:sqlite` for zero-dependency caching).
+
+```bash
+vibecop context benchmark  # See projected savings for your project
+vibecop init --context     # Configure hooks (Claude Code only)
+vibecop context stats      # View actual token savings after sessions
+```
+
+How it works:
+1. **First read** — full file passes through, skeleton is cached
+2. **Re-read (unchanged)** — smart-limited to 30 lines + skeleton injected via `additionalContext`
+3. **Re-read (changed)** — full file passes through with "file changed" note
+
+Skeletons include imports, function signatures, class outlines, and exports — enough for Claude to understand file structure without re-reading the full implementation.
 
 ## Benchmarks
 
@@ -114,7 +133,7 @@ Catches: god functions, N+1 queries, unsafe shell exec, SQL injection, hardcoded
 - [x] **Phase 2.5**: Agent integration (7 tools), 6 LLM/agent detectors, `vibecop init`
 - [x] **Phase 3**: Test quality detectors, custom YAML rules (28 → 35)
 - [x] **Phase 3.5**: MCP server with scan/check/explain tools
-- [ ] **Phase 4**: Context optimization (Read tool interception, AST skeleton caching)
+- [x] **Phase 4**: Context optimization (Read tool interception, AST skeleton caching)
 - [ ] **Phase 5**: VS Code extension, cross-file analysis
 
 ## Links

package/dist/cli.js

@@ -13785,22 +13785,210 @@ var init_insecure_defaults = __esm(() => {
   };
 });
 
-// src/detectors/undeclared-import.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "node:fs";
-import { basename, dirname, join as join2 } from "node:path";
+// src/ast-utils.ts
 function extractJsPackageName(specifier) {
   if (!specifier)
     return null;
   if (specifier.startsWith("@")) {
     const parts = specifier.split("/");
-    if (parts.length >= 2) {
-      return `${parts[0]}/${parts[1]}`;
-    }
-    return null;
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
   }
   const slashIdx = specifier.indexOf("/");
   return slashIdx === -1 ? specifier : specifier.slice(0, slashIdx);
 }
+function findImports(root, language) {
+  if (language === "python")
+    return findPythonImports(root);
+  return findJsImports(root);
+}
+function findJsImports(root) {
+  const results = [];
+  const nodes = root.findAll({ rule: { kind: "import_statement" } });
+  for (const node of nodes) {
+    const sourceNode = node.children().find((ch) => ch.kind() === "string");
+    if (!sourceNode)
+      continue;
+    const source = sourceNode.text().slice(1, -1);
+    results.push({ node, source, text: node.text() });
+  }
+  return results;
+}
+function findPythonImports(root) {
+  const results = [];
+  for (const node of root.findAll({ rule: { kind: "import_statement" } })) {
+    const nameNode = node.children().find((ch) => ch.kind() === "dotted_name" || ch.kind() === "aliased_import");
+    if (!nameNode)
+      continue;
+    let source;
+    if (nameNode.kind() === "aliased_import") {
+      const dotted = nameNode.children().find((ch) => ch.kind() === "dotted_name");
+      source = dotted ? dotted.text() : nameNode.text();
+    } else {
+      source = nameNode.text();
+    }
+    results.push({ node, source, text: node.text() });
+  }
+  for (const node of root.findAll({ rule: { kind: "import_from_statement" } })) {
+    const nameNode = node.children().find((ch) => ch.kind() === "dotted_name");
+    if (!nameNode)
+      continue;
+    results.push({ node, source: nameNode.text(), text: node.text() });
+  }
+  return results;
+}
+function findFunctions(root, language) {
+  if (language === "python")
+    return findPythonFunctions(root);
+  return findJsFunctions(root);
+}
+function findJsFunctions(root) {
+  const results = [];
+  for (const kind of ["function_declaration", "method_definition", "arrow_function"]) {
+    for (const node of root.findAll({ rule: { kind } })) {
+      const name = getJsFunctionName(node);
+      const params = countJsParams(node);
+      const body = node.children().find((c) => c.kind() === "statement_block") ?? null;
+      results.push({ node, name, params, body, kind });
+    }
+  }
+  return results;
+}
+function getJsFunctionName(node) {
+  const kind = node.kind();
+  if (kind === "function_declaration") {
+    return node.children().find((ch) => ch.kind() === "identifier")?.text() ?? "<anonymous>";
+  }
+  if (kind === "method_definition") {
+    const nameNode = node.children().find((ch) => ch.kind() === "property_identifier" || ch.kind() === "identifier");
+    return nameNode?.text() ?? "<anonymous>";
+  }
+  if (kind === "arrow_function") {
+    const parent = node.parent();
+    if (parent?.kind() === "variable_declarator") {
+      return parent.children().find((ch) => ch.kind() === "identifier")?.text() ?? "<anonymous>";
+    }
+    if (parent?.kind() === "pair") {
+      const nameNode = parent.children().find((ch) => ch.kind() === "property_identifier" || ch.kind() === "string");
+      return nameNode?.text() ?? "<anonymous>";
+    }
+    return "<anonymous>";
+  }
+  return "<anonymous>";
+}
+function countJsParams(node) {
+  const params = node.children().find((ch) => ch.kind() === "formal_parameters");
+  if (!params)
+    return 0;
+  return params.children().filter((ch) => {
+    const k = ch.kind();
+    return k !== "(" && k !== ")" && k !== ",";
+  }).length;
+}
+function findPythonFunctions(root) {
+  const results = [];
+  for (const node of root.findAll({ rule: { kind: "function_definition" } })) {
+    const nameNode = node.children().find((ch) => ch.kind() === "identifier");
+    const name = nameNode?.text() ?? "<anonymous>";
+    const body = node.children().find((ch) => ch.kind() === "block") ?? null;
+    const params = countPyParams(node);
+    results.push({ node, name, params, body, kind: "function_definition" });
+  }
+  return results;
+}
+function countPyParams(node) {
+  const params = node.children().find((ch) => ch.kind() === "parameters");
+  if (!params)
+    return 0;
+  return params.children().filter((ch) => {
+    const k = ch.kind();
+    if (k === "(" || k === ")" || k === ",")
+      return false;
+    const text = ch.text().split(":")[0].split("=")[0].trim();
+    return text !== "self" && text !== "cls";
+  }).length;
+}
+function findClasses(root, language) {
+  if (language === "python")
+    return findPythonClasses(root);
+  return findJsClasses(root);
+}
+function findJsClasses(root) {
+  const results = [];
+  for (const node of root.findAll({ rule: { kind: "class_declaration" } })) {
+    const nameNode = node.children().find((ch) => ch.kind() === "type_identifier" || ch.kind() === "identifier");
+    const name = nameNode?.text() ?? "<anonymous>";
+    const methods = [];
+    const classBody = node.children().find((ch) => ch.kind() === "class_body");
+    if (classBody) {
+      for (const member of classBody.findAll({ rule: { kind: "method_definition" } })) {
+        const methodName = member.children().find((ch) => ch.kind() === "property_identifier" || ch.kind() === "identifier");
+        if (methodName)
+          methods.push(methodName.text());
+      }
+    }
+    results.push({ node, name, methods });
+  }
+  return results;
+}
+function findPythonClasses(root) {
+  const results = [];
+  for (const node of root.findAll({ rule: { kind: "class_definition" } })) {
+    const nameNode = node.children().find((ch) => ch.kind() === "identifier");
+    const name = nameNode?.text() ?? "<anonymous>";
+    const methods = [];
+    for (const method of node.findAll({ rule: { kind: "function_definition" } })) {
+      const methodName = method.children().find((ch) => ch.kind() === "identifier");
+      if (methodName)
+        methods.push(methodName.text());
+    }
+    results.push({ node, name, methods });
+  }
+  return results;
+}
+function findExports(root, language) {
+  if (language === "python")
+    return [];
+  const results = [];
+  for (const node of root.findAll({ rule: { kind: "export_statement" } })) {
+    const children = node.children();
+    const hasDefault = children.some((ch) => ch.kind() === "default");
+    if (hasDefault) {
+      results.push({ node, name: "default", kind: "default" });
+      continue;
+    }
+    const funcDecl = children.find((ch) => ch.kind() === "function_declaration");
+    if (funcDecl) {
+      const name = funcDecl.children().find((ch) => ch.kind() === "identifier")?.text() ?? "<unknown>";
+      results.push({ node, name, kind: "function" });
+      continue;
+    }
+    const classDecl = children.find((ch) => ch.kind() === "class_declaration");
+    if (classDecl) {
+      const nameNode = classDecl.children().find((ch) => ch.kind() === "type_identifier" || ch.kind() === "identifier");
+      results.push({ node, name: nameNode?.text() ?? "<unknown>", kind: "class" });
+      continue;
+    }
+    const typeDecl = children.find((ch) => ch.kind() === "type_alias_declaration" || ch.kind() === "interface_declaration");
+    if (typeDecl) {
+      const name = typeDecl.children().find((ch) => ch.kind() === "type_identifier")?.text() ?? "<unknown>";
+      results.push({ node, name, kind: "type" });
+      continue;
+    }
+    const lexDecl = children.find((ch) => ch.kind() === "lexical_declaration");
+    if (lexDecl) {
+      const declarator = lexDecl.children().find((ch) => ch.kind() === "variable_declarator");
+      const name = declarator?.children().find((ch) => ch.kind() === "identifier")?.text() ?? "<unknown>";
+      results.push({ node, name, kind: "variable" });
+      continue;
+    }
+    results.push({ node, name: "<unknown>", kind: "variable" });
+  }
+  return results;
+}
+
+// src/detectors/undeclared-import.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "node:fs";
+import { basename, dirname, join as join2 } from "node:path";
 function isRelativeImport(specifier) {
   return specifier.startsWith("./") || specifier.startsWith("../") || specifier === "." || specifier === "..";
 }
@@ -15622,8 +15810,7 @@ function detect6(ctx) {
   const useReducerCount = (source.match(/\buseReducer\s*[<(]/g) || []).length;
   const totalHooks = useStateCount + useEffectCount + useRefCount + useMemoCount + useCallbackCount + useReducerCount;
   const root = ctx.root.root();
-  const importStatements = root.findAll({ rule: { kind: "import_statement" } });
-  const importCount = importStatements.length;
+  const importCount = findImports(root, ctx.file.language).length;
   const lineCount = source.split(`
 `).length;
   const violations = [];
@@ -15699,52 +15886,6 @@ function countComplexity(node, isPython) {
   }
   return count;
 }
-function countJsParams(funcNode) {
-  const params = funcNode.children().find((ch) => ch.kind() === "formal_parameters");
-  if (!params)
-    return 0;
-  return params.children().filter((ch) => {
-    const k = ch.kind();
-    return k !== "(" && k !== ")" && k !== ",";
-  }).length;
-}
-function countPyParams(funcNode) {
-  const params = funcNode.children().find((ch) => ch.kind() === "parameters");
-  if (!params)
-    return 0;
-  const paramNodes = params.children().filter((ch) => {
-    const k = ch.kind();
-    return k !== "(" && k !== ")" && k !== ",";
-  });
-  return paramNodes.filter((ch) => {
-    const text = ch.text().split(":")[0].split("=")[0].trim();
-    return text !== "self" && text !== "cls";
-  }).length;
-}
-function getJsFunctionName(node) {
-  const kind = node.kind();
-  if (kind === "function_declaration") {
-    const nameNode = node.children().find((ch) => ch.kind() === "identifier");
-    return nameNode?.text() ?? "<anonymous>";
-  }
-  if (kind === "method_definition") {
-    const nameNode = node.children().find((ch) => ch.kind() === "property_identifier" || ch.kind() === "identifier");
-    return nameNode?.text() ?? "<anonymous>";
-  }
-  if (kind === "arrow_function") {
-    const parent = node.parent();
-    if (parent?.kind() === "variable_declarator") {
-      const nameNode = parent.children().find((ch) => ch.kind() === "identifier");
-      return nameNode?.text() ?? "<anonymous>";
-    }
-    if (parent?.kind() === "pair") {
-      const nameNode = parent.children().find((ch) => ch.kind() === "property_identifier" || ch.kind() === "string");
-      return nameNode?.text() ?? "<anonymous>";
-    }
-    return "<anonymous>";
-  }
-  return "<anonymous>";
-}
 function buildFinding(ctx, m, severity) {
   return makeLineFinding("god-function", ctx, m.startLine, m.startColumn, `Function '${m.name}' is too complex (${m.lines} lines, cyclomatic complexity ${m.complexity}, ${m.params} params)`, severity, "Break this function into smaller, focused functions. Extract helper methods, use early returns, and reduce branching.", m.endLine, m.endColumn);
 }
@@ -15754,49 +15895,47 @@ function detectJavaScript5(ctx) {
   const maxLines = ctx.config?.maxLines ?? 50;
   const maxComplexity = ctx.config?.maxComplexity ?? 15;
   const maxParams = ctx.config?.maxParams ?? 5;
-  const funcKinds = ["function_declaration", "method_definition", "arrow_function"];
-  for (const kind of funcKinds) {
-    const nodes = root.findAll({ rule: { kind } });
-    for (const node of nodes) {
-      const range = node.range();
-      const lines = range.end.line - range.start.line + 1;
-      if (kind === "arrow_function") {
-        if (lines <= 10)
-          continue;
-        const parent = node.parent();
-        if (!parent)
-          continue;
-        const pk = parent.kind();
-        if (pk !== "variable_declarator" && pk !== "pair" && pk !== "assignment_expression") {
-          continue;
-        }
-      }
-      const name = getJsFunctionName(node);
-      const complexity = 1 + countComplexity(node, false);
-      const params = countJsParams(node);
-      const linesExceeded = lines > maxLines;
-      const complexityExceeded = complexity > maxComplexity;
-      const paramsExceeded = params > maxParams;
-      if (!linesExceeded && !complexityExceeded && !paramsExceeded)
+  const allFunctions = findFunctions(root, ctx.file.language);
+  for (const fn of allFunctions) {
+    const node = fn.node;
+    const range = node.range();
+    const lines = range.end.line - range.start.line + 1;
+    if (fn.kind === "arrow_function") {
+      if (lines <= 10)
         continue;
-      if (!complexityExceeded && !paramsExceeded && complexity <= 2)
+      const parent = node.parent();
+      if (!parent)
+        continue;
+      const pk = parent.kind();
+      if (pk !== "variable_declarator" && pk !== "pair" && pk !== "assignment_expression") {
         continue;
-      let severity = "warning";
-      if (lines > 100 || complexity > 20) {
-        severity = "error";
       }
-      const metrics = {
-        name,
-        lines,
-        complexity,
-        params,
-        startLine: range.start.line + 1,
-        startColumn: range.start.column + 1,
-        endLine: range.end.line + 1,
-        endColumn: range.end.column + 1
-      };
-      findings.push(buildFinding(ctx, metrics, severity));
     }
+    const name = fn.name;
+    const complexity = 1 + countComplexity(node, false);
+    const params = fn.params;
+    const linesExceeded = lines > maxLines;
+    const complexityExceeded = complexity > maxComplexity;
+    const paramsExceeded = params > maxParams;
+    if (!linesExceeded && !complexityExceeded && !paramsExceeded)
+      continue;
+    if (!complexityExceeded && !paramsExceeded && complexity <= 2)
+      continue;
+    let severity = "warning";
+    if (lines > 100 || complexity > 20) {
+      severity = "error";
+    }
+    const metrics = {
+      name,
+      lines,
+      complexity,
+      params,
+      startLine: range.start.line + 1,
+      startColumn: range.start.column + 1,
+      endLine: range.end.line + 1,
+      endColumn: range.end.column + 1
+    };
+    findings.push(buildFinding(ctx, metrics, severity));
   }
   return findings;
 }
@@ -15806,14 +15945,14 @@ function detectPython5(ctx) {
   const maxLines = ctx.config?.maxLines ?? 50;
   const maxComplexity = ctx.config?.maxComplexity ?? 15;
   const maxParams = ctx.config?.maxParams ?? 5;
-  const funcNodes = root.findAll({ rule: { kind: "function_definition" } });
-  for (const node of funcNodes) {
+  const allFunctions = findFunctions(root, ctx.file.language);
+  for (const fn of allFunctions) {
+    const node = fn.node;
     const range = node.range();
     const lines = range.end.line - range.start.line + 1;
-    const nameNode = node.children().find((ch) => ch.kind() === "identifier");
-    const name = nameNode?.text() ?? "<anonymous>";
+    const name = fn.name;
     const complexity = 1 + countComplexity(node, true);
-    const params = countPyParams(node);
+    const params = fn.params;
     const linesExceeded = lines > maxLines;
     const complexityExceeded = complexity > maxComplexity;
     const paramsExceeded = params > maxParams;
@@ -16173,17 +16312,14 @@ function detect8(ctx) {
   if (ctx.source.includes('"use server"') || ctx.source.includes("'use server'"))
     return findings;
   const root = ctx.root.root();
-  const imports = root.findAll({ rule: { kind: "import_statement" } });
+  const imports = findImports(root, ctx.file.language);
   let hasUIImport = false;
   let hasDBImport = false;
   let hasServerImport = false;
   let uiImportName = "";
   let dbImportName = "";
   for (const imp of imports) {
-    const sourceNode = imp.children().find((ch) => ch.kind() === "string");
-    if (!sourceNode)
-      continue;
-    const specifier = sourceNode.text().slice(1, -1);
+    const specifier = imp.source;
     const pkgName = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
     if (UI_IMPORTS.has(pkgName)) {
       hasUIImport = true;
@@ -22710,6 +22846,24 @@ __export(exports_init, {
 import { execSync } from "node:child_process";
 import { existsSync as existsSync6, mkdirSync, readFileSync as readFileSync7, writeFileSync } from "node:fs";
 import { join as join7 } from "node:path";
+function resolveContextScript() {
+  const fromDist = new URL("../dist/context.js", import.meta.url);
+  try {
+    const { existsSync: existsSync7 } = __require("node:fs");
+    if (existsSync7(fromDist))
+      return fromDist.pathname;
+  } catch {}
+  const { resolve: resolve4 } = __require("node:path");
+  return resolve4("dist/context.js");
+}
+function contextCommands() {
+  const script = resolveContextScript();
+  return {
+    pre: `bun ${script} --pre`,
+    post: `bun ${script} --post`,
+    compact: `bun ${script} --compact`
+  };
+}
 function detectTools(cwd) {
   const tools = [];
   tools.push({
@@ -22933,11 +23087,102 @@ After every code edit, run \`${SCAN_CMD}\` and fix any findings before proceedin
 function padEnd(str, len) {
   return str + " ".repeat(Math.max(0, len - str.length));
 }
-async function runInit(cwd) {
+function isBunAvailable() {
+  try {
+    execSync("bun --version", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function generateContextHooks(root) {
+  const generated = [];
+  if (!existsSync6(join7(root, ".claude"))) {
+    console.log("  Context optimization requires Claude Code (.claude/ directory).");
+    return generated;
+  }
+  const settingsPath = join7(root, ".claude", "settings.json");
+  let settings = {};
+  if (existsSync6(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+    } catch {
+      console.log("  Warning: Could not parse .claude/settings.json");
+      return generated;
+    }
+  }
+  const hooks = settings.hooks ?? {};
+  const preHooks = hooks.PreToolUse ?? [];
+  const hasExistingReadHook = preHooks.some((h) => h.matcher && /\bRead\b/.test(h.matcher));
+  if (hasExistingReadHook) {
+    console.log("  Warning: Existing PreToolUse Read hook detected.");
+    console.log("  Context optimization uses updatedInput which is single-consumer.");
+    console.log("  Skipping to avoid conflicts. See docs/agent-integration.md.");
+    generated.push({
+      path: ".claude/settings.json",
+      description: "context hooks skipped (existing Read hook)"
+    });
+    return generated;
+  }
+  const cmds = contextCommands();
+  hooks.PreToolUse = [
+    ...hooks.PreToolUse ?? [],
+    {
+      matcher: "Read",
+      hooks: [{ type: "command", command: cmds.pre }]
+    }
+  ];
+  hooks.PostToolUse = [
+    ...hooks.PostToolUse ?? [],
+    {
+      matcher: "Read",
+      hooks: [{ type: "command", command: cmds.post }]
+    }
+  ];
+  const postCompact = hooks.PostCompact ?? [];
+  postCompact.push({
+    hooks: [{ type: "command", command: cmds.compact }]
+  });
+  hooks.PostCompact = postCompact;
+  settings.hooks = hooks;
+  mkdirSync(join7(root, ".claude"), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
+`);
+  generated.push({
+    path: ".claude/settings.json",
+    description: "context optimization hooks (Pre/Post Read, PostCompact)"
+  });
+  return generated;
+}
+async function runInit(cwd, options) {
   const root = cwd ?? process.cwd();
+  const enableContext = options?.context ?? false;
   console.log("");
   console.log("  vibecop — agent integration setup");
   console.log("");
+  if (enableContext) {
+    if (!isBunAvailable()) {
+      console.log("  Error: Context optimization requires the bun runtime.");
+      console.log("  Install bun: https://bun.sh");
+      console.log("");
+      return;
+    }
+    console.log("  Setting up context optimization...");
+    console.log("");
+    const generated2 = generateContextHooks(root);
+    if (generated2.length > 0) {
+      const maxPath = Math.max(...generated2.map((g) => g.path.length));
+      console.log("  Generated:");
+      for (const file of generated2) {
+        console.log(`    ${padEnd(file.path, maxPath)}  — ${file.description}`);
+      }
+      console.log("");
+    }
+    console.log("  Context optimization configured.");
+    console.log("  Run 'vibecop context stats' to see token savings.");
+    console.log("");
+    return;
+  }
   const tools = detectTools(root);
   const anyDetected = tools.some((t) => t.detected);
   if (!anyDetected) {
@@ -38820,6 +39065,224 @@ var init_stdio2 = __esm(() => {
   init_stdio();
 });
 
+// src/context/skeleton.ts
+import { parse as parse7, Lang as SgLang2, registerDynamicLanguage as registerDynamicLanguage2 } from "@ast-grep/napi";
+import { createRequire as createRequire3 } from "node:module";
+function ensurePython() {
+  if (pythonRegistered2)
+    return;
+  try {
+    const req = createRequire3(import.meta.url);
+    const pythonLang = req("@ast-grep/lang-python");
+    registerDynamicLanguage2({ python: pythonLang });
+    pythonRegistered2 = true;
+  } catch {}
+}
+function languageForExtension(ext) {
+  return EXTENSION_TO_LANG[ext] ?? null;
+}
+function extractSkeleton(source, language) {
+  if (language === "python")
+    ensurePython();
+  const sgLang = LANG_TO_SG[language];
+  let root;
+  try {
+    root = parse7(sgLang, source).root();
+  } catch {
+    return fallbackSkeleton(source);
+  }
+  const lines = [];
+  const imports = findImports(root, language);
+  if (imports.length > 0) {
+    for (const imp of imports) {
+      lines.push(imp.text);
+    }
+    lines.push("");
+  }
+  const classes = findClasses(root, language);
+  for (const cls of classes) {
+    if (language === "python") {
+      lines.push(`class ${cls.name}:`);
+    } else {
+      lines.push(`class ${cls.name} {`);
+    }
+    for (const method of cls.methods) {
+      lines.push(`  ${method}(...)`);
+    }
+    if (language !== "python")
+      lines.push("}");
+    lines.push("");
+  }
+  const functions = findFunctions(root, language);
+  const classMethodNodes = new Set(classes.flatMap((cls) => cls.node.findAll({ rule: { kind: language === "python" ? "function_definition" : "method_definition" } })).map((n) => n.range().start.line));
+  for (const fn of functions) {
+    if (classMethodNodes.has(fn.node.range().start.line))
+      continue;
+    const range = fn.node.range();
+    const sig = source.split(`
+`).slice(range.start.line, range.start.line + 1)[0]?.trim() ?? "";
+    if (sig)
+      lines.push(sig.replace(/\{[\s\S]*$/, "{ ... }"));
+  }
+  if (functions.length > 0 && classes.length === 0)
+    lines.push("");
+  const exports = findExports(root, language);
+  for (const exp of exports) {
+    if (exp.kind === "function" || exp.kind === "class")
+      continue;
+    lines.push(`export ${exp.kind === "default" ? "default" : ""} ${exp.name}`.trim());
+  }
+  const skeleton = lines.join(`
+`).trim();
+  return skeleton || fallbackSkeleton(source);
+}
+function fallbackSkeleton(source) {
+  const lines = source.split(`
+`);
+  const skeleton = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("import ") || trimmed.startsWith("from ") || trimmed.startsWith("export ") || trimmed.startsWith("class ") || /^(async\s+)?function\s/.test(trimmed) || /^(const|let|var)\s+\w+\s*=\s*(async\s+)?\(/.test(trimmed) || /^def\s/.test(trimmed)) {
+      skeleton.push(trimmed);
+    }
+  }
+  return skeleton.join(`
+`);
+}
+var EXTENSION_TO_LANG, LANG_TO_SG, pythonRegistered2 = false;
+var init_skeleton = __esm(() => {
+  EXTENSION_TO_LANG = {
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".py": "python"
+  };
+  LANG_TO_SG = {
+    javascript: SgLang2.JavaScript,
+    typescript: SgLang2.TypeScript,
+    tsx: SgLang2.Tsx,
+    python: "python"
+  };
+});
+
+// src/context/session.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function isSupportedExtension(filePath) {
+  const lastDot = filePath.lastIndexOf(".");
+  if (lastDot === -1)
+    return false;
+  return SUPPORTED_EXTENSIONS.has(filePath.slice(lastDot));
+}
+var SUPPORTED_EXTENSIONS;
+var init_session = __esm(() => {
+  SUPPORTED_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".py"]);
+});
+
+// src/context/benchmark.ts
+var exports_benchmark = {};
+__export(exports_benchmark, {
+  formatBenchmark: () => formatBenchmark,
+  benchmark: () => benchmark
+});
+import { readdirSync as readdirSync5, readFileSync as readFileSync8, statSync as statSync2 } from "node:fs";
+import { extname as extname2, join as join8, relative as relative2, resolve as resolve4 } from "node:path";
+function walkSupported(dir, root, results) {
+  let entries;
+  try {
+    entries = readdirSync5(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith("."))
+      continue;
+    if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "build")
+      continue;
+    const fullPath = join8(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkSupported(fullPath, root, results);
+    } else if (entry.isFile() && isSupportedExtension(fullPath)) {
+      try {
+        const stat = statSync2(fullPath);
+        if (stat.size > 500000 || stat.size === 0)
+          continue;
+        const source = readFileSync8(fullPath, "utf-8");
+        const lang = languageForExtension(extname2(fullPath));
+        if (!lang)
+          continue;
+        const fullTokens = estimateTokens(source);
+        const skeleton = extractSkeleton(source, lang);
+        const skeletonTokens = estimateTokens(skeleton);
+        const reductionPercent = fullTokens > 0 ? Math.round((1 - (skeletonTokens + 128) / fullTokens) * 100) : 0;
+        results.push({
+          path: relative2(root, fullPath),
+          fullTokens,
+          skeletonTokens,
+          reductionPercent: Math.max(0, reductionPercent)
+        });
+      } catch {}
+    }
+  }
+}
+function benchmark(projectRoot) {
+  const root = resolve4(projectRoot);
+  const files = [];
+  walkSupported(root, root, files);
+  const totalTokens = files.reduce((sum, f) => sum + f.fullTokens, 0);
+  const sorted = [...files].sort((a, b) => b.fullTokens - a.fullTokens);
+  const projections = [20, 40, 60].map((rereadPercent) => {
+    const rereadCount = Math.round(files.length * rereadPercent / 100);
+    const rereadFiles = sorted.slice(0, rereadCount);
+    const tokensSaved = rereadFiles.reduce((sum, f) => {
+      const limited = 128 + f.skeletonTokens;
+      return sum + Math.max(0, f.fullTokens - limited);
+    }, 0);
+    return {
+      rereadPercent,
+      tokensSaved,
+      percentOfTotal: totalTokens > 0 ? Math.round(tokensSaved / totalTokens * 100) : 0
+    };
+  });
+  return { files: sorted, totalFiles: files.length, totalTokens, projections };
+}
+function formatBenchmark(result) {
+  if (result.totalFiles === 0) {
+    return "No supported files found (.js, .ts, .tsx, .py).";
+  }
+  const lines = [];
+  lines.push("vibecop context benchmark");
+  lines.push("═════════════════════════");
+  lines.push("");
+  lines.push(`Files:        ${result.totalFiles} supported`);
+  lines.push(`Total tokens: ~${result.totalTokens.toLocaleString()}`);
+  lines.push("");
+  const top = result.files.slice(0, 10);
+  lines.push("Largest files (most savings potential):");
+  const maxPath = Math.max(...top.map((f) => f.path.length), 10);
+  for (const f of top) {
+    const pathPad = f.path.padEnd(maxPath);
+    lines.push(`  ${pathPad}  ${f.fullTokens.toLocaleString().padStart(6)} tokens → skeleton: ${f.skeletonTokens.toLocaleString().padStart(5)} (${f.reductionPercent}% reduction)`);
+  }
+  lines.push("");
+  lines.push("Projected savings per session:");
+  for (const p of result.projections) {
+    lines.push(`  ${p.rereadPercent}% re-read rate:  ~${p.tokensSaved.toLocaleString()} tokens saved (${p.percentOfTotal}% of total Read usage)`);
+  }
+  lines.push("");
+  lines.push("To enable: vibecop init --context");
+  return lines.join(`
+`);
+}
+var init_benchmark = __esm(() => {
+  init_skeleton();
+  init_session();
+});
+
 // src/mcp/server.ts
 function formatScanResult(result) {
   return {
@@ -38897,11 +39360,52 @@ ${availableIds.map((id) => `  - ${id}`).join(`
     ]
   };
 }
-var scanInputSchema, checkInputSchema, explainInputSchema;
+async function handleContextBenchmark(args) {
+  try {
+    const result = benchmark(args.path ?? ".");
+    if (result.totalFiles === 0) {
+      return {
+        content: [{ type: "text", text: "No supported files found (.js, .ts, .tsx, .py)." }]
+      };
+    }
+    const top10 = result.files.slice(0, 10).map((f) => ({
+      file: f.path,
+      tokens: f.fullTokens,
+      skeletonTokens: f.skeletonTokens,
+      reduction: `${f.reductionPercent}%`
+    }));
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            totalFiles: result.totalFiles,
+            totalTokens: result.totalTokens,
+            topFiles: top10,
+            projections: result.projections.map((p) => ({
+              rereadRate: `${p.rereadPercent}%`,
+              tokensSaved: p.tokensSaved,
+              percentOfTotal: `${p.percentOfTotal}%`
+            })),
+            enableCommand: "vibecop init --context"
+          }, null, 2)
+        }
+      ]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error running benchmark: ${message}` }],
+      isError: true
+    };
+  }
+}
+var scanInputSchema, checkInputSchema, explainInputSchema, contextBenchmarkInputSchema;
 var init_server3 = __esm(() => {
   init_zod();
   init_engine();
   init_detectors();
+  init_benchmark();
   scanInputSchema = {
     path: exports_external.string().optional().describe("Directory to scan. Defaults to current working directory."),
     maxFindings: exports_external.number().optional().describe("Maximum findings to return. Default 50.")
@@ -38913,6 +39417,9 @@ var init_server3 = __esm(() => {
   explainInputSchema = {
     detector_id: exports_external.string().describe('The detector ID (e.g., "unsafe-shell-exec", "god-function").')
   };
+  contextBenchmarkInputSchema = {
+    path: exports_external.string().optional().describe("Directory to benchmark. Defaults to current working directory.")
+  };
 });
 
 // src/mcp/index.ts
@@ -38921,11 +39428,11 @@ __export(exports_mcp, {
   startServer: () => startServer,
   createServer: () => createServer
 });
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 function getVersion() {
   try {
     const pkgPath = new URL("../../package.json", import.meta.url);
-    const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
     return pkg.version;
   } catch {
     return "0.0.0";
@@ -38949,6 +39456,10 @@ function createServer() {
     description: "Explain what a vibecop detector checks for, its severity, and category.",
     inputSchema: explainInputSchema
   }, handleExplain);
+  server.registerTool("vibecop_context_benchmark", {
+    description: "Benchmark context optimization potential for a project. Shows per-file skeleton compression ratios and projected token savings at different re-read rates. No bun required.",
+    inputSchema: contextBenchmarkInputSchema
+  }, handleContextBenchmark);
   return server;
 }
 async function startServer() {
@@ -38976,9 +39487,9 @@ var exports_test_rules = {};
 __export(exports_test_rules, {
   runTestRules: () => runTestRules
 });
-import { existsSync as existsSync7, readdirSync as readdirSync5, readFileSync as readFileSync9 } from "node:fs";
-import { join as join8 } from "node:path";
-import { parse as parse7, Lang as SgLang2 } from "@ast-grep/napi";
+import { existsSync as existsSync7, readdirSync as readdirSync6, readFileSync as readFileSync10 } from "node:fs";
+import { join as join9 } from "node:path";
+import { parse as parse8, Lang as SgLang3 } from "@ast-grep/napi";
 function testRule(rule) {
   const details = [];
   let passed = true;
@@ -38990,11 +39501,11 @@ function testRule(rule) {
     };
   }
   const lang = rule.languages[0];
-  const sgLang = LANG_MAP2[lang] ?? SgLang2.JavaScript;
+  const sgLang = LANG_MAP2[lang] ?? SgLang3.JavaScript;
   if (rule.examples.invalid) {
     for (let i = 0;i < rule.examples.invalid.length; i++) {
       const code = rule.examples.invalid[i];
-      const root = parse7(sgLang, code);
+      const root = parse8(sgLang, code);
       const matches = root.root().findAll({
         rule: rule.rule
       });
@@ -39007,7 +39518,7 @@ function testRule(rule) {
   if (rule.examples.valid) {
     for (let i = 0;i < rule.examples.valid.length; i++) {
       const code = rule.examples.valid[i];
-      const root = parse7(sgLang, code);
+      const root = parse8(sgLang, code);
       const matches = root.root().findAll({
         rule: rule.rule
       });
@@ -39029,7 +39540,7 @@ function runTestRules(rulesDir) {
     console.error(`Error: Rules directory not found: ${rulesDir}`);
     return { results: [], passed: 0, failed: 0 };
   }
-  const entries = readdirSync5(rulesDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+  const entries = readdirSync6(rulesDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
   if (entries.length === 0) {
     console.log("No rule files found.");
     return { results: [], passed: 0, failed: 0 };
@@ -39038,10 +39549,10 @@ function runTestRules(rulesDir) {
   let passed = 0;
   let failed = 0;
   for (const entry of entries) {
-    const filePath = join8(rulesDir, entry);
+    const filePath = join9(rulesDir, entry);
     let raw;
     try {
-      raw = readFileSync9(filePath, "utf-8");
+      raw = readFileSync10(filePath, "utf-8");
     } catch {
       console.error(`Could not read ${filePath}`);
       continue;
@@ -39087,17 +39598,17 @@ var init_test_rules = __esm(() => {
   init_custom_rules();
   import_yaml3 = __toESM(require_dist(), 1);
   LANG_MAP2 = {
-    javascript: SgLang2.JavaScript,
-    typescript: SgLang2.TypeScript,
-    tsx: SgLang2.Tsx,
-    python: SgLang2.JavaScript
+    javascript: SgLang3.JavaScript,
+    typescript: SgLang3.TypeScript,
+    tsx: SgLang3.Tsx,
+    python: SgLang3.JavaScript
   };
 });
 
 // src/cli.ts
 import { execSync as execSync2 } from "node:child_process";
-import { readFileSync as readFileSync10 } from "node:fs";
-import { resolve as resolve4 } from "node:path";
+import { readFileSync as readFileSync11 } from "node:fs";
+import { resolve as resolve5 } from "node:path";
 
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
@@ -39641,7 +40152,7 @@ function getFormatter(format, options) {
 function getVersion2() {
   try {
     const pkgPath = new URL("../package.json", import.meta.url);
-    const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
     return pkg.version;
   } catch {
     return "0.0.0";
@@ -39707,7 +40218,7 @@ async function resolveFiles(options, scanRoot) {
   return;
 }
 async function scanAction(scanPath, options) {
-  const scanRoot = resolve4(scanPath ?? ".");
+  const scanRoot = resolve5(scanPath ?? ".");
   const maxFindings = Number.parseInt(options.maxFindings, 10);
   const files = await resolveFiles(options, scanRoot);
   const result = await scan({
@@ -39753,17 +40264,48 @@ function main() {
   program2.name("vibecop").description("AI code quality linter built on ast-grep").version(getVersion2());
   program2.command("scan").description("Scan a directory for code quality issues").argument("[path]", "Directory to scan", ".").option("-f, --format <format>", "Output format (text, json, github, sarif, html, agent, gcc)", "text").option("-c, --config <path>", "Path to config file").option("--no-config", "Disable config file loading").option("--max-findings <number>", "Maximum number of findings to report", "50").option("--verbose", "Show timing information", false).option("--diff <ref>", "Scan only files changed vs git ref").option("--stdin-files", "Read file list from stdin", false).option("--group-by <mode>", "Group findings by 'file' or 'rule'", "file").action(scanAction);
   program2.command("check").description("Check a single file for code quality issues").argument("<file>", "File to check").option("-f, --format <format>", "Output format (text, json, github, sarif, html, agent, gcc)", "text").option("--max-findings <number>", "Maximum number of findings to report", "50").option("--verbose", "Show timing information", false).option("--group-by <mode>", "Group findings by 'file' or 'rule'", "file").action(checkAction);
-  program2.command("init").description("Set up vibecop integration with AI coding tools").action(async () => {
+  program2.command("init").description("Set up vibecop integration with AI coding tools").option("--context", "Enable context optimization (requires bun)", false).action(async (options) => {
     const { runInit: runInit2 } = await Promise.resolve().then(() => (init_init(), exports_init));
-    await runInit2();
+    await runInit2(undefined, { context: options.context });
   });
   program2.command("serve").description("Start MCP server (stdio transport)").action(async () => {
     const { startServer: startServer2 } = await Promise.resolve().then(() => (init_mcp2(), exports_mcp));
     await startServer2();
   });
+  program2.command("context").description("Context optimization — run as hook handler or view stats").argument("[mode]", "Mode: stats | benchmark (default: stats)").option("--pre", "PreToolUse handler (reads stdin)", false).option("--post", "PostToolUse handler (reads stdin)", false).option("--compact", "PostCompact handler (reads stdin)", false).action(async (mode, options) => {
+    if (mode === "benchmark") {
+      const { benchmark: benchmark2, formatBenchmark: formatBenchmark2 } = await Promise.resolve().then(() => (init_benchmark(), exports_benchmark));
+      console.log(formatBenchmark2(benchmark2(process.cwd())));
+      return;
+    }
+    const args = [];
+    if (options.pre)
+      args.push("--pre");
+    else if (options.post)
+      args.push("--post");
+    else if (options.compact)
+      args.push("--compact");
+    else
+      args.push(mode ?? "stats");
+    const { execSync: execSync3 } = await import("node:child_process");
+    const { existsSync: existsSync8 } = await import("node:fs");
+    const distPath = new URL("../dist/context.js", import.meta.url).pathname;
+    const srcPath = new URL("./context.ts", import.meta.url).pathname;
+    const contextPath = existsSync8(distPath) ? distPath : srcPath;
+    try {
+      execSync3(`bun ${contextPath} ${args.join(" ")}`, {
+        stdio: "inherit",
+        cwd: process.cwd()
+      });
+    } catch (err) {
+      if (err && typeof err === "object" && "status" in err) {
+        process.exit(err.status);
+      }
+    }
+  });
   program2.command("test-rules").description("Validate custom rules against their inline examples").option("--rules-dir <path>", "Path to custom rules directory", ".vibecop/rules").action(async (options) => {
     const { runTestRules: runTestRules2 } = await Promise.resolve().then(() => (init_test_rules(), exports_test_rules));
-    const result = runTestRules2(resolve4(options.rulesDir));
+    const result = runTestRules2(resolve5(options.rulesDir));
     process.exit(result.failed > 0 ? 1 : 0);
   });
   program2.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibecop",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "AI code quality toolkit — deterministic linter for the AI coding era",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "build": "bun build src/cli.ts --outdir dist --target node --external @ast-grep/napi --external @ast-grep/lang-python",
+    "build:context": "bun build src/context.ts --outdir dist --target bun --external @ast-grep/napi --external @ast-grep/lang-python",
     "build:action": "npx ncc build src/action/main.ts -o dist/action --source-map --license licenses.txt",
     "test": "bun test",
     "lint": "bunx biome check",
@@ -17,6 +18,7 @@
   },
   "files": [
     "dist/cli.js",
+    "dist/context.js",
     "README.md",
     "LICENSE"
   ],