openreport 0.1.0

package/src/ingestion/token-budget.ts

@@ -0,0 +1,52 @@
+// Approximate token limits per model family
+const MODEL_TOKEN_LIMITS: Record<string, number> = {
+  // Anthropic
+  "claude-sonnet-4-5": 200_000,
+  "claude-opus-4": 200_000,
+  "claude-haiku-4": 200_000,
+  // OpenAI
+  "gpt-4o": 128_000,
+  "gpt-4-turbo": 128_000,
+  "gpt-4": 8_192,
+  "gpt-3.5": 16_000,
+  "o1": 200_000,
+  "o3": 200_000,
+  // Google
+  "gemini-2": 1_000_000,
+  "gemini-1.5": 1_000_000,
+  // Mistral
+  "mistral-large": 128_000,
+  "mistral-medium": 32_000,
+  // Ollama local models
+  "qwen2.5-coder": 32_000,
+  "qwen2.5": 32_000,
+  "llama3": 8_192,
+  "llama3.1": 128_000,
+  "llama3.2": 128_000,
+  "codellama": 16_000,
+  "deepseek-coder": 16_000,
+  "mistral": 32_000,
+  "mixtral": 32_000,
+  "phi3": 128_000,
+  "gemma2": 8_192,
+};
+
+export function getModelTokenLimit(modelId: string, configLimits?: Record<string, number>): number {
+  const allLimits = { ...MODEL_TOKEN_LIMITS, ...configLimits };
+
+  // Try exact match first
+  if (allLimits[modelId]) return allLimits[modelId];
+
+  // Try prefix match
+  for (const [prefix, limit] of Object.entries(allLimits)) {
+    if (modelId.startsWith(prefix)) return limit;
+  }
+
+  // Default to a conservative limit
+  return 128_000;
+}
+
+// Rough token estimation (4 chars ~ 1 token for English text/code)
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}

package/src/pipeline/agent-runner.ts

