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

package/cli/search-queries-graph.js

@@ -1,4 +1,23 @@
+import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
+import { extractSymbolBlock } from './reader.js';
+
+const _require = createRequire(import.meta.url);
+let _parse = null;
+let _traverse = null;
+const loadBabel = () => {
+  if (_parse) return { parse: _parse, traverse: _traverse };
+  try {
+    _parse = _require('@babel/parser').parse;
+    const t = _require('@babel/traverse');
+    _traverse = t.default?.default || t.default || t;
+  } catch {
+    _parse = null;
+    _traverse = null;
+  }
+  return { parse: _parse, traverse: _traverse };
+};
 
 const isSpecOrTest = (filePath) => {
   if (!filePath || typeof filePath !== 'string') return false;
@@ -107,3 +126,278 @@ export const calculateBlastRadius = (db, targetPathOrSymbol, options = {}) => {
     tiers
   };
 };
+
+/**
+ * Extracts called function and method symbols from a code block via AST parsing.
+ * Falls back to regex extraction if @babel/parser is unavailable.
+ *
+ * @param {string} code Source code snippet.
+ * @returns {string[]} List of unique called symbol names.
+ */
+export const extractCalleesFromCode = (code) => {
+  const callees = new Set();
+  const { parse, traverse } = loadBabel();
+  try {
+    if (!parse || !traverse) throw new Error('babel unavailable');
+    const ast = parse(code, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx', 'decorators-legacy', 'topLevelAwait'],
+      errorRecovery: true,
+    });
+    traverse(ast, {
+      CallExpression(nodePath) {
+        const callee = nodePath.node.callee;
+        if (callee.type === 'Identifier') {
+          callees.add(callee.name);
+        } else if (callee.type === 'MemberExpression') {
+          const obj = callee.object?.name || callee.object?.property?.name || '';
+          const prop = callee.property?.name || '';
+          if (obj && prop) callees.add(`${obj}.${prop}`);
+          else if (prop) callees.add(prop);
+        }
+      },
+      OptionalCallExpression(nodePath) {
+        const callee = nodePath.node.callee;
+        if (callee.type === 'Identifier') {
+          callees.add(callee.name);
+        } else if (callee.type === 'MemberExpression') {
+          const obj = callee.object?.name || '';
+          const prop = callee.property?.name || '';
+          if (obj && prop) callees.add(`${obj}.${prop}`);
+          else if (prop) callees.add(prop);
+        }
+      }
+    });
+  } catch {
+    const matches = code.matchAll(/\b([A-Za-z0-9_$]+)\s*\(/g);
+    for (const m of matches) {
+      if (!['if', 'for', 'while', 'switch', 'catch', 'function'].includes(m[1])) {
+        callees.add(m[1]);
+      }
+    }
+  }
+  return Array.from(callees);
+};
+
+/**
+ * Calculates forward call trace: downstream functions invoked by target symbol.
+ *
+ * @param {object} db SQLite index database.
+ * @param {string} targetSymbolOrPath Target symbol or file path.
+ * @param {object} options Traversal options.
+ * @returns {object} Call trace tree payload.
+ */
+export const calculateCallTrace = (db, targetSymbolOrPath, options = {}) => {
+  if (!db || !targetSymbolOrPath) {
+    return { target: targetSymbolOrPath || '', totalCallees: 0, depth: 0, callees: [] };
+  }
+
+  const cleanTarget = targetSymbolOrPath.trim();
+  const maxDepth = typeof options.maxDepth === 'number' ? options.maxDepth : 3;
+
+  const symRow = db.prepare(`
+    SELECT s.name, s.kind, s.start_line, s.end_line, s.file_path, f.tier
+    FROM symbols s
+    JOIN files f ON s.file_path = f.path
+    WHERE s.name = ?
+    LIMIT 1
+  `).get(cleanTarget);
+
+  let targetPath = symRow ? symRow.file_path : cleanTarget;
+  let symbolName = symRow ? symRow.name : cleanTarget;
+  let startLine = symRow ? Number(symRow.start_line) : 1;
+  let endLine = symRow ? Number(symRow.end_line) : 1;
+  let tier = symRow ? symRow.tier : 'utility';
+
+  const visited = new Set([symbolName]);
+
+  const traceCallees = (symbol, filePath, currentDepth) => {
+    if (currentDepth > maxDepth) return [];
+
+    let codeSlice = '';
+    let fullText = '';
+    const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+    if (fs.existsSync(absPath)) {
+      fullText = fs.readFileSync(absPath, 'utf-8');
+      const block = extractSymbolBlock(fullText, symbol);
+      if (block) {
+        codeSlice = block.code;
+      } else {
+        const fileLines = fullText.split('\n');
+        const start = Math.max(0, startLine - 1);
+        const end = Math.min(fileLines.length, endLine > start ? endLine : start + 100);
+        codeSlice = fileLines.slice(start, end).join('\n');
+      }
+    }
+
+    if (!codeSlice) return [];
+
+    const foundCallees = extractCalleesFromCode(codeSlice);
+    const results = [];
+
+    for (const c of foundCallees) {
+      if (visited.has(c)) continue;
+      visited.add(c);
+
+      const calleeSym = db.prepare(`
+        SELECT s.name, s.kind, s.start_line, s.end_line, s.file_path, f.tier
+        FROM symbols s
+        JOIN files f ON s.file_path = f.path
+        WHERE s.name = ?
+        LIMIT 1
+      `).get(c);
+
+      if (calleeSym) {
+        const subCallees = traceCallees(calleeSym.name, calleeSym.file_path, currentDepth + 1);
+        results.push({
+          symbol: calleeSym.name,
+          file: calleeSym.file_path,
+          line: Number(calleeSym.start_line),
+          tier: calleeSym.tier,
+          depth: currentDepth,
+          isExternal: false,
+          callees: subCallees
+        });
+      } else {
+        const baseName = c.includes('.') ? c.split('.')[0] : c;
+        const importRow = db.prepare(`
+          SELECT source_module
+          FROM imports
+          WHERE (importer_path = ? OR importer_path LIKE ?)
+            AND (imported_symbol = ? OR imported_symbol = ? OR imported_symbol = '*')
+          LIMIT 1
+        `).get(filePath, `%${path.basename(filePath)}%`, c, baseName);
+
+        if (importRow) {
+          results.push({
+            symbol: c,
+            file: importRow.source_module,
+            line: 1,
+            tier: 'external',
+            depth: currentDepth,
+            isExternal: true,
+            callees: []
+          });
+        } else {
+          const isLocal = new RegExp(`(?:const|function|let|var|class)\\s+${baseName}\\b`).test(fullText);
+          if (isLocal && baseName !== symbol) {
+            const subCallees = traceCallees(baseName, filePath, currentDepth + 1);
+            results.push({
+              symbol: c,
+              file: filePath,
+              line: 1,
+              tier: 'local',
+              depth: currentDepth,
+              isExternal: false,
+              callees: subCallees
+            });
+          }
+        }
+      }
+    }
+
+    return results;
+  };
+
+  const calleeTree = traceCallees(symbolName, targetPath, 1);
+  const totalCount = visited.size - 1;
+
+  return {
+    target: symbolName,
+    filePath: targetPath,
+    startLine,
+    tier,
+    totalCallees: totalCount,
+    depth: calleeTree.reduce((acc, c) => Math.max(acc, c.depth), 0),
+    callees: calleeTree
+  };
+};
+
+/**
+ * Calculates reverse backtrace: upstream callers leading to target symbol.
+ *
+ * @param {object} db SQLite index database.
+ * @param {string} targetSymbolOrPath Target symbol or file path.
+ * @param {object} options Traversal options.
+ * @returns {object} Backtrace causal path payload.
+ */
+export const calculateBacktrace = (db, targetSymbolOrPath, options = {}) => {
+  if (!db || !targetSymbolOrPath) {
+    return { target: targetSymbolOrPath || '', totalCallers: 0, depth: 0, chains: [], callers: [] };
+  }
+
+  const cleanTarget = targetSymbolOrPath.trim();
+  const maxDepth = typeof options.maxDepth === 'number' ? options.maxDepth : 5;
+
+  let seedPath = '';
+  let targetSymbolName = cleanTarget;
+  const symRow = db.prepare('SELECT file_path, name FROM symbols WHERE name = ? LIMIT 1').get(cleanTarget);
+  if (symRow) {
+    seedPath = symRow.file_path;
+    targetSymbolName = symRow.name;
+  } else {
+    const fileRow = db.prepare('SELECT path FROM files WHERE path = ? OR path LIKE ? LIMIT 1').get(cleanTarget, `%${cleanTarget}%`);
+    if (fileRow) seedPath = fileRow.path;
+  }
+
+  const seedBaseName = seedPath ? path.basename(seedPath).replace(/\.[^.]+$/, '') : cleanTarget;
+
+  const querySql = `
+    WITH RECURSIVE backtrace_tree(caller_path, caller_symbol, depth, chain) AS (
+      SELECT DISTINCT i.importer_path, i.imported_symbol, 1, i.importer_path || ' (' || i.imported_symbol || ')'
+      FROM imports i
+      WHERE (? != '' AND i.imported_symbol = ?)
+         OR (i.resolved_path = ? AND i.resolved_path != '')
+         OR (? != '' AND i.source_module LIKE '%' || ? || '%')
+
+      UNION
+
+      SELECT DISTINCT i.importer_path, i.imported_symbol, bt.depth + 1, i.importer_path || ' -> ' || bt.chain
+      FROM imports i
+      JOIN backtrace_tree bt ON (
+        (i.resolved_path = bt.caller_path AND i.resolved_path != '')
+        OR i.source_module LIKE '%' || bt.caller_path || '%'
+      )
+      WHERE bt.depth < ?
+        AND instr(bt.chain, i.importer_path) = 0
+    )
+    SELECT bt.caller_path, bt.caller_symbol, min(bt.depth) as depth, bt.chain, COALESCE(f.tier, 'utility') as tier
+    FROM backtrace_tree bt
+    LEFT JOIN files f ON bt.caller_path = f.path
+    WHERE bt.caller_path != ?
+    GROUP BY bt.caller_path, bt.caller_symbol
+    ORDER BY depth DESC, bt.caller_path ASC;
+  `;
+
+  const rows = db.prepare(querySql).all(
+    targetSymbolName,
+    targetSymbolName,
+    seedPath,
+    seedBaseName,
+    seedBaseName,
+    maxDepth,
+    seedPath
+  );
+
+  const callers = rows.map((r) => ({
+    path: r.caller_path,
+    symbol: r.caller_symbol,
+    depth: Number(r.depth),
+    chain: r.chain,
+    tier: r.tier,
+    isEntry: ['view', 'page', 'route', 'template'].includes(r.tier) || isSpecOrTest(r.caller_path)
+  }));
+
+  const chains = callers.map((c) => `${c.chain} -> ${cleanTarget}`);
+  const maxReachedDepth = callers.reduce((acc, c) => Math.max(acc, c.depth), 0);
+
+  return {
+    target: cleanTarget,
+    seedPath,
+    totalCallers: callers.length,
+    depth: maxReachedDepth,
+    chains,
+    callers,
+    rootCallers: callers.filter((c) => c.isEntry || c.depth === maxReachedDepth)
+  };
+};

