@chemx/starter-kit 26.9.25-943 → 26.9.26-253

package/cli/reader.js

@@ -4,63 +4,27 @@ import { parse } from '@babel/parser';
 import traverseModule from '@babel/traverse';
 import { ANSI } from './theme.js';
 
-const traverse = traverseModule.default || traverseModule;
-
-/**
- * Strips JavaScript/TypeScript comments while preserving line boundaries where possible.
- *
- * @param {string} code Source code.
- * @returns {string} Code without comments.
- */
-export const stripCodeComments = (code) => {
-  return code
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .replace(/(^|[^\:])\/\/.*$/gm, '$1');
-};
-
-/**
- * Collapses consecutive blank lines and trims trailing spaces.
- *
- * @param {string} code Source code.
- * @returns {string} Compact code.
- */
-export const compactCode = (code) => {
-  return code
-    .split('\n')
-    .map((line) => line.trimEnd())
-    .filter((line, idx, arr) => {
-      const isCurrentEmpty = line.trim() === '';
-      const isPrevEmpty = idx > 0 && arr[idx - 1].trim() === '';
-      return !(isCurrentEmpty && isPrevEmpty);
-    })
-    .join('\n');
-};
-
-const resolveDeclarationKind = (declaration) => {
-  const init = declaration.init;
-  if (!init) return 'const';
-
-  if (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') {
-    return 'function';
-  }
-
-  if (init.type !== 'CallExpression') {
-    return 'const';
-  }
+import {
+  stripCodeComments,
+  compactCode,
+  resolveDeclarationKind,
+  summarizeTemplate,
+  extractTemplateContent,
+  generateAstLogicSkeleton
+} from './reader-logic.js';
+import { runReaderCli } from './reader-cli.js';
+
+export {
+  stripCodeComments,
+  compactCode,
+  resolveDeclarationKind,
+  summarizeTemplate,
+  extractTemplateContent,
+  generateAstLogicSkeleton
+} from './reader-logic.js';
+export { runReaderCli } from './reader-cli.js';
 
-  const calleeName = init.callee?.name;
-  if (calleeName === 'computed') {
-    return 'computed';
-  }
-  if (calleeName === 'ref') {
-    return 'ref';
-  }
-  if (calleeName && calleeName.startsWith('use')) {
-    return 'hook';
-  }
-
-  return 'const';
-};
+const traverse = traverseModule.default || traverseModule;
 
 /**
  * Extracts an AST structural outline of a file (types, exports, props, signatures).
@@ -215,6 +179,22 @@ export const extractSymbolBlock = (code, symbol) => {
   };
 };
 
+/**
+ * Appends a compacted logic skeleton after an outline block.
+ * Composable overlay: enriches outline without replacing it.
+ *
+ * @param {string} rawContent Full file source.
+ * @param {string} filePath File path (for template detection).
+ * @param {object} options Reader options forwarded to skeleton generator.
+ * @returns {{ text: string, tokensEst: number }} Enriched section text and token estimate.
+ */
+const enrichOutline = (rawContent, filePath, options) => {
+  const skeleton = generateAstLogicSkeleton(rawContent, filePath, options);
+  const compacted = compactCode(skeleton);
+  const text = `\n// --- Logic Skeleton ---\n${compacted}`;
+  return { text, tokensEst: Math.round(text.length / 3.8) };
+};
+
 /**
  * Primary token-optimized file reader.
  *
@@ -249,14 +229,52 @@ export const readTokenOptimized = (targetPath, options = {}) => {
   const rawLines = rawContent.split('\n');
   const totalLines = rawLines.length;
 
+  if (options.template) {
+    const templateText = extractTemplateContent(rawContent, targetPath);
+    return {
+      file: targetPath,
+      totalLines,
+      mode: 'template',
+      tokensEst: Math.round(templateText.length / 3.8),
+      content: templateText,
+    };
+  }
+
+  if (options.logic) {
+    let logicSource = rawContent;
+    if (options.symbol) {
+      const block = extractSymbolBlock(rawContent, options.symbol);
+      if (!block) {
+        throw new Error(`Symbol "${options.symbol}" not found in ${targetPath}`);
+      }
+      logicSource = block.code;
+    }
+    let logicText = generateAstLogicSkeleton(logicSource, targetPath, options);
+    if (options.compact !== false) {
+      logicText = compactCode(logicText);
+    }
+    return {
+      file: targetPath,
+      totalLines,
+      mode: 'logic',
+      symbol: options.symbol || null,
+      lineCount: logicText.split('\n').length,
+      tokensEst: Math.round(logicText.length / 3.8),
+      content: logicText,
+    };
+  }
+
   if (options.outline) {
     const outlineText = generateAstOutline(rawContent, targetPath);
+    const enriched = options.enrich ? enrichOutline(rawContent, targetPath, options) : null;
     return {
       file: targetPath,
       totalLines,
       mode: 'outline',
       tokensEst: Math.round(outlineText.length / 3.8),
+      tokensEnriched: enriched ? enriched.tokensEst : 0,
       content: outlineText,
+      enriched: enriched ? enriched.text : null,
     };
   }
 
@@ -290,12 +308,15 @@ export const readTokenOptimized = (targetPath, options = {}) => {
       `// To read a specific block, request symbol: chemx({ action: 'read', params: { path: '${rawPath}', symbol: '<name>' } })`,
       `// Or specify a line range: chemx({ action: 'read', params: { path: '${rawPath}', startLine: 1, endLine: 50 } })\n`
     ].join('\n');
+    const enriched = options.enrich ? enrichOutline(rawContent, rawPath, options) : null;
     return {
       file: rawPath,
       totalLines,
       mode: 'auto-outline',
       tokensEst: Math.round((outlineText.length + notice.length) / 3.8),
-      content: notice + outlineText
+      tokensEnriched: enriched ? enriched.tokensEst : 0,
+      content: notice + outlineText,
+      enriched: enriched ? enriched.text : null,
     };
   }
 
@@ -345,117 +366,3 @@ export const readTokenOptimized = (targetPath, options = {}) => {
     content: processedContent,
   };
 };
-
-/**
- * CLI command runner for chemx read / chemx view.
- *
- * @param {string[]} args CLI arguments.
- * @param {boolean} isCli Whether invoked directly from CLI.
- */
-export const runReaderCli = (args, isCli = false) => {
-  if (args.includes('--help') || args.includes('-h') || args.includes('help')) {
-    const isJson = args.includes('--json');
-    if (isJson) {
-      process.stdout.write(JSON.stringify({ help: true, success: true }) + '\n');
-    } else {
-      process.stdout.write([
-        `${ANSI.BOLD}USAGE${ANSI.RESET}`,
-        `  chemx read <file> [options]`,
-        '',
-        `${ANSI.BOLD}OPTIONS${ANSI.RESET}`,
-        `  --outline                AST structure outline only (80%+ token savings)`,
-        `  --symbol=<name>          Extract specific function/hook/interface declaration`,
-        `  --start=<N>              Start line number (1-indexed)`,
-        `  --end=<N>                End line number (1-indexed)`,
-        `  --strip-comments         Remove comments to minimize tokens`,
-        `  --compact                Collapse empty whitespace lines`,
-        `  --json                   Output result as minified JSON`,
-        `  -h, --help               Show this help message`,
-        ''
-      ].join('\n'));
-    }
-    if (isCli) process.exit(0);
-    return { help: true, success: true };
-  }
-
-  const nonFlagArgs = args.filter((a) => !a.startsWith('-'));
-  let filePath = nonFlagArgs[0];
-
-  if (!filePath) {
-    process.stderr.write(`${ANSI.RED}✕ Missing file path. Usage: chemx r <file[:start-end]> [-o] [-s name]${ANSI.RESET}\n`);
-    if (isCli) process.exit(1);
-    return null;
-  }
-
-  let startLine;
-  let endLine;
-
-  const colonMatch = filePath.match(/^([^:]+):(\d+)(?:[-:](\d+))?$/);
-  if (colonMatch) {
-    filePath = colonMatch[1];
-    startLine = parseInt(colonMatch[2], 10);
-    if (colonMatch[3]) endLine = parseInt(colonMatch[3], 10);
-  }
-
-  const isJson = args.includes('--json') || args.includes('-j');
-  const isOutline = args.includes('--outline') || args.includes('-o');
-  const isCompact = args.includes('--compact') || args.includes('-c');
-  const isStripComments = args.includes('--strip-comments') || args.includes('--no-comments') || args.includes('-sc');
-
-  let symbol = null;
-  const symEqFlag = args.find((a) => a.startsWith('--symbol=') || a.startsWith('-sym='));
-  if (symEqFlag) {
-    symbol = symEqFlag.split('=')[1];
-  } else {
-    const sIndex = args.findIndex((a) => a === '-s' || a === '--symbol');
-    if (sIndex !== -1 && args[sIndex + 1] && !args[sIndex + 1].startsWith('-')) {
-      symbol = args[sIndex + 1];
-    } else {
-      const sFlag = args.find((a) => a.startsWith('-s='));
-      if (sFlag) {
-        const val = sFlag.split('=')[1];
-        if (/^\d+$/.test(val)) {
-          if (startLine === undefined) startLine = parseInt(val, 10);
-        } else {
-          symbol = val;
-        }
-      }
-    }
-  }
-
-  if (startLine === undefined) {
-    const startFlag = args.find((a) => a.startsWith('--start='));
-    if (startFlag) startLine = parseInt(startFlag.split('=')[1], 10);
-  }
-
-  if (endLine === undefined) {
-    const endFlag = args.find((a) => a.startsWith('--end=') || a.startsWith('-e='));
-    if (endFlag) endLine = parseInt(endFlag.split('=')[1], 10);
-  }
-
-  try {
-    const res = readTokenOptimized(filePath, {
-      outline: isOutline,
-      compact: isCompact,
-      stripComments: isStripComments,
-      symbol,
-      startLine,
-      endLine,
-    });
-
-    if (isJson) {
-      process.stdout.write(JSON.stringify(res, null, 2) + '\n');
-    } else {
-      process.stdout.write(`${ANSI.BOLD}${ANSI.CYAN}--- ${res.file} (${res.lineCount || res.totalLines} lines, ~${res.tokensEst} tokens) ---${ANSI.RESET}\n`);
-      process.stdout.write(res.content + '\n');
-    }
-
-    if (isCli) process.exit(0);
-    return res;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`${ANSI.RED}✕ ${msg}${ANSI.RESET}\n`);
-    if (isCli) process.exit(1);
-    return null;
-  }
-};