@@ -0,0 +1,360 @@
+import { generateText, streamText } from "ai";
+import type { LanguageModelV1 } from "ai";
+import { ProgressTracker } from "./progress.js";
+import { extractSubReport } from "./extraction.js";
+import { buildFileContentBlock, type SharedContext } from "./context.js";
+import { getAgentById } from "../agents/registry.js";
+import { createBaseTools, createExtendedTools, type BaseTools, type ExtendedTools } from "../tools/index.js";
+import { getRelevantFilePaths } from "../ingestion/context-selector.js";
+import { debugLog } from "../utils/debug.js";
+import { getErrorMessage } from "../utils/format.js";
+import type { AgentId, AgentDefinition, SubReport } from "../types/index.js";
+import type { OpenReportConfig } from "../config/schema.js";
+
+// ── Retry with exponential backoff ───────────────────────────────────────
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries = 2,
+  baseDelay = 2000,
+): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= maxRetries || !isRetryableError(err)) throw err;
+      const delay = baseDelay * 2 ** attempt;
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+}
+
+export function isRetryableError(err: unknown): boolean {
+  if (err instanceof Error) {
+    if (err.name === "AbortError") return false;
+
+    const status = (err as unknown as Record<string, unknown>).status;
+    if (typeof status === "number") {
+      if (status === 401 || status === 403) return false;
+      if (status === 429 || status >= 500) return true;
+    }
+    const code = (err as unknown as Record<string, unknown>).code;
+    if (typeof code === "string") {
+      if (code === "ECONNRESET" || code === "ECONNREFUSED" || code === "ETIMEDOUT") return true;
+    }
+
+    const msg = err.message.toLowerCase();
+    if (msg.includes("401") || msg.includes("403") || msg.includes("authentication") || msg.includes("unauthorized")) return false;
+    if (msg.includes("429") || msg.includes("rate limit") || msg.includes("timeout") || msg.includes("econnreset") || msg.includes("econnrefused") || msg.includes("500") || msg.includes("502") || msg.includes("503") || msg.includes("504") || msg.includes("fetch failed")) return true;
+  }
+  return false;
+}
+
+// ── Streaming throttle helper ────────────────────────────────────────────
+
+export function createStreamThrottle(onUpdate: (preview: string) => void, intervalMs = 500) {
+  let fullText = "";
+  let lastUpdate = 0;
+  return {
+    push(chunk: string) {
+      fullText += chunk;
+      const now = Date.now();
+      if (now - lastUpdate > intervalMs) {
+        lastUpdate = now;
+        onUpdate(fullText.slice(-120).replace(/\n/g, " "));
+      }
+    },
+    getFullText() {
+      return fullText;
+    },
+  };
+}
+
+// ── Shared agent context preparation ────────────────────────────────────
+
+interface PreparedAgentContext {
+  agentDef: AgentDefinition;
+  relevantFiles: string[];
+  contextWithFiles: string;
+  tools: BaseTools | ExtendedTools;
+}
+
+function prepareAgentContext(
+  agentId: AgentId,
+  projectRoot: string,
+  sharedContext: SharedContext,
+): PreparedAgentContext | null {
+  const agentDef = getAgentById(agentId);
+  if (!agentDef) return null;
+
+  const relevantFiles = sharedContext.agentFilePaths?.get(agentId)
+    ?? getRelevantFilePaths(agentId, sharedContext.fileTree);
+  const fileContentBlock = buildFileContentBlock(sharedContext, relevantFiles);
+  const orchestratorSection = sharedContext.orchestratorAnalysis
+    ? `## Orchestrator Project Overview\n> This analysis was produced by a preliminary scan of the project. Use it as context for your specialized analysis.\n\n${sharedContext.orchestratorAnalysis}`
+    : "";
+  const contextWithFiles = [
+    sharedContext.contextInfo,
+    orchestratorSection,
+    fileContentBlock,
+  ].filter(Boolean).join("\n\n");
+
+  const tools =
+    agentDef.toolSet === "extended"
+      ? (sharedContext.extendedTools ?? createExtendedTools(projectRoot))
+      : (sharedContext.baseTools ?? createBaseTools(projectRoot));
+
+  return { agentDef, relevantFiles, contextWithFiles, tools };
+}
+
+// ── Prompt building ─────────────────────────────────────────────────────
+
+export function buildAnalysisPrompt(agentId: string, agentName: string, contextInfo: string): string {
+  return `Analyze this project and produce a structured sub-report.
+Start your analysis directly from the pre-loaded source files provided below. Only use tools to read additional files not already provided.
+
+${contextInfo}
+
+After your analysis, output your findings as a JSON object wrapped in <report> tags.
+
+IMPORTANT: Output ONLY the JSON inside <report> tags — no code fences, no extra text around it.
+
+<report>
+{
+  "title": "Your Section Title",
+  "summary": "Brief 1-2 sentence summary of findings",
+  "sections": [
+    { "heading": "Section Name", "content": "Detailed markdown content for this section..." }
+  ],
+  "findings": [
+    {
+      "id": "unique-id",
+      "severity": "critical|warning|info|suggestion",
+      "category": "security|performance|architecture|code-quality|dependency|testing|documentation|maintainability",
+      "title": "Short finding title",
+      "description": "Detailed description of the issue",
+      "files": ["path/to/file.ts"],
+      "recommendation": "How to fix this",
+      "effort": "low|medium|high"
+    }
+  ]
+}
+</report>
+
+Rules for the JSON:
+- severity MUST be exactly one of: critical, warning, info, suggestion
+- effort MUST be exactly one of: low, medium, high
+- sections[].content should be proper Markdown (headings, lists, code blocks, bold/italic)
+- Each section should cover a distinct aspect of your analysis
+- findings should be specific, actionable items`;
+}
+
+// ── Orchestrator: global project analysis before specialized agents ──────
+
+const ORCHESTRATOR_PROMPT = `You are a senior software architect performing a preliminary analysis of a codebase.
+Your goal is to produce a concise project overview that will be shared with specialized analysis agents.
+
+Analyze the provided project information and source files, then produce a structured overview covering:
+
+1. **Architecture Overview** - What kind of project is this? What's the high-level architecture?
+2. **Key Components** - What are the main modules/components and their responsibilities?
+3. **Technology Stack** - Key technologies, frameworks, libraries in use
+4. **Code Patterns** - What patterns are used (MVC, Repository, etc.)? Any anti-patterns?
+5. **Entry Points** - Where does the application start? What are the main flows?
+6. **Areas of Concern** - What stands out as potentially problematic at first glance?
+
+Keep your analysis factual and concise (aim for 800-1500 words). Reference specific files when relevant.
+This overview will be provided to specialized agents (security, performance, code quality, etc.) so they can focus on their domain without re-discovering the project structure.
+
+Output your analysis as plain markdown (no JSON, no tags).`;
+
+export async function runOrchestratorAgent(
+  model: LanguageModelV1,
+  sharedContext: SharedContext,
+  config: OpenReportConfig,
+  progress: ProgressTracker,
+  signal?: AbortSignal
+): Promise<string> {
+  const allPaths = [...sharedContext.fileContents.keys()];
+  const fileContentBlock = buildFileContentBlock(sharedContext, allPaths);
+
+  const prompt = `${ORCHESTRATOR_PROMPT}
+
+${sharedContext.contextInfo}
+
+${fileContentBlock}
+
+Produce your project overview now.`;
+
+  try {
+    const fullText = await withRetry(async () => {
+      const result = await streamText({
+        model,
+        prompt,
+        maxSteps: 1,
+        maxTokens: config.agents.maxTokens,
+        temperature: 0.3,
+        abortSignal: signal,
+      });
+
+      const throttle = createStreamThrottle((preview) => {
+        progress.setPhaseDetail(preview);
+      });
+
+      for await (const chunk of result.textStream) {
+        throttle.push(chunk);
+      }
+
+      return throttle.getFullText();
+    });
+
+    return fullText;
+  } catch (e) {
+    const reason = getErrorMessage(e);
+    debugLog("pipeline:orchestrator", `Orchestrator analysis failed: ${reason}`);
+    progress.emit("warning", `Orchestrator analysis failed: ${reason}`);
+    return "Orchestrator analysis was not available.";
+  }
+}
+
+// ── Run agent via API provider (with tools + multi-step) ────────────────
+
+export async function runAgentWithTools(
+  agentId: AgentId,
+  model: LanguageModelV1,
+  projectRoot: string,
+  sharedContext: SharedContext,
+  config: OpenReportConfig,
+  progress: ProgressTracker,
+  signal?: AbortSignal
+): Promise<SubReport | null> {
+  const ctx = prepareAgentContext(agentId, projectRoot, sharedContext);
+  if (!ctx) {
+    progress.setAgentError(agentId, "Agent definition not found");
+    return null;
+  }
+
+  const { agentDef, relevantFiles, contextWithFiles, tools } = ctx;
+
+  progress.updateAgentStatus(agentId, "running", "Starting analysis...");
+
+  const maxSteps =
+    config.agents.maxStepsOverride[agentId] || agentDef.maxSteps;
+
+  try {
+    const result = await withRetry(() => generateText({
+      model,
+      system: agentDef.systemPrompt,
+      prompt: buildAnalysisPrompt(agentId, agentDef.name, contextWithFiles),
+      tools,
+      maxSteps,
+      temperature: config.agents.temperature,
+      maxTokens: config.agents.maxTokens,
+      abortSignal: signal,
+      onStepFinish: (step) => {
+        if (step.text) {
+          progress.updateAgentStatus(agentId, "running", step.text.slice(0, 100));
+          progress.addStreamText(step.text, agentId);
+        }
+        if (step.usage) {
+          progress.updateAgentTokens(agentId, {
+            input: step.usage.promptTokens,
+            output: step.usage.completionTokens,
+          });
+        }
+      },
+    }));
+
+    const subReport = extractSubReport(
+      agentId,
+      agentDef.name,
+      result.text,
+      relevantFiles.length,
+      result.usage
+    );
+
+    progress.updateAgentStatus(agentId, "completed", "Done");
+    return subReport;
+  } catch (err: unknown) {
+    progress.setAgentError(agentId, getErrorMessage(err));
+    return null;
+  }
+}
+
+// ── Run agent via CLI provider (single call, no SDK tools, streaming) ───
+
+export async function runAgentWithCli(
+  agentId: AgentId,
+  model: LanguageModelV1,
+  projectRoot: string,
+  sharedContext: SharedContext,
+  config: OpenReportConfig,
+  progress: ProgressTracker,
+  signal?: AbortSignal
+): Promise<SubReport | null> {
+  const ctx = prepareAgentContext(agentId, projectRoot, sharedContext);
+  if (!ctx) {
+    progress.setAgentError(agentId, "Agent definition not found");
+    return null;
+  }
+
+  const { agentDef, relevantFiles, contextWithFiles } = ctx;
+
+  progress.updateAgentStatus(agentId, "running", "Preparing analysis...");
+
+  const prompt = `${agentDef.systemPrompt}
+
+${contextWithFiles}
+
+${buildAnalysisPrompt(agentId, agentDef.name, "")}`;
+
+  progress.updateAgentStatus(agentId, "running", "Analyzing with AI...");
+
+  try {
+    const { text: fullText, usage } = await withRetry(async () => {
+      const result = await streamText({
+        model,
+        prompt,
+        maxSteps: 1,
+        temperature: config.agents.temperature,
+        maxTokens: config.agents.maxTokens,
+        abortSignal: signal,
+      });
+
+      const pendingChunks: string[] = [];
+      const throttle = createStreamThrottle((preview) => {
+        progress.updateAgentStatus(agentId, "running", preview);
+        progress.addStreamText(pendingChunks.join(""), agentId);
+        pendingChunks.length = 0;
+      });
+
+      for await (const chunk of result.textStream) {
+        pendingChunks.push(chunk);
+        throttle.push(chunk);
+      }
+
+      const collected = throttle.getFullText();
+      const u = await result.usage;
+      return { text: collected, usage: u };
+    });
+
+    progress.updateAgentTokens(agentId, {
+      input: usage.promptTokens,
+      output: usage.completionTokens,
+    });
+
+    const subReport = extractSubReport(
+      agentId,
+      agentDef.name,
+      fullText,
+      relevantFiles.length,
+      usage
+    );
+
+    progress.updateAgentStatus(agentId, "completed", "Done");
+    return subReport;
+  } catch (err: unknown) {
+    progress.setAgentError(agentId, getErrorMessage(err));
+    return null;
+  }
+}