package/cli/search-queries.js

@@ -239,7 +239,12 @@ export const queryFilesByHealth = (db, { status = 'all', limit = 50 } = {}) => {
   }));
 };
 
-export { calculateBlastRadius } from './search-queries-graph.js';
+export {
+  calculateBlastRadius,
+  calculateCallTrace,
+  calculateBacktrace,
+  extractCalleesFromCode
+} from './search-queries-graph.js';
 export { querySemanticIndex, queryHybridIndex } from './search-queries-semantic.js';
 
 

package/cli/search.js

@@ -28,6 +28,8 @@ import {
   handleHealthFilterCommand,
   handleCheckCommand,
   handleBlastRadiusCommand,
+  handleCallTraceCommand,
+  handleBacktraceCommand,
   handleSemanticCommand,
   handleHybridCommand
 } from './search-commands.js';
@@ -39,41 +41,21 @@ import { ANSI } from './theme.js';
 export { toColumnar, fromColumnar } from './columnar.js';
 
 export {
-  openIndexDb,
-  upsertFileIndex,
-  getIndexStats,
-  findSymbolDefinition,
-  findSymbolReferences,
-  findFileDependencies,
-  findFileDependents,
-  calculateBlastRadius,
-  querySemanticIndex,
-  queryHybridIndex,
-  syncViolationsIndex,
-  queryViolations,
-  recordAuditSnapshot,
-  getAuditProgression,
-  queryFilesByHealth
+  openIndexDb, upsertFileIndex, getIndexStats,
+  findSymbolDefinition, findSymbolReferences,
+  findFileDependencies, findFileDependents,
+  calculateBlastRadius, querySemanticIndex, queryHybridIndex,
+  syncViolationsIndex, queryViolations,
+  recordAuditSnapshot, getAuditProgression, queryFilesByHealth
 } from './search-db.js';
 export {
-  handleCheckCommand,
-  handleBlastRadiusCommand,
-  handleSemanticCommand,
-  handleHybridCommand
+  handleCheckCommand, handleBlastRadiusCommand,
+  handleSemanticCommand, handleHybridCommand
 } from './search-commands.js';
 
 const IGNORED_DIRS = new Set([
-  'node_modules',
-  'dist',
-  'build',
-  'vendor',
-  '.git',
-  '.next',
-  '.turbo',
-  '.output',
-  '.nuxt',
-  '.cache',
-  'out'
+  'node_modules', 'dist', 'build', 'vendor', '.git',
+  '.next', '.turbo', '.output', '.nuxt', '.cache', 'out'
 ]);
 
 const EXCLUDED_NAME_PATTERNS = ['.test.', '.spec.', '.min.'];
