codesummary 1.2.1 → 1.2.2

package/src/ai/promptTemplates.js

@@ -0,0 +1,337 @@
+export function buildSemanticClustersPrompt(context) {
+  const compactClusters = context.semanticClusters.map(cluster => ({
+    name: cluster.name,
+    files: cluster.files.slice(0, 12)
+  }));
+
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Refine semantic repository clusters',
+        constraints: {
+          keepClusterCountCloseToInput: true,
+          maxWordsPerDescription: 24,
+          preserveFilePaths: true,
+          outputFormat: {
+            clusters: [
+              {
+                name: 'string',
+                description: 'string',
+                files: ['path1', 'path2']
+              }
+            ]
+          }
+        },
+        input: {
+          projectName: context.projectName,
+          entrypoints: context.entrypoints.slice(0, 12),
+          coreModules: context.coreModules.slice(0, 12).map(item => item.path || item),
+          semanticClusters: compactClusters
+        }
+      })
+    }
+  ];
+}
+
+export function buildPdfProjectIntroPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Generate a concise project context block for a technical PDF report',
+        constraints: {
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          maxWordsPerField: 80,
+          tone: 'neutral technical',
+          avoidMarketingLanguage: true,
+          outputFormat: {
+            overview: 'string',
+            primaryPurpose: 'string',
+            keyComponents: ['string'],
+            suggestedReadingPath: ['string']
+          }
+        },
+        input: {
+          projectName: context.projectName,
+          totalFiles: context.totalFiles,
+          selectedExtensions: context.selectedExtensions,
+          topExtensions: context.topExtensions,
+          entrypoints: context.entrypoints || [],
+          coreModules: context.coreModules || [],
+          semanticClusters: context.semanticClusters || []
+        }
+      })
+    }
+  ];
+}
+
+export function buildPdfArchitectureInsightsPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Generate Architecture & Design Patterns insights for a technical PDF report',
+        constraints: {
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          language: 'English',
+          maxSentenceLength: 220,
+          maxItemsPerList: 8,
+          avoidSpeculationWithoutEvidence: true,
+          outputFormat: {
+            structuralPatterns: ['string'],
+            implementationParadigm: ['string'],
+            couplingPoints: ['string']
+          }
+        },
+        input: context
+      })
+    }
+  ];
+}
+
+export function buildPdfOperationsInsightsPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Generate Data/State lifecycle + configuration strategy + language breakdown insights for a technical PDF report',
+        constraints: {
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          language: 'English',
+          maxSentenceLength: 220,
+          maxItemsPerList: 10,
+          outputFormat: {
+            dataAndStateLifecycle: {
+              inboundOutbound: ['string'],
+              criticalTransformations: ['string'],
+              stateManagement: ['string']
+            },
+            configurationAndEnvironmentStrategy: {
+              configurationHierarchy: ['string'],
+              infrastructureDependencies: ['string']
+            },
+            languageSpecificBreakdown: {
+              responsibilityDistribution: ['string'],
+              interoperability: ['string']
+            }
+          }
+        },
+        input: context
+      })
+    }
+  ];
+}
+
+export function buildPdfMaintenanceAndSecurityPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Generate Onboarding/Maintenance guidance plus Security/Compliance insights for a technical PDF report',
+        constraints: {
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          language: 'English',
+          maxSentenceLength: 220,
+          maxItemsPerList: 10,
+          outputFormat: {
+            onboardingAndMaintenanceGuide: {
+              complexityHotspots: ['string'],
+              modificationGuide: ['string'],
+              domainGlossary: ['string']
+            },
+            securityAndComplianceSurface: {
+              exposureSurface: ['string'],
+              sensitiveDataHandling: ['string']
+            }
+          }
+        },
+        input: context
+      })
+    }
+  ];
+}
+
+export function buildPdfVisualInsightsPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Generate text-based visualisations for a technical PDF report',
+        constraints: {
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          language: 'English',
+          maxLinesPerBlock: 40,
+          outputFormat: {
+            semanticDirectoryTree: ['string'],
+            dependencyTextGraph: ['string']
+          }
+        },
+        input: context
+      })
+    }
+  ];
+}
+
+export function buildPdfApplicabilityPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a software architecture assistant. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Explain why the generated architecture analysis is useful across project categories',
+        constraints: {
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          language: 'English',
+          maxSentenceLength: 220,
+          maxItemsPerList: 8,
+          outputFormat: {
+            whyItHelpsAcrossProjects: {
+              infrastructureAsCode: ['string'],
+              dataPlatforms: ['string'],
+              frontendApplications: ['string'],
+              backendServices: ['string'],
+              genericTransferableValue: ['string']
+            }
+          }
+        },
+        input: context
+      })
+    }
+  ];
+}
+
+export function buildPdfExecutiveBriefPrompt(context) {
+  return [
+    {
+      role: 'system',
+      content:
+        'You are a Principal Technical Writer, elite Software Architect, and editorial design director. ' +
+        'Return only valid JSON. Do not include markdown fences.'
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        task: 'Generate a high-impact, infographic-ready technical executive brief for a PDF',
+        constraints: {
+          language: 'English',
+          projectAgnostic: true,
+          evidenceOnly: true,
+          avoidDomainAssumptions: true,
+          style: 'clinical, concise, high-signal',
+          paragraphLimitLines: 3,
+          maxItemsPerList: 5,
+          fallbackWhenMissingEvidence: 'Not detected from available repository signals',
+          sections: [
+            'Executive Summary',
+            'Architecture Blueprint',
+            'Data Flow',
+            'Onboarding Quick Guide',
+            'Risk & Hotspots'
+          ],
+          outputFormat: {
+            executiveSummary: {
+              purpose: 'string (exactly 2 sentences)',
+              killerFeatures: ['string (exactly 3 items)']
+            },
+            architectureBlueprint: [
+              {
+                pattern: 'string',
+                primaryModule: 'string',
+                value: 'string'
+              }
+            ],
+            dataFlow: {
+              primaryFlow: 'string (A -> B -> C format)',
+              keyFlows: ['string']
+            },
+            onboardingQuickGuide: [
+              {
+                goal: 'string',
+                modify: 'string'
+              }
+            ],
+            riskHotspots: [
+              {
+                severity: 'string',
+                file: 'string',
+                reason: 'string'
+              }
+            ]
+          }
+        },
+        input: context
+      })
+    }
+  ];
+}
+
+export default {
+  buildSemanticClustersPrompt,
+  buildPdfProjectIntroPrompt,
+  buildPdfArchitectureInsightsPrompt,
+  buildPdfOperationsInsightsPrompt,
+  buildPdfMaintenanceAndSecurityPrompt,
+  buildPdfVisualInsightsPrompt,
+  buildPdfApplicabilityPrompt,
+  buildPdfExecutiveBriefPrompt
+};

