openreport 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 timiliris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# OpenReport
+
+**AI-powered code analysis reports for your projects.**
+
+OpenReport is a modern CLI/TUI tool that orchestrates multiple AI agents to generate comprehensive, structured reports about your codebase. Get architecture reviews, security audits, code quality assessments, and more — all from your terminal.
+
+[![npm version](https://img.shields.io/npm/v/openreport)](https://www.npmjs.com/package/openreport)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-Bun-f472b6)](https://bun.sh)
+
+## Features
+
+- **Multi-agent AI analysis** — Specialized agents work in parallel to analyze different aspects of your project
+- **8 analysis agents** — Architecture, security, code quality, dependencies, performance, test coverage, API docs, onboarding
+- **Interactive TUI** — Navigate reports, configure settings, and manage history from a beautiful terminal UI
+- **HTML reports** — Export reports as styled HTML pages you can share with your team
+- **Todo list generation** — Automatically generate actionable todo lists from findings
+- **Multi-provider support** — Use any AI provider: Anthropic, OpenAI, Google, Mistral, Ollama, or CLI tools like Claude Code, Gemini CLI, Codex CLI
+
+## Quick Start
+
+```bash
+# Install globally
+bun add -g openreport
+
+# Initialize configuration
+openreport init
+
+# Launch the interactive TUI
+openreport
+
+# Or run a report directly
+openreport run
+```
+
+## Report Types
+
+| Report Type | Agents | Description |
+|---|---|---|
+| **Full Audit** | architecture, security, code-quality, dependencies, performance, test-coverage | Comprehensive analysis covering all aspects |
+| **Quick Health** | code-quality, dependencies | Fast overview of code quality and dependencies |
+| **Security Review** | security, dependencies | Focused security audit |
+| **Architecture** | architecture | Architecture analysis with diagrams and patterns |
+| **Dependencies** | dependencies | Dependency health, vulnerabilities, and licenses |
+| **Onboarding** | onboarding, architecture | New developer onboarding guide |
+
+Additional agents available: **API Documentation**, **Todo Generator**.
+
+## Providers
+
+### API Providers
+
+| Provider | Default Model | Env Variable |
+|---|---|---|
+| Anthropic | `claude-sonnet-4-5-20250929` | `ANTHROPIC_API_KEY` |
+| OpenAI | `gpt-4o` | `OPENAI_API_KEY` |
+| Google | `gemini-2.0-flash` | `GOOGLE_GENERATIVE_AI_API_KEY` |
+| Mistral | `mistral-large-latest` | `MISTRAL_API_KEY` |
+| Ollama | `qwen2.5-coder:14b` | Local (no key needed) |
+
+### CLI Providers
+
+| Provider | CLI Tool | Description |
+|---|---|---|
+| `claude-code` | `claude` | Uses Claude Code CLI (default provider) |
+| `gemini-cli` | `gemini` | Uses Gemini CLI |
+| `codex-cli` | `codex` | Uses Codex CLI |
+
+CLI providers are auto-detected and wrap existing CLI tools via subprocess.
+
+## Configuration
+
+OpenReport uses a `.openreport.json` file in your project root. Run `openreport init` to create one, or create it manually:
+
+```json
+{
+  "defaultProvider": "claude-code",
+  "defaultModel": "sonnet",
+  "providers": {
+    "anthropic": { "apiKey": "sk-..." }
+  },
+  "output": {
+    "directory": ".openreport/reports",
+    "format": "markdown"
+  },
+  "agents": {
+    "maxConcurrency": 3,
+    "temperature": 0.3
+  },
+  "features": {
+    "todoList": false
+  }
+}
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `openreport` | Launch the interactive TUI |
+| `openreport run` | Run a report directly (non-interactive) |
+| `openreport init` | Initialize configuration in the current project |
+| `openreport list` | List previously generated reports |
+| `openreport view <id>` | View a specific report |
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.0
+- At least one AI provider configured (API key or CLI tool installed)
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2025 timiliris

package/bin/openreport.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { createCli } from "../src/cli.js";
+
+const cli = createCli();
+cli.runExit(process.argv.slice(2));

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "openreport",
+  "version": "0.1.0",
+  "packageManager": "bun@1.3.9",
+  "description": "A modern TUI to generate detailed AI-powered reports on software projects",
+  "type": "module",
+  "bin": {
+    "openreport": "./bin/openreport.ts"
+  },
+  "scripts": {
+    "start": "bun run bin/openreport.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "bun test --coverage",
+    "check": "bun run typecheck && bun run lint && bun run test",
+    "dev": "bun run --watch bin/openreport.ts"
+  },
+  "keywords": ["cli", "tui", "ai", "report", "code-analysis", "ink", "bun", "openreport", "code-review", "security-audit", "multi-agent"],
+  "license": "MIT",
+  "author": "timiliris",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timiliris/OpenReport.git"
+  },
+  "homepage": "https://github.com/timiliris/OpenReport#readme",
+  "bugs": {
+    "url": "https://github.com/timiliris/OpenReport/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.2.0",
+    "@ai-sdk/google": "^1.2.0",
+    "@ai-sdk/mistral": "^1.2.0",
+    "@ai-sdk/openai": "^1.3.0",
+    "ai": "^4.3.0",
+    "chalk": "^5.4.0",
+    "clipanion": "^3.2.0",
+    "ignore": "^7.0.0",
+    "ink": "^5.1.0",
+    "ink-spinner": "^5.0.0",
+    "marked": "^15.0.0",
+    "marked-terminal": "^7.3.0",
+    "react": "^18.3.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.15",
+    "@types/bun": "^1.3.9",
+    "@types/react": "^18.3.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/agents/api-documentation.ts

@@ -0,0 +1,66 @@
+import type { AgentDefinition } from "../types/index.js";
+
+export const apiDocumentation: AgentDefinition = {
+  id: "api-documentation",
+  name: "API Documentation",
+  description:
+    "Documents API endpoints, schemas, authentication requirements, error handling patterns, and generates API reference.",
+  maxSteps: 15,
+  toolSet: "base",
+  relevantFor: (classification) =>
+    classification.projectType === "api" ||
+    classification.projectType === "web-app",
+
+  systemPrompt: `You are an expert API technical writer documenting the API surface of a project.
+
+1. **Endpoint Discovery**
+   - Find all API routes/endpoints
+   - Map HTTP methods and paths
+   - Identify route parameters and query parameters
+   - Document request body schemas
+
+2. **Authentication & Authorization**
+   - Authentication method (Bearer, API Key, OAuth, etc.)
+   - Authorization levels per endpoint
+   - Required headers
+
+3. **Request/Response Schemas**
+   - Request body structure and validation
+   - Response body structure
+   - Status codes used
+   - Content types
+
+4. **Error Handling**
+   - Error response format
+   - Common error codes and their meaning
+   - Validation error patterns
+   - Rate limiting headers
+
+5. **API Patterns**
+   - RESTful compliance
+   - Pagination approach
+   - Filtering and sorting
+   - Versioning strategy
+
+6. **Documentation Quality**
+   - Existing OpenAPI/Swagger specs
+   - Inline documentation
+   - Code examples
+   - Missing documentation
+
+## Output Format
+For each endpoint, document:
+- Method + Path
+- Description
+- Authentication requirements
+- Parameters (path, query, body)
+- Response format
+- Error responses
+
+## Methodology
+- Search for route definitions (express, fastify, next.js API routes, etc.)
+- Read route handlers to understand request/response
+- Check for validation middleware
+- Look for OpenAPI or Swagger definitions
+- Review error handling middleware`,
+};

package/src/agents/architecture-analyst.ts

@@ -0,0 +1,46 @@
+import type { AgentDefinition } from "../types/index.js";
+
+export const architectureAnalyst: AgentDefinition = {
+  id: "architecture-analyst",
+  name: "Architecture Analyst",
+  description:
+    "Analyzes project structure, module organization, design patterns, data flow, and generates architecture diagrams.",
+  maxSteps: 15,
+  toolSet: "base",
+  relevantFor: () => true, // Always relevant
+
+  systemPrompt: `You are an expert software architect analyzing a codebase. Your role is to:
+
+1. **Project Structure Analysis**
+   - Map the overall directory structure and module organization
+   - Identify the architectural pattern (MVC, Clean Architecture, Hexagonal, Monolith, Microservices, etc.)
+   - Assess separation of concerns
+
+2. **Module & Dependency Mapping**
+   - Identify core modules and their responsibilities
+   - Map internal dependencies between modules
+   - Identify circular dependencies or tight coupling
+
+3. **Design Patterns**
+   - Identify design patterns in use (Singleton, Factory, Observer, Repository, etc.)
+   - Evaluate their appropriateness
+   - Suggest missing patterns that could improve the codebase
+
+4. **Data Flow**
+   - Trace the flow of data through the application
+   - Identify data transformation points
+   - Document state management approach
+
+5. **Diagrams**
+   - Generate Mermaid diagrams for architecture overview
+   - Create component dependency graphs
+
+## Output Format
+Produce a structured analysis with clear sections and actionable findings. Each finding should have a severity (critical, warning, info, suggestion), description, and recommendation.
+
+## Methodology
+- Start by reading the file tree and config files
+- Identify entry points and trace the application flow
+- Read key source files to understand patterns
+- Focus on structure, not implementation details`,
+};

package/src/agents/code-quality-reviewer.ts

@@ -0,0 +1,59 @@
+import type { AgentDefinition } from "../types/index.js";
+
+export const codeQualityReviewer: AgentDefinition = {
+  id: "code-quality-reviewer",
+  name: "Code Quality Reviewer",
+  description:
+    "Reviews code quality including consistency, complexity, duplication, dead code, and SOLID principles adherence.",
+  maxSteps: 15,
+  toolSet: "extended",
+  relevantFor: () => true,
+
+  systemPrompt: `You are an expert code quality reviewer. Your role is to analyze the codebase for quality issues and improvement opportunities.
+
+1. **Code Consistency**
+   - Naming conventions (variables, functions, files)
+   - Formatting consistency
+   - Import organization
+   - Comment style and quality
+
+2. **Complexity Analysis**
+   - Overly complex functions (high cyclomatic complexity)
+   - Deep nesting levels
+   - Long functions or files
+   - Complex conditional logic
+
+3. **Code Duplication**
+   - Identify duplicated logic across files
+   - Copy-paste code patterns
+   - Opportunities for shared utilities or abstractions
+
+4. **Dead Code**
+   - Unused exports, functions, or variables
+   - Commented-out code blocks
+   - Unreachable code paths
+
+5. **SOLID Principles**
+   - Single Responsibility violations
+   - Open/Closed principle adherence
+   - Dependency inversion usage
+   - Interface segregation
+
+6. **Error Handling**
+   - Proper error handling patterns
+   - Unhandled promise rejections
+   - Generic catch blocks
+   - Error propagation strategy
+
+7. **Type Safety** (for TypeScript projects)
+   - Usage of \`any\` type
+   - Proper type narrowing
+   - Missing type annotations
+   - Type assertion overuse
+
+## Methodology
+- Start with linter/formatter config to understand project standards
+- Read source files, focusing on business logic
+- Look for patterns across multiple files
+- Use grep to find common anti-patterns (any, TODO, HACK, console.log)`,
+};

package/src/agents/dependency-analyzer.ts

@@ -0,0 +1,51 @@
+import type { AgentDefinition } from "../types/index.js";
+
+export const dependencyAnalyzer: AgentDefinition = {
+  id: "dependency-analyzer",
+  name: "Dependency Analyzer",
+  description:
+    "Analyzes project dependencies for vulnerabilities, outdated packages, license issues, bundle size impact, and redundancy.",
+  maxSteps: 10,
+  toolSet: "extended",
+  relevantFor: (classification) => classification.packageManager !== null,
+
+  systemPrompt: `You are an expert dependency analyst. Your role is to analyze all project dependencies for health, security, and optimization.
+
+1. **Dependency Overview**
+   - Total dependency count (direct + dev)
+   - Dependency categories (frameworks, utilities, dev tools, etc.)
+   - Dependency tree depth
+
+2. **Version Analysis**
+   - Outdated dependencies
+   - Major version behind
+   - Pre-release or unstable versions
+   - Version pinning strategy (exact vs range)
+
+3. **Vulnerability Assessment**
+   - Run npm audit if available
+   - Known CVEs in dependencies
+   - Transitive vulnerability exposure
+
+4. **License Compliance**
+   - License types across all dependencies
+   - Copyleft license contamination risk
+   - Missing license declarations
+
+5. **Bundle Impact**
+   - Heavy dependencies that could be replaced
+   - Tree-shaking compatibility
+   - Duplicate functionality across packages
+
+6. **Redundancy**
+   - Multiple packages serving the same purpose
+   - Built-in alternatives (Node.js APIs vs packages)
+   - Unnecessary polyfills
+
+## Methodology
+- Read package.json or equivalent manifest
+- Run npm audit or similar if available
+- Check for lock file presence and health
+- Analyze each dependency category
+- Look for opportunities to reduce dependency count`,
+};

package/src/agents/onboarding-guide.ts

@@ -0,0 +1,59 @@
+import type { AgentDefinition } from "../types/index.js";
+
+export const onboardingGuide: AgentDefinition = {
+  id: "onboarding-guide",
+  name: "Onboarding Guide",
+  description:
+    "Generates a comprehensive onboarding guide for new developers including prerequisites, setup, project structure, workflow, and troubleshooting.",
+  maxSteps: 12,
+  toolSet: "base",
+  relevantFor: () => true,
+
+  systemPrompt: `You are an expert developer relations engineer creating an onboarding guide for new developers joining this project.
+
+1. **Prerequisites**
+   - Required system software and versions (Node.js, Python, etc.)
+   - Required global tools (CLI tools, package managers)
+   - Required accounts or access (API keys, services)
+   - Environment setup (env variables)
+
+2. **Getting Started**
+   - Step-by-step setup instructions
+   - Installation commands
+   - Configuration steps
+   - Running the application locally
+   - Running tests
+
+3. **Project Structure**
+   - Directory layout explanation
+   - Key files and their purposes
+   - Module organization
+   - Configuration files
+
+4. **Development Workflow**
+   - Branch naming conventions
+   - Commit message format
+   - Code review process
+   - CI/CD pipeline overview
+   - Common development commands
+
+5. **Key Concepts**
+   - Architecture overview
+   - Core patterns used in the codebase
+   - Important abstractions
+   - Domain terminology
+
+6. **Troubleshooting**
+   - Common setup issues and solutions
+   - Debugging tips
+   - Useful commands
+   - Where to find help
+
+## Methodology
+- Read README.md and CONTRIBUTING.md first
+- Check package.json scripts
+- Review configuration files
+- Look at CI/CD configuration
+- Examine project structure
+- Read key documentation files`,
+};

package/src/agents/orchestrator.ts

@@ -0,0 +1,41 @@
+import type { LanguageModelV1 } from "ai";
+import type { OpenReportConfig } from "../config/schema.js";
+import type { FullReport } from "../types/index.js";
+import { ProgressTracker } from "../pipeline/progress.js";
+import { runPipeline } from "../pipeline/runner.js";
+
+export interface OrchestratorOptions {
+  projectRoot: string;
+  reportType: string;
+  model: LanguageModelV1;
+  modelId: string;
+  config: OpenReportConfig;
+  onProgress?: (progress: ProgressTracker) => void;
+  signal?: AbortSignal;
+  generateTodoList?: boolean;
+}
+
+export async function orchestrate(
+  options: OrchestratorOptions
+): Promise<{ report: FullReport; progress: ProgressTracker }> {
+  const { projectRoot, reportType, model, modelId, config, onProgress, signal, generateTodoList } = options;
+
+  const progress = new ProgressTracker();
+
+  if (onProgress) {
+    onProgress(progress);
+  }
+
+  const report = await runPipeline({
+    projectRoot,
+    reportType,
+    model,
+    modelId,
+    config,
+    progress,
+    signal,
+    generateTodoList,
+  });
+
+  return { report, progress };
+}

package/src/agents/performance-analyzer.ts

@@ -0,0 +1,57 @@
+import type { AgentDefinition } from "../types/index.js";
+
+export const performanceAnalyzer: AgentDefinition = {
+  id: "performance-analyzer",
+  name: "Performance Analyzer",
+  description:
+    "Identifies performance bottlenecks including algorithmic complexity, N+1 queries, memory leaks, caching opportunities, and async patterns.",
+  maxSteps: 15,
+  toolSet: "extended",
+  relevantFor: (classification) =>
+    classification.projectType !== "library" || classification.hasTests,
+
+  systemPrompt: `You are an expert performance engineer analyzing a codebase for performance issues and optimization opportunities.
+
+1. **Algorithmic Complexity**
+   - Identify O(n^2) or worse operations
+   - Nested loops over large datasets
+   - Inefficient sorting or searching
+   - Missing memoization or caching
+
+2. **Database & Query Patterns**
+   - N+1 query patterns
+   - Missing indexes (if schema files exist)
+   - Unbounded queries (missing LIMIT)
+   - Inefficient ORM usage
+
+3. **Memory Management**
+   - Potential memory leaks (event listeners, closures, global caches)
+   - Large object allocations
+   - Missing cleanup in effects/hooks (React)
+   - Buffer/stream handling
+
+4. **Async Patterns**
+   - Sequential awaits that could be parallel
+   - Missing error handling in async code
+   - Unhandled promise rejections
+   - Blocking operations on the main thread
+
+5. **Caching Opportunities**
+   - Expensive computations without caching
+   - API responses that could be cached
+   - Static assets optimization
+   - Build-time vs runtime computation
+
+6. **Frontend Performance** (if applicable)
+   - Bundle size concerns
+   - Render performance (unnecessary re-renders)
+   - Image/asset optimization
+   - Code splitting opportunities
+
+## Methodology
+- Read entry points and hot paths first
+- Search for common performance anti-patterns
+- Analyze database interaction code
+- Review async/await patterns
+- Check for caching mechanisms`,
+};

package/src/agents/registry.ts

@@ -0,0 +1,50 @@
+import type { AgentDefinition, AgentId } from "../types/index.js";
+import { architectureAnalyst } from "./architecture-analyst.js";
+import { securityAuditor } from "./security-auditor.js";
+import { codeQualityReviewer } from "./code-quality-reviewer.js";
+import { dependencyAnalyzer } from "./dependency-analyzer.js";
+import { performanceAnalyzer } from "./performance-analyzer.js";
+import { testCoverageAnalyst } from "./test-coverage-analyst.js";
+import { apiDocumentation } from "./api-documentation.js";
+import { onboardingGuide } from "./onboarding-guide.js";
+import { todoGenerator } from "./todo-generator.js";
+import { REPORT_TYPES, type ReportTypeId } from "../config/defaults.js";
+
+const AGENT_REGISTRY: Map<AgentId, AgentDefinition> = new Map([
+  ["architecture-analyst", architectureAnalyst],
+  ["security-auditor", securityAuditor],
+  ["code-quality-reviewer", codeQualityReviewer],
+  ["dependency-analyzer", dependencyAnalyzer],
+  ["performance-analyzer", performanceAnalyzer],
+  ["test-coverage-analyst", testCoverageAnalyst],
+  ["api-documentation", apiDocumentation],
+  ["onboarding-guide", onboardingGuide],
+  ["todo-generator", todoGenerator],
+]);
+
+export function getAgentById(id: AgentId): AgentDefinition | undefined {
+  return AGENT_REGISTRY.get(id);
+}
+
+export function getAllAgents(): AgentDefinition[] {
+  return Array.from(AGENT_REGISTRY.values());
+}
+
+export function getAgentIds(): AgentId[] {
+  return Array.from(AGENT_REGISTRY.keys());
+}
+
+export function getAgentsForReportType(reportTypeId: string): AgentId[] {
+  const reportType = REPORT_TYPES[reportTypeId as ReportTypeId];
+  if (reportType) {
+    return [...reportType.agents] as AgentId[];
+  }
+
+  // If unknown type, try to find matching agent ID directly
+  if (AGENT_REGISTRY.has(reportTypeId as AgentId)) {
+    return [reportTypeId as AgentId];
+  }
+
+  // Default to full audit
+  return [...REPORT_TYPES["full-audit"].agents] as AgentId[];
+}