@@ -370,6 +352,22 @@ export const runSearch = async (rawArgs = [], isCli = true) => {
     return handleBlastRadiusCommand(db, target, { isJson, isCli, isColumnar, maxDepth });
   }
 
+  const isTraceCommand = firstArg === 'trace' || rawArgs.includes('--trace');
+  if (isTraceCommand) {
+    const target = firstArg === 'trace' ? secondArg : firstArg;
+    const maxDepthFlag = rawArgs.find((a) => a.startsWith('--max-depth='));
+    const maxDepth = maxDepthFlag ? parseInt(maxDepthFlag.split('=')[1], 10) : 3;
+    return handleCallTraceCommand(db, target, { isJson, isCli, maxDepth });
+  }
+
+  const isBacktraceCommand = firstArg === 'backtrace' || rawArgs.includes('--backtrace');
+  if (isBacktraceCommand) {
+    const target = firstArg === 'backtrace' ? secondArg : firstArg;
+    const maxDepthFlag = rawArgs.find((a) => a.startsWith('--max-depth='));
+    const maxDepth = maxDepthFlag ? parseInt(maxDepthFlag.split('=')[1], 10) : 5;
+    return handleBacktraceCommand(db, target, { isJson, isCli, maxDepth });
+  }
+
   const isSemanticCommand = firstArg === 'semantic' || rawArgs.includes('--semantic');
   if (isSemanticCommand) {
     const query = firstArg === 'semantic' ? secondArg : firstArg;

package/cli/team/team-memory.js

@@ -84,17 +84,26 @@ export const runAblationComparison = (db) => {
     const precisionGain = (100 / 12.0).toFixed(1) + 'x';
     return {
       hasRealData: false,
+      hasMeasuredTokens: false,
       isSimulated: true,
       workloadTurns: turns,
       memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: 0.0, retrievalPrecisionPct: 100, astQualityScore: 100 },
       memoryDisabled: { mode: 'Stateless Monolithic File Re-read', tokensUsed: baseTokens, staleRetryRatePct: 18.5, retrievalPrecisionPct: 12.0, astQualityScore: 84 },
-      delta: { tokenReductionPct: Math.round((tokensSaved / baseTokens) * 100), costAvoidedUsd: Number(((tokensSaved / 1000000) * 10.0).toFixed(4)), retrievalPrecisionGainRatio: precisionGain, staleRetriesEliminated: Math.round(turns * 0.185) }
+      delta: {
+        tokenReductionPct: Math.round((tokensSaved / baseTokens) * 100),
+        tokenReductionBasis: 'estimated_typical_usage',
+        isEstimated: true,
+        costAvoidedUsd: Number(((tokensSaved / 1000000) * 10.0).toFixed(4)),
+        retrievalPrecisionGainRatio: precisionGain,
+        staleRetriesEliminated: Math.round(turns * 0.185)
+      }
     };
   }
 
   const turns = taskStats.totalTasks + m.totalCount;
   const liveTokens = taskStats.totalPromptTokens + taskStats.totalCompletionTokens;
