code-survey 1.0.0

package/dist/bin/code-survey.js

@@ -0,0 +1,1620 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/index.ts
+import * as fs6 from "node:fs";
+import * as path8 from "node:path";
+import * as os2 from "node:os";
+import { execSync as execSync2 } from "node:child_process";
+
+// src/scanner.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+var DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  ".code-survey",
+  "node_modules",
+  ".venv",
+  "venv",
+  "dist",
+  "bin",
+  "build",
+  "target",
+  "obj"
+]);
+function calculateHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+function scanDirectory(rootDir, customExcludes = [], maxDepth) {
+  const absoluteRoot = path.resolve(rootDir);
+  const excludeSet = new Set(customExcludes);
+  const results = [];
+  function walk(currentDir, currentDepth = 0) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryName = entry.name;
+      const fullPath = path.join(currentDir, entryName);
+      const relativePath = path.relative(absoluteRoot, fullPath);
+      if (DEFAULT_IGNORED_DIRS.has(entryName) || excludeSet.has(entryName) || excludeSet.has(relativePath)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (maxDepth === undefined || currentDepth < maxDepth) {
+          walk(fullPath, currentDepth + 1);
+        }
+      } else if (entry.isFile()) {
+        const hash = calculateHash(fullPath);
+        results.push({
+          relativePath,
+          absolutePath: fullPath,
+          hash
+        });
+      }
+    }
+  }
+  walk(absoluteRoot);
+  return results;
+}
+
+// src/parser.ts
+import * as path3 from "node:path";
+
+// src/wasm/wasm-loader.ts
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import * as os from "node:os";
+import { fileURLToPath } from "node:url";
+var WASM_FILE_MAP = {
+  typescript: "tree-sitter-typescript.wasm",
+  javascript: "tree-sitter-javascript.wasm",
+  python: "tree-sitter-python.wasm",
+  go: "tree-sitter-go.wasm",
+  java: "tree-sitter-java.wasm",
+  csharp: "tree-sitter-c_sharp.wasm",
+  rust: "tree-sitter-rust.wasm"
+};
+var CDN_BASE_URL = "https://cdn.jsdelivr.net/npm/tree-sitter-wasms@0.1.13/out";
+async function getWasmPath(language) {
+  const fileName = WASM_FILE_MAP[language];
+  if (!fileName) {
+    throw new Error(`Unsupported tree-sitter language: ${language}`);
+  }
+  const currentDir = path2.dirname(fileURLToPath(import.meta.url));
+  const nodeModulesPath = path2.resolve(currentDir, "..", "..", "node_modules", "tree-sitter-wasms", "out", fileName);
+  if (fs2.existsSync(nodeModulesPath)) {
+    return nodeModulesPath;
+  }
+  const localPath = path2.resolve(process.cwd(), "node_modules", "tree-sitter-wasms", "out", fileName);
+  if (fs2.existsSync(localPath)) {
+    return localPath;
+  }
+  const cacheDir = path2.resolve(os.homedir(), ".code-survey", "grammars");
+  const cachePath = path2.resolve(cacheDir, fileName);
+  if (fs2.existsSync(cachePath)) {
+    return cachePath;
+  }
+  if (!fs2.existsSync(cacheDir)) {
+    fs2.mkdirSync(cacheDir, { recursive: true });
+  }
+  const url = `${CDN_BASE_URL}/${fileName}`;
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch WASM from CDN: ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    fs2.writeFileSync(cachePath, buffer);
+    return cachePath;
+  } catch (err) {
+    throw new Error(`Could not resolve or download WASM grammar for ${language}: ${err.message}`);
+  }
+}
+
+// src/parser.ts
+class CodebaseParser {
+  parsers = {};
+  async initialize(fileExtensions) {
+    const extensions = fileExtensions ? new Set(fileExtensions) : null;
+    const loadParser = async (exts, importPath, className, wasmName) => {
+      if (extensions) {
+        const needsLoad = exts.some((ext) => extensions.has(ext));
+        if (!needsLoad)
+          return;
+      }
+      try {
+        const module = await import(importPath);
+        const constructor = module[className];
+        const parser = new constructor;
+        await parser.initialize(await getWasmPath(wasmName));
+        for (const ext of exts) {
+          this.parsers[ext] = parser;
+        }
+      } catch (err) {
+        console.error(`Failed to initialize parser for ${wasmName}: ${err.message}`);
+      }
+    };
+    await loadParser([".ts", ".tsx"], "./parsers/typescript.ts", "TypeScriptParser", "typescript");
+    await loadParser([".js", ".jsx"], "./parsers/javascript.ts", "JavaScriptParser", "javascript");
+    await loadParser([".py"], "./parsers/python.ts", "PythonParser", "python");
+    await loadParser([".go"], "./parsers/go.ts", "GoParser", "go");
+    await loadParser([".java"], "./parsers/java.ts", "JavaParser", "java");
+    await loadParser([".cs"], "./parsers/csharp.ts", "CSharpParser", "csharp");
+    await loadParser([".rs"], "./parsers/rust.ts", "RustParser", "rust");
+  }
+  getParserForFile(filePath) {
+    const ext = path3.extname(filePath);
+    return this.parsers[ext] || null;
+  }
+  parseFile(filePath, code, options) {
+    const parser = this.getParserForFile(filePath);
+    if (!parser) {
+      return { imports: [], exports: [], symbols: [] };
+    }
+    return parser.parse(code, options);
+  }
+}
+
+// src/package-parser.ts
+import * as fs3 from "node:fs";
+import * as path4 from "node:path";
+function parsePackageDependencies(dir) {
+  const deps = {};
+  const pkgJsonPath = path4.join(dir, "package.json");
+  if (fs3.existsSync(pkgJsonPath)) {
+    try {
+      const content = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+      deps.npm = {
+        ...content.dependencies || {},
+        ...content.devDependencies || {}
+      };
+    } catch {}
+  }
+  const goModPath = path4.join(dir, "go.mod");
+  if (fs3.existsSync(goModPath)) {
+    try {
+      const content = fs3.readFileSync(goModPath, "utf-8");
+      const goDeps = {};
+      const requireBlockRegex = /require\s*\(([\s\S]*?)\)/g;
+      let match;
+      while ((match = requireBlockRegex.exec(content)) !== null) {
+        const lines = match[1].split(`
+`);
+        for (const line of lines) {
+          const parts = line.trim().split(/\s+/);
+          if (parts.length >= 2 && !parts[0].startsWith("//")) {
+            goDeps[parts[0]] = parts[1];
+          }
+        }
+      }
+      const singleRequireRegex = /^\s*require\s+([a-zA-Z0-9.\-_\/]+)\s+([^\s]+)/gm;
+      while ((match = singleRequireRegex.exec(content)) !== null) {
+        goDeps[match[1]] = match[2];
+      }
+      if (Object.keys(goDeps).length > 0) {
+        deps.go = goDeps;
+      }
+    } catch {}
+  }
+  const pomPath = path4.join(dir, "pom.xml");
+  if (fs3.existsSync(pomPath)) {
+    try {
+      const content = fs3.readFileSync(pomPath, "utf-8");
+      const mavenDeps = {};
+      const depRegex = /<dependency>([\s\S]*?)<\/dependency>/g;
+      let match;
+      while ((match = depRegex.exec(content)) !== null) {
+        const block = match[1];
+        const groupId = block.match(/<groupId>(.*?)<\/groupId>/)?.[1]?.trim();
+        const artifactId = block.match(/<artifactId>(.*?)<\/artifactId>/)?.[1]?.trim();
+        const version = block.match(/<version>(.*?)<\/version>/)?.[1]?.trim();
+        if (groupId && artifactId && version) {
+          mavenDeps[`${groupId}:${artifactId}`] = version;
+        }
+      }
+      if (Object.keys(mavenDeps).length > 0) {
+        deps.maven = mavenDeps;
+      }
+    } catch {}
+  }
+  const files = fs3.readdirSync(dir);
+  const csprojFile = files.find((f) => f.endsWith(".csproj"));
+  if (csprojFile) {
+    try {
+      const content = fs3.readFileSync(path4.join(dir, csprojFile), "utf-8");
+      const nugetDeps = {};
+      const packageRefRegex = /<PackageReference\s+([\s\S]*?)\/>/g;
+      let match;
+      while ((match = packageRefRegex.exec(content)) !== null) {
+        const attrs = match[1];
+        const include = attrs.match(/Include="([^"]+)"/)?.[1];
+        const version = attrs.match(/Version="([^"]+)"/)?.[1];
+        if (include && version) {
+          nugetDeps[include] = version;
+        }
+      }
+      if (Object.keys(nugetDeps).length > 0) {
+        deps.nuget = nugetDeps;
+      }
+    } catch {}
+  }
+  const reqPath = path4.join(dir, "requirements.txt");
+  if (fs3.existsSync(reqPath)) {
+    try {
+      const lines = fs3.readFileSync(reqPath, "utf-8").split(`
+`);
+      const pipDeps = {};
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith("#")) {
+          const match = trimmed.match(/^([^>=<#\s]+)\s*(>=|<=|==|!=|<|>)\s*([^\s]+)/);
+          if (match) {
+            pipDeps[match[1]] = match[2] + match[3];
+          } else {
+            pipDeps[trimmed] = "latest";
+          }
+        }
+      }
+      if (Object.keys(pipDeps).length > 0) {
+        deps.pip = pipDeps;
+      }
+    } catch {}
+  }
+  return deps;
+}
+
+// src/resolver.ts
+import * as path5 from "node:path";
+function resolveImports(files, namespaces, packageDeps) {
+  const externalImports = {};
+  const internalLinks = {};
+  const filePaths = Object.keys(files);
+  const addExternalImport = (pkg, file) => {
+    if (!externalImports[pkg])
+      externalImports[pkg] = [];
+    if (!externalImports[pkg].includes(file)) {
+      externalImports[pkg].push(file);
+    }
+  };
+  const addInternalLink = (targetFile, symbol, sourceFile) => {
+    const key = symbol ? `${targetFile}:${symbol}` : targetFile;
+    if (!internalLinks[key])
+      internalLinks[key] = [];
+    if (!internalLinks[key].includes(sourceFile)) {
+      internalLinks[key].push(sourceFile);
+    }
+  };
+  const npmPackages = new Set(Object.keys(packageDeps.npm || {}));
+  const pipPackages = new Set(Object.keys(packageDeps.pip || {}));
+  const nugetPackages = new Set(Object.keys(packageDeps.nuget || {}));
+  const mavenPackages = new Set(Object.keys(packageDeps.maven || {}));
+  const goPackages = new Set(Object.keys(packageDeps.go || {}));
+  function isExternal(source) {
+    return npmPackages.has(source) || pipPackages.has(source) || nugetPackages.has(source) || mavenPackages.has(source) || goPackages.has(source);
+  }
+  for (const sourceFile of filePaths) {
+    const entry = files[sourceFile];
+    const sourceDir = path5.dirname(sourceFile);
+    for (const imp of entry.imports) {
+      const { source, symbols } = imp;
+      if (isExternal(source)) {
+        addExternalImport(source, sourceFile);
+        continue;
+      }
+      if (source.startsWith(".")) {
+        const resolvedBase = path5.normalize(path5.join(sourceDir, source));
+        const candidates = [
+          resolvedBase,
+          resolvedBase + ".ts",
+          resolvedBase + ".tsx",
+          resolvedBase + ".js",
+          resolvedBase + ".jsx",
+          resolvedBase + ".d.ts",
+          path5.join(resolvedBase, "index.ts"),
+          path5.join(resolvedBase, "index.tsx"),
+          path5.join(resolvedBase, "index.js")
+        ];
+        let resolvedFile = null;
+        for (const cand of candidates) {
+          const normalizedCand = cand.replace(/\\/g, "/");
+          if (files[normalizedCand]) {
+            resolvedFile = normalizedCand;
+            break;
+          }
+        }
+        if (resolvedFile) {
+          if (symbols.length === 0) {
+            addInternalLink(resolvedFile, null, sourceFile);
+          } else {
+            for (const sym of symbols) {
+              addInternalLink(resolvedFile, sym, sourceFile);
+            }
+          }
+        }
+        continue;
+      }
+      const isPythonDotted = sourceFile.endsWith(".py") && !source.includes("/") && (source.includes(".") || source.startsWith("."));
+      if (isPythonDotted) {
+        let normalizedSource = source;
+        if (source.startsWith(".")) {
+          const dots = source.match(/^\.+/)?.[0] || "";
+          const remainder = source.substring(dots.length);
+          const dotCount = dots.length;
+          let targetDir = sourceDir;
+          for (let i = 1;i < dotCount; i++) {
+            targetDir = path5.dirname(targetDir);
+          }
+          normalizedSource = remainder ? path5.join(targetDir, remainder.replace(/\./g, "/")) : targetDir;
+        } else {
+          normalizedSource = source.replace(/\./g, "/");
+        }
+        const candidate = (normalizedSource + ".py").replace(/\\/g, "/");
+        if (files[candidate]) {
+          if (symbols.length === 0) {
+            addInternalLink(candidate, null, sourceFile);
+          } else {
+            for (const sym of symbols) {
+              addInternalLink(candidate, sym, sourceFile);
+            }
+          }
+          continue;
+        }
+      }
+      if (namespaces[source]) {
+        const ns = namespaces[source];
+        for (const targetFile of ns.files) {
+          if (symbols.length === 0) {
+            addInternalLink(targetFile, null, sourceFile);
+          } else {
+            for (const sym of symbols) {
+              const targetEntry = files[targetFile];
+              if (targetEntry && targetEntry.exports.some((e) => e.name === sym)) {
+                addInternalLink(targetFile, sym, sourceFile);
+              }
+            }
+          }
+        }
+        continue;
+      }
+      if (source.includes(".")) {
+        const lastDot = source.lastIndexOf(".");
+        const nsName = source.substring(0, lastDot);
+        const className = source.substring(lastDot + 1);
+        if (namespaces[nsName]) {
+          const ns = namespaces[nsName];
+          for (const targetFile of ns.files) {
+            const targetEntry = files[targetFile];
+            if (targetEntry && targetEntry.exports.some((e) => e.name === className)) {
+              addInternalLink(targetFile, className, sourceFile);
+            }
+          }
+          continue;
+        }
+      }
+      const simpleCandidate = source.replace(/\\/g, "/");
+      if (files[simpleCandidate]) {
+        addInternalLink(simpleCandidate, null, sourceFile);
+      }
+    }
+  }
+  return { externalImports, internalLinks };
+}
+
+// src/writer.ts
+import { stringify } from "yaml";
+import * as fs4 from "node:fs";
+import * as path6 from "node:path";
+function sortObjectKeys(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(sortObjectKeys);
+  }
+  const sortedObj = {};
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sortedObj[key] = sortObjectKeys(obj[key]);
+  }
+  return sortedObj;
+}
+function sortCodeSurveyData(data) {
+  const clone = JSON.parse(JSON.stringify(data));
+  if (clone.project?.languages) {
+    clone.project.languages.sort();
+  }
+  if (clone.files) {
+    for (const fileKey of Object.keys(clone.files)) {
+      const fileEntry = clone.files[fileKey];
+      if (fileEntry.imports) {
+        fileEntry.imports.sort((a, b) => a.source.localeCompare(b.source));
+        for (const imp of fileEntry.imports) {
+          if (imp.symbols)
+            imp.symbols.sort();
+        }
+      }
+      if (fileEntry.exports) {
+        fileEntry.exports.sort((a, b) => a.name.localeCompare(b.name));
+      }
+      if (fileEntry.symbols) {
+        fileEntry.symbols.sort((a, b) => a.name.localeCompare(b.name));
+      }
+    }
+  }
+  if (clone.namespaces) {
+    for (const nsKey of Object.keys(clone.namespaces)) {
+      const nsEntry = clone.namespaces[nsKey];
+      if (nsEntry.files)
+        nsEntry.files.sort();
+      if (nsEntry.exports)
+        nsEntry.exports.sort();
+    }
+  }
+  if (clone.externalImports) {
+    for (const extKey of Object.keys(clone.externalImports)) {
+      clone.externalImports[extKey].sort();
+    }
+  }
+  if (clone.internalLinks) {
+    for (const linkKey of Object.keys(clone.internalLinks)) {
+      clone.internalLinks[linkKey].sort();
+    }
+  }
+  return sortObjectKeys(clone);
+}
+function generateDeterministicJson(data) {
+  const sortedData = sortCodeSurveyData(data);
+  return JSON.stringify(sortedData, null, 2);
+}
+function generateDeterministicYaml(data) {
+  const sortedData = sortCodeSurveyData(data);
+  return stringify(sortedData, { sortMapEntries: true });
+}
+function generateDeterministicMermaid(data) {
+  const sortedData = sortCodeSurveyData(data);
+  const lines = ["graph TD"];
+  const fileKeys = Object.keys(sortedData.files).sort();
+  if (fileKeys.length === 0) {
+    return `graph TD
+`;
+  }
+  const fileToId = {};
+  fileKeys.forEach((fileKey, index) => {
+    fileToId[fileKey] = `node_${index}`;
+    lines.push(`  node_${index}["${fileKey}"]`);
+  });
+  const linkSet = new Set;
+  const linkKeys = Object.keys(sortedData.internalLinks).sort();
+  for (const linkKey of linkKeys) {
+    const sourceFile = linkKey.split(":")[0];
+    const sourceId = fileToId[sourceFile];
+    if (!sourceId)
+      continue;
+    const targets = sortedData.internalLinks[linkKey];
+    for (const targetFile of targets) {
+      const targetId = fileToId[targetFile];
+      if (targetId && sourceId !== targetId) {
+        const edge = `  ${targetId} --> ${sourceId}`;
+        linkSet.add(edge);
+      }
+    }
+  }
+  const sortedEdges = Array.from(linkSet).sort();
+  lines.push(...sortedEdges);
+  return lines.join(`
+`) + `
+`;
+}
+function generateProjectMarkdown(data) {
+  return `# Project: ${data.project.name}
+Languages: ${data.project.languages.join(", ")}
+`;
+}
+function generateDependenciesMarkdown(data) {
+  const lines = [];
+  const depKeys = Object.keys(data.packageDependencies).sort();
+  if (depKeys.length > 0) {
+    lines.push("## Dependencies");
+    for (const key of depKeys) {
+      const deps = data.packageDependencies[key];
+      const items = Object.keys(deps).sort().map((d) => `${d} (${deps[d]})`);
+      if (items.length > 0) {
+        lines.push(`- **${key}**: ${items.join(", ")}`);
+      }
+    }
+  }
+  return lines.length > 0 ? lines.join(`
+`) + `
+` : "";
+}
+function generateFilesMarkdown(data, options) {
+  const lines = [];
+  const fileKeys = Object.keys(data.files).sort();
+  if (fileKeys.length > 0) {
+    lines.push("## Files");
+    for (const fileKey of fileKeys) {
+      const fileEntry = data.files[fileKey];
+      lines.push(`
+### \`${fileKey}\``);
+      lines.push(`Hash: ${fileEntry.hash}`);
+      if (fileEntry.imports.length > 0) {
+        lines.push("- **Imports**:");
+        for (const imp of fileEntry.imports) {
+          const syms = imp.symbols.length > 0 ? `: ${imp.symbols.join(", ")}` : "";
+          lines.push(`  - \`${imp.source}\`${syms}`);
+        }
+      }
+      if (fileEntry.exports.length > 0) {
+        lines.push("- **Exports**:");
+        for (const exp of fileEntry.exports) {
+          const docStr = exp.doc ? ` - ${exp.doc}` : "";
+          const dispName = exp.signature ? `${exp.name}${exp.signature}` : exp.name;
+          lines.push(`  - \`${dispName}\` (${exp.type}, ${exp.location})${docStr}`);
+        }
+      }
+      if (fileEntry.symbols.length > 0) {
+        lines.push("- **Symbols**:");
+        for (const sym of fileEntry.symbols) {
+          const docStr = sym.doc ? ` - ${sym.doc}` : "";
+          const dispName = sym.signature ? `${sym.name}${sym.signature}` : sym.name;
+          lines.push(`  - \`${dispName}\` (${sym.type}, ${sym.location})${docStr}`);
+        }
+      }
+      if (options?.includeToc) {
+        lines.push(`
+[Back to Table of Contents](#table-of-contents)`);
+      }
+    }
+  }
+  return lines.length > 0 ? lines.join(`
+`) + `
+` : "";
+}
+function generateNamespacesMarkdown(data) {
+  const lines = [];
+  const nsKeys = Object.keys(data.namespaces).sort();
+  if (nsKeys.length > 0) {
+    lines.push("## Namespaces");
+    for (const nsKey of nsKeys) {
+      const nsEntry = data.namespaces[nsKey];
+      lines.push(`
+### ${nsKey}`);
+      lines.push(`- **Files**: ${nsEntry.files.join(", ")}`);
+      lines.push(`- **Exports**: ${nsEntry.exports.join(", ")}`);
+    }
+  }
+  return lines.length > 0 ? lines.join(`
+`) + `
+` : "";
+}
+function generateLinksMarkdown(data) {
+  const lines = [];
+  const linkKeys = Object.keys(data.internalLinks).sort();
+  if (linkKeys.length > 0) {
+    lines.push("## Links");
+    for (const linkKey of linkKeys) {
+      const targets = data.internalLinks[linkKey];
+      lines.push(`- \`${linkKey}\` -> ${targets.map((t) => `\`${t}\``).join(", ")}`);
+    }
+  }
+  return lines.length > 0 ? lines.join(`
+`) + `
+` : "";
+}
+function generateDeterministicMarkdown(data, options) {
+  const sortedData = sortCodeSurveyData(data);
+  const parts = [];
+  parts.push(generateProjectMarkdown(sortedData));
+  if (options?.includeToc) {
+    const tocLines = [];
+    tocLines.push("## Table of Contents");
+    tocLines.push("- [Dependencies](#dependencies)");
+    tocLines.push("- [Files](#files)");
+    const fileKeys = Object.keys(sortedData.files).sort();
+    for (const fileKey of fileKeys) {
+      const anchor = fileKey.toLowerCase().replace(/[^a-z0-9]/g, "");
+      tocLines.push(`  - [${fileKey}](#${anchor})`);
+    }
+    const nsKeys = Object.keys(sortedData.namespaces).sort();
+    if (nsKeys.length > 0) {
+      tocLines.push("- [Namespaces](#namespaces)");
+    }
+    const linkKeys = Object.keys(sortedData.internalLinks).sort();
+    if (linkKeys.length > 0) {
+      tocLines.push("- [Links](#links)");
+    }
+    parts.push(tocLines.join(`
+`) + `
+`);
+  }
+  const depsMd = generateDependenciesMarkdown(sortedData);
+  if (depsMd)
+    parts.push(depsMd);
+  const filesMd = generateFilesMarkdown(sortedData, options);
+  if (filesMd)
+    parts.push(filesMd);
+  const nsMd = generateNamespacesMarkdown(sortedData);
+  if (nsMd)
+    parts.push(nsMd);
+  const linksMd = generateLinksMarkdown(sortedData);
+  if (linksMd)
+    parts.push(linksMd);
+  return parts.join(`
+`);
+}
+function writeSurveyOutput(schemaObj, options) {
+  if (!options.output)
+    return;
+  let format = options.format;
+  if (!format) {
+    const ext = path6.extname(options.output).toLowerCase();
+    if (ext === ".yaml" || ext === ".yml") {
+      format = "yaml";
+    } else if (ext === ".md" || ext === ".markdown") {
+      format = "markdown";
+    } else if (ext === ".mermaid" || ext === ".mmd") {
+      format = "mermaid";
+    } else {
+      format = "json";
+    }
+  }
+  if (options.split) {
+    if (!fs4.existsSync(options.output)) {
+      fs4.mkdirSync(options.output, { recursive: true });
+    }
+    const ext = format === "yaml" ? ".yaml" : format === "markdown" ? ".md" : format === "mermaid" ? ".mermaid" : ".json";
+    if (format === "json") {
+      fs4.writeFileSync(path6.join(options.output, `project${ext}`), generateDeterministicJson({ version: schemaObj.version, project: schemaObj.project }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `dependencies${ext}`), generateDeterministicJson({ packageDependencies: schemaObj.packageDependencies }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `files${ext}`), generateDeterministicJson({ files: schemaObj.files }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `namespaces${ext}`), generateDeterministicJson({ namespaces: schemaObj.namespaces }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `links${ext}`), generateDeterministicJson({ externalImports: schemaObj.externalImports, internalLinks: schemaObj.internalLinks }), "utf-8");
+    } else if (format === "yaml") {
+      fs4.writeFileSync(path6.join(options.output, `project${ext}`), generateDeterministicYaml({ version: schemaObj.version, project: schemaObj.project }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `dependencies${ext}`), generateDeterministicYaml({ packageDependencies: schemaObj.packageDependencies }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `files${ext}`), generateDeterministicYaml({ files: schemaObj.files }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `namespaces${ext}`), generateDeterministicYaml({ namespaces: schemaObj.namespaces }), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `links${ext}`), generateDeterministicYaml({ externalImports: schemaObj.externalImports, internalLinks: schemaObj.internalLinks }), "utf-8");
+    } else if (format === "markdown") {
+      fs4.writeFileSync(path6.join(options.output, `project${ext}`), generateProjectMarkdown(schemaObj), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `dependencies${ext}`), generateDependenciesMarkdown(schemaObj), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `files${ext}`), generateFilesMarkdown(schemaObj), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `namespaces${ext}`), generateNamespacesMarkdown(schemaObj), "utf-8");
+      fs4.writeFileSync(path6.join(options.output, `links${ext}`), generateLinksMarkdown(schemaObj), "utf-8");
+    } else if (format === "mermaid") {
+      fs4.writeFileSync(path6.join(options.output, `links${ext}`), generateDeterministicMermaid(schemaObj), "utf-8");
+    }
+  } else {
+    const outputStr = format === "yaml" ? generateDeterministicYaml(schemaObj) : format === "markdown" ? generateDeterministicMarkdown(schemaObj, { includeToc: options.includeToc }) : format === "mermaid" ? generateDeterministicMermaid(schemaObj) : generateDeterministicJson(schemaObj);
+    const outputDir = path6.dirname(options.output);
+    if (!fs4.existsSync(outputDir)) {
+      fs4.mkdirSync(outputDir, { recursive: true });
+    }
+    fs4.writeFileSync(options.output, outputStr, "utf-8");
+  }
+}
+
+// src/cache/cache.ts
+import * as fs5 from "node:fs";
+import * as path7 from "node:path";
+import * as crypto2 from "node:crypto";
+function loadCache(rootDir, options) {
+  const optionsHash = crypto2.createHash("md5").update(JSON.stringify({
+    includeInternalVars: !!options.includeInternalVars,
+    includeDocs: !!options.includeDocs,
+    includeSignatures: !!options.includeSignatures
+  })).digest("hex");
+  const cacheDir = path7.join(rootDir, ".code-survey");
+  const cacheFile = path7.join(cacheDir, "cache.json");
+  let cache = {
+    optionsHash,
+    files: {}
+  };
+  if (fs5.existsSync(cacheFile)) {
+    try {
+      const rawCache = JSON.parse(fs5.readFileSync(cacheFile, "utf-8"));
+      if (rawCache && rawCache.optionsHash === optionsHash && rawCache.files) {
+        cache = rawCache;
+      }
+    } catch {}
+  }
+  return { cache, cacheDir, cacheFile };
+}
+function saveCache(cacheDir, cacheFile, cache) {
+  try {
+    if (!fs5.existsSync(cacheDir)) {
+      fs5.mkdirSync(cacheDir, { recursive: true });
+    }
+    fs5.writeFileSync(cacheFile, JSON.stringify(cache, null, 2), "utf-8");
+  } catch {}
+}
+
+// src/git/git.ts
+import { execSync } from "node:child_process";
+function getGitChangedFiles(rootDir, diffTarget) {
+  const changed = new Set;
+  try {
+    const target = typeof diffTarget === "string" ? diffTarget : "HEAD";
+    const diffOutput = execSync(`git diff --name-only ${target}`, { cwd: rootDir, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] });
+    for (const line of diffOutput.split(`
+`)) {
+      const trimmed = line.trim();
+      if (trimmed)
+        changed.add(trimmed);
+    }
+    const statusOutput = execSync("git status --porcelain", { cwd: rootDir, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] });
+    for (const line of statusOutput.split(`
+`)) {
+      const trimmed = line.trim();
+      if (trimmed) {
+        const filePath = trimmed.substring(3).trim();
+        if (filePath)
+          changed.add(filePath);
+      }
+    }
+  } catch {}
+  return changed;
+}
+
+// src/index.ts
+async function createCodeSurvey(options) {
+  let rootDir = path8.resolve(options.root);
+  let tempDir = null;
+  try {
+    if (options.remote) {
+      tempDir = fs6.mkdtempSync(path8.join(os2.tmpdir(), "code-survey-remote-"));
+      const refArg = options.ref ? `--branch ${options.ref} ` : "";
+      execSync2(`git clone --depth 1 ${refArg}${options.remote} "${tempDir}"`, { stdio: ["ignore", "ignore", "pipe"] });
+      rootDir = tempDir;
+    }
+    const ignoreFile = path8.join(rootDir, ".codesurveyignore");
+    const ignoreExcludes = [];
+    if (fs6.existsSync(ignoreFile)) {
+      const content = fs6.readFileSync(ignoreFile, "utf-8");
+      for (const line of content.split(`
+`)) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith("#")) {
+          ignoreExcludes.push(trimmed);
+        }
+      }
+    }
+    const excludes = [...options.excludes || [], ...ignoreExcludes];
+    const scannedFiles = scanDirectory(rootDir, excludes, options.maxDepth);
+    let filesToProcess = scannedFiles;
+    if (options.diff) {
+      const changedFiles = getGitChangedFiles(rootDir, options.diff);
+      filesToProcess = scannedFiles.filter((f) => changedFiles.has(f.relativePath));
+    }
+    const symbolsCount = {
+      class: 0,
+      interface: 0,
+      struct: 0,
+      method: 0,
+      function: 0,
+      variable: 0,
+      type: 0
+    };
+    const parser = new CodebaseParser;
+    const extensionsToInitialize = new Set(filesToProcess.map((f) => path8.extname(f.relativePath)));
+    await parser.initialize(extensionsToInitialize);
+    const files = {};
+    const namespaces = {};
+    const detectedLanguages = new Set;
+    const { cache, cacheDir, cacheFile } = loadCache(rootDir, options);
+    const supportedExtensions = new Set([
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".py",
+      ".go",
+      ".java",
+      ".cs",
+      ".rs"
+    ]);
+    for (const file of filesToProcess) {
+      const ext = path8.extname(file.relativePath);
+      if (!supportedExtensions.has(ext)) {
+        continue;
+      }
+      let lang = "";
+      if (ext === ".ts" || ext === ".tsx") {
+        lang = "typescript";
+      } else if (ext === ".js" || ext === ".jsx") {
+        lang = "javascript";
+      } else if (ext === ".py") {
+        lang = "python";
+      } else if (ext === ".go") {
+        lang = "go";
+      } else if (ext === ".java") {
+        lang = "java";
+      } else if (ext === ".cs") {
+        lang = "csharp";
+      } else if (ext === ".rs") {
+        lang = "rust";
+      }
+      if (lang) {
+        detectedLanguages.add(lang);
+      }
+      try {
+        let parseResult;
+        const cached = cache.files[file.relativePath];
+        if (cached && cached.hash === file.hash) {
+          parseResult = cached;
+        } else {
+          const code = fs6.readFileSync(file.absolutePath, "utf-8");
+          parseResult = parser.parseFile(file.relativePath, code, {
+            includeInternalVars: options.includeInternalVars,
+            includeDocs: options.includeDocs,
+            includeSignatures: options.includeSignatures
+          });
+          cache.files[file.relativePath] = {
+            hash: file.hash,
+            imports: parseResult.imports,
+            exports: parseResult.exports,
+            symbols: parseResult.symbols,
+            namespace: parseResult.namespace
+          };
+        }
+        const filterSymbols = (list) => {
+          if (!options.symbolsFilter)
+            return list;
+          return list.filter((s) => options.symbolsFilter.includes(s.type));
+        };
+        const filteredExports = filterSymbols(parseResult.exports);
+        const filteredSymbols = filterSymbols(parseResult.symbols);
+        for (const exp of filteredExports) {
+          if (exp.type in symbolsCount) {
+            symbolsCount[exp.type]++;
+          }
+        }
+        for (const sym of filteredSymbols) {
+          if (sym.type in symbolsCount) {
+            symbolsCount[sym.type]++;
+          }
+        }
+        files[file.relativePath] = {
+          hash: file.hash,
+          imports: parseResult.imports,
+          exports: filteredExports,
+          symbols: filteredSymbols
+        };
+        if (parseResult.namespace) {
+          const ns = parseResult.namespace;
+          if (!namespaces[ns]) {
+            namespaces[ns] = { files: [], exports: [] };
+          }
+          if (!namespaces[ns].files.includes(file.relativePath)) {
+            namespaces[ns].files.push(file.relativePath);
+          }
+          for (const exp of filteredExports) {
+            if (!namespaces[ns].exports.includes(exp.name)) {
+              namespaces[ns].exports.push(exp.name);
+            }
+          }
+        }
+      } catch {}
+    }
+    if (!options.remote) {
+      saveCache(cacheDir, cacheFile, cache);
+    }
+    const packageDependencies = parsePackageDependencies(rootDir);
+    const { externalImports, internalLinks } = resolveImports(files, namespaces, packageDependencies);
+    let projectName = path8.basename(rootDir) || "project";
+    if (options.remote) {
+      const parts = options.remote.split("/");
+      const last = parts[parts.length - 1];
+      if (last) {
+        projectName = last.replace(/\.git$/, "");
+      }
+    }
+    const schemaObj = {
+      version: "1.0.0",
+      $schema: "https://raw.githubusercontent.com/username/code-survey/main/schema.json",
+      project: {
+        name: projectName,
+        languages: Array.from(detectedLanguages),
+        root: "."
+      },
+      packageDependencies,
+      files,
+      namespaces,
+      externalImports,
+      internalLinks
+    };
+    writeSurveyOutput(schemaObj, options);
+    return {
+      filesCount: Object.keys(files).length,
+      symbolsCount,
+      data: schemaObj
+    };
+  } finally {
+    if (tempDir && fs6.existsSync(tempDir)) {
+      try {
+        fs6.rmSync(tempDir, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+}
+
+// src/mcp-server.ts
+import * as path9 from "node:path";
+import * as readline from "node:readline";
+var PROTOCOL_VERSION = "2024-11-05";
+function runMcpServer() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+  });
+  console.error("Code Survey MCP Server started.");
+  rl.on("line", async (line) => {
+    if (!line.trim())
+      return;
+    try {
+      const message = JSON.parse(line);
+      const { jsonrpc, id, method, params } = message;
+      if (jsonrpc !== "2.0") {
+        sendError(id, -32600, "Invalid Request");
+        return;
+      }
+      switch (method) {
+        case "initialize": {
+          sendResponse(id, {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {
+              tools: {}
+            },
+            serverInfo: {
+              name: "code-survey-mcp",
+              version: "1.0.0"
+            }
+          });
+          break;
+        }
+        case "notifications/initialized": {
+          break;
+        }
+        case "tools/list": {
+          sendResponse(id, {
+            tools: [
+              {
+                name: "get_codebase_survey",
+                description: "Generates and returns the complete codebase survey data, including project details, file mappings, dependencies, and syntax symbols.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    root: { type: "string", description: "The absolute or relative path to the codebase root (defaults to current working directory)." },
+                    includeSignatures: { type: "boolean", description: "Include function parameter signatures and return types (defaults to false)." },
+                    includeDocs: { type: "boolean", description: "Extract docstrings/JSDocs for symbols (defaults to false)." },
+                    includeInternalVars: { type: "boolean", description: "Include local/internal variables (defaults to false)." }
+                  }
+                }
+              },
+              {
+                name: "search_symbols",
+                description: "Searches for matching symbols (classes, functions, methods, variables, types) across the codebase.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    query: { type: "string", description: "The search term/substring to look for (case-insensitive)." },
+                    root: { type: "string", description: "The codebase root directory path." }
+                  },
+                  required: ["query"]
+                }
+              },
+              {
+                name: "get_file_symbols",
+                description: "Retrieves parsed symbol structure, imports, and exports for a specific file relative to codebase root.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    file: { type: "string", description: "The relative file path (e.g. src/index.ts)." },
+                    root: { type: "string", description: "The codebase root directory path." }
+                  },
+                  required: ["file"]
+                }
+              },
+              {
+                name: "get_dependencies",
+                description: "Retrieves project-level external/npm and package dependencies.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    root: { type: "string", description: "The codebase root directory path." }
+                  }
+                }
+              }
+            ]
+          });
+          break;
+        }
+        case "tools/call": {
+          const { name, arguments: args } = params || {};
+          const result = await handleToolCall(name, args || {});
+          sendResponse(id, result);
+          break;
+        }
+        default: {
+          if (id !== undefined) {
+            sendError(id, -32601, `Method not found: ${method}`);
+          }
+          break;
+        }
+      }
+    } catch (err) {
+      sendError(null, -32700, `Parse error: ${err.message}`);
+    }
+  });
+  function sendResponse(id, result) {
+    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + `
+`);
+  }
+  function sendError(id, code, message) {
+    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + `
+`);
+  }
+  async function handleToolCall(name, args) {
+    const root = args.root ? path9.resolve(args.root) : process.cwd();
+    try {
+      switch (name) {
+        case "get_codebase_survey": {
+          const resultObj = await createCodeSurvey({
+            root,
+            includeSignatures: !!args.includeSignatures,
+            includeDocs: !!args.includeDocs,
+            includeInternalVars: !!args.includeInternalVars
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(resultObj.data, null, 2)
+              }
+            ],
+            isError: false
+          };
+        }
+        case "search_symbols": {
+          const resultObj = await createCodeSurvey({
+            root,
+            includeSignatures: true,
+            includeDocs: true
+          });
+          const query = String(args.query).toLowerCase();
+          const matches = [];
+          for (const [filePath, fileEntry] of Object.entries(resultObj.data.files || {})) {
+            const allSymbols = [...fileEntry.exports || [], ...fileEntry.symbols || []];
+            for (const sym of allSymbols) {
+              if (sym.name.toLowerCase().includes(query)) {
+                matches.push({
+                  file: filePath,
+                  name: sym.name,
+                  type: sym.type,
+                  location: sym.location,
+                  signature: sym.signature,
+                  doc: sym.doc
+                });
+              }
+            }
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(matches, null, 2)
+              }
+            ],
+            isError: false
+          };
+        }
+        case "get_file_symbols": {
+          const resultObj = await createCodeSurvey({
+            root,
+            includeSignatures: true,
+            includeDocs: true,
+            includeInternalVars: true
+          });
+          const relativeFile = String(args.file).replace(/\\/g, "/");
+          const fileEntry = resultObj.data.files?.[relativeFile];
+          if (!fileEntry) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `File not found or has no symbols in survey: ${relativeFile}`
+                }
+              ],
+              isError: true
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(fileEntry, null, 2)
+              }
+            ],
+            isError: false
+          };
+        }
+        case "get_dependencies": {
+          const resultObj = await createCodeSurvey({
+            root
+          });
+          const deps = {
+            packageDependencies: resultObj.data.packageDependencies || {},
+            externalImports: resultObj.data.externalImports || []
+          };
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(deps, null, 2)
+              }
+            ],
+            isError: false
+          };
+        }
+        default:
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Unknown tool: ${name}`
+              }
+            ],
+            isError: true
+          };
+      }
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error executing tool: ${err.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+}
+
+// src/cli/cli-parser.ts
+import * as path11 from "node:path";
+
+// src/config/config.ts
+import * as fs7 from "node:fs";
+import * as path10 from "node:path";
+async function resolveConfigOptions(configFilePath) {
+  const ext = path10.extname(configFilePath).toLowerCase();
+  const content = fs7.readFileSync(configFilePath, "utf-8");
+  if (ext === ".yaml" || ext === ".yml") {
+    try {
+      const { parse: parseYaml } = await import("yaml");
+      return parseYaml(content);
+    } catch (err) {
+      console.error(`Error parsing YAML config at ${configFilePath}: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    try {
+      return JSON.parse(content);
+    } catch (err) {
+      console.error(`Error parsing JSON config at ${configFilePath}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+}
+async function loadConfig(configPath, absoluteRoot) {
+  if (configPath) {
+    const absoluteConfig = path10.resolve(configPath);
+    if (!fs7.existsSync(absoluteConfig)) {
+      console.error(`Error: Configuration file not found at ${absoluteConfig}`);
+      process.exit(1);
+    }
+    return resolveConfigOptions(absoluteConfig);
+  }
+  const jsonConfig = path10.join(absoluteRoot, "code-survey.config.json");
+  const yamlConfig = path10.join(absoluteRoot, "code-survey.config.yaml");
+  const ymlConfig = path10.join(absoluteRoot, "code-survey.config.yml");
+  if (fs7.existsSync(jsonConfig)) {
+    return resolveConfigOptions(jsonConfig);
+  } else if (fs7.existsSync(yamlConfig)) {
+    return resolveConfigOptions(yamlConfig);
+  } else if (fs7.existsSync(ymlConfig)) {
+    return resolveConfigOptions(ymlConfig);
+  }
+  return null;
+}
+
+// src/cli/cli-parser.ts
+function printHelp() {
+  console.log(`
+Code Survey - Deterministically maps codebases for AI coding agents.
+
+Usage:
+  code-survey [options]
+
+Options:
+  --root, -r         The root directory of the codebase to map (default: current directory)
+  --output, -o       The output path for the mapped artifact (default: <root>/code-survey.json)
+  --config, -c       Path to a configuration file containing survey option profiles (JSON or YAML)
+  --exclude, -e      Comma-separated list of additional file/folder patterns to exclude
+  --format, -f       The output format: 'json', 'yaml', 'markdown', or 'mermaid' (default: inferred from output path)
+  --internal-vars    Include internal/local variables in the mapping (default: false)
+  --include-docs     Extract docstring/JSDoc summaries for class/function symbols (default: false)
+  --include-signatures Extract function/method parameters and return types (default: false)
+  --include-toc      Generate a Table of Contents and navigation links in Markdown format (default: false)
+  --split            Split the output into multiple modular files (default: false)
+  --max-depth <n>    Maximum directory traversal depth (default: unlimited)
+  --symbols-filter   Comma-separated list of symbol types to keep (e.g. class,method) (default: all)
+  --diff <target>    Generate map only for files changed since <target> (default: HEAD). Staged/unstaged files are always included.
+  --remote <url>     Clone and map a remote Git repository (url/ssh path)
+  --ref <name>       The branch, tag, or commit hash to check out when mapping a remote repository
+  --watch, -w        Watch for file changes and automatically regenerate surveys (default: false)
+  --mcp              Run the built-in MCP (Model Context Protocol) stdio server (default: false)
+  --help, -h         Show this help message
+`);
+}
+async function parseCliArgs(args, cwd) {
+  let root = cwd;
+  let configPath = null;
+  for (let i = 0;i < args.length; i++) {
+    if (args[i] === "--root" || args[i] === "-r") {
+      if (args[i + 1])
+        root = args[i + 1];
+    } else if (args[i] === "--config" || args[i] === "-c") {
+      if (args[i + 1])
+        configPath = args[i + 1];
+    }
+  }
+  const absoluteRoot = path11.resolve(root);
+  const loadedConfig = await loadConfig(configPath, absoluteRoot);
+  let isMultiSurvey = false;
+  let surveysList = [];
+  let configOptions = {};
+  if (loadedConfig) {
+    if (Array.isArray(loadedConfig)) {
+      isMultiSurvey = true;
+      surveysList = loadedConfig;
+    } else if (Array.isArray(loadedConfig.surveys)) {
+      isMultiSurvey = true;
+      surveysList = loadedConfig.surveys;
+    } else {
+      configOptions = loadedConfig;
+    }
+  }
+  let output = configOptions.output;
+  let excludes = configOptions.excludes || [];
+  let format = configOptions.format;
+  let includeInternalVars = configOptions.includeInternalVars ?? false;
+  let includeDocs = configOptions.includeDocs ?? false;
+  let includeSignatures = configOptions.includeSignatures ?? false;
+  let includeToc = configOptions.includeToc ?? false;
+  let split = configOptions.split ?? false;
+  let maxDepth = configOptions.maxDepth;
+  let symbolsFilter = configOptions.symbolsFilter;
+  let diff = configOptions.diff;
+  let remote = configOptions.remote;
+  let ref = configOptions.ref;
+  let watchMode = configOptions.watch ?? false;
+  let mcpMode = configOptions.mcp ?? false;
+  let hasCliOverrides = false;
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    } else if (arg === "--root" || arg === "-r") {
+      i++;
+    } else if (arg === "--config" || arg === "-c") {
+      i++;
+    } else {
+      hasCliOverrides = true;
+      if (arg === "--output" || arg === "-o") {
+        output = args[++i];
+      } else if (arg === "--exclude" || arg === "-e") {
+        const patterns = args[++i];
+        if (patterns) {
+          excludes = [
+            ...excludes,
+            ...patterns.split(",").map((p) => p.trim())
+          ];
+        }
+      } else if (arg === "--format" || arg === "-f") {
+        const val = args[++i];
+        if (val === "json" || val === "yaml" || val === "markdown" || val === "mermaid") {
+          format = val;
+        } else {
+          console.error(`Error: format must be 'json', 'yaml', 'markdown', or 'mermaid', got '${val}'.`);
+          process.exit(1);
+        }
+      } else if (arg === "--internal-vars") {
+        includeInternalVars = true;
+      } else if (arg === "--include-docs") {
+        includeDocs = true;
+      } else if (arg === "--include-signatures") {
+        includeSignatures = true;
+      } else if (arg === "--include-toc") {
+        includeToc = true;
+      } else if (arg === "--split") {
+        split = true;
+      } else if (arg === "--watch" || arg === "-w") {
+        watchMode = true;
+      } else if (arg === "--mcp") {
+        mcpMode = true;
+      } else if (arg === "--max-depth") {
+        const val = args[++i];
+        maxDepth = parseInt(val, 10);
+        if (isNaN(maxDepth)) {
+          console.error(`Error: --max-depth must be a number, got '${val}'.`);
+          process.exit(1);
+        }
+      } else if (arg === "--symbols-filter") {
+        const val = args[++i];
+        if (val) {
+          symbolsFilter = val.split(",").map((s) => s.trim());
+        }
+      } else if (arg === "--diff") {
+        const nextArg = args[i + 1];
+        if (nextArg && !nextArg.startsWith("-")) {
+          diff = nextArg;
+          i++;
+        } else {
+          diff = true;
+        }
+      } else if (arg === "--remote") {
+        remote = args[++i];
+      } else if (arg === "--ref") {
+        ref = args[++i];
+      } else {
+        console.error(`Unknown argument: ${arg}`);
+        printHelp();
+        process.exit(1);
+      }
+    }
+  }
+  return {
+    absoluteRoot,
+    isMultiSurvey,
+    surveysList,
+    hasCliOverrides,
+    options: {
+      output,
+      excludes,
+      format,
+      includeInternalVars,
+      includeDocs,
+      includeSignatures,
+      includeToc,
+      split,
+      maxDepth,
+      symbolsFilter,
+      diff,
+      remote,
+      ref,
+      watchMode,
+      mcpMode
+    }
+  };
+}
+
+// src/cli/watcher.ts
+import * as fs8 from "node:fs";
+import * as path12 from "node:path";
+function startWatcher(absoluteRoot, isMultiSurvey, hasCliOverrides, surveysList, output, split, excludes, executeSurveys) {
+  const allOutputPaths = new Set;
+  if (isMultiSurvey && !hasCliOverrides) {
+    for (const s of surveysList) {
+      const resolvedRoot = s.root ? path12.resolve(absoluteRoot, s.root) : absoluteRoot;
+      const out = s.output ? path12.resolve(resolvedRoot, s.output) : s.split ? path12.join(resolvedRoot, "code-survey-results") : path12.join(resolvedRoot, "code-survey.json");
+      allOutputPaths.add(out);
+    }
+  } else {
+    const out = output ? path12.resolve(output) : split ? path12.join(absoluteRoot, "code-survey-results") : path12.join(absoluteRoot, "code-survey.json");
+    allOutputPaths.add(out);
+  }
+  console.error(`
+Watching for changes in ${absoluteRoot}... (Press Ctrl+C to stop)`);
+  let debounceTimeout = null;
+  let isRunning = false;
+  return fs8.watch(absoluteRoot, { recursive: true }, (eventType, filename) => {
+    if (!filename)
+      return;
+    const relPath = filename.replace(/\\/g, "/");
+    if (relPath.startsWith(".git/") || relPath === ".git" || relPath.startsWith(".code-survey/") || relPath === ".code-survey" || relPath.startsWith("node_modules/") || relPath === "node_modules") {
+      return;
+    }
+    for (const pattern of excludes) {
+      if (relPath.includes(pattern) || relPath.startsWith(pattern)) {
+        return;
+      }
+    }
+    const absChangedPath = path12.resolve(absoluteRoot, filename);
+    for (const outPath of allOutputPaths) {
+      if (absChangedPath === outPath || absChangedPath.startsWith(outPath + path12.sep)) {
+        return;
+      }
+    }
+    if (isRunning)
+      return;
+    if (debounceTimeout)
+      clearTimeout(debounceTimeout);
+    debounceTimeout = setTimeout(async () => {
+      isRunning = true;
+      console.error(`
+File change detected: ${relPath}. Regenerating surveys...`);
+      try {
+        await executeSurveys();
+        console.error(`Regeneration complete.`);
+      } catch (err) {
+        console.error(`Error regenerating: ${err.message}`);
+      } finally {
+        isRunning = false;
+      }
+    }, 300);
+  });
+}
+
+// src/cli/token-estimator.ts
+import * as fs9 from "node:fs";
+import * as path13 from "node:path";
+function reportTokenBudget(absoluteOutput, format, split, result) {
+  if (!fs9.existsSync(absoluteOutput))
+    return;
+  const isDir = fs9.statSync(absoluteOutput).isDirectory();
+  let sizeBytes = 0;
+  let totalLength = 0;
+  const actualExt = isDir ? "" : path13.extname(absoluteOutput).toLowerCase();
+  const actualFormat = format || (isDir ? "json" : actualExt === ".yaml" || actualExt === ".yml" ? "yaml" : actualExt === ".md" || actualExt === ".markdown" ? "markdown" : actualExt === ".mermaid" || actualExt === ".mmd" ? "mermaid" : "json");
+  if (isDir) {
+    const files = fs9.readdirSync(absoluteOutput);
+    for (const f of files) {
+      const fPath = path13.join(absoluteOutput, f);
+      if (fs9.statSync(fPath).isFile()) {
+        sizeBytes += fs9.statSync(fPath).size;
+        totalLength += fs9.readFileSync(fPath, "utf-8").length;
+      }
+    }
+  } else {
+    sizeBytes = fs9.statSync(absoluteOutput).size;
+    totalLength = fs9.readFileSync(absoluteOutput, "utf-8").length;
+  }
+  const sizeKb = (sizeBytes / 1024).toFixed(1);
+  let charToTokenRatio = 3.2;
+  if (actualFormat === "yaml") {
+    charToTokenRatio = 3.7;
+  } else if (actualFormat === "markdown") {
+    charToTokenRatio = 4.2;
+  } else if (actualFormat === "mermaid") {
+    charToTokenRatio = 3.8;
+  }
+  const estTokens = Math.round(totalLength / charToTokenRatio);
+  process.stderr.write(`
+--- Code Survey Token Budget Estimator ---
+`);
+  process.stderr.write(`Output Format:    ${actualFormat}${isDir ? " (split)" : ""}
+`);
+  process.stderr.write(`Files Mapped:     ${result.filesCount}
+`);
+  const symbolLines = [];
+  for (const [key, val] of Object.entries(result.symbolsCount)) {
+    if (val > 0) {
+      symbolLines.push(`  - ${key}: ${val}`);
+    }
+  }
+  if (symbolLines.length > 0) {
+    process.stderr.write(`Symbol Breakdown:
+`);
+    process.stderr.write(symbolLines.join(`
+`) + `
+`);
+  }
+  process.stderr.write(`File Size:        ${sizeKb} KB (${sizeBytes} bytes)
+`);
+  process.stderr.write(`Estimated Tokens: ~${estTokens.toLocaleString()} tokens
+`);
+  process.stderr.write(`--------------------------------------
+
+`);
+}
+
+// bin/code-survey.ts
+import * as path14 from "node:path";
+async function runSurvey(opts) {
+  const absoluteRoot = path14.resolve(opts.root);
+  const absoluteOutput = opts.output ? path14.resolve(opts.output) : opts.split ? path14.join(absoluteRoot, "code-survey-results") : path14.join(absoluteRoot, "code-survey.json");
+  if (opts.remote) {
+    console.error(`Remote repository:   ${opts.remote}`);
+    if (opts.ref) {
+      console.error(`Ref/Branch:          ${opts.ref}`);
+    }
+  } else {
+    console.error(`Mapping codebase at: ${absoluteRoot}`);
+  }
+  console.error(`Output target:       ${absoluteOutput}`);
+  const result = await createCodeSurvey({
+    root: absoluteRoot,
+    output: absoluteOutput,
+    excludes: opts.excludes,
+    format: opts.format,
+    includeInternalVars: opts.includeInternalVars,
+    includeDocs: opts.includeDocs,
+    includeSignatures: opts.includeSignatures,
+    includeToc: opts.includeToc,
+    maxDepth: opts.maxDepth,
+    symbolsFilter: opts.symbolsFilter,
+    diff: opts.diff,
+    remote: opts.remote,
+    ref: opts.ref,
+    split: opts.split
+  });
+  console.error("Code Survey generated successfully!");
+  reportTokenBudget(absoluteOutput, opts.format, opts.split, result);
+}
+async function main() {
+  const { absoluteRoot, isMultiSurvey, surveysList, hasCliOverrides, options } = await parseCliArgs(process.argv.slice(2), process.cwd());
+  const executeSurveys = async () => {
+    if (isMultiSurvey && !hasCliOverrides) {
+      console.error(`Running batch code surveys from configuration (${surveysList.length} targets)...`);
+      for (const survey of surveysList) {
+        console.error(`
+----------------------------------------`);
+        const resolvedRoot = survey.root ? path14.resolve(absoluteRoot, survey.root) : absoluteRoot;
+        await runSurvey({
+          root: resolvedRoot,
+          output: survey.output ? path14.resolve(resolvedRoot, survey.output) : "",
+          excludes: survey.excludes || [],
+          format: survey.format,
+          includeInternalVars: survey.includeInternalVars ?? false,
+          includeDocs: survey.includeDocs ?? false,
+          includeSignatures: survey.includeSignatures ?? false,
+          includeToc: survey.includeToc ?? false,
+          maxDepth: survey.maxDepth,
+          symbolsFilter: survey.symbolsFilter,
+          diff: survey.diff,
+          remote: survey.remote,
+          ref: survey.ref,
+          split: survey.split ?? false
+        });
+      }
+    } else {
+      await runSurvey({
+        root: absoluteRoot,
+        output: options.output || "",
+        excludes: options.excludes,
+        format: options.format,
+        includeInternalVars: options.includeInternalVars,
+        includeDocs: options.includeDocs,
+        includeSignatures: options.includeSignatures,
+        includeToc: options.includeToc,
+        maxDepth: options.maxDepth,
+        symbolsFilter: options.symbolsFilter,
+        diff: options.diff,
+        remote: options.remote,
+        ref: options.ref,
+        split: options.split
+      });
+    }
+  };
+  try {
+    if (options.mcpMode) {
+      runMcpServer();
+    } else {
+      await executeSurveys();
+      if (options.watchMode) {
+        startWatcher(absoluteRoot, isMultiSurvey, hasCliOverrides, surveysList, options.output, options.split, options.excludes, executeSurveys);
+      }
+    }
+  } catch (err) {
+    console.error(`Error generating code-survey: ${err.message}`);
+    process.exit(1);
+  }
+}
+main();