package/src/ai/providerClient.js

@@ -0,0 +1,81 @@
+import OpenAiCompatibleProvider from './providers/openaiCompatible.js';
+import OllamaProvider from './providers/ollama.js';
+import { AiProviderError, normalizeAiError } from './errors.js';
+
+export default class ProviderClient {
+  constructor(config = {}) {
+    this.config = config;
+    this.provider = this.createProvider(config);
+  }
+
+  createProvider(config) {
+    const providerName = (config.provider || 'openai-compatible').toLowerCase();
+    if (providerName === 'ollama') {
+      return new OllamaProvider(config);
+    }
+    return new OpenAiCompatibleProvider(config);
+  }
+
+  async chat(messages, options = {}) {
+    const maxRetries = Number.isInteger(options.maxRetries)
+      ? options.maxRetries
+      : (Number.isInteger(this.config.maxRetries) ? this.config.maxRetries : 2);
+    const initialBackoffMs = Number.isInteger(options.retryBackoffMs)
+      ? options.retryBackoffMs
+      : (Number.isInteger(this.config.retryBackoffMs) ? this.config.retryBackoffMs : 500);
+    const maxBackoffMs = Number.isInteger(options.maxBackoffMs)
+      ? options.maxBackoffMs
+      : (Number.isInteger(options.maxBackoffMaxMs)
+        ? options.maxBackoffMaxMs
+        : (Number.isInteger(this.config.maxBackoffMs) ? this.config.maxBackoffMs : 5000));
+
+    const totalAttempts = Math.max(1, maxRetries + 1);
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+      try {
+        const response = await this.provider.chat(messages, options);
+        return {
+          ...response,
+          attempts: attempt
+        };
+      } catch (error) {
+        const normalized = normalizeAiError(error, { provider: this.getModelInfo().provider });
+        lastError = normalized;
+        const canRetry = normalized.retryable && attempt < totalAttempts;
+
+        if (!canRetry) {
+          throw new AiProviderError(normalized.message, {
+            ...normalized,
+            details: {
+              ...(normalized.details || {}),
+              attempts: attempt
+            }
+          });
+        }
+
+        const delay = Math.min(maxBackoffMs, initialBackoffMs * Math.pow(2, attempt - 1));
+        const jitter = Math.floor(delay * 0.2 * Math.random());
+        await this.sleep(delay + jitter);
+      }
+    }
+
+    throw lastError || new AiProviderError('AI request failed', {
+      code: 'ai_error',
+      retryable: false,
+      provider: this.getModelInfo().provider
+    });
+  }
+
+  async healthCheck() {
+    return this.provider.healthCheck();
+  }
+
+  getModelInfo() {
+    return this.provider.getModelInfo();
+  }
+
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/src/ai/providers/ollama.js