-  const memTokens = liveTokens > 0 ? liveTokens : Math.max(turns * 70, m.totalInjectedTokens || 70);
+  const hasMeasuredTokens = liveTokens > 0;
+  const memTokens = hasMeasuredTokens ? liveTokens : Math.max(turns * 70, m.totalInjectedTokens || 70);
   const baseTokens = turns * 2500 + Math.round(memTokens * 0.5);
   const tokensSaved = Math.max(0, baseTokens - memTokens);
   const tokenReductionPct = baseTokens > 0 ? Math.round((tokensSaved / baseTokens) * 100) : 0;
@@ -105,11 +114,19 @@ export const runAblationComparison = (db) => {
 
   return {
     hasRealData: true,
+    hasMeasuredTokens,
     isSimulated: false,
     workloadTurns: turns,
     memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: retryRatePct, retrievalPrecisionPct: m.precisionPct, astQualityScore: 100 },
     memoryDisabled: { mode: 'Stateless Monolithic File Re-read', tokensUsed: baseTokens, staleRetryRatePct: 18.5, retrievalPrecisionPct: 12.0, astQualityScore: 84 },
-    delta: { tokenReductionPct, costAvoidedUsd, retrievalPrecisionGainRatio: precisionGainRatio, staleRetriesEliminated }
+    delta: {
+      tokenReductionPct,
+      tokenReductionBasis: hasMeasuredTokens ? 'measured' : 'estimated_typical_usage',
+      isEstimated: !hasMeasuredTokens,
+      costAvoidedUsd,
+      retrievalPrecisionGainRatio: precisionGainRatio,
+      staleRetriesEliminated
+    }
   };
 };
 
