octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-code-engineer/src/reporting/summary-md.ts

@@ -0,0 +1,714 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { PILLAR_CATEGORIES, SEVERITY_ORDER } from '../types/index.js';
+
+import type { ReportAnalysisSummary } from './analysis.js';
+import type { Finding } from '../types/index.js';
+
+export function severityBreakdown(findings: Finding[]): Record<string, number> {
+  const counts: Record<string, number> = {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    info: 0,
+  };
+  for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+  return counts;
+}
+
+export function categoryBreakdown(findings: Finding[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const f of findings) counts[f.category] = (counts[f.category] || 0) + 1;
+  return counts;
+}
+
+export function computeHealthScore(
+  findings: Finding[],
+  totalFiles: number
+): number {
+  return computeHealthScoreFromSeverityBreakdown(
+    severityBreakdown(findings),
+    totalFiles
+  );
+}
+
+function computeHealthScoreFromSeverityBreakdown(
+  breakdown: Record<string, number>,
+  totalFiles: number
+): number {
+  if (totalFiles === 0) return 100;
+  const weights = { critical: 25, high: 10, medium: 3, low: 1, info: 0 };
+  let penalty = 0;
+  for (const [severity, count] of Object.entries(breakdown)) {
+    penalty += (weights[severity as keyof typeof weights] || 0) * count;
+  }
+  const weightedFindingsPerFile = penalty / totalFiles;
+  return Math.max(
+    0,
+    Math.min(100, Math.round(100 / (1 + weightedFindingsPerFile / 10)))
+  );
+}
+
+export function collectTagCloud(
+  findings: Finding[]
+): { tag: string; count: number }[] {
+  const tagCounts = new Map<string, number>();
+  for (const f of findings) {
+    if (!f.tags) continue;
+    for (const tag of f.tags) {
+      tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+    }
+  }
+  return [...tagCounts.entries()]
+    .map(([tag, count]) => ({ tag, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function summarizeActiveFeatures(activeFeatures: Set<string>): string[] {
+  const remaining = new Set(activeFeatures);
+  const labels: string[] = [];
+
+  for (const [pillar, categories] of Object.entries(PILLAR_CATEGORIES)) {
+    if (categories.length > 0 && categories.every(cat => remaining.has(cat))) {
+      labels.push(pillar);
+      for (const cat of categories) remaining.delete(cat);
+    }
+  }
+
+  return [...labels, ...[...remaining].sort()];
+}
+
+function isPillarActive(
+  pillarKey: string,
+  activeFeatures: Set<string> | null
+): boolean {
+  if (!activeFeatures) return true;
+  const pillarCats = PILLAR_CATEGORIES[pillarKey] || [];
+  return pillarCats.some(cat => activeFeatures.has(cat));
+}
+
+type FindingLike = Omit<Finding, 'id'> & { id?: string };
+
+export function diversifyFindings<T extends FindingLike>(
+  sorted: T[],
+  limit: number
+): T[] {
+  if (!Number.isFinite(limit) || limit >= sorted.length) return sorted;
+
+  const groups = new Map<string, T[]>();
+  for (const f of sorted) {
+    const cat = f.category;
+    if (!groups.has(cat)) groups.set(cat, []);
+    groups.get(cat)!.push(f);
+  }
+
+  const categoryOrder = [...groups.entries()].sort((a, b) => {
+    const aTop = SEVERITY_ORDER[a[1][0].severity] ?? 0;
+    const bTop = SEVERITY_ORDER[b[1][0].severity] ?? 0;
+    return bTop - aTop;
+  });
+
+  const result: T[] = [];
+  const cursors = new Map<string, number>();
+  for (const [cat] of categoryOrder) cursors.set(cat, 0);
+
+  while (result.length < limit) {
+    let picked = false;
+    for (const [cat, items] of categoryOrder) {
+      if (result.length >= limit) break;
+      const cursor = cursors.get(cat)!;
+      if (cursor < items.length) {
+        result.push(items[cursor]);
+        cursors.set(cat, cursor + 1);
+        picked = true;
+      }
+    }
+    if (!picked) break;
+  }
+  return result;
+}
+
+export function diverseTopRecommendations(
+  findings: Finding[],
+  limit: number = 20,
+  maxPerCategory: number = 2
+): Finding[] {
+  const result: Finding[] = [];
+  const countByCategory = new Map<string, number>();
+  for (const f of findings) {
+    const catCount = countByCategory.get(f.category) || 0;
+    if (catCount >= maxPerCategory) continue;
+    result.push(f);
+    countByCategory.set(f.category, catCount + 1);
+    if (result.length >= limit) break;
+  }
+  return result;
+}
+
+export interface SummaryMdOptions {
+  dir: string;
+  report: import('./writer.js').FullReport;
+  outputFiles: Record<string, string>;
+  architectureFindings: Finding[];
+  codeQualityFindings: Finding[];
+  deadCodeFindings: Finding[];
+  hotFiles?: import('../types/index.js').HotFile[];
+  activeFeatures?: Set<string> | null;
+  scope?: string[] | null;
+  root?: string;
+  scopeSymbols?: Map<string, string[]> | null;
+  semanticEnabled?: boolean;
+  securityFindings?: Finding[];
+  testQualityFindings?: Finding[];
+  reportAnalysis?: ReportAnalysisSummary;
+}
+
+function formatCliPath(filePath: string): string {
+  return JSON.stringify(filePath.replace(/\\/g, '/'));
+}
+
+export function generateSummaryMd(opts: SummaryMdOptions): string {
+  const {
+    dir,
+    report,
+    outputFiles,
+    architectureFindings,
+    codeQualityFindings,
+    deadCodeFindings,
+    hotFiles = [],
+    activeFeatures = null,
+    scope = null,
+    root = process.cwd(),
+    scopeSymbols = null,
+    semanticEnabled = false,
+    securityFindings = [],
+    testQualityFindings = [],
+    reportAnalysis = null,
+  } = opts;
+  const allFindings = report.optimizationFindings || [];
+  const summary = report.summary as Record<string, unknown>;
+  const agentOutput = report.agentOutput as Record<string, unknown>;
+  const findingStats = (agentOutput?.findingStats ??
+    null) as
+    | {
+        overall?: {
+          totalFindings: number;
+          severityBreakdown: Record<string, number>;
+        };
+        pillars?: Record<
+          string,
+          {
+            totalFindings: number;
+            severityBreakdown: Record<string, number>;
+          }
+        >;
+      }
+    | null;
+  const depGraph = report.dependencyGraph;
+  const relativeScanDir = path.relative(root, dir) || '.';
+  const exampleFileFilter = ((scope?.[0] ?? 'src/index').split(':')[0] || 'src/index')
+    .replace(/\\/g, '/');
+  const overallFindingStats = findingStats?.overall ?? {
+    totalFindings: allFindings.length,
+    severityBreakdown: severityBreakdown(allFindings),
+  };
+
+  const lines: string[] = [];
+  lines.push('# Code Quality Scan Report\n');
+  lines.push(`**Generated**: ${report.generatedAt}  `);
+  lines.push(`**Root**: \`${report.repoRoot}\`\n`);
+
+  lines.push('## Scan Scope\n');
+  lines.push(`| Metric | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Files analyzed | ${summary.totalFiles ?? '—'} |`);
+  lines.push(`| Functions | ${summary.totalFunctions ?? '—'} |`);
+  lines.push(`| Flow nodes | ${summary.totalFlows ?? '—'} |`);
+  lines.push(`| Dependency files | ${summary.totalDependencyFiles ?? '—'} |`);
+  lines.push(`| Packages | ${summary.totalPackages ?? '—'} |`);
+  lines.push('');
+
+  lines.push('## Findings Overview\n');
+  lines.push(`| Severity | Count |`);
+  lines.push(`|----------|-------|`);
+  lines.push(`| Critical | ${overallFindingStats.severityBreakdown.critical ?? 0} |`);
+  lines.push(`| High | ${overallFindingStats.severityBreakdown.high ?? 0} |`);
+  lines.push(`| Medium | ${overallFindingStats.severityBreakdown.medium ?? 0} |`);
+  lines.push(`| Low | ${overallFindingStats.severityBreakdown.low ?? 0} |`);
+  lines.push(`| **Total** | **${overallFindingStats.totalFindings}** |`);
+  lines.push('');
+
+  const totalBefore = overallFindingStats.totalFindings || (agentOutput as Record<string, unknown>)
+    ?.totalBeforeTruncation as number | undefined;
+  const dropped = (agentOutput as Record<string, unknown>)
+    ?.droppedCategories as string[] | undefined;
+  if (totalBefore && totalBefore > allFindings.length) {
+    lines.push(
+      `> **Truncated**: Showing ${allFindings.length} of ${totalBefore} findings (\`--findings-limit ${allFindings.length}\`).`
+    );
+    if (dropped && dropped.length > 0) {
+      lines.push(
+        `> Dropped categories: ${dropped.map(c => `\`${c}\``).join(', ')}`
+      );
+    }
+    lines.push('');
+  }
+
+  if (activeFeatures) {
+    const featureLabels = summarizeActiveFeatures(activeFeatures);
+    lines.push(
+      `> **Features filter**: \`--features=${featureLabels.join(',')}\``
+    );
+    lines.push('');
+  }
+
+  if (scope && scope.length > 0) {
+    const scopeDisplay = scope.map(s => path.relative(root, s)).filter(Boolean);
+    if (scopeDisplay.length > 0) {
+      let scopeLabel = scopeDisplay.map(p => `\`${p}\``).join(', ');
+      if (scopeSymbols && scopeSymbols.size > 0) {
+        const symParts: string[] = [];
+        for (const [absFile, names] of scopeSymbols) {
+          const rel = path.relative(root, absFile);
+          symParts.push(...names.map(n => `\`${rel}:${n}\``));
+        }
+        scopeLabel = symParts.join(', ');
+      }
+      lines.push(`> **Scoped scan**: Only showing findings for: ${scopeLabel}`);
+      lines.push('');
+    }
+  }
+
+  if (semanticEnabled) {
+    lines.push(
+      '> **Semantic analysis**: TypeChecker + LanguageService enabled (14 additional categories)'
+    );
+    lines.push('');
+  }
+
+  const renderPillarCategories = (
+    pillarKey: string,
+    findings: Finding[]
+  ): void => {
+    const breakdown = categoryBreakdown(findings);
+    const pillarCats = PILLAR_CATEGORIES[pillarKey] || [];
+    const isFiltered = activeFeatures !== null;
+    for (const cat of pillarCats) {
+      const count = breakdown[cat] || 0;
+      const skipped = isFiltered && !activeFeatures!.has(cat);
+      if (skipped) {
+        lines.push(`- \`${cat}\`: — *(skipped)*`);
+      } else {
+        lines.push(`- \`${cat}\`: ${count}`);
+      }
+    }
+    lines.push('');
+  };
+
+  const totalFiles = (summary.totalFiles as number) || 1;
+  const archStats = findingStats?.pillars?.['architecture'];
+  const qualStats = findingStats?.pillars?.['code-quality'];
+  const deadStats = findingStats?.pillars?.['dead-code'];
+  const secStats = findingStats?.pillars?.['security'];
+  const testStats = findingStats?.pillars?.['test-quality'];
+  const overallHealth = computeHealthScoreFromSeverityBreakdown(
+    overallFindingStats.severityBreakdown,
+    totalFiles
+  );
+  const archHealth = computeHealthScoreFromSeverityBreakdown(
+    archStats?.severityBreakdown ?? severityBreakdown(architectureFindings),
+    totalFiles
+  );
+  const qualHealth = computeHealthScoreFromSeverityBreakdown(
+    qualStats?.severityBreakdown ?? severityBreakdown(codeQualityFindings),
+    totalFiles
+  );
+  const deadHealth = computeHealthScoreFromSeverityBreakdown(
+    deadStats?.severityBreakdown ?? severityBreakdown(deadCodeFindings),
+    totalFiles
+  );
+  const secHealth = computeHealthScoreFromSeverityBreakdown(
+    secStats?.severityBreakdown ?? severityBreakdown(securityFindings),
+    totalFiles
+  );
+  const testHealth = computeHealthScoreFromSeverityBreakdown(
+    testStats?.severityBreakdown ?? severityBreakdown(testQualityFindings),
+    totalFiles
+  );
+
+  lines.push('## Health Scores\n');
+  lines.push('| Pillar | Score | Grade |');
+  lines.push('|--------|-------|-------|');
+  const grade = (s: number) =>
+    s >= 80 ? 'A' : s >= 60 ? 'B' : s >= 40 ? 'C' : s >= 20 ? 'D' : 'F';
+  const pushHealthRow = (label: string, pillarKey: string, score: number): void => {
+    if (!isPillarActive(pillarKey, activeFeatures)) {
+      lines.push(`| ${label} | — | skipped |`);
+      return;
+    }
+    lines.push(`| ${label} | ${score}/100 | ${grade(score)} |`);
+  };
+  const pushPillarSummary = (
+    pillarKey: string,
+    findingsCount: number,
+    score: number,
+    artifactKey?: string,
+    artifactName?: string
+  ): void => {
+    if (!isPillarActive(pillarKey, activeFeatures)) {
+      lines.push('> skipped by feature filter\n');
+      return;
+    }
+
+    if (artifactKey && outputFiles[artifactKey]) {
+      lines.push(
+        `> ${findingsCount} findings (score: ${score}/100) — see [\`${artifactName}\`](./${outputFiles[artifactKey]})\n`
+      );
+      return;
+    }
+
+    if (artifactName) {
+      lines.push(
+        `> ${findingsCount} findings (score: ${score}/100) — no \`${artifactName}\` written for this scan\n`
+      );
+      return;
+    }
+
+    lines.push(`> ${findingsCount} findings (score: ${score}/100)\n`);
+  };
+  lines.push(
+    `| **Overall** | **${overallHealth}/100** | **${grade(overallHealth)}** |`
+  );
+  pushHealthRow('Architecture', 'architecture', archHealth);
+  pushHealthRow('Code Quality', 'code-quality', qualHealth);
+  pushHealthRow('Dead Code & Hygiene', 'dead-code', deadHealth);
+  pushHealthRow('Security', 'security', secHealth);
+  pushHealthRow('Test Quality', 'test-quality', testHealth);
+  lines.push('');
+
+  const tagCloud = collectTagCloud(allFindings);
+  if (tagCloud.length > 0) {
+    lines.push('## Top Concern Tags\n');
+    lines.push(
+      'Searchable tags across all findings — use to filter `findings.json` with `jq`.\n'
+    );
+    for (const { tag, count } of tagCloud.slice(0, 12)) {
+      lines.push(`- \`${tag}\`: ${count} findings`);
+    }
+    lines.push('');
+  }
+
+  if (reportAnalysis) {
+    lines.push('## Analysis Signals\n');
+    lines.push(
+      `- **Graph Signal**: ${reportAnalysis.strongestGraphSignal?.summary || 'No dominant graph signal in this scan.'}`
+    );
+    lines.push(
+      `- **AST Signal**: ${reportAnalysis.strongestAstSignal?.summary || 'No dominant AST signal in this scan.'}`
+    );
+    lines.push(
+      `- **Combined Interpretation**: ${reportAnalysis.combinedInterpretation?.summary || 'No combined interpretation available yet.'}`
+    );
+    lines.push(
+      `- **Confidence**: ${reportAnalysis.combinedInterpretation?.confidence || reportAnalysis.strongestGraphSignal?.confidence || reportAnalysis.strongestAstSignal?.confidence || 'low'}`
+    );
+    const validationSummary = reportAnalysis.recommendedValidation
+      ? `${reportAnalysis.recommendedValidation.summary} (tools: ${reportAnalysis.recommendedValidation.tools.join(' -> ')})`
+      : 'Use Octocode local tools to confirm the strongest signal before presenting it as fact.';
+    lines.push(`- **Recommended Validation**: ${validationSummary}`);
+    const megaFolderSignal = reportAnalysis.graphSignals.find(
+      signal => signal.kind === 'mega-folder-cluster'
+    );
+    if (megaFolderSignal) {
+      lines.push(`- **Structural Layout Alert**: ${megaFolderSignal.summary}`);
+    }
+    if (reportAnalysis.investigationPrompts.length > 0) {
+      lines.push('');
+      lines.push('**Investigation Prompts**');
+      for (const prompt of reportAnalysis.investigationPrompts.slice(0, 4)) {
+        lines.push(`- ${prompt}`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('## Architecture Health\n');
+  pushPillarSummary(
+    'architecture',
+    archStats?.totalFindings ?? architectureFindings.length,
+    archHealth,
+    'architecture',
+    'architecture.json'
+  );
+  if (depGraph) {
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Modules | ${depGraph.totalModules} |`);
+    lines.push(`| Import edges | ${depGraph.totalEdges} |`);
+    lines.push(`| Cycles | ${depGraph.cycles?.length ?? 0} |`);
+    lines.push(`| Critical paths | ${depGraph.criticalPaths?.length ?? 0} |`);
+    lines.push(`| Root modules | ${depGraph.rootsCount} |`);
+    lines.push(`| Leaf modules | ${depGraph.leavesCount} |`);
+    lines.push(
+      `| Test-only modules | ${depGraph.testOnlyModules?.length ?? 0} |`
+    );
+    lines.push(`| Unresolved imports | ${depGraph.unresolvedEdgeCount} |`);
+    lines.push('');
+  }
+  renderPillarCategories('architecture', architectureFindings);
+
+  renderHotspots(lines, hotFiles);
+
+  renderPillarSections(lines, {
+    architectureFindings,
+    codeQualityFindings,
+    deadCodeFindings,
+    securityFindings,
+    testQualityFindings,
+    archStats,
+    qualStats,
+    deadStats,
+    secStats,
+    testStats,
+    archHealth,
+    qualHealth,
+    deadHealth,
+    secHealth,
+    testHealth,
+    activeFeatures,
+    outputFiles,
+    renderPillarCategories,
+    pushPillarSummary,
+  });
+
+  renderRecommendations(lines, agentOutput);
+
+  if (outputFiles.astTrees) {
+    renderAstTreesSection(lines, dir, outputFiles, root, relativeScanDir, exampleFileFilter);
+  }
+
+  renderOutputFilesTable(lines, dir, outputFiles);
+
+  if (report.parseErrors?.length > 0) {
+    lines.push('## Parse Errors\n');
+    lines.push(`${report.parseErrors.length} file(s) failed to parse:\n`);
+    for (const err of report.parseErrors.slice(0, 10)) {
+      lines.push(`- \`${err.file}\`: ${err.message}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function renderHotspots(
+  lines: string[],
+  hotFiles: SummaryMdOptions['hotFiles']
+): void {
+  if (!hotFiles || hotFiles.length === 0) return;
+  lines.push('## Change Risk Hotspots\n');
+  lines.push(
+    'Files most dangerous to change — high fan-in, complexity, or cycle membership.\n'
+  );
+  lines.push(
+    '| File | Risk | Fan-In | Fan-Out | Complexity | Exports | Cycle | Critical Path |'
+  );
+  lines.push(
+    '|------|------|--------|---------|------------|---------|-------|---------------|'
+  );
+  for (const hf of hotFiles.slice(0, 15)) {
+    lines.push(
+      `| \`${hf.file}\` | ${hf.riskScore} | ${hf.fanIn} | ${hf.fanOut} | ${hf.complexityScore} | ${hf.exportCount} | ${hf.inCycle ? 'Y' : '-'} | ${hf.onCriticalPath ? 'Y' : '-'} |`
+    );
+  }
+  lines.push('');
+}
+
+function renderPillarSections(
+  lines: string[],
+  ctx: {
+    architectureFindings: Finding[];
+    codeQualityFindings: Finding[];
+    deadCodeFindings: Finding[];
+    securityFindings: Finding[];
+    testQualityFindings: Finding[];
+    archStats: { totalFindings: number; severityBreakdown: Record<string, number> } | undefined;
+    qualStats: { totalFindings: number; severityBreakdown: Record<string, number> } | undefined;
+    deadStats: { totalFindings: number; severityBreakdown: Record<string, number> } | undefined;
+    secStats: { totalFindings: number; severityBreakdown: Record<string, number> } | undefined;
+    testStats: { totalFindings: number; severityBreakdown: Record<string, number> } | undefined;
+    archHealth: number;
+    qualHealth: number;
+    deadHealth: number;
+    secHealth: number;
+    testHealth: number;
+    activeFeatures: Set<string> | null;
+    outputFiles: Record<string, string>;
+    renderPillarCategories: (pillarKey: string, findings: Finding[]) => void;
+    pushPillarSummary: (pillarKey: string, count: number, score: number, artifactKey?: string, artifactName?: string) => void;
+  }
+): void {
+  const { architectureFindings, codeQualityFindings, deadCodeFindings, securityFindings, testQualityFindings } = ctx;
+  const { qualStats, deadStats, secStats, testStats } = ctx;
+  const { qualHealth, deadHealth, secHealth, testHealth } = ctx;
+  const { renderPillarCategories, pushPillarSummary } = ctx;
+
+  lines.push('## Code Quality\n');
+  pushPillarSummary(
+    'code-quality',
+    qualStats?.totalFindings ?? codeQualityFindings.length,
+    qualHealth,
+    'codeQuality',
+    'code-quality.json'
+  );
+  renderPillarCategories('code-quality', codeQualityFindings);
+
+  lines.push('## Dead Code & Hygiene\n');
+  pushPillarSummary(
+    'dead-code',
+    deadStats?.totalFindings ?? deadCodeFindings.length,
+    deadHealth,
+    'deadCode',
+    'dead-code.json'
+  );
+  renderPillarCategories('dead-code', deadCodeFindings);
+
+  lines.push('## Security\n');
+  pushPillarSummary(
+    'security',
+    secStats?.totalFindings ?? securityFindings.length,
+    secHealth,
+    'security',
+    'security.json'
+  );
+  renderPillarCategories('security', securityFindings);
+
+  lines.push('## Test Quality\n');
+  pushPillarSummary(
+    'test-quality',
+    testStats?.totalFindings ?? testQualityFindings.length,
+    testHealth,
+    'testQuality',
+    'test-quality.json'
+  );
+  renderPillarCategories('test-quality', testQualityFindings);
+
+  const untestedCount = architectureFindings.filter(
+    f => f.category === 'untested-critical-code'
+  ).length;
+  if (
+    untestedCount > 0 &&
+    (testStats?.totalFindings ?? testQualityFindings.length) === 0
+  ) {
+    lines.push(
+      `> **Note**: Test Quality reflects analyzed test files only. ${untestedCount} modules flagged as \`untested-critical-code\` (architecture pillar) have no test coverage — use \`--include-tests\` for test-quality analysis.\n`
+    );
+  }
+}
+
+function renderRecommendations(
+  lines: string[],
+  agentOutput: Record<string, unknown>
+): void {
+  const topRecs = (agentOutput?.topRecommendations ?? []) as Array<{
+    severity: string;
+    title: string;
+    file: string;
+    category: string;
+  }>;
+  if (topRecs.length > 0) {
+    lines.push('## Top Recommendations\n');
+    for (const rec of topRecs.slice(0, 10)) {
+      lines.push(
+        `- **[${rec.severity.toUpperCase()}]** \`${rec.file}\` — ${rec.title} *(${rec.category})* `
+      );
+    }
+    lines.push('');
+  }
+}
+
+function renderAstTreesSection(
+  lines: string[],
+  dir: string,
+  outputFiles: Record<string, string>,
+  root: string,
+  relativeScanDir: string,
+  exampleFileFilter: string
+): void {
+  const astTreePath = path.resolve(dir, outputFiles.astTrees);
+  const astTreeArg = formatCliPath(astTreePath);
+  lines.push('## AST Trees (`ast-trees.txt`)\n');
+  lines.push(
+    'Compact indented text format — each node is `Kind[startLine:endLine]`, nesting = indentation.\n'
+  );
+  lines.push(
+    `Run these commands from the skill directory. Current scan: \`${relativeScanDir}\`.\n`
+  );
+  lines.push('```');
+  lines.push('SourceFile[1:152]');
+  lines.push('  ImportDeclaration[1]');
+  lines.push('  FunctionDeclaration[3:20]');
+  lines.push('    Block[4:19]');
+  lines.push('      IfStatement[5:12] ...');
+  lines.push('```\n');
+  lines.push('**Smart navigation:**\n');
+  lines.push(
+    `- Find functions: \`node scripts/ast/tree-search.js -i ${astTreeArg} -k function_declaration --limit 25\``
+  );
+  lines.push(
+    `- Find classes: \`node scripts/ast/tree-search.js -i ${astTreeArg} -k class_declaration --limit 25\``
+  );
+  lines.push(
+    `- Find control flow: \`node scripts/ast/tree-search.js -i ${astTreeArg} -p 'IfStatement|SwitchStatement|ForStatement|WhileStatement' --limit 25\``
+  );
+  lines.push(
+    `- Narrow to one file: \`node scripts/ast/tree-search.js -i ${astTreeArg} --file "${exampleFileFilter}" -k function_declaration --limit 10\``
+  );
+  lines.push(
+    `- Raw text fallback: \`rg 'FunctionDeclaration|IfStatement' ${astTreeArg}\``
+  );
+  lines.push('');
+}
+
+function renderOutputFilesTable(
+  lines: string[],
+  dir: string,
+  outputFiles: Record<string, string>
+): void {
+  lines.push('## Output Files\n');
+  lines.push('| File | Size | Description |');
+  lines.push('|------|------|-------------|');
+  const descriptions: Record<string, string> = {
+    summary: 'Scan metadata, agent output, parse errors',
+    architecture:
+      'Dependency graph, cycles, critical paths, architecture findings',
+    codeQuality: 'Duplicate detection, complexity, god modules/functions',
+    deadCode: 'Dead files/exports/re-exports, unused deps, boundary violations',
+    fileInventory: 'Per-file function/flow/dependency details',
+    findings: 'All findings across all categories (master list)',
+    graph: 'Mermaid dependency graph',
+    astTrees:
+      'AST tree snapshots (compact indented text — grep/regex friendly)',
+    summaryMd: 'This file — human-readable overview',
+  };
+  for (const [key, file] of Object.entries(outputFiles)) {
+    let size = '—';
+    try {
+      size = formatFileSize(fs.statSync(path.join(dir, file)).size);
+    } catch {
+      size = '—';
+    }
+    lines.push(
+      `| [\`${file}\`](./${file}) | ${size} | ${descriptions[key] || key} |`
+    );
+  }
+  lines.push('');
+}