package/cli/search-commands-graph.js

@@ -1,6 +1,11 @@
 import { ANSI } from './theme.js';
 import { toColumnar } from './columnar.js';
-import { calculateBlastRadius } from './search-db.js';
+import {
+  calculateBlastRadius,
+  calculateCallTrace,
+  calculateBacktrace,
+  openIndexDb
+} from './search-db.js';
 
 export const handleBlastRadiusCommand = (db, target, { isJson = false, isCli = true, isColumnar = false, maxDepth = 5 } = {}) => {
   const result = calculateBlastRadius(db, target, { maxDepth });
@@ -80,3 +85,122 @@ export const handleBlastRadiusCommand = (db, target, { isJson = false, isCli = t
   if (isCli) process.exit(0);
   return result;
 };
+
+const renderCalleeTreeLines = (callees, indent = '  ') => {
+  const lines = [];
+  callees.forEach((c, idx) => {
+    const isLast = idx === callees.length - 1;
+    const branch = isLast ? '└── ' : '├── ';
+    const subIndent = isLast ? '    ' : '│   ';
+    const tag = c.isExternal ? `${ANSI.DIM}[external]${ANSI.RESET}` : `${ANSI.GOLD}[${c.tier}]${ANSI.RESET}`;
+    const loc = c.file ? ` ${ANSI.DIM}(${c.file}${c.line ? `:${c.line}` : ''})${ANSI.RESET}` : '';
+    lines.push(`${indent}${branch}${ANSI.BOLD}${c.symbol}${ANSI.RESET} ${tag}${loc}`);
+    if (c.callees && c.callees.length > 0) {
+      lines.push(...renderCalleeTreeLines(c.callees, `${indent}${subIndent}`));
+    }
+  });
+  return lines;
+};
+
+export const handleCallTraceCommand = (db, target, { isJson = false, isCli = true, maxDepth = 3 } = {}) => {
+  const result = calculateCallTrace(db, target, { maxDepth });
+
+  if (isJson) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+    if (isCli) process.exit(0);
+    return result;
+  }
+
+  process.stdout.write(`\n${ANSI.BOLD}${ANSI.CYAN}Forward Call Trace:${ANSI.RESET} ${ANSI.BOLD}${result.target}${ANSI.RESET}\n`);
+  if (result.filePath) {
+    process.stdout.write(`  ${ANSI.DIM}Defined in:${ANSI.RESET} ${result.filePath}:${result.startLine} ${ANSI.DIM}[${result.tier}]${ANSI.RESET}\n`);
+  }
+  process.stdout.write(`  ${ANSI.MINT}Callee Summary:${ANSI.RESET} ${result.totalCallees} downstream calls mapped across ${result.depth} hops\n`);
+
+  if (result.callees.length === 0) {
+    process.stdout.write(`    ${ANSI.DIM}No downstream calls or external invocations detected.${ANSI.RESET}\n\n`);
+    if (isCli) process.exit(0);
+    return result;
+  }
+
+  const treeLines = renderCalleeTreeLines(result.callees, '  ');
+  process.stdout.write(treeLines.join('\n') + '\n\n');
+
+  if (isCli) process.exit(0);
+  return result;
+};
+
+export const handleBacktraceCommand = (db, target, { isJson = false, isCli = true, maxDepth = 5 } = {}) => {
+  const result = calculateBacktrace(db, target, { maxDepth });
+
+  if (isJson) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+    if (isCli) process.exit(0);
+    return result;
+  }
+
+  process.stdout.write(`\n${ANSI.BOLD}${ANSI.CYAN}Backtrace Causal Path:${ANSI.RESET} ${ANSI.BOLD}${result.target}${ANSI.RESET}\n`);
+  if (result.seedPath) {
+    process.stdout.write(`  ${ANSI.DIM}Resolved Target:${ANSI.RESET} ${result.seedPath}\n`);
+  }
+  process.stdout.write(`  ${ANSI.MINT}Caller Summary:${ANSI.RESET} ${result.totalCallers} upstream callers across ${result.depth} causal hops\n`);
+
+  if (result.totalCallers === 0) {
+    process.stdout.write(`    ${ANSI.DIM}No upstream callers found in project imports.${ANSI.RESET}\n\n`);
+    if (isCli) process.exit(0);
+    return result;
+  }
+
+  if (result.chains.length > 0) {
+    process.stdout.write(`  ${ANSI.GOLD}Causal Chains (${result.chains.length}):${ANSI.RESET}\n`);
+    result.chains.slice(0, 10).forEach((chain, idx) => {
+      process.stdout.write(`    ${ANSI.DIM}${idx + 1}.${ANSI.RESET} ${chain}\n`);
+    });
+    if (result.chains.length > 10) {
+      process.stdout.write(`    ${ANSI.DIM}...and ${result.chains.length - 10} more causal chain(s)${ANSI.RESET}\n`);
+    }
+  }
+
+  if (result.rootCallers && result.rootCallers.length > 0) {
+    process.stdout.write(`  ${ANSI.PURPLE}Root Entry Points (${result.rootCallers.length}):${ANSI.RESET}\n`);
+    result.rootCallers.forEach((r) => {
+      process.stdout.write(`    ${ANSI.BOLD}${r.path}${ANSI.RESET} ${ANSI.DIM}[${r.tier}] (depth ${r.depth})${ANSI.RESET}\n`);
+    });
+  }
+
+  process.stdout.write('\n');
+  if (isCli) process.exit(0);
+  return result;
+};
+
+export const runTraceCli = async (args = [], isCli = true) => {
+  const nonFlagArgs = args.filter((a) => !a.startsWith('-'));
+  const target = nonFlagArgs[0];
+  if (!target) {
+    process.stderr.write(`${ANSI.RED}✕ Missing symbol or file target. Usage: chemx trace <symbol> [--max-depth=N] [--json]${ANSI.RESET}\n`);
+    if (isCli) process.exit(1);
+    return null;
+  }
+  const isJson = args.includes('--json') || args.includes('-j');
+  const maxDepthFlag = args.find((a) => a.startsWith('--max-depth=') || a.startsWith('-d='));
+  const maxDepth = maxDepthFlag ? parseInt(maxDepthFlag.split('=')[1], 10) : 3;
+
+  const db = openIndexDb(process.cwd());
+  return handleCallTraceCommand(db, target, { isJson, isCli, maxDepth });
+};
+
+export const runBacktraceCli = async (args = [], isCli = true) => {
+  const nonFlagArgs = args.filter((a) => !a.startsWith('-'));
+  const target = nonFlagArgs[0];
+  if (!target) {
+    process.stderr.write(`${ANSI.RED}✕ Missing symbol or file target. Usage: chemx backtrace <symbol> [--max-depth=N] [--json]${ANSI.RESET}\n`);
+    if (isCli) process.exit(1);
+    return null;
+  }
+  const isJson = args.includes('--json') || args.includes('-j');
+  const maxDepthFlag = args.find((a) => a.startsWith('--max-depth=') || a.startsWith('-d='));
+  const maxDepth = maxDepthFlag ? parseInt(maxDepthFlag.split('=')[1], 10) : 5;
+
+  const db = openIndexDb(process.cwd());
+  return handleBacktraceCommand(db, target, { isJson, isCli, maxDepth });
+};

package/cli/search-commands.js

@@ -384,7 +384,13 @@ export const handleCheckCommand = (targetFile, { isJson = false, isCli = true }
   return payload;
 };
 
-export { handleBlastRadiusCommand } from './search-commands-graph.js';
+export {
+  handleBlastRadiusCommand,
+  handleCallTraceCommand,
+  handleBacktraceCommand,
+  runTraceCli,
+  runBacktraceCli
+} from './search-commands-graph.js';
 export { handleSemanticCommand, handleHybridCommand } from './search-commands-semantic.js';
 
 

package/cli/search-db.js

@@ -17,6 +17,8 @@ export {
   findFileDependencies,
   findFileDependents,
   calculateBlastRadius,
+  calculateCallTrace,
+  calculateBacktrace,
   querySemanticIndex,
   queryHybridIndex,
   syncViolationsIndex,