@@ -0,0 +1,92 @@
+import { AiProviderError, createHttpAiError, normalizeAiError } from '../errors.js';
+
+export default class OllamaProvider {
+  constructor(config) {
+    this.config = config;
+    this.providerName = 'ollama';
+  }
+
+  async chat(messages, options = {}) {
+    const timeoutMs = options.timeoutMs || this.config.timeoutMs || 30000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const baseUrl = (this.config.baseUrl || 'http://localhost:11434').replace(/\/+$/, '');
+    const url = `${baseUrl}/api/chat`;
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        signal: controller.signal,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          model: options.model || this.config.model || 'llama3.1',
+          messages,
+          stream: false
+        })
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw createHttpAiError(this.providerName, response.status, errorText);
+      }
+
+      const data = await response.json();
+      const content = data?.message?.content;
+      if (!content) {
+        throw new AiProviderError('Ollama response missing content', {
+          code: 'invalid_response',
+          retryable: false,
+          provider: this.providerName
+        });
+      }
+      return { content, raw: data };
+    } catch (error) {
+      throw normalizeAiError(error, { provider: this.providerName });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async healthCheck() {
+    const timeoutMs = Math.min(this.config.timeoutMs || 30000, 7000);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const baseUrl = (this.config.baseUrl || 'http://localhost:11434').replace(/\/+$/, '');
+    const url = `${baseUrl}/api/tags`;
+
+    try {
+      const response = await fetch(url, {
+        method: 'GET',
+        signal: controller.signal
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        return {
+          ok: false,
+          provider: this.providerName,
+          error: createHttpAiError(this.providerName, response.status, text)
+        };
+      }
+
+      return { ok: true, provider: this.providerName };
+    } catch (error) {
+      return {
+        ok: false,
+        provider: this.providerName,
+        error: normalizeAiError(error, { provider: this.providerName })
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  getModelInfo() {
+    return {
+      provider: 'ollama',
+      model: this.config.model || 'llama3.1'
+    };
+  }
+}

package/src/ai/providers/openaiCompatible.js

@@ -0,0 +1,96 @@
+import { AiProviderError, createHttpAiError, normalizeAiError } from '../errors.js';
+
+export default class OpenAiCompatibleProvider {
+  constructor(config) {
+    this.config = config;
+    this.providerName = 'openai-compatible';
+  }
+
+  async chat(messages, options = {}) {
+    const timeoutMs = options.timeoutMs || this.config.timeoutMs || 30000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const baseUrl = (this.config.baseUrl || '').replace(/\/+$/, '');
+    const url = `${baseUrl}/chat/completions`;
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        signal: controller.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.apiKey ? { Authorization: `Bearer ${this.config.apiKey}` } : {})
+        },
+        body: JSON.stringify({
+          model: options.model || this.config.model,
+          messages,
+          temperature: options.temperature ?? 0.2
+        })
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw createHttpAiError(this.providerName, response.status, errorText);
+      }
+
+      const data = await response.json();
+      const content = data?.choices?.[0]?.message?.content;
+      if (!content) {
+        throw new AiProviderError('OpenAI-compatible response missing content', {
+          code: 'invalid_response',
+          retryable: false,
+          provider: this.providerName
+        });
+      }
+      return { content, raw: data };
+    } catch (error) {
+      throw normalizeAiError(error, { provider: this.providerName });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async healthCheck() {
+    const timeoutMs = Math.min(this.config.timeoutMs || 30000, 7000);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const baseUrl = (this.config.baseUrl || '').replace(/\/+$/, '');
+    const url = `${baseUrl}/models`;
+
+    try {
+      const response = await fetch(url, {
+        method: 'GET',
+        signal: controller.signal,
+        headers: {
+          ...(this.config.apiKey ? { Authorization: `Bearer ${this.config.apiKey}` } : {})
+        }
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        return {
+          ok: false,
+          provider: this.providerName,
+          error: createHttpAiError(this.providerName, response.status, text)
+        };
+      }
+
+      return { ok: true, provider: this.providerName };
+    } catch (error) {
+      return {
+        ok: false,
+        provider: this.providerName,
+        error: normalizeAiError(error, { provider: this.providerName })
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  getModelInfo() {
+    return {
+      provider: 'openai-compatible',
+      model: this.config.model || 'unknown'
+    };
+  }
+}