@@ -132,13 +149,19 @@ export const formatAblationCard = (a) => {
     );
   }
 
+  const tokenReductionLabel = a.hasMeasuredTokens
+    ? `${delta.tokenReductionPct}% fewer tokens consumed (measured vs modeled baseline)`
+    : `${delta.tokenReductionPct}% fewer tokens consumed (estimated based on typical usage)`;
+  const costAvoidedSuffix = a.hasMeasuredTokens ? '' : ' (projected)';
+  const memoryTokensSuffix = a.hasMeasuredTokens ? '' : ' (est.)';
+
   lines.push(
     `  \x1b[1mWorkload:\x1b[0m              ${a.workloadTurns} agent turns / tasks`,
-    `  \x1b[1mMemory Mode (SQLite):\x1b[0m  ${m.tokensUsed.toLocaleString()} tokens │ Precision: ${m.retrievalPrecisionPct}% │ Retry: ${m.staleRetryRatePct}%`,
-    `  \x1b[1mBaseline (Stateless):\x1b[0m  ${d.tokensUsed.toLocaleString()} tokens │ Precision: ${d.retrievalPrecisionPct}% │ Retry: ${d.staleRetryRatePct}%`,
+    `  \x1b[1mMemory Mode (SQLite):\x1b[0m  ${m.tokensUsed.toLocaleString()} tokens${memoryTokensSuffix} │ Precision: ${m.retrievalPrecisionPct}% │ Retry: ${m.staleRetryRatePct}%`,
+    `  \x1b[1mBaseline (Stateless):\x1b[0m  ${d.tokensUsed.toLocaleString()} tokens (modeled) │ Precision: ${d.retrievalPrecisionPct}% │ Retry: ${d.staleRetryRatePct}%`,
     `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
-    `  \x1b[32m✔ Token Reduction:\x1b[0m     ${delta.tokenReductionPct}% fewer tokens consumed`,
-    `  \x1b[32m✔ Cost Avoided:\x1b[0m        ${delta.costAvoidedUsd.toFixed(4)} USD`,
+    `  \x1b[32m✔ Token Reduction:\x1b[0m     ${tokenReductionLabel}`,
+    `  \x1b[32m✔ Cost Avoided:\x1b[0m        ${delta.costAvoidedUsd.toFixed(4)} USD${costAvoidedSuffix}`,
     `  \x1b[32m✔ Precision Gain:\x1b[0m      ${delta.retrievalPrecisionGainRatio} higher retrieval precision per dollar`,
     `  \x1b[32m✔ Stale Retries:\x1b[0m       ${delta.staleRetriesEliminated} retries eliminated`,
     `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`

package/cli/team/team-memory.spec.js

@@ -95,5 +95,29 @@ test("runAblationComparison computes dynamic metrics from live task and memory r
 
   const card = formatAblationCard(ablation);
   assert.ok(card.includes("Live Project Telemetry"));
+  assert.ok(card.includes("measured vs modeled baseline"));
+  assert.strictEqual(ablation.hasMeasuredTokens, true);
+  assert.strictEqual(ablation.delta.isEstimated, false);
+  assert.strictEqual(ablation.delta.tokenReductionBasis, "measured");
   assert.strictEqual(card.includes("—"), false);
 }));
+
+test("runAblationComparison marks token reduction as estimated when live tasks lack token counts", () => withTmpCwd((db) => {
+  db.prepare(`
+    INSERT INTO agent_tasks (title, status, created_at, updated_at)
+    VALUES ('Task without token telemetry', 'done', 1000, 1000)
+  `).run();
+
+  const ablation = runAblationComparison(db);
+  assert.strictEqual(ablation.hasRealData, true);
+  assert.strictEqual(ablation.hasMeasuredTokens, false);
+  assert.strictEqual(ablation.delta.isEstimated, true);
+  assert.strictEqual(ablation.delta.tokenReductionBasis, "estimated_typical_usage");
+  assert.strictEqual(ablation.delta.tokenReductionPct, 97);
+
+  const card = formatAblationCard(ablation);
+  assert.ok(card.includes("estimated based on typical usage"));
+  assert.ok(card.includes("(projected)"));
+  assert.strictEqual(card.includes("—"), false);
+}));
+

package/cli/tesseract.spec.js

@@ -27,7 +27,7 @@ test('tesseract: cli command execution succeeds with exit code 0', () => {
   const cliPath = path.resolve('cli/index.js');
   const res = spawnSync(process.execPath, [cliPath, 'tesseract'], {
     encoding: 'utf8',
-    timeout: 5000
+    timeout: 15000
   });
 
   assert.strictEqual(res.status, 0, 'CLI tesseract should exit with 0');
@@ -40,7 +40,7 @@ test('tesseract: cli aliases cube and matrix work identically', () => {
   for (const alias of ['cube', 'matrix']) {
     const res = spawnSync(process.execPath, [cliPath, alias], {
       encoding: 'utf8',
-      timeout: 5000
+      timeout: 15000
     });
     assert.strictEqual(res.status, 0, `CLI ${alias} should exit with 0`);
     assert.ok(res.stdout.includes('TESSERACT'), `CLI ${alias} should render Tesseract`);

package/cli/trace.spec.js

@@ -0,0 +1,92 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  extractCalleesFromCode,
+  calculateCallTrace,
+  calculateBacktrace
+} from './search-queries-graph.js';
+import {
+  handleCallTraceCommand,
+  handleBacktraceCommand
+} from './search-commands-graph.js';
+import { openIndexDb, upsertFileIndex } from './search-db.js';
+
+describe('Call Trace & Backtrace Engine', () => {
+  it('extracts call expressions from code snippet', () => {
+    const code = `
+      const handleAction = async () => {
+        if (!canProceed.value) return;
+        state.value = { status: 'loading' };
+        await api.postOrder(items.value);
+        emit('success');
+      };
+    `;
+    const callees = extractCalleesFromCode(code);
+    assert.ok(callees.includes('api.postOrder'), 'Should extract api.postOrder');
+    assert.ok(callees.includes('emit'), 'Should extract emit');
+  });
+
+  it('calculates forward call trace gracefully on unknown or empty target', () => {
+    const db = openIndexDb();
+    const trace = calculateCallTrace(db, 'nonExistentSymbol', { maxDepth: 2 });
+    assert.equal(trace.target, 'nonExistentSymbol');
+    assert.equal(trace.totalCallees, 0);
+    assert.deepEqual(trace.callees, []);
+  });
+
+  it('calculates reverse backtrace using recursive imports CTE', () => {
+    const db = openIndexDb();
+
+    upsertFileIndex(db, {
+      path: 'src/controllers/trace-cart.ts',
+      mtime: Date.now(),
+      size: 400,
+      tier: 'hook',
+      lines: 40,
+      chars: 400,
+      symbols: [{ name: 'useTraceCartController', kind: 'const', isExport: true, startLine: 1, endLine: 40 }],
+      imports: []
+    });
+
+    upsertFileIndex(db, {
+      path: 'src/organisms/trace-cart.vue',
+      mtime: Date.now(),
+      size: 800,
+      tier: 'organism',
+      lines: 80,
+      chars: 800,
+      symbols: [{ name: 'TraceCartOrganism', kind: 'const', isExport: true, startLine: 1, endLine: 80 }],
+      imports: [
+        { importedSymbol: 'useTraceCartController', sourceModule: '@/controllers/trace-cart.ts', resolvedPath: 'src/controllers/trace-cart.ts', line: 3 }
+      ]
+    });
+
+    upsertFileIndex(db, {
+      path: 'src/views/trace-checkout.vue',
+      mtime: Date.now(),
+      size: 500,
+      tier: 'view',
+      lines: 50,
+      chars: 500,
+      symbols: [{ name: 'TraceCheckoutView', kind: 'const', isExport: true, startLine: 1, endLine: 50 }],
+      imports: [
+        { importedSymbol: 'TraceCartOrganism', sourceModule: '@/organisms/trace-cart.vue', resolvedPath: 'src/organisms/trace-cart.vue', line: 5 }
+      ]
+    });
+
+    const backtrace = calculateBacktrace(db, 'useTraceCartController', { maxDepth: 5 });
+    assert.equal(backtrace.target, 'useTraceCartController');
+    assert.ok(backtrace.totalCallers >= 2, `Expected at least 2 callers, got ${backtrace.totalCallers}`);
+    assert.ok(backtrace.chains.some((c) => c.includes('trace-checkout.vue')), 'Causal chain should reach root view');
+    assert.ok(backtrace.rootCallers.some((r) => r.tier === 'view'), 'Root callers should include view tier');
+  });
+
+  it('formats call trace and backtrace as JSON payloads', () => {
+    const db = openIndexDb();
+    const traceRes = handleCallTraceCommand(db, 'foo', { isJson: true, isCli: false });
+    assert.equal(traceRes.target, 'foo');
+
+    const backtraceRes = handleBacktraceCommand(db, 'foo', { isJson: true, isCli: false });
+    assert.equal(backtraceRes.target, 'foo');
+  });
+});

package/cli/verify-helpers.js

@@ -30,16 +30,59 @@ export const detectTypecheckCommand = (customCmd, cwd = process.cwd()) => {
   return `${pm} run typecheck`;
 };
 
-export const detectTestCommand = (customCmd, cwd = process.cwd()) => {
-  if (customCmd && customCmd.trim().length > 0) return customCmd.trim();
+export const detectTestCommand = (customCmd, cwd = process.cwd(), options = {}) => {
+  const target = options.target ? String(options.target).trim() : null;
+  const filter = options.filter ? String(options.filter).trim() : null;
+
+  if (customCmd && customCmd.trim().length > 0) {
+    let cmd = customCmd.trim();
+    if (target && !cmd.includes(target)) cmd += ` ${target}`;
+    if (filter && !cmd.includes(filter)) cmd += ` -t "${filter}"`;
+    return cmd;
+  }
+
   const pkg = loadLocalPackageJson(cwd);
   const scripts = (pkg && pkg.scripts) || {};
+  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) };
   const pm = resolvePackageManager(cwd);
 
+  const hasVitest = Boolean(
+    deps.vitest ||
+    (scripts.test && scripts.test.includes('vitest')) ||
+    fs.existsSync(path.join(cwd, 'vitest.config.ts')) ||
+    fs.existsSync(path.join(cwd, 'vitest.config.js'))
+  );
+
+  const hasNodeTest = Boolean(
+    scripts.test && (scripts.test.includes('node --test') || scripts.test.includes('node:test'))
+  );
+
+  if (target || filter) {
+    if (hasVitest) {
+      let vitestCmd = 'npx vitest run';
+      if (target) vitestCmd += ` ${target}`;
+      if (filter) vitestCmd += ` -t "${filter}"`;
+      return vitestCmd;
+    }
+
+    if (hasNodeTest || target?.endsWith('.spec.js') || target?.endsWith('.test.js')) {
+      let nodeCmd = 'node --test';
+      if (target) nodeCmd += ` ${target}`;
+      if (filter) nodeCmd += ` --test-name-pattern="${filter}"`;
+      return nodeCmd;
+    }
+
+    const baseTest = pm === 'yarn' ? 'yarn test' : `${pm} test`;
+    let args = '';
+    if (target) args += ` ${target}`;
+    if (filter) args += ` -t "${filter}"`;
+    return `${baseTest} --${args}`;
+  }
+
   const isLegitTest = scripts.test && !scripts.test.includes('no test specified');
   if (isLegitTest) return pm === 'yarn' ? 'yarn test' : `${pm} run test`;
 
-  if (fs.existsSync(path.join(cwd, 'vitest.config.ts')) || fs.existsSync(path.join(cwd, 'vitest.config.js'))) {
+  if (hasVitest) {
     return 'npx vitest run';
   }