codesummary 1.2.0 → 1.2.2

package/src/cli.js

@@ -8,8 +8,19 @@ import { createRequire } from 'module';
 import ConfigManager from './configManager.js';
 import Scanner from './scanner.js';
 import PDFGenerator from './pdfGenerator.js';
-import RagGenerator from './ragGenerator.js';
+
 import LlmGenerator from './llmGenerator.js';
+import LlmSummaryRenderer from './renderers/llmSummaryRenderer.js';
+import ProviderClient from './ai/providerClient.js';
+import {
+  buildPdfProjectIntroPrompt,
+  buildPdfArchitectureInsightsPrompt,
+  buildPdfOperationsInsightsPrompt,
+  buildPdfMaintenanceAndSecurityPrompt,
+  buildPdfVisualInsightsPrompt,
+  buildPdfApplicabilityPrompt,
+  buildPdfExecutiveBriefPrompt
+} from './ai/promptTemplates.js';
 import ErrorHandler from './errorHandler.js';
 import { formatFileSize, resolveVersionedPath } from './utils.js';
 
@@ -74,6 +85,19 @@ export class CLI {
       help: false,
       version: false,
       noInteractive: false,
+      emitLlmSummary: false,
+      focus: null,
+      maxTokens: null,
+      aiSemantic: false,
+      aiProvider: null,
+      aiBaseUrl: null,
+      aiApiKey: null,
+      aiModel: null,
+      aiTimeoutMs: null,
+      aiRetries: null,
+      aiRetryBackoffMs: null,
+      aiMaxBackoffMs: null,
+      includeCode: null,
       format: 'pdf'
     };
 
