codesummary 1.2.0 → 1.2.2

package/src/llmGenerator.js

@@ -1,5 +1,10 @@
 import fs from 'fs-extra';
 import path from 'path';
+import RepositorySignals from './analysis/repositorySignals.js';
+import GraphEngine from './graph/graphEngine.js';
+import ProviderClient from './ai/providerClient.js';
+import { buildSemanticClustersPrompt } from './ai/promptTemplates.js';
+import { isAiSemanticEnabled } from './ai/featureFlags.js';
 import { formatFileSize } from './utils.js';
 
 /**
@@ -9,6 +14,8 @@ import { formatFileSize } from './utils.js';
  */
 export class LlmGenerator {
   constructor() {
+    this.repositorySignals = new RepositorySignals();
+    this.graphEngine = new GraphEngine();
     this.stats = {
       filesProcessed: 0,
       filesSkipped: 0,
@@ -22,9 +29,10 @@ export class LlmGenerator {
    * @param {Array} selectedExtensions - Extensions selected by user
    * @param {string} outputPath - Output .md file path
    * @param {string} projectName - Project name
+   * @param {object} generationOptions - Optional rendering options
    * @returns {Promise<object>} Result with outputPath and stats
    */
-  async generateLlmOutput(filesByExtension, selectedExtensions, outputPath, projectName) {
+  async generateLlmOutput(filesByExtension, selectedExtensions, outputPath, projectName, generationOptions = {}) {
     this.stats.startTime = Date.now();
 
     // Collect and sort all selected files
@@ -35,14 +43,23 @@ export class LlmGenerator {
       }
     }
     allFiles.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    const projectUnderstanding = await this.buildProjectUnderstanding(allFiles, {
+      ...generationOptions,
+      projectName
+    });
+    const renderPlan = this.buildRenderPlan(allFiles, projectUnderstanding, generationOptions);
 
     const stream = fs.createWriteStream(outputPath, { encoding: 'utf8' });
 
     await this.writeLine(stream, this.buildHeader(projectName, allFiles));
-    await this.writeLine(stream, this.buildFileTree(allFiles));
+    await this.writeLine(stream, this.buildFocusedContextSection(renderPlan));
+    await this.writeLine(stream, this.buildProjectSummary(projectUnderstanding));
+    await this.writeLine(stream, this.buildDependencySection(projectUnderstanding));
+    await this.writeLine(stream, this.buildSemanticSection(projectUnderstanding));
+    await this.writeLine(stream, this.buildFileTree(renderPlan.filesToRender, renderPlan.focusQuery ? 'Focused File Tree' : 'File Tree'));
 
-    for (const file of allFiles) {
-      const block = await this.buildFileBlock(file);
+    for (const file of renderPlan.filesToRender) {
+      const block = await this.buildFileBlock(file, projectUnderstanding.fileContentsByPath.get(file.relativePath));
       await this.writeLine(stream, block);
     }
 
@@ -59,6 +76,7 @@ export class LlmGenerator {
       totalFiles: this.stats.filesProcessed,
       skippedFiles: this.stats.filesSkipped,
       duration,
+      summaryData: this.buildLlmSummaryData(projectName, allFiles, projectUnderstanding, renderPlan)
     };
   }
 
@@ -90,14 +108,35 @@ export class LlmGenerator {
     );
   }
 
-  buildFileTree(allFiles) {
+  buildFileTree(allFiles, title = 'File Tree') {
     const lines = allFiles.map(f => `  ${f.relativePath}`).join('\n');
-    return `## File Tree\n\n\`\`\`\n${lines}\n\`\`\`\n\n---\n\n`;
+    return `## ${title}\n\n\`\`\`\n${lines}\n\`\`\`\n\n---\n\n`;
+  }
+
+  buildFocusedContextSection(renderPlan) {
+    const { focusQuery, maxTokens, filesToRender, excludedFiles, estimatedTokens } = renderPlan;
+    if (!focusQuery && !maxTokens) return '';
+
+    const primary = filesToRender.slice(0, 6).map(file => file.relativePath);
+    const supporting = filesToRender.slice(6, 16).map(file => file.relativePath);
+    const excluded = excludedFiles.slice(0, 6);
+
+    return (
+      `## Focused Context${focusQuery ? `: ${focusQuery}` : ''}\n\n` +
+      `${focusQuery ? `- Query: ${focusQuery}\n` : ''}` +
+      `${maxTokens ? `- Max tokens budget: ${maxTokens}\n` : ''}` +
+      `- Estimated selected tokens: ${estimatedTokens}\n` +
+      `- Selected files: ${filesToRender.length}\n` +
+      `${primary.length > 0 ? `- Primary files: ${primary.join(', ')}\n` : ''}` +
+      `${supporting.length > 0 ? `- Supporting files: ${supporting.join(', ')}\n` : ''}` +
+      `${excluded.length > 0 ? `- Excluded as lower relevance: ${excluded.join(', ')}\n` : ''}` +
+      '\n---\n\n'
+    );
   }
 
-  async buildFileBlock(file) {
+  async buildFileBlock(file, prefetchedRawContent = null) {
     try {
-      const raw = await fs.readFile(file.absolutePath, 'utf8');
+      const raw = prefetchedRawContent ?? await fs.readFile(file.absolutePath, 'utf8');
       const ext = path.extname(file.relativePath).toLowerCase();
       const optimized = this.optimizeContent(raw, ext);
       const lang = this.fenceLang(ext);
@@ -111,6 +150,682 @@ export class LlmGenerator {
     }
   }
 
+  /**
+   * Build heuristic project-understanding data before rendering.
+   * @param {Array} allFiles - Selected files
+   * @returns {Promise<object>}
+   */
+  async buildProjectUnderstanding(allFiles, generationOptions = {}) {
+    const fileContentsByPath = new Map();
+    const fileInfos = [];
+
+    for (const file of allFiles) {
+      const ext = path.extname(file.relativePath).toLowerCase();
+
+      try {
+        const raw = await fs.readFile(file.absolutePath, 'utf8');
+        fileContentsByPath.set(file.relativePath, raw);
+
+        const imports = this.repositorySignals.extractImports(raw, ext);
+        const calls = this.repositorySignals.extractCalls(raw);
+        const tags = this.repositorySignals.extractFileTags(file.relativePath, ext);
+        const lineCount = raw.split(/\r\n|\r|\n/).length;
+
+        fileInfos.push({
+          path: file.relativePath,
+          ext,
+          size: file.size || 0,
+          lineCount,
+          imports,
+          calls,
+          tags
+        });
+      } catch {
+        // Keep generation resilient even if single-file reads fail.
+      }
+    }
+
+    const graphAnalysis = await this.graphEngine.analyze(allFiles, fileContentsByPath);
+    const dependencyEdges = graphAnalysis.graph.edges.map(edge => [edge.from, edge.to]);
+    const inDegree = graphAnalysis.metrics.inDegree;
+    const outDegree = graphAnalysis.metrics.outDegree;
+
+    const fileScores = fileInfos.map(info => {
+      const indeg = inDegree.get(info.path) || 0;
+      const outdeg = outDegree.get(info.path) || 0;
+      const complexity = (Math.log2(Math.max(1, info.lineCount)) * 1.2) + (info.imports.length * 1.6) + (info.calls.length * 0.25);
+      const centrality = (indeg * 2) + (outdeg * 1.2);
+      const hotspotScore = complexity + centrality;
+
+      return { path: info.path, complexity, centrality, hotspotScore, indeg, outdeg };
+    });
+
+    const fallbackEntrypoints = this.detectFallbackEntrypoints(fileInfos);
+    const entrypoints = graphAnalysis.entrypoints.length > 0 ? graphAnalysis.entrypoints : fallbackEntrypoints;
+    const coreModules = fileScores
+      .slice()
+      .sort((a, b) => b.centrality - a.centrality || b.hotspotScore - a.hotspotScore)
+      .slice(0, 6);
+    const hotspots = fileScores
+      .slice()
+      .sort((a, b) => b.hotspotScore - a.hotspotScore)
+      .slice(0, 6);
+    const suggestedReadingOrder = this.buildSuggestedReadingOrder(entrypoints, dependencyEdges, fileScores);
+    const semanticClusters = this.buildSemanticClusters(fileInfos);
+    const aiSemantic = await this.enrichSemanticClustersWithAi({
+      semanticClusters,
+      entrypoints,
+      coreModules,
+      projectName: generationOptions.projectName || path.basename(process.cwd()),
+      aiOptions: generationOptions.ai || {}
+    });
+
+    return {
+      fileInfos,
+      fileContentsByPath: graphAnalysis.fileContentsByPath,
+      dependencyEdges,
+      entrypoints,
+      coreModules,
+      hotspots,
+      suggestedReadingOrder,
+      semanticClusters: aiSemantic.clusters,
+      aiSemantic,
+      graphMetrics: graphAnalysis.metrics,
+      connectedSubmodules: graphAnalysis.connectedSubmodules,
+      adapterModes: graphAnalysis.graph.metadata.adapterModes
+    };
+  }
+
+  async enrichSemanticClustersWithAi({ projectName, semanticClusters, entrypoints, coreModules, aiOptions }) {
+    const result = {
+      enabled: isAiSemanticEnabled(aiOptions),
+      provider: aiOptions?.provider || null,
+      model: aiOptions?.model || null,
+      used: false,
+      error: null,
+      errorCode: null,
+      retryable: false,
+      failureScope: null,
+      attempts: 0,
+      healthCheckOk: null,
+      clusters: semanticClusters
+    };
+
+    if (!result.enabled || semanticClusters.length === 0) {
+      return result;
+    }
+
+    try {
+      const client = new ProviderClient(aiOptions);
+      const health = await client.healthCheck();
+      result.healthCheckOk = Boolean(health?.ok);
+      if (!health?.ok) {
+        const healthErr = health?.error;
+        result.error = healthErr?.message || 'AI provider health check failed';
+        result.errorCode = healthErr?.code || 'provider_unavailable';
+        result.retryable = Boolean(healthErr?.retryable);
+        result.failureScope = healthErr?.scope || 'provider';
+        return result;
+      }
+
+      const messages = buildSemanticClustersPrompt({
+        projectName,
+        semanticClusters,
+        entrypoints,
+        coreModules
+      });
+
+      const response = await client.chat(messages, {
+        model: aiOptions.model,
+        timeoutMs: aiOptions.timeoutMs,
+        maxRetries: aiOptions.maxRetries,
+        retryBackoffMs: aiOptions.retryBackoffMs,
+        maxBackoffMs: aiOptions.maxBackoffMs
+      });
+      const parsed = this.safeParseJson(response.content);
+      const refined = this.normalizeAiSemanticClusters(parsed?.clusters, semanticClusters);
+      result.attempts = Number.isInteger(response?.attempts) ? response.attempts : 1;
+      if (refined.length > 0) {
+        result.clusters = refined;
+        result.used = true;
+      } else {
+        result.error = 'AI response produced no usable semantic clusters';
+        result.errorCode = 'invalid_semantic_payload';
+        result.failureScope = 'provider';
+      }
+    } catch (error) {
+      result.error = error.message;
+      result.errorCode = error.code || 'ai_error';
+      result.retryable = Boolean(error.retryable);
+      result.failureScope = error.scope || 'provider';
+      result.attempts = Number.isInteger(error?.details?.attempts) ? error.details.attempts : 0;
+    }
+
+    return result;
+  }
+
+  safeParseJson(rawText) {
+    if (typeof rawText !== 'string') return null;
+    const trimmed = rawText.trim();
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      const fencedMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+      if (!fencedMatch) return null;
+      try {
+        return JSON.parse(fencedMatch[1].trim());
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  normalizeAiSemanticClusters(clusters, fallbackClusters) {
+    if (!Array.isArray(clusters)) return fallbackClusters;
+    const normalized = clusters
+      .filter(cluster => cluster && typeof cluster.name === 'string' && Array.isArray(cluster.files))
+      .map(cluster => ({
+        name: cluster.name.trim(),
+        description: typeof cluster.description === 'string' ? cluster.description.trim() : '',
+        files: [...new Set(cluster.files.filter(file => typeof file === 'string' && file.trim().length > 0))]
+      }))
+      .filter(cluster => cluster.name.length > 0 && cluster.files.length > 0);
+
+    return normalized.length > 0 ? normalized : fallbackClusters;
+  }
+
+  buildRenderPlan(allFiles, projectUnderstanding, generationOptions) {
+    const focusQuery = (generationOptions.focus || '').trim();
+    const maxTokens = Number.isInteger(generationOptions.maxTokens) ? generationOptions.maxTokens : null;
+    const fileInfoByPath = new Map(projectUnderstanding.fileInfos.map(info => [info.path, info]));
+    const scoreByPath = new Map();
+    const baseCentralityByPath = new Map(projectUnderstanding.coreModules.map(item => [item.path, item.centrality]));
+    const adjacency = this.buildUndirectedAdjacency(projectUnderstanding.dependencyEdges);
+    const focusTerms = this.extractFocusTerms(focusQuery);
+
+    for (const file of allFiles) {
+      const info = fileInfoByPath.get(file.relativePath);
+      const score = this.computeFocusScore(file.relativePath, info, focusQuery, focusTerms, baseCentralityByPath);
+      scoreByPath.set(file.relativePath, score);
+    }
+
+    const rankedPaths = allFiles
+      .map(file => file.relativePath)
+      .sort((a, b) => (scoreByPath.get(b) || 0) - (scoreByPath.get(a) || 0) || a.localeCompare(b));
+
+    let candidatePaths;
+    if (focusQuery) {
+      const primarySeeds = rankedPaths.filter(pathKey => (scoreByPath.get(pathKey) || 0) > 0).slice(0, 8);
+      const fallbackSeeds = primarySeeds.length > 0 ? primarySeeds : rankedPaths.slice(0, 5);
+      candidatePaths = this.expandFocusNeighborhood(fallbackSeeds, adjacency, 2, 28);
+    } else {
+      candidatePaths = rankedPaths;
+    }
+
+    const selectedPaths = this.applyTokenBudget(candidatePaths, allFiles, projectUnderstanding.fileContentsByPath, maxTokens);
+    const selectedSet = new Set(selectedPaths);
+    const filesToRender = allFiles.filter(file => selectedSet.has(file.relativePath));
+    const excludedFiles = allFiles
+      .map(file => file.relativePath)
+      .filter(pathKey => !selectedSet.has(pathKey))
+      .sort((a, b) => (scoreByPath.get(b) || 0) - (scoreByPath.get(a) || 0) || a.localeCompare(b));
+
+    const estimatedTokens = filesToRender.reduce((sum, file) => (
+      sum + this.estimateFileTokens(file, projectUnderstanding.fileContentsByPath.get(file.relativePath))
+    ), 0);
+
+    return {
+      focusQuery,
+      focusTerms,
+      maxTokens,
+      filesToRender,
+      excludedFiles,
+      scoreByPath,
+      estimatedTokens
+    };
+  }
+
+  extractFocusTerms(focusQuery) {
+    if (!focusQuery) return [];
+    const stopwords = new Set(['the', 'and', 'for', 'with', 'from', 'into', 'that', 'this', 'how', 'what', 'where', 'when']);
+    return focusQuery
+      .toLowerCase()
+      .split(/[^a-z0-9_]+/)
+      .map(term => term.trim())
+      .filter(term => term.length >= 2 && !stopwords.has(term));
+  }
+
+  computeFocusScore(filePath, fileInfo, focusQuery, focusTerms, baseCentralityByPath) {
+    const lowPath = filePath.toLowerCase();
+    const tags = (fileInfo?.tags || []).map(tag => String(tag).toLowerCase());
+    const imports = (fileInfo?.imports || []).map(dep => String(dep).toLowerCase());
+    const calls = (fileInfo?.calls || []).map(call => String(call).toLowerCase());
+    const baseCentrality = baseCentralityByPath.get(filePath) || 0;
+
+    let score = baseCentrality * 0.1;
+
+    if (focusQuery) {
+      const normalizedQuery = focusQuery.toLowerCase();
+      if (lowPath.includes(normalizedQuery)) score += 10;
+    }
+
+    for (const term of focusTerms) {
+      if (lowPath.includes(term)) score += 4;
+      if (tags.some(tag => tag.includes(term))) score += 3;
+      if (imports.some(dep => dep.includes(term))) score += 2;
+      if (calls.some(call => call.includes(term))) score += 1;
+    }
+
+    return score;
+  }
+
+  buildUndirectedAdjacency(dependencyEdges) {
+    const adjacency = new Map();
+    const ensure = key => {
+      if (!adjacency.has(key)) adjacency.set(key, new Set());
+      return adjacency.get(key);
+    };
+
+    for (const [from, to] of dependencyEdges) {
+      ensure(from).add(to);
+      ensure(to).add(from);
+    }
+
+    return adjacency;
+  }
+
+  expandFocusNeighborhood(seedPaths, adjacency, maxDepth = 2, maxNodes = 28) {
+    const seen = new Set(seedPaths);
+    const queue = seedPaths.map(pathKey => ({ pathKey, depth: 0 }));
+
+    while (queue.length > 0 && seen.size < maxNodes) {
+      const current = queue.shift();
+      if (!current) continue;
+      if (current.depth >= maxDepth) continue;
+
+      const neighbors = [...(adjacency.get(current.pathKey) || [])].sort((a, b) => a.localeCompare(b));
+      for (const neighbor of neighbors) {
+        if (!seen.has(neighbor)) {
+          seen.add(neighbor);
+          queue.push({ pathKey: neighbor, depth: current.depth + 1 });
+        }
+        if (seen.size >= maxNodes) break;
+      }
+    }
+
+    return [...seen];
+  }
+
+  applyTokenBudget(candidatePaths, allFiles, fileContentsByPath, maxTokens) {
+    if (!maxTokens) return candidatePaths;
+
+    const fileByPath = new Map(allFiles.map(file => [file.relativePath, file]));
+    let usedTokens = 0;
+    const selected = [];
+
+    for (const pathKey of candidatePaths) {
+      const file = fileByPath.get(pathKey);
+      if (!file) continue;
+
+      const estimated = this.estimateFileTokens(file, fileContentsByPath.get(pathKey));
+      if (selected.length > 0 && usedTokens + estimated > maxTokens) continue;
+
+      selected.push(pathKey);
+      usedTokens += estimated;
+      if (usedTokens >= maxTokens) break;
+    }
+
+    if (selected.length === 0 && candidatePaths.length > 0) {
+      selected.push(candidatePaths[0]);
+    }
+
+    return selected;
+  }
+
+  estimateFileTokens(file, content) {
+    const baseHeaderTokens = 24;
+    const text = typeof content === 'string' ? content : '';
+    const bodyTokens = Math.ceil(text.length / 4);
+    const pathTokens = Math.ceil((file.relativePath || '').length / 4);
+    return baseHeaderTokens + bodyTokens + pathTokens;
+  }
+
+  detectFallbackEntrypoints(fileInfos) {
+    const sourceLikeExtensions = new Set([
+      '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+      '.py', '.java', '.cs', '.cpp', '.c', '.h',
+      '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala',
+      '.sh', '.bash', '.bat', '.ps1'
+    ]);
+
+    const priorityPatterns = [
+      /^bin\//,
+      /^src\/index\./,
+      /^src\/main\./,
+      /^src\/cli\./,
+      /\/index\./,
+      /\/main\./,
+      /\/app\./,
+      /\/server\./
+    ];
+
+    const scored = fileInfos.map(info => {
+      if (!sourceLikeExtensions.has(info.ext)) {
+        return { path: info.path, score: 0 };
+      }
+
+      const lowPath = info.path.toLowerCase();
+      const patternScore = priorityPatterns.reduce((score, pattern, idx) => (
+        pattern.test(lowPath) ? Math.max(score, priorityPatterns.length - idx) : score
+      ), 0);
+      const entryTagScore = info.tags.includes('entry') ? 2 : 0;
+
+      return {
+        path: info.path,
+        score: patternScore + entryTagScore
+      };
+    });
+
+    return scored
+      .filter(item => item.score > 0)
+      .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+      .slice(0, 6)
+      .map(item => item.path);
+  }
+
+  buildSuggestedReadingOrder(entrypoints, dependencyEdges, fileScores) {
+    const sourceLikeExtensions = new Set([
+      '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+      '.py', '.java', '.cs', '.cpp', '.c', '.h',
+      '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala',
+      '.sh', '.bash', '.bat', '.ps1'
+    ]);
+
+    const sourceScores = fileScores.filter(item => {
+      const ext = path.extname(item.path).toLowerCase();
+      return sourceLikeExtensions.has(ext);
+    });
+
+    const adjacency = new Map();
+    for (const [source, target] of dependencyEdges) {
+      if (!adjacency.has(source)) adjacency.set(source, []);
+      adjacency.get(source).push(target);
+    }
+
+    const order = [];
+    const seen = new Set();
+    const queue = [...entrypoints];
+
+    while (queue.length > 0 && order.length < 12) {
+      const current = queue.shift();
+      if (!current || seen.has(current)) continue;
+      seen.add(current);
+      order.push(current);
+
+      const deps = (adjacency.get(current) || []).slice().sort((a, b) => a.localeCompare(b));
+      for (const dep of deps) {
+        const depExt = path.extname(dep).toLowerCase();
+        if (!seen.has(dep) && sourceLikeExtensions.has(depExt)) {
+          queue.push(dep);
+        }
+      }
+    }
+
+    if (order.length < 12) {
+      const centralFallback = sourceScores
+        .slice()
+        .sort((a, b) => b.centrality - a.centrality || b.hotspotScore - a.hotspotScore)
+        .map(item => item.path);
+
+      for (const candidate of centralFallback) {
+        if (!seen.has(candidate)) {
+          seen.add(candidate);
+          order.push(candidate);
+        }
+        if (order.length >= 12) break;
+      }
+    }
+
+    return order;
+  }
+
+  buildProjectSummary(projectUnderstanding) {
+    const { fileInfos, entrypoints, coreModules, hotspots, suggestedReadingOrder, graphMetrics, connectedSubmodules, adapterModes } = projectUnderstanding;
+    const totalLines = fileInfos.reduce((sum, info) => sum + info.lineCount, 0);
+    const languageCount = new Map();
+
+    for (const info of fileInfos) {
+      languageCount.set(info.ext, (languageCount.get(info.ext) || 0) + 1);
+    }
+
+    const topExtensions = [...languageCount.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([ext, count]) => `${ext || '(none)'} (${count})`)
+      .join(', ');
+
+    const entrypointText = entrypoints.length > 0 ? entrypoints.join(', ') : 'None detected';
+    const coreText = coreModules.length > 0
+      ? coreModules.map(module => `${module.path} (centrality ${module.centrality.toFixed(1)})`).join(', ')
+      : 'None detected';
+    const hotspotText = hotspots.length > 0
+      ? hotspots.map(module => `${module.path} (score ${module.hotspotScore.toFixed(1)})`).join(', ')
+      : 'None detected';
+    const readingText = suggestedReadingOrder.length > 0 ? suggestedReadingOrder.join(' -> ') : 'None suggested';
+    const hubsText = graphMetrics.hubs.length > 0
+      ? graphMetrics.hubs.slice(0, 5).map(item => `${item.id} (${item.degree})`).join(', ')
+      : 'None detected';
+    const isolatedText = graphMetrics.isolated.length > 0 ? graphMetrics.isolated.slice(0, 5).join(', ') : 'None';
+    const adapterText = Object.keys(adapterModes).length > 0
+      ? Object.entries(adapterModes).map(([ext, mode]) => `${ext}:${mode}`).join(', ')
+      : 'None';
+    const submoduleText = connectedSubmodules.length > 0
+      ? connectedSubmodules.slice(0, 3).map(group => `[${group.length}] ${group.slice(0, 3).join(', ')}`).join(' | ')
+      : 'None detected';
+
+    return (
+      '## Project Summary\n\n' +
+      `- Total lines (approx): ${totalLines}\n` +
+      `- Top file types: ${topExtensions || 'None'}\n` +
+      `- Entrypoints: ${entrypointText}\n` +
+      `- Core modules: ${coreText}\n` +
+      `- Hotspots (complexity + centrality): ${hotspotText}\n` +
+      `- Graph hubs (out-degree): ${hubsText}\n` +
+      `- Isolated files: ${isolatedText}\n` +
+      `- Connected submodules: ${submoduleText}\n` +
+      `- Language analysis mode: ${adapterText}\n` +
+      `- Suggested reading order: ${readingText}\n\n` +
+      '---\n\n'
+    );
+  }
+
+  buildDependencySection(projectUnderstanding) {
+    const { dependencyEdges, graphMetrics } = projectUnderstanding;
+    const edges = dependencyEdges
+      .slice()
+      .sort((a, b) => {
+        if (a[0] !== b[0]) return a[0].localeCompare(b[0]);
+        return a[1].localeCompare(b[1]);
+      })
+      .slice(0, 30);
+
+    if (edges.length === 0) {
+      return '## Code Dependency Graph\n\n- No internal dependency edges detected with current heuristics.\n\n---\n\n';
+    }
+
+    const lines = edges.map(([source, target]) => `- ${source} -> ${target}`).join('\n');
+    const central = graphMetrics.centralNodes
+      .slice(0, 5)
+      .map(item => `- ${item.id} (in-degree ${item.degree})`)
+      .join('\n');
+    const hubs = graphMetrics.hubs
+      .slice(0, 5)
+      .map(item => `- ${item.id} (out-degree ${item.degree})`)
+      .join('\n');
+
+    return (
+      '## Code Dependency Graph\n\n' +
+      `${lines}\n\n` +
+      '### Central Nodes\n\n' +
+      `${central || '- None'}\n\n` +
+      '### Hub Nodes\n\n' +
+      `${hubs || '- None'}\n\n` +
+      '---\n\n'
+    );
+  }
+
+  buildSemanticClusters(fileInfos) {
+    const clusterMap = new Map();
+    const addToCluster = (name, filePath) => {
+      if (!clusterMap.has(name)) clusterMap.set(name, new Set());
+      clusterMap.get(name).add(filePath);
+    };
+
+    for (const info of fileInfos) {
+      const lowPath = info.path.toLowerCase();
+      const tags = new Set(info.tags || []);
+
+      if (lowPath.includes('/cli') || tags.has('entry')) addToCluster('CLI orchestration', info.path);
+      if (tags.has('config') || lowPath.includes('config')) addToCluster('Configuration', info.path);
+      if (tags.has('api') || lowPath.includes('/api/')) addToCluster('API surface', info.path);
+      if (tags.has('service')) addToCluster('Service layer', info.path);
+      if (tags.has('controller') || lowPath.includes('/controller')) addToCluster('Controllers', info.path);
+      if (tags.has('model') || lowPath.includes('/model')) addToCluster('Data models', info.path);
+      if (lowPath.includes('pdf') || lowPath.includes('doc') || lowPath.includes('summary')) addToCluster('Document generation', info.path);
+      if (tags.has('utility') || lowPath.includes('utils')) addToCluster('Shared utilities', info.path);
+      if (tags.has('test')) addToCluster('Testing', info.path);
+      if (lowPath.includes('/graph/')) addToCluster('Graph analysis', info.path);
+      if (info.ext === '.md' || info.ext === '.txt') addToCluster('Documentation', info.path);
+    }
+
+    return [...clusterMap.entries()]
+      .map(([name, files]) => ({
+        name,
+        files: [...files].sort((a, b) => a.localeCompare(b))
+      }))
+      .sort((a, b) => b.files.length - a.files.length || a.name.localeCompare(b.name))
+      .slice(0, 12);
+  }
+
+  buildSemanticSection(projectUnderstanding) {
+    const { semanticClusters, aiSemantic } = projectUnderstanding;
+
+    if (!semanticClusters || semanticClusters.length === 0) {
+      return '## Semantic Dependency Graph\n\n- No semantic clusters detected with current heuristics.\n\n---\n\n';
+    }
+
+    const aiNote = aiSemantic?.used
+      ? `- Enrichment mode: AI-assisted (${aiSemantic.provider || 'provider'}${aiSemantic.model ? ` / ${aiSemantic.model}` : ''})\n`
+      : (aiSemantic?.enabled
+        ? `- Enrichment mode: heuristic fallback (${this.describeAiFallbackReason(aiSemantic)})\n` +
+          `${aiSemantic.errorCode ? `- AI error code: ${aiSemantic.errorCode}\n` : ''}` +
+          `${aiSemantic.error ? `- AI error detail: ${aiSemantic.error}\n` : ''}` +
+          `${aiSemantic.attempts ? `- AI attempts: ${aiSemantic.attempts}\n` : ''}`
+        : '');
+
+    const lines = semanticClusters
+      .map(cluster => `- ${cluster.name}${cluster.description ? ` (${cluster.description})` : ''} -> ${cluster.files.slice(0, 6).join(', ')}`)
+      .join('\n');
+
+    return `## Semantic Dependency Graph\n\n${aiNote}${lines}\n\n---\n\n`;
+  }
+
+  buildLlmSummaryData(projectName, allFiles, projectUnderstanding, renderPlan = null) {
+    const { entrypoints, coreModules, hotspots, suggestedReadingOrder, dependencyEdges, graphMetrics, adapterModes, semanticClusters, aiSemantic } = projectUnderstanding;
+    const generatedAt = new Date().toISOString();
+    const totalSize = allFiles.reduce((sum, file) => sum + (file.size || 0), 0);
+
+    const codeGraph = {
+      edges: dependencyEdges.map(([from, to]) => ({ from, to })),
+      centralNodes: graphMetrics.centralNodes.map(item => ({ path: item.id, inDegree: item.degree })),
+      hubNodes: graphMetrics.hubs.map(item => ({ path: item.id, outDegree: item.degree })),
+      isolated: graphMetrics.isolated
+    };
+
+    return {
+      version: 1,
+      project: {
+        name: projectName,
+        generatedAt,
+        fileCount: allFiles.length,
+        totalSizeBytes: totalSize
+      },
+      summary: {
+        entrypoints,
+        coreModules: coreModules.map(item => ({
+          path: item.path,
+          centrality: Number(item.centrality.toFixed(2)),
+          hotspotScore: Number(item.hotspotScore.toFixed(2))
+        })),
+        hotspots: hotspots.map(item => ({
+          path: item.path,
+          score: Number(item.hotspotScore.toFixed(2))
+        })),
+        suggestedReadingOrder,
+        languageAnalysisMode: adapterModes,
+        aiSemantic: {
+          enabled: Boolean(aiSemantic?.enabled),
+          used: Boolean(aiSemantic?.used),
+          provider: aiSemantic?.provider || null,
+          model: aiSemantic?.model || null,
+          error: aiSemantic?.error || null,
+          errorCode: aiSemantic?.errorCode || null,
+          retryable: Boolean(aiSemantic?.retryable),
+          failureScope: aiSemantic?.failureScope || null,
+          fallbackReason: aiSemantic?.used ? null : this.describeAiFallbackReason(aiSemantic),
+          attempts: aiSemantic?.attempts || 0,
+          healthCheckOk: aiSemantic?.healthCheckOk
+        },
+        focus: renderPlan ? {
+          query: renderPlan.focusQuery || null,
+          maxTokens: renderPlan.maxTokens || null,
+          estimatedSelectedTokens: renderPlan.estimatedTokens,
+          selectedFiles: renderPlan.filesToRender.map(file => file.relativePath)
+        } : null
+      },
+      graphs: {
+        code: codeGraph,
+        semantic: {
+          clusters: semanticClusters.map(cluster => ({
+            name: cluster.name,
+            files: cluster.files
+          }))
+        }
+      }
+    };
+  }
+
+  /**
+   * Produce a human-readable fallback reason without assuming API downtime for every error.
+   */
+  describeAiFallbackReason(aiSemantic) {
+    if (!aiSemantic?.enabled || aiSemantic?.used) return 'not applicable';
+
+    const code = String(aiSemantic?.errorCode || '').toLowerCase();
+
+    if (['network_unavailable', 'timeout', 'server_error'].includes(code)) {
+      return 'API unavailable';
+    }
+
+    if (code === 'rate_limited') {
+      return 'API rate limited';
+    }
+
+    if (code === 'auth_error') {
+      return 'API authentication/configuration error';
+    }
+
+    if (['bad_request', 'unprocessable', 'payload_too_large'].includes(code)) {
+      return 'API request rejected';
+    }
+
+    if (['invalid_response', 'invalid_semantic_payload'].includes(code)) {
+      return 'AI response not usable';
+    }
+
+    return 'AI enrichment failed';
+  }
+
   /**
    * Apply lossless content optimisations
    * @param {string} content - Raw file content