package/src/pipeline/combiner.ts

@@ -0,0 +1,199 @@
+import crypto from "crypto";
+import type { SubReport, FullReport, ReportMetadata, Finding } from "../types/index.js";
+import type { AgentStatus } from "../types/index.js";
+import { SEVERITY_ORDER, SEVERITY_EMOJI } from "../schemas/findings.js";
+
+export function countFindings(findings: Finding[]) {
+  const summary = { critical: 0, warning: 0, info: 0, suggestion: 0 };
+  for (const f of findings) {
+    if (f.severity in summary) {
+      summary[f.severity as keyof typeof summary]++;
+    }
+  }
+  return summary;
+}
+
+function calculateGrade(
+  summary: { critical: number; warning: number; info: number; suggestion: number },
+  agentCount: number,
+): string {
+  // Critical findings are absolute deal-breakers
+  if (summary.critical >= 5) return "F";
+  if (summary.critical >= 3) return "D";
+  if (summary.critical >= 1) return "C";
+
+  // Normalize warnings by the number of analysis agents to account for project scope
+  const normalizedWarnings = agentCount > 0
+    ? summary.warning / agentCount
+    : summary.warning;
+
+  if (normalizedWarnings >= 3) return "C";
+  if (normalizedWarnings >= 1.5) return "B-";
+  if (normalizedWarnings >= 0.8) return "B";
+  if (normalizedWarnings >= 0.3) return "B+";
+  return "A";
+}
+
+function generateFindingSummaryTable(summary: {
+  critical: number;
+  warning: number;
+  info: number;
+  suggestion: number;
+}): string {
+  return `| Severity | Count |
+|----------|-------|
+| Critical | ${summary.critical} |
+| Warning | ${summary.warning} |
+| Info | ${summary.info} |
+| Suggestion | ${summary.suggestion} |
+| **Total** | **${summary.critical + summary.warning + summary.info + summary.suggestion}** |`;
+}
+
+function generateTableOfContents(subReports: SubReport[]): string {
+  let toc = "## Table of Contents\n\n";
+  toc += "1. [Executive Summary](#executive-summary)\n";
+  toc += "2. [Finding Summary](#finding-summary)\n";
+
+  subReports.forEach((report, idx) => {
+    const anchor = report.title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    toc += `${idx + 3}. [${report.title}](#${anchor})\n`;
+  });
+
+  toc += `${subReports.length + 3}. [All Findings by Severity](#all-findings-by-severity)\n`;
+  return toc;
+}
+
+function generateFindingsAppendix(allFindings: Finding[]): string {
+  const sorted = [...allFindings].sort((a, b) => {
+    return (SEVERITY_ORDER[a.severity] ?? 4) - (SEVERITY_ORDER[b.severity] ?? 4);
+  });
+
+  let md = "## All Findings by Severity\n\n";
+
+  for (const finding of sorted) {
+    const emoji = SEVERITY_EMOJI[finding.severity] || "";
+    md += `### ${emoji} [${finding.severity.toUpperCase()}] ${finding.title}\n\n`;
+    md += `${finding.description}\n\n`;
+    if (finding.files.length > 0) {
+      md += `**Files:** ${finding.files.join(", ")}\n\n`;
+    }
+    if (finding.codeSnippet) {
+      md += `\`\`\`\n${finding.codeSnippet}\n\`\`\`\n\n`;
+    }
+    md += `**Recommendation:** ${finding.recommendation}\n\n`;
+    md += `**Effort:** ${finding.effort}\n\n---\n\n`;
+  }
+
+  return md;
+}
+
+export interface CombineOptions {
+  projectName: string;
+  projectPath: string;
+  reportType: string;
+  model: string;
+  executiveSummary: string;
+  subReports: SubReport[];
+  agentStatuses: AgentStatus[];
+  startedAt: Date;
+  totalTokens: { input: number; output: number };
+}
+
+export function combineReport(options: CombineOptions): FullReport {
+  const {
+    projectName,
+    projectPath,
+    reportType,
+    model,
+    executiveSummary,
+    subReports,
+    agentStatuses,
+    startedAt,
+    totalTokens,
+  } = options;
+
+  const allFindings = subReports.flatMap((r) => r.findings);
+  const findingSummary = countFindings(allFindings);
+  const grade = calculateGrade(findingSummary, subReports.length);
+  const duration = Date.now() - startedAt.getTime();
+  const id = `rpt_${crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+
+  // Build markdown content using array for efficient string building
+  const parts: string[] = [];
+  parts.push(`# ${projectName} - ${reportType}\n\n`);
+  parts.push(`> Generated on ${new Date().toISOString().split("T")[0]} using ${model}\n\n`);
+  parts.push(`**Grade: ${grade}**\n\n`);
+  parts.push("---\n\n");
+
+  // Finding summary
+  parts.push("## Finding Summary\n\n");
+  parts.push(generateFindingSummaryTable(findingSummary));
+  parts.push("\n\n");
+
+  // Executive summary
+  parts.push("## Executive Summary\n\n");
+  parts.push(executiveSummary);
+  parts.push("\n\n---\n\n");
+
+  // Table of contents
+  parts.push(generateTableOfContents(subReports));
+  parts.push("\n---\n\n");
+
+  // Sub-reports
+  for (const report of subReports) {
+    parts.push(`## ${report.title}\n\n`);
+    parts.push(`*${report.summary}*\n\n`);
+
+    for (const section of report.sections) {
+      parts.push(`### ${section.heading}\n\n`);
+      parts.push(section.content);
+      parts.push("\n\n");
+    }
+
+    if (report.findings.length > 0) {
+      parts.push(`### Findings (${report.findings.length})\n\n`);
+      for (const finding of report.findings) {
+        parts.push(`- ${SEVERITY_EMOJI[finding.severity] || ""} **[${finding.severity}]** ${finding.title}: ${finding.description}\n`);
+      }
+      parts.push("\n");
+    }
+
+    parts.push("---\n\n");
+  }
+
+  // Findings appendix
+  if (allFindings.length > 0) {
+    parts.push(generateFindingsAppendix(allFindings));
+  }
+
+  const md = parts.join("");
+
+  const metadata: ReportMetadata = {
+    id,
+    type: reportType,
+    projectName,
+    projectPath,
+    createdAt: new Date().toISOString(),
+    duration,
+    model,
+    tokens: totalTokens,
+    agentStatuses: agentStatuses.map((a) => ({
+      agentId: a.agentId,
+      status: a.status === "completed" ? "completed" : a.status === "skipped" ? "skipped" : "failed",
+      duration: a.completedAt && a.startedAt
+        ? a.completedAt.getTime() - a.startedAt.getTime()
+        : undefined,
+    })),
+    grade,
+    sections: subReports.map((r) => r.title),
+  };
+
+  return {
+    metadata,
+    executiveSummary,
+    findingSummary,
+    subReports,
+    allFindings,
+    markdownContent: md,
+  };
+}