@@ -136,15 +160,112 @@ export class CLI {
         case '--no-interactive':
           options.noInteractive = true;
           break;
+        case '--emit-llmsummary':
+          options.emitLlmSummary = true;
+          break;
+        case '--focus':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.focus = args[i];
+          break;
+        case '--max-tokens':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.maxTokens = Number.parseInt(args[i], 10);
+          if (!Number.isInteger(options.maxTokens) || options.maxTokens <= 0) {
+            throw new Error(`Invalid --max-tokens value: ${args[i]}. Use a positive integer.`);
+          }
+          break;
+        case '--ai-semantic':
+          options.aiSemantic = true;
+          break;
+        case '--provider':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiProvider = args[i];
+          break;
+        case '--base-url':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiBaseUrl = args[i];
+          break;
+        case '--api-key':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiApiKey = args[i];
+          break;
+        case '--model':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiModel = args[i];
+          break;
+        case '--timeout-ms':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiTimeoutMs = Number.parseInt(args[i], 10);
+          if (!Number.isInteger(options.aiTimeoutMs) || options.aiTimeoutMs <= 0) {
+            throw new Error(`Invalid --timeout-ms value: ${args[i]}. Use a positive integer.`);
+          }
+          break;
+        case '--ai-retries':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiRetries = Number.parseInt(args[i], 10);
+          if (!Number.isInteger(options.aiRetries) || options.aiRetries < 0) {
+            throw new Error(`Invalid --ai-retries value: ${args[i]}. Use an integer >= 0.`);
+          }
+          break;
+        case '--ai-retry-backoff-ms':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiRetryBackoffMs = Number.parseInt(args[i], 10);
+          if (!Number.isInteger(options.aiRetryBackoffMs) || options.aiRetryBackoffMs <= 0) {
+            throw new Error(`Invalid --ai-retry-backoff-ms value: ${args[i]}. Use a positive integer.`);
+          }
+          break;
+        case '--ai-max-backoff-ms':
+          if (i + 1 >= args.length) {
+            throw new Error(`Option ${arg} requires a value`);
+          }
+          i++;
+          options.aiMaxBackoffMs = Number.parseInt(args[i], 10);
+          if (!Number.isInteger(options.aiMaxBackoffMs) || options.aiMaxBackoffMs <= 0) {
+            throw new Error(`Invalid --ai-max-backoff-ms value: ${args[i]}. Use a positive integer.`);
+          }
+          break;
+        case '--no-code':
+          options.includeCode = false;
+          break;
+        case '--include-code':
+          options.includeCode = true;
+          break;
         case '--format':
         case '-f':
           if (i + 1 >= args.length) {
-            throw new Error(`Option ${arg} requires a value (pdf or rag)`);
+            throw new Error(`Option ${arg} requires a value (pdf, llm, or both)`);
           }
           i++;
           const format = args[i].toLowerCase();
-          if (!['pdf', 'rag', 'both', 'llm'].includes(format)) {
-            throw new Error(`Invalid format: ${format}. Use 'pdf', 'rag', 'llm', or 'both'`);
+          if (!['pdf', 'both', 'llm'].includes(format)) {
+            throw new Error(`Invalid format: ${format}. Use 'pdf', 'llm', or 'both'`);
           }
           options.format = format;
           break;
@@ -185,6 +306,9 @@ export class CLI {
     // Determine scan path (default: current working directory)
     const scanPath = process.cwd();
     const projectName = path.basename(scanPath);
+    const aiRuntimeOptions = this.buildAiRuntimeOptions(options);
+
+    await this.confirmAiShareRiskIfNeeded(options, aiRuntimeOptions);
 
     console.log(chalk.cyan(`CodeSummary - Scanning project: ${chalk.bold(projectName)}\n`));
 
@@ -216,22 +340,33 @@ export class CLI {
     const totalFiles = this.calculateTotalFiles(filesByExtension, selectedExtensions);
     await this.checkFileCountThreshold(totalFiles, options.noInteractive);
 
-    // Generate output based on format (--both runs pdf+rag; errors are collected)
+    // Generate output based on format
     const runPdf = options.format === 'pdf' || options.format === 'both';
-    const runRag = options.format === 'rag' || options.format === 'both';
-    const runLlm = options.format === 'llm';
+    const runLlm = options.format === 'llm' || options.format === 'both';
     const generationErrors = [];
 
     if (runPdf) {
       try {
         const outputPath = this.determineOutputPath(options.output, projectName);
         await PDFGenerator.ensureOutputDirectory(path.dirname(outputPath));
+        const pdfContentMode = this.resolvePdfContentMode(options, aiRuntimeOptions);
+        const aiProjectContext = await this.generateAiPdfProjectContext(
+          filesByExtension,
+          selectedExtensions,
+          projectName,
+          aiRuntimeOptions
+        );
         const pdfSpinner = ora('Generating PDF document...').start();
         const result = await this.pdfGenerator.generatePDF(
           filesByExtension,
           selectedExtensions,
           outputPath,
-          projectName
+          projectName,
+          {
+            aiProjectContext,
+            includeFileTree: pdfContentMode.includeFileTree,
+            includeSourceCode: pdfContentMode.includeSourceCode
+          }
         );
         pdfSpinner.succeed('PDF generation completed');
         await this.displayCompletionSummary(result.outputPath, selectedExtensions, totalFiles, result.pageCount);
@@ -241,27 +376,6 @@ export class CLI {
       }
     }
 
-    if (runRag) {
-      try {
-        const ragOutputPath = this.determineRagOutputPath(options.output, projectName);
-        await fs.ensureDir(path.dirname(ragOutputPath));
-        const ragSpinner = ora('Generating RAG-optimized output...').start();
-        const ragGenerator = new RagGenerator();
-        const result = await ragGenerator.generateRagOutput(
-          filesByExtension,
-          selectedExtensions,
-          ragOutputPath,
-          projectName,
-          scanPath
-        );
-        ragSpinner.succeed('RAG output generation completed');
-        await this.displayRagCompletionSummary(result.outputPath, selectedExtensions, totalFiles, result.totalChunks);
-      } catch (error) {
-        generationErrors.push(`RAG: ${error.message}`);
-        console.error(chalk.red(`ERROR generating RAG output: ${error.message}`));
-      }
-    }
-
     if (runLlm) {
       try {
         const llmOutputPath = this.determineLlmOutputPath(options.output, projectName);
@@ -272,10 +386,25 @@ export class CLI {
           filesByExtension,
           selectedExtensions,
           llmOutputPath,
-          projectName
+          projectName,
+          {
+            focus: options.focus,
+            maxTokens: options.maxTokens,
+            ai: aiRuntimeOptions
+          }
         );
         llmSpinner.succeed('LLM output generation completed');
         await this.displayLlmCompletionSummary(result.outputPath, selectedExtensions, totalFiles);
+
+        if (options.emitLlmSummary) {
+          const llmSummaryOutputPath = this.determineLlmSummaryOutputPath(options.output);
+          await fs.ensureDir(path.dirname(llmSummaryOutputPath));
+          const summarySpinner = ora('Generating .llmsummary.json...').start();
+          const llmSummaryRenderer = new LlmSummaryRenderer();
+          const summaryResult = await llmSummaryRenderer.render(llmSummaryOutputPath, result.summaryData);
+          summarySpinner.succeed('.llmsummary.json generation completed');
+          await this.displayLlmSummaryCompletionSummary(summaryResult.outputPath);
+        }
       } catch (error) {
         generationErrors.push(`LLM: ${error.message}`);
         console.error(chalk.red(`ERROR generating LLM output: ${error.message}`));
@@ -372,19 +501,23 @@ export class CLI {
   }
 
   /**
-   * Determine final output path for RAG format
+   * Determine final output path for PDF
    * @param {string} overridePath - Optional override path from CLI
    * @param {string} projectName - Project name
    * @returns {string} Final output path
    */
-  determineRagOutputPath(overridePath, projectName) {
+  determineOutputPath(overridePath, projectName) {
     let outputDir;
 
     if (overridePath) {
+      // Validate and sanitize override path from CLI
       const sanitizedPath = ErrorHandler.sanitizeInput(overridePath, { allowPath: true });
       ErrorHandler.validatePath(sanitizedPath, { preventTraversal: true });
+      
       outputDir = path.resolve(sanitizedPath);
+      console.log(chalk.gray(`PDF will be saved to: ${outputDir}`));
     } else {
+      // Use config settings
       if (this.config.output.mode === 'relative') {
         outputDir = process.cwd();
       } else {
@@ -392,28 +525,26 @@ export class CLI {
       }
     }
 
+    // Sanitize project name for filename
     const sanitizedProjectName = ErrorHandler.sanitizeInput(projectName);
-    return resolveVersionedPath(path.join(outputDir, `${sanitizedProjectName}_rag.json`));
+    
+    return PDFGenerator.generateOutputPath(sanitizedProjectName, outputDir);
   }
 
   /**
-   * Determine final output path for PDF
+   * Determine final output path for LLM Markdown format
    * @param {string} overridePath - Optional override path from CLI
    * @param {string} projectName - Project name
    * @returns {string} Final output path
    */
-  determineOutputPath(overridePath, projectName) {
+  determineLlmOutputPath(overridePath, projectName) {
     let outputDir;
 
     if (overridePath) {
-      // Validate and sanitize override path from CLI
       const sanitizedPath = ErrorHandler.sanitizeInput(overridePath, { allowPath: true });
       ErrorHandler.validatePath(sanitizedPath, { preventTraversal: true });
-      
       outputDir = path.resolve(sanitizedPath);
-      console.log(chalk.gray(`PDF will be saved to: ${outputDir}`));
     } else {
-      // Use config settings
       if (this.config.output.mode === 'relative') {
         outputDir = process.cwd();
       } else {
@@ -421,35 +552,634 @@ export class CLI {
       }
     }
 
-    // Sanitize project name for filename
     const sanitizedProjectName = ErrorHandler.sanitizeInput(projectName);
-    
-    return PDFGenerator.generateOutputPath(sanitizedProjectName, outputDir);
+    return resolveVersionedPath(path.join(outputDir, `${sanitizedProjectName}_llm.md`));
   }
 
   /**
-   * Determine final output path for LLM Markdown format
+   * Determine final output path for .llmsummary.json artifact
    * @param {string} overridePath - Optional override path from CLI
-   * @param {string} projectName - Project name
    * @returns {string} Final output path
    */
-  determineLlmOutputPath(overridePath, projectName) {
+  determineLlmSummaryOutputPath(overridePath) {
     let outputDir;
 
     if (overridePath) {
       const sanitizedPath = ErrorHandler.sanitizeInput(overridePath, { allowPath: true });
       ErrorHandler.validatePath(sanitizedPath, { preventTraversal: true });
       outputDir = path.resolve(sanitizedPath);
+    } else if (this.config.output.mode === 'relative') {
+      outputDir = process.cwd();
     } else {
-      if (this.config.output.mode === 'relative') {
-        outputDir = process.cwd();
-      } else {
-        outputDir = path.resolve(this.config.output.fixedPath);
+      outputDir = path.resolve(this.config.output.fixedPath);
+    }
+
+    return resolveVersionedPath(path.join(outputDir, '.llmsummary.json'));
+  }
+
+  buildAiRuntimeOptions(options) {
+    const configAi = this.config?.ai || {};
+    const provider = options.aiProvider || configAi.provider || 'openai-compatible';
+    const baseUrl = options.aiBaseUrl || configAi.baseUrl || 'http://localhost:11434/v1';
+    const apiKey = options.aiApiKey ?? configAi.apiKey ?? '';
+    const model = options.aiModel || configAi.model || (provider === 'ollama' ? 'llama3.1' : '');
+    const timeoutMs = options.aiTimeoutMs || configAi.timeoutMs || 30000;
+    const maxRetries = Number.isInteger(options.aiRetries) ? options.aiRetries : (configAi.maxRetries ?? 2);
+    const retryBackoffMs = Number.isInteger(options.aiRetryBackoffMs) ? options.aiRetryBackoffMs : (configAi.retryBackoffMs ?? 500);
+    const maxBackoffMs = Number.isInteger(options.aiMaxBackoffMs) ? options.aiMaxBackoffMs : (configAi.maxBackoffMs ?? 5000);
+    const enabled = Boolean(options.aiSemantic) || configAi.enabled === true;
+
+    return {
+      enabled,
+      semantic: options.aiSemantic || configAi.enabled === true,
+      provider,
+      baseUrl,
+      apiKey,
+      model,
+      timeoutMs,
+      maxRetries,
+      retryBackoffMs,
+      maxBackoffMs
+    };
+  }
+
+  resolvePdfContentMode(options, aiRuntimeOptions) {
+    if (typeof options.includeCode === 'boolean') {
+      return {
+        includeFileTree: true,
+        includeSourceCode: options.includeCode
+      };
+    }
+
+    const aiExecutiveMode = Boolean(aiRuntimeOptions?.enabled && aiRuntimeOptions?.semantic);
+    return {
+      includeFileTree: true,
+      includeSourceCode: !aiExecutiveMode
+    };
+  }
+
+  buildSelectedFilesList(filesByExtension, selectedExtensions) {
+    const allFiles = [];
+    selectedExtensions.forEach(ext => {
+      if (filesByExtension[ext]) {
+        allFiles.push(...filesByExtension[ext]);
+      }
+    });
+    allFiles.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return allFiles;
+  }
+
+  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 {
+        const start = trimmed.indexOf('{');
+        const end = trimmed.lastIndexOf('}');
+        if (start === -1 || end === -1 || end <= start) return null;
+        try {
+          return JSON.parse(trimmed.slice(start, end + 1));
+        } catch {
+          return null;
+        }
       }
     }
+  }
 
-    const sanitizedProjectName = ErrorHandler.sanitizeInput(projectName);
-    return resolveVersionedPath(path.join(outputDir, `${sanitizedProjectName}_llm.md`));
+  normalizePdfProjectContext(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+    const overview = typeof payload.overview === 'string' ? payload.overview.trim() : '';
+    const primaryPurpose = typeof payload.primaryPurpose === 'string' ? payload.primaryPurpose.trim() : '';
+    const keyComponents = Array.isArray(payload.keyComponents)
+      ? payload.keyComponents.filter(item => typeof item === 'string').map(item => item.trim()).filter(Boolean).slice(0, 8)
+      : [];
+    const suggestedReadingPath = Array.isArray(payload.suggestedReadingPath)
+      ? payload.suggestedReadingPath.filter(item => typeof item === 'string').map(item => item.trim()).filter(Boolean).slice(0, 8)
+      : [];
+
+    if (!overview && !primaryPurpose && keyComponents.length === 0 && suggestedReadingPath.length === 0) {
+      return null;
+    }
+
+    return {
+      overview,
+      primaryPurpose,
+      keyComponents,
+      suggestedReadingPath
+    };
+  }
+
+  normalizeStringList(list, maxItems = 10) {
+    if (!Array.isArray(list)) return [];
+    return list
+      .filter(item => typeof item === 'string')
+      .map(item => item.trim())
+      .filter(Boolean)
+      .slice(0, maxItems);
+  }
+
+  normalizePdfArchitectureContext(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+    const structuralPatterns = this.normalizeStringList(payload.structuralPatterns, 8);
+    const implementationParadigm = this.normalizeStringList(payload.implementationParadigm, 8);
+    const couplingPoints = this.normalizeStringList(payload.couplingPoints, 8);
+
+    if (
+      structuralPatterns.length === 0 &&
+      implementationParadigm.length === 0 &&
+      couplingPoints.length === 0
+    ) {
+      return null;
+    }
+
+    return {
+      structuralPatterns,
+      implementationParadigm,
+      couplingPoints
+    };
+  }
+
+  normalizePdfOperationsContext(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+    const inboundOutbound = this.normalizeStringList(payload?.dataAndStateLifecycle?.inboundOutbound, 10);
+    const criticalTransformations = this.normalizeStringList(payload?.dataAndStateLifecycle?.criticalTransformations, 10);
+    const stateManagement = this.normalizeStringList(payload?.dataAndStateLifecycle?.stateManagement, 10);
+    const configurationHierarchy = this.normalizeStringList(payload?.configurationAndEnvironmentStrategy?.configurationHierarchy, 10);
+    const infrastructureDependencies = this.normalizeStringList(payload?.configurationAndEnvironmentStrategy?.infrastructureDependencies, 10);
+    const responsibilityDistribution = this.normalizeStringList(payload?.languageSpecificBreakdown?.responsibilityDistribution, 10);
+    const interoperability = this.normalizeStringList(payload?.languageSpecificBreakdown?.interoperability, 10);
+
+    if (
+      inboundOutbound.length === 0 &&
+      criticalTransformations.length === 0 &&
+      stateManagement.length === 0 &&
+      configurationHierarchy.length === 0 &&
+      infrastructureDependencies.length === 0 &&
+      responsibilityDistribution.length === 0 &&
+      interoperability.length === 0
+    ) {
+      return null;
+    }
+
+    return {
+      dataAndStateLifecycle: {
+        inboundOutbound,
+        criticalTransformations,
+        stateManagement
+      },
+      configurationAndEnvironmentStrategy: {
+        configurationHierarchy,
+        infrastructureDependencies
+      },
+      languageSpecificBreakdown: {
+        responsibilityDistribution,
+        interoperability
+      }
+    };
+  }
+
+  normalizePdfMaintenanceAndSecurityContext(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+    const complexityHotspots = this.normalizeStringList(payload?.onboardingAndMaintenanceGuide?.complexityHotspots, 10);
+    const modificationGuide = this.normalizeStringList(payload?.onboardingAndMaintenanceGuide?.modificationGuide, 10);
+    const domainGlossary = this.normalizeStringList(payload?.onboardingAndMaintenanceGuide?.domainGlossary, 16);
+    const exposureSurface = this.normalizeStringList(payload?.securityAndComplianceSurface?.exposureSurface, 10);
+    const sensitiveDataHandling = this.normalizeStringList(payload?.securityAndComplianceSurface?.sensitiveDataHandling, 10);
+
+    if (
+      complexityHotspots.length === 0 &&
+      modificationGuide.length === 0 &&
+      domainGlossary.length === 0 &&
+      exposureSurface.length === 0 &&
+      sensitiveDataHandling.length === 0
+    ) {
+      return null;
+    }
+
+    return {
+      onboardingAndMaintenanceGuide: {
+        complexityHotspots,
+        modificationGuide,
+        domainGlossary
+      },
+      securityAndComplianceSurface: {
+        exposureSurface,
+        sensitiveDataHandling
+      }
+    };
+  }
+
+  normalizePdfVisualContext(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+    const semanticDirectoryTree = this.normalizeStringList(payload.semanticDirectoryTree, 60);
+    const dependencyTextGraph = this.normalizeStringList(payload.dependencyTextGraph, 60);
+
+    if (semanticDirectoryTree.length === 0 && dependencyTextGraph.length === 0) {
+      return null;
+    }
+
+    return {
+      semanticDirectoryTree,
+      dependencyTextGraph
+    };
+  }
+
+  normalizePdfApplicabilityContext(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+    const infrastructureAsCode = this.normalizeStringList(payload?.whyItHelpsAcrossProjects?.infrastructureAsCode, 8);
+    const dataPlatforms = this.normalizeStringList(payload?.whyItHelpsAcrossProjects?.dataPlatforms, 8);
+    const frontendApplications = this.normalizeStringList(payload?.whyItHelpsAcrossProjects?.frontendApplications, 8);
+    const backendServices = this.normalizeStringList(payload?.whyItHelpsAcrossProjects?.backendServices, 8);
+    const genericTransferableValue = this.normalizeStringList(payload?.whyItHelpsAcrossProjects?.genericTransferableValue, 8);
+
+    if (
+      infrastructureAsCode.length === 0 &&
+      dataPlatforms.length === 0 &&
+      frontendApplications.length === 0 &&
+      backendServices.length === 0 &&
+      genericTransferableValue.length === 0
+    ) {
+      return null;
+    }
+
+    return {
+      whyItHelpsAcrossProjects: {
+        infrastructureAsCode,
+        dataPlatforms,
+        frontendApplications,
+        backendServices,
+        genericTransferableValue
+      }
+    };
+  }
+
+  normalizePdfExecutiveBrief(payload) {
+    if (!payload || typeof payload !== 'object') return null;
+
+    const purpose = typeof payload?.executiveSummary?.purpose === 'string'
+      ? payload.executiveSummary.purpose.trim()
+      : '';
+    const killerFeatures = this.normalizeStringList(payload?.executiveSummary?.killerFeatures, 3).slice(0, 3);
+
+    const architectureBlueprint = Array.isArray(payload.architectureBlueprint)
+      ? payload.architectureBlueprint
+        .map(item => ({
+          pattern: typeof item?.pattern === 'string' ? item.pattern.trim() : '',
+          primaryModule: typeof item?.primaryModule === 'string' ? item.primaryModule.trim() : '',
+          value: typeof item?.value === 'string' ? item.value.trim() : ''
+        }))
+        .filter(item => item.pattern && item.primaryModule && item.value)
+        .slice(0, 3)
+      : [];
+
+    const primaryFlow = typeof payload?.dataFlow?.primaryFlow === 'string'
+      ? payload.dataFlow.primaryFlow.trim()
+      : '';
+    const keyFlows = this.normalizeStringList(payload?.dataFlow?.keyFlows, 5);
+
+    const onboardingQuickGuide = Array.isArray(payload.onboardingQuickGuide)
+      ? payload.onboardingQuickGuide
+        .map(item => ({
+          goal: typeof item?.goal === 'string' ? item.goal.trim() : '',
+          modify: typeof item?.modify === 'string' ? item.modify.trim() : ''
+        }))
+        .filter(item => item.goal && item.modify)
+        .slice(0, 5)
+      : [];
+
+    const riskHotspots = Array.isArray(payload.riskHotspots)
+      ? payload.riskHotspots
+        .map(item => ({
+          severity: typeof item?.severity === 'string' ? item.severity.trim() : 'High',
+          file: typeof item?.file === 'string' ? item.file.trim() : '',
+          reason: typeof item?.reason === 'string' ? item.reason.trim() : ''
+        }))
+        .filter(item => item.file && item.reason)
+        .slice(0, 3)
+      : [];
+
+    if (
+      !purpose &&
+      killerFeatures.length === 0 &&
+      architectureBlueprint.length === 0 &&
+      !primaryFlow &&
+      keyFlows.length === 0 &&
+      onboardingQuickGuide.length === 0 &&
+      riskHotspots.length === 0
+    ) {
+      return null;
+    }
+
+    return {
+      executiveSummary: {
+        purpose,
+        killerFeatures
+      },
+      architectureBlueprint,
+      dataFlow: {
+        primaryFlow,
+        keyFlows
+      },
+      onboardingQuickGuide,
+      riskHotspots
+    };
+  }
+
+  buildPdfComponentLanguageMap(fileInfos) {
+    const bucket = new Map();
+    for (const info of fileInfos) {
+      const parts = info.path.split('/');
+      const topLevel = parts.length > 1 ? parts[0] : '.';
+      const key = `${topLevel}:${info.ext || 'unknown'}`;
+      bucket.set(key, (bucket.get(key) || 0) + 1);
+    }
+
+    return [...bucket.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 12)
+      .map(([key, count]) => {
+        const [segment, ext] = key.split(':');
+        return `${segment} -> ${ext} (${count} files)`;
+      });
+  }
+
+  async loadDependencySnapshot() {
+    const packageJsonPath = path.join(process.cwd(), 'package.json');
+    if (!(await fs.pathExists(packageJsonPath))) return [];
+
+    try {
+      const pkg = await fs.readJson(packageJsonPath);
+      const deps = Object.entries(pkg.dependencies || {}).map(([name, version]) => `${name}@${version}`);
+      const devDeps = Object.entries(pkg.devDependencies || {}).map(([name, version]) => `${name}@${version} (dev)`);
+      return [...deps, ...devDeps].slice(0, 20);
+    } catch {
+      return [];
+    }
+  }
+
+  buildAiPdfContextInput(projectName, allFiles, selectedExtensions, filesByExtension, projectUnderstanding, dependencySnapshot) {
+    const topExtensions = selectedExtensions
+      .map(ext => ({
+        ext,
+        count: filesByExtension[ext]?.length || 0
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 8);
+
+    return {
+      projectName,
+      totalFiles: allFiles.length,
+      selectedExtensions,
+      topExtensions: topExtensions.map(item => `${item.ext} (${item.count})`),
+      entrypoints: projectUnderstanding.entrypoints.slice(0, 10),
+      coreModules: projectUnderstanding.coreModules.slice(0, 10).map(item => ({
+        path: item.path,
+        centrality: Number(item.centrality?.toFixed?.(2) ?? item.centrality ?? 0),
+        inDegree: item.indeg || 0,
+        outDegree: item.outdeg || 0,
+        hotspotScore: Number(item.hotspotScore?.toFixed?.(2) ?? item.hotspotScore ?? 0)
+      })),
+      hotspots: projectUnderstanding.hotspots.slice(0, 10).map(item => ({
+        path: item.path,
+        hotspotScore: Number(item.hotspotScore?.toFixed?.(2) ?? item.hotspotScore ?? 0),
+        complexity: Number(item.complexity?.toFixed?.(2) ?? item.complexity ?? 0),
+        centrality: Number(item.centrality?.toFixed?.(2) ?? item.centrality ?? 0)
+      })),
+      semanticClusters: projectUnderstanding.semanticClusters.slice(0, 8).map(cluster => ({
+        name: cluster.name,
+        description: cluster.description || '',
+        files: (cluster.files || []).slice(0, 8)
+      })),
+      adapterModes: projectUnderstanding.adapterModes || {},
+      graphMetrics: {
+        hubs: (projectUnderstanding.graphMetrics?.hubs || []).slice(0, 8),
+        centralNodes: (projectUnderstanding.graphMetrics?.centralNodes || []).slice(0, 8),
+        isolatedCount: projectUnderstanding.graphMetrics?.isolated?.length || 0,
+        isolatedExamples: (projectUnderstanding.graphMetrics?.isolated || []).slice(0, 8)
+      },
+      connectedSubmodules: (projectUnderstanding.connectedSubmodules || [])
+        .slice(0, 8)
+        .map(component => component.slice(0, 8)),
+      suggestedReadingOrder: projectUnderstanding.suggestedReadingOrder.slice(0, 12),
+      dependencyEdges: projectUnderstanding.dependencyEdges.slice(0, 120).map(([from, to]) => `${from} -> ${to}`),
+      componentLanguageMap: this.buildPdfComponentLanguageMap(projectUnderstanding.fileInfos || []),
+      dependencySnapshot,
+      outputContext: {
+        outputModes: ['pdf', 'llm'],
+        configResolution: [
+          'Global config: ~/.codesummary/config.json (POSIX) or %APPDATA%/CodeSummary/config.json (Windows)',
+          'Runtime path: process.cwd()',
+          'Sensitive path filtering: .csignore'
+        ],
+        pipeline: [
+          'CLI argument parsing and config merge',
+          'Scanner recursive traversal and extension filtering',
+          'GraphEngine dependency extraction and metrics',
+          'PDF generator structured rendering'
+        ],
+        knownInterfaces: [
+          'CLI options and config file settings',
+          '.csignore for sensitive path filtering',
+          'LLM provider API endpoint'
+        ]
+      }
+    };
+  }
+
+  async requestAiPdfSection(client, prompt, aiOptions) {
+    try {
+      const response = await client.chat(prompt, {
+        model: aiOptions.model,
+        timeoutMs: aiOptions.timeoutMs,
+        maxRetries: aiOptions.maxRetries,
+        retryBackoffMs: aiOptions.retryBackoffMs,
+        maxBackoffMs: aiOptions.maxBackoffMs
+      });
+      return this.safeParseJson(response?.content);
+    } catch {
+      return null;
+    }
+  }
+
+  normalizeUnifiedPdfAiContext({ executiveBriefPayload, introPayload, architecturePayload, operationsPayload, maintenancePayload, visualPayload, applicabilityPayload }) {
+    const executiveBrief = this.normalizePdfExecutiveBrief(executiveBriefPayload);
+    const intro = this.normalizePdfProjectContext(introPayload);
+    const architecture = this.normalizePdfArchitectureContext(architecturePayload);
+    const operations = this.normalizePdfOperationsContext(operationsPayload);
+    const maintenanceAndSecurity = this.normalizePdfMaintenanceAndSecurityContext(maintenancePayload);
+    const visualizations = this.normalizePdfVisualContext(visualPayload);
+    const applicability = this.normalizePdfApplicabilityContext(applicabilityPayload);
+
+    if (!executiveBrief && !intro && !architecture && !operations && !maintenanceAndSecurity && !visualizations && !applicability) {
+      return null;
+    }
+
+    return {
+      executiveBrief,
+      intro,
+      architecture,
+      operations,
+      maintenanceAndSecurity,
+      visualizations,
+      applicability
+    };
+  }
+
+  async generateAiPdfProjectContext(filesByExtension, selectedExtensions, projectName, aiOptions) {
+    if (!aiOptions?.enabled || !aiOptions?.semantic) {
+      console.log(chalk.gray('AI enrichment skipped: not enabled or semantic flag missing.'));
+      return null;
+    }
+
+    try {
+      console.log(chalk.cyan('Generating AI project context...'));
+      const allFiles = this.buildSelectedFilesList(filesByExtension, selectedExtensions);
+      const llmGenerator = new LlmGenerator();
+      
+      console.log(chalk.gray('  • Building project understanding...'));
+      const projectUnderstanding = await llmGenerator.buildProjectUnderstanding(allFiles, {
+        projectName,
+        ai: { enabled: false, semantic: false }
+      });
+      
+      console.log(chalk.gray('  • Loading dependency snapshot...'));
+      const dependencySnapshot = await this.loadDependencySnapshot();
+      
+      const contextInput = this.buildAiPdfContextInput(
+        projectName,
+        allFiles,
+        selectedExtensions,
+        filesByExtension,
+        projectUnderstanding,
+        dependencySnapshot
+      );
+
+      console.log(chalk.gray(`  • Connecting to AI provider: ${aiOptions.provider}...`));
+      const client = new ProviderClient(aiOptions);
+      const health = await client.healthCheck();
+      if (!health?.ok) {
+        console.log(chalk.red(`  • AI Health check failed: ${health?.error || 'Unknown error'}`));
+        return null;
+      }
+
+      console.log(chalk.gray('  • Fetching executive brief from AI...'));
+      const executiveBriefPayload = await this.requestAiPdfSection(
+        client,
+        buildPdfExecutiveBriefPrompt(contextInput),
+        aiOptions
+      );
+
+      if (this.normalizePdfExecutiveBrief(executiveBriefPayload)) {
+        console.log(chalk.green('  ✓ AI context generated successfully (Executive Brief).'));
+        return this.normalizeUnifiedPdfAiContext({
+          executiveBriefPayload
+        });
+      }
+
+      console.log(chalk.gray('  • Fetching detailed insights from AI (mult-request mode)...'));
+      const introPayload = await this.requestAiPdfSection(
+        client,
+        buildPdfProjectIntroPrompt(contextInput),
+        aiOptions
+      );
+      const architecturePayload = await this.requestAiPdfSection(
+        client,
+        buildPdfArchitectureInsightsPrompt(contextInput),
+        aiOptions
+      );
+      const operationsPayload = await this.requestAiPdfSection(
+        client,
+        buildPdfOperationsInsightsPrompt(contextInput),
+        aiOptions
+      );
+      const maintenancePayload = await this.requestAiPdfSection(
+        client,
+        buildPdfMaintenanceAndSecurityPrompt(contextInput),
+        aiOptions
+      );
+      const visualPayload = await this.requestAiPdfSection(
+        client,
+        buildPdfVisualInsightsPrompt(contextInput),
+        aiOptions
+      );
+      const applicabilityPayload = await this.requestAiPdfSection(
+        client,
+        buildPdfApplicabilityPrompt(contextInput),
+        aiOptions
+      );
+
+      console.log(chalk.green('  ✓ AI context generated successfully (Multi-section).'));
+      return this.normalizeUnifiedPdfAiContext({
+        executiveBriefPayload,
+        introPayload,
+        architecturePayload,
+        operationsPayload,
+        maintenancePayload,
+        visualPayload,
+        applicabilityPayload
+      });
+    } catch (error) {
+      console.log(chalk.red(`  • Error generating AI context: ${error.message}`));
+      return null;
+    }
+  }
+
+  /**
+   * Ask for explicit confirmation when AI enrichment may send repository content
+   * to a configured external provider and no .csignore exists in the current working directory.
+   * @param {object} options - Parsed CLI options
+   * @param {object} aiOptions - Resolved AI runtime options
+   */
+  async confirmAiShareRiskIfNeeded(options, aiOptions) {
+    const runLlm = options.format === 'llm' || options.format === 'both';
+    const runPdf = options.format === 'pdf' || options.format === 'both';
+    const willShareWithProvider = Boolean(
+      (runLlm || runPdf) &&
+      aiOptions?.enabled &&
+      aiOptions?.semantic &&
+      aiOptions?.provider
+    );
+
+    if (!willShareWithProvider) {
+      return;
+    }
+
+    const csIgnorePath = path.join(process.cwd(), '.csignore');
+    const hasCsIgnore = await fs.pathExists(csIgnorePath);
+    if (hasCsIgnore) {
+      return;
+    }
+
+    console.log(chalk.yellow('\nSECURITY WARNING'));
+    console.log(chalk.yellow(`Code may be shared with the configured LLM provider (${aiOptions.provider}${aiOptions.model ? ` / ${aiOptions.model}` : ''}).`));
+    console.log(chalk.yellow('This may include credentials, API tokens, or other sensitive information.'));
+    console.log(chalk.gray('To reduce exposure, add sensitive paths to a .csignore file in the current working directory.'));
+    console.log(chalk.gray('.csignore uses .gitignore-style syntax and is applied to CodeSummary reports.\n'));
+
+    if (options.noInteractive || !process.stdin.isTTY) {
+      console.error(chalk.red('ERROR: Confirmation cannot be requested in non-interactive mode without .csignore.'));
+      console.error(chalk.red('Create .csignore in the current directory or run without --no-interactive to confirm explicitly.'));
+      await ErrorHandler.safeExit(1, 'AI risk confirmation required');
+      return;
+    }
+
+    const { continueWithRisks } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'continueWithRisks',
+      message: 'Do you want to continue, acknowledging these risks?',
+      default: false
+    }]);
+
+    if (!continueWithRisks) {
+      console.log(chalk.gray('Operation cancelled to protect sensitive information.'));
+      await ErrorHandler.safeExit(0, 'Operation cancelled by user due to AI sharing risk');
+    }
   }
 
   /**
@@ -472,28 +1202,6 @@ export class CLI {
     console.log();
   }
 
-  /**
-   * Display RAG completion summary
-   * @param {string} outputPath - Generated RAG JSON path
-   * @param {Array} selectedExtensions - Selected extensions
-   * @param {number} totalFiles - Total files processed
-   * @param {number} totalChunks - Number of chunks generated
-   */
-  async displayRagCompletionSummary(outputPath, selectedExtensions, totalFiles, totalChunks) {
-    const stats = await fs.stat(outputPath);
-    const fileSizeFormatted = formatFileSize(stats.size);
-
-    console.log(chalk.green('\nSUCCESS: RAG-optimized output generated successfully!\n'));
-    console.log(chalk.cyan('Summary:'));
-    console.log(chalk.gray(`   Output: ${outputPath}`));
-    console.log(chalk.gray(`   Extensions: ${selectedExtensions.join(', ')}`));
-    console.log(chalk.gray(`   Total files: ${totalFiles}`));
-    console.log(chalk.gray(`   Total chunks: ${totalChunks}`));
-    console.log(chalk.gray(`   JSON size: ${fileSizeFormatted}`));
-    console.log(chalk.gray(`   Ready for RAG/LLM ingestion`));
-    console.log();
-  }
-
   /**
    * Display completion summary
    * @param {string} outputPath - Generated PDF path
@@ -568,7 +1276,7 @@ export class CLI {
    * Show help information
    */
   showHelp() {
-    console.log(chalk.cyan('\nCodeSummary - Generate PDF documentation from source code\n'));
+    console.log(chalk.cyan('\nCodeSummary - Generate AI and PDF documentation from source code\n'));
     
     console.log(chalk.white('Usage:'));
     console.log('  codesummary [options]                 Scan current directory and generate PDF');
@@ -577,7 +1285,23 @@ export class CLI {
     
     console.log(chalk.white('Options:'));
     console.log('  -o, --output <path>                   Override output directory');
-    console.log('  -f, --format <format>                 Output format: pdf (default), rag, llm, or both (pdf+rag)');
+    console.log('  -f, --format <format>                 Output format: llm (primary), pdf, or both (pdf+llm)');
+    console.log('  --emit-llmsummary                     Emit structured repository artifact (.llmsummary.json)');
+    console.log('  --focus <query>                       Generate focused context pack for a specific task/query');
+    console.log('  --max-tokens <n>                      Cap output context to approximately n tokens');
+    console.log('  --ai-semantic                         Enable optional LLM-assisted semantic enrichment');
+    console.log('                                        Adds AI semantic enrichment in LLM output and AI project context in PDF when available');
+    console.log('                                        If .csignore is missing, CodeSummary asks for risk confirmation before scan');
+    console.log('  --provider <name>                     AI provider: openai-compatible (default) or ollama');
+    console.log('  --base-url <url>                      Provider base URL');
+    console.log('  --api-key <key>                       Provider API key (if required)');
+    console.log('  --model <name>                        Provider model name');
+    console.log('  --timeout-ms <n>                      AI request timeout in milliseconds');
+    console.log('  --ai-retries <n>                      AI retry attempts on retryable API errors');
+    console.log('  --ai-retry-backoff-ms <n>             Initial retry backoff in milliseconds');
+    console.log('  --ai-max-backoff-ms <n>               Max retry backoff cap in milliseconds');
+    console.log('  --no-code                             Exclude full source code section from PDF');
+    console.log('  --include-code                        Force include full source code section in PDF');
     console.log('  --show-config                         Display current configuration');
     console.log('  --reset-config                        Reset configuration to defaults');
     console.log('  -h, --help                            Show this help message');
@@ -586,8 +1310,15 @@ export class CLI {
     
     console.log(chalk.white('Examples:'));
     console.log('  codesummary                           Scan current project (PDF)');
-    console.log('  codesummary --format rag              Generate RAG-optimised JSON');
     console.log('  codesummary --format llm              Generate LLM-optimised Markdown');
+    console.log('  codesummary --format llm --emit-llmsummary  Generate LLM Markdown + .llmsummary.json');
+    console.log('  codesummary --format llm --focus "pdf generation" --max-tokens 12000');
+    console.log('  codesummary --format llm --ai-semantic --provider ollama --model llama3.1');
+    console.log('  # Add sensitive paths to .csignore (gitignore syntax) before enabling AI enrichment');
+    console.log('  codesummary --format llm --ai-semantic --ai-retries 3 --ai-retry-backoff-ms 700');
+    console.log('  codesummary --format pdf --ai-semantic            Executive brief PDF (no code by default)');
+    console.log('  codesummary --format pdf --ai-semantic --include-code   Executive brief + full code appendix');
+    console.log('  codesummary --format both             Generate both LLM Markdown and PDF');
     console.log('  codesummary --output ./docs           Save output to ./docs folder');
     console.log('  codesummary config                    Edit settings');
     console.log('  codesummary --show-config             View current settings');
@@ -595,6 +1326,17 @@ export class CLI {
     
     console.log(chalk.gray('For more information, visit: https://github.com/skamoll/CodeSummary'));
   }
+
+  async displayLlmSummaryCompletionSummary(outputPath) {
+    const stats = await fs.stat(outputPath);
+    const fileSizeFormatted = formatFileSize(stats.size);
+
+    console.log(chalk.green('SUCCESS: Repository context artifact generated successfully!\n'));
+    console.log(chalk.cyan('Summary:'));
+    console.log(chalk.gray(`   Output: ${outputPath}`));
+    console.log(chalk.gray(`   File size: ${fileSizeFormatted}`));
+    console.log();
+  }
 }
 
-export default CLI;
+export default CLI;