openreport 0.1.0

package/src/tools/read-file.ts

@@ -0,0 +1,52 @@
+import { tool } from "ai";
+import { z } from "zod";
+import * as fs from "fs";
+import { resolveAndValidatePath } from "../utils/file-utils.js";
+
+export function createReadFileTool(projectRoot: string) {
+  return tool({
+    description:
+      "Read the contents of a file. Path must be relative to the project root. Can optionally read a specific range of lines.",
+    parameters: z.object({
+      path: z.string().describe("Relative file path from project root"),
+      maxLines: z
+        .number()
+        .optional()
+        .describe("Maximum number of lines to read (default: 500)"),
+      startLine: z
+        .number()
+        .optional()
+        .describe("Line number to start reading from (1-indexed)"),
+    }),
+    execute: async ({ path: filePath, maxLines = 500, startLine = 1 }) => {
+      const resolved = resolveAndValidatePath(projectRoot, filePath);
+      if (!resolved) {
+        return { error: "Path is outside project root" };
+      }
+
+      try {
+        const stat = await fs.promises.stat(resolved);
+        if (stat.isDirectory()) {
+          return { error: "Path is a directory, not a file" };
+        }
+
+        const content = await fs.promises.readFile(resolved, "utf-8");
+        const lines = content.split("\n");
+        const start = Math.max(0, startLine - 1);
+        const end = Math.min(lines.length, start + maxLines);
+        const selectedLines = lines.slice(start, end);
+
+        return {
+          content: selectedLines.join("\n"),
+          totalLines: lines.length,
+          readFrom: start + 1,
+          readTo: end,
+          truncated: end < lines.length,
+        };
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `Failed to read file: ${msg}` };
+      }
+    },
+  });
+}

package/src/tools/read-package-json.ts

@@ -0,0 +1,48 @@
+import { tool } from "ai";
+import { z } from "zod";
+import * as fs from "fs";
+import { resolveAndValidatePath } from "../utils/file-utils.js";
+
+export function createReadPackageJsonTool(projectRoot: string) {
+  return tool({
+    description:
+      "Read and parse a package.json (or similar manifest) file. Returns structured data about dependencies, scripts, and metadata.",
+    parameters: z.object({
+      path: z
+        .string()
+        .default("package.json")
+        .describe("Relative path to manifest file (default: package.json)"),
+    }),
+    execute: async ({ path: filePath }) => {
+      const resolved = resolveAndValidatePath(projectRoot, filePath);
+      if (!resolved) {
+        return { error: "Path is outside project root" };
+      }
+
+      try {
+        const content = await fs.promises.readFile(resolved, "utf-8");
+        const parsed = JSON.parse(content);
+
+        return {
+          name: parsed.name,
+          version: parsed.version,
+          description: parsed.description,
+          main: parsed.main,
+          type: parsed.type,
+          scripts: parsed.scripts || {},
+          dependencies: parsed.dependencies || {},
+          devDependencies: parsed.devDependencies || {},
+          peerDependencies: parsed.peerDependencies || {},
+          engines: parsed.engines,
+          workspaces: parsed.workspaces,
+          dependencyCount:
+            Object.keys(parsed.dependencies || {}).length +
+            Object.keys(parsed.devDependencies || {}).length,
+        };
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `Failed to read manifest: ${msg}` };
+      }
+    },
+  });
+}

package/src/tools/run-command.ts

@@ -0,0 +1,154 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { execFile } from "child_process";
+import * as path from "path";
+import { isInsidePath } from "../utils/file-utils.js";
+
+const ALLOWED_COMMANDS = new Set([
+  "eslint",
+  "tsc",
+  "npm",
+  "bun",
+  "yarn",
+  "pnpm",
+  "node",
+  "cat",
+  "wc",
+  "head",
+  "tail",
+  "depcheck",
+  "license-checker",
+  "madge",
+]);
+
+const ALLOWED_SUBCOMMANDS: Record<string, Set<string>> = {
+  npm: new Set(["audit", "ls", "list", "outdated", "pack", "explain"]),
+  yarn: new Set(["audit", "list", "outdated", "info", "why"]),
+  pnpm: new Set(["audit", "ls", "list", "outdated", "pack", "explain"]),
+  bun: new Set(["pm"]),
+};
+
+interface ExecError extends Error {
+  stdout?: string;
+  stderr?: string;
+  code?: number | null;
+}
+
+const FILE_READING_COMMANDS = new Set(["cat", "head", "tail", "wc"]);
+
+export function isCommandAllowed(command: string, projectRoot: string): boolean {
+  // Block dangerous shell metacharacters
+  if (/[;&|`$\n\r><()%]/.test(command) || command.includes("..")) {
+    return false;
+  }
+
+  const parts = command.trim().split(/\s+/);
+  const base = parts[0];
+
+  if (!ALLOWED_COMMANDS.has(base)) return false;
+
+  const subcommands = ALLOWED_SUBCOMMANDS[base];
+  if (subcommands) {
+    if (parts.length <= 1) return false;  // Require a subcommand
+    return subcommands.has(parts[1]);
+  }
+
+  // eslint: block --init and --fix (write operations)
+  if (base === "eslint") {
+    for (const arg of parts.slice(1)) {
+      if (arg === "--init" || arg === "--fix" || arg === "--config" || arg === "-c" || arg === "--rulesdir" || arg === "--resolve-plugins-relative-to") return false;
+    }
+  }
+
+  // tsc: only allow with --noEmit
+  if (base === "tsc") {
+    if (!parts.includes("--noEmit")) return false;
+  }
+
+  // node: only allow --version
+  if (base === "node") {
+    if (parts.length !== 2 || parts[1] !== "--version") return false;
+  }
+
+  // Validate paths for file-reading commands (cat, head, tail)
+  if (FILE_READING_COMMANDS.has(base)) {
+    const fileArgs = parts.slice(1).filter((a) => !a.startsWith("-"));
+    if (fileArgs.length === 0) return false;
+    for (const filePath of fileArgs) {
+      const resolved = path.resolve(projectRoot, filePath);
+      if (!isInsidePath(resolved, projectRoot)) return false;
+    }
+  }
+
+  return true;
+}
+
+export function createRunCommandTool(projectRoot: string) {
+  return tool({
+    description:
+      "Run an allowed shell command in the project directory. Only safe, read-only commands are permitted (eslint, tsc --noEmit, npm audit, etc.).",
+    parameters: z.object({
+      command: z.string().describe("The shell command to execute"),
+    }),
+    execute: async ({ command }) => {
+      if (!isCommandAllowed(command, projectRoot)) {
+        return {
+          error: `Command not allowed. Allowed base commands: ${Array.from(ALLOWED_COMMANDS).join(", ")}`,
+        };
+      }
+
+      // Block dangerous patterns (defense-in-depth, also checked in isCommandAllowed)
+      if (/[;&|`$\n\r><()%]/.test(command) || command.includes("..")) {
+        return {
+          error:
+            "Command contains disallowed characters (;, &, |, `, $, \\n, \\r, >, <, (, ), %, ..)",
+        };
+      }
+
+      try {
+        const parts = command.trim().split(/\s+/);
+        const base = parts[0];
+        const args = parts.slice(1);
+
+        const { stdout, stderr } = await new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
+          execFile(base, args, {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            timeout: 30_000,
+            maxBuffer: 1024 * 1024,
+          }, (error, stdout, stderr) => {
+            if (error) {
+              // Attach stdout/stderr to the error for the catch block
+              (error as ExecError).stdout = stdout;
+              (error as ExecError).stderr = stderr;
+              reject(error);
+            } else {
+              resolve({ stdout, stderr });
+            }
+          });
+        });
+
+        return {
+          stdout: stdout.slice(0, 10_000),
+          truncated: stdout.length > 10_000,
+          exitCode: 0,
+        };
+      } catch (err: unknown) {
+        if (err && typeof err === "object" && "stdout" in err) {
+          const execErr = err as {
+            stdout: string;
+            stderr: string;
+            code: number | null;
+          };
+          return {
+            stdout: (execErr.stdout || "").slice(0, 5000),
+            stderr: (execErr.stderr || "").slice(0, 5000),
+            exitCode: execErr.code ?? 1,
+          };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `Command failed: ${msg}` };
+      }
+    },
+  });
+}

package/src/tools/shared-ignore.ts

@@ -0,0 +1,58 @@
+import ignore from "ignore";
+import * as path from "path";
+import * as fs from "fs";
+
+export const DEFAULT_IGNORE = [
+  "node_modules/**",
+  ".git/**",
+  "dist/**",
+  "build/**",
+  "coverage/**",
+  ".next/**",
+  "*.lock",
+  "*.map",
+];
+
+const DEFAULT_IGNORE_GLOBS = DEFAULT_IGNORE.map((p) => new Bun.Glob(p));
+
+const gitignoreCache = new Map<string, ReturnType<typeof ignore>>();
+
+export async function loadGitignore(projectRoot: string): Promise<ReturnType<typeof ignore>> {
+  const cached = gitignoreCache.get(projectRoot);
+  if (cached) return cached;
+
+  const ig = ignore();
+  try {
+    const content = await fs.promises.readFile(path.join(projectRoot, ".gitignore"), "utf-8");
+    ig.add(content);
+  } catch {
+    // No .gitignore, that's fine
+  }
+  gitignoreCache.set(projectRoot, ig);
+  return ig;
+}
+
+/**
+ * Filter file paths by DEFAULT_IGNORE patterns, gitignore rules, and optional extra patterns.
+ * Returns only paths that pass all filters.
+ */
+export async function filterIgnoredFiles(
+  files: string[],
+  projectRoot: string,
+  extraIgnore: string[] = [],
+): Promise<string[]> {
+  const ig = await loadGitignore(projectRoot);
+  const extraGlobs = extraIgnore.map((p) => new Bun.Glob(p));
+
+  return files.filter((f) => {
+    const normalized = f.replace(/\\/g, "/");
+    for (const g of DEFAULT_IGNORE_GLOBS) {
+      if (g.match(normalized)) return false;
+    }
+    for (const g of extraGlobs) {
+      if (g.match(normalized)) return false;
+    }
+    if (ig.ignores(normalized)) return false;
+    return true;
+  });
+}

package/src/types/index.ts

@@ -0,0 +1,127 @@
+import type { z } from "zod";
+import type {
+  FindingSchema,
+  SubReportSchema,
+  FullReportSchema,
+  ReportMetadataSchema,
+} from "../schemas/report.js";
+
+// ── Project Classification ──────────────────────────────────────────────
+
+export interface ProjectClassification {
+  language: string;
+  framework: string | null;
+  projectType: "web-app" | "api" | "library" | "cli" | "monorepo" | "other";
+  buildTool: string | null;
+  packageManager: "npm" | "yarn" | "pnpm" | "bun" | null;
+  hasTests: boolean;
+  hasCI: boolean;
+  hasDocker: boolean;
+  testFramework: string | null;
+  linter: string | null;
+}
+
+// ── Agent Types ─────────────────────────────────────────────────────────
+
+export type AgentId =
+  | "architecture-analyst"
+  | "security-auditor"
+  | "code-quality-reviewer"
+  | "dependency-analyzer"
+  | "performance-analyzer"
+  | "test-coverage-analyst"
+  | "api-documentation"
+  | "onboarding-guide"
+  | "todo-generator";
+
+export type AgentRunStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "skipped";
+
+export interface AgentDefinition {
+  id: AgentId;
+  name: string;
+  description: string;
+  systemPrompt: string;
+  maxSteps: number;
+  toolSet: "base" | "extended";
+  relevantFor: (classification: ProjectClassification) => boolean;
+}
+
+export interface AgentStatus {
+  agentId: AgentId;
+  agentName: string;
+  status: AgentRunStatus;
+  statusMessage?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+  tokensUsed?: { input: number; output: number };
+  error?: string;
+}
+
+// ── Pipeline Types ──────────────────────────────────────────────────────
+
+export type PipelinePhase =
+  | "scanning"
+  | "classifying"
+  | "pre-reading"
+  | "analyzing"
+  | "running-agents"
+  | "generating-todo"
+  | "combining"
+  | "saving"
+  | "done"
+  | "error";
+
+export interface PipelineProgress {
+  phase: PipelinePhase;
+  phaseDetail?: string;
+  agents: AgentStatus[];
+  totalTokens: { input: number; output: number };
+  startedAt: Date;
+  estimatedTimeRemaining?: number;
+  currentStreamText?: string;
+}
+
+// ── Report Types (inferred from Zod) ────────────────────────────────────
+
+export type Finding = z.infer<typeof FindingSchema>;
+export type SubReport = z.infer<typeof SubReportSchema>;
+export type FullReport = z.infer<typeof FullReportSchema>;
+export type ReportMetadata = z.infer<typeof ReportMetadataSchema>;
+
+// ── Screen Navigation ───────────────────────────────────────────────────
+
+export type Screen =
+  | "home"
+  | "config"
+  | "generation"
+  | "viewer"
+  | "history";
+
+export interface NavigationState {
+  screen: Screen;
+  params?: Record<string, string>;
+}
+
+// ── Config Types ────────────────────────────────────────────────────────
+
+export interface ProviderConfig {
+  apiKey?: string;
+  baseURL?: string;
+}
+
+// ── File Tree Types ─────────────────────────────────────────────────────
+
+export interface FileTreeNode {
+  name: string;
+  path: string;
+  type: "file" | "directory";
+  language?: string;
+  size?: number;
+  isLarge?: boolean;
+  children?: FileTreeNode[];
+}

package/src/types/marked-terminal.d.ts

@@ -0,0 +1,17 @@
+declare module "marked-terminal" {
+  interface TerminalRendererOptions {
+    reflowText?: boolean;
+    showSectionPrefix?: boolean;
+    tab?: number;
+    width?: number;
+    tableOptions?: {
+      chars?: Record<string, string>;
+      style?: Record<string, string[]>;
+    };
+    [key: string]: unknown;
+  }
+
+  export default class TerminalRenderer {
+    constructor(options?: TerminalRendererOptions);
+  }
+}

package/src/utils/debug.ts

@@ -0,0 +1,25 @@
+const DEBUG =
+  process.env.OPENREPORT_DEBUG === "1" ||
+  process.env.OPENREPORT_DEBUG === "true";
+
+const REDACT_PATTERNS = [
+  /sk-[a-zA-Z0-9]{20,}/g,        // OpenAI/Anthropic keys
+  /key-[a-zA-Z0-9]{20,}/g,       // Generic API keys
+  /Bearer\s+[a-zA-Z0-9._-]+/gi,  // Bearer tokens
+  /AIza[a-zA-Z0-9_-]{35}/g,      // Google API keys
+  /(?:api[_-]?key|api[_-]?secret|token|secret[_-]?key|access[_-]?key)\s*[:=]\s*["']?[a-zA-Z0-9_-]{20,}["']?/gi, // Generic key=value patterns (covers Mistral and others)
+];
+
+function sanitize(text: string): string {
+  let result = text;
+  for (const pattern of REDACT_PATTERNS) {
+    result = result.replace(pattern, "[REDACTED]");
+  }
+  return result;
+}
+
+export function debugLog(context: string, error: unknown): void {
+  if (!DEBUG) return;
+  const msg = error instanceof Error ? error.message : String(error);
+  console.error(`[debug] ${context}: ${sanitize(msg)}`);
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,77 @@
+import * as fs from "fs";
+import * as path from "path";
+import { debugLog } from "./debug.js";
+
+export function safeReadFile(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch (e) {
+    debugLog("file:safeReadFile", e);
+    return null;
+  }
+}
+
+export async function safeReadFileAsync(filePath: string): Promise<string | null> {
+  try {
+    return await fs.promises.readFile(filePath, "utf-8");
+  } catch (e) {
+    debugLog("file:safeReadFileAsync", e);
+    return null;
+  }
+}
+
+export function ensureDir(dirPath: string): void {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function isInsidePath(child: string, parent: string): boolean {
+  try {
+    const resolvedChild = fs.realpathSync(path.resolve(child));
+    const resolvedParent = fs.realpathSync(path.resolve(parent));
+    return resolvedChild.startsWith(resolvedParent + path.sep) || resolvedChild === resolvedParent;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveAndValidatePath(projectRoot: string, userPath: string): string | null {
+  const resolved = path.resolve(projectRoot, userPath);
+  if (!isInsidePath(resolved, projectRoot)) {
+    return null;
+  }
+  return resolved;
+}
+
+export function getProjectName(projectRoot: string): string {
+  // Try package.json name first
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, "package.json"), "utf-8")
+    );
+    if (pkg.name) return pkg.name;
+  } catch (e) {
+    debugLog("file:readPackageJson", e);
+  }
+
+  // Fallback to directory name
+  return path.basename(projectRoot);
+}
+
+export function fileSize(filePath: string): number {
+  try {
+    return fs.statSync(filePath).size;
+  } catch (e) {
+    debugLog("file:stat", e);
+    return 0;
+  }
+}
+
+export async function fileSizeAsync(filePath: string): Promise<number> {
+  try {
+    const stat = await fs.promises.stat(filePath);
+    return stat.size;
+  } catch (e) {
+    debugLog("file:statAsync", e);
+    return 0;
+  }
+}

package/src/utils/format.ts

@@ -0,0 +1,56 @@
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return String(count);
+  if (count < 1_000_000) return `${(count / 1000).toFixed(1)}K`;
+  return `${(count / 1_000_000).toFixed(2)}M`;
+}
+
+export function formatDate(date: Date | string): string {
+  const d = typeof date === "string" ? new Date(date) : date;
+  return d.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+export function formatRelativeDate(date: Date | string): string {
+  const d = typeof date === "string" ? new Date(date) : date;
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+
+  if (diffSec < 60) return "just now";
+  if (diffMin < 60) return `${diffMin}m ago`;
+  if (diffHour < 24) return `${diffHour}h ago`;
+  if (diffDay < 7) return `${diffDay}d ago`;
+  return formatDate(d);
+}
+
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
+
+export function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/utils/grade-colors.ts

@@ -0,0 +1,43 @@
+/** Terminal color names for Ink/chalk */
+export function getGradeTerminalColor(grade: string): string {
+  switch (grade) {
+    case "A+":
+    case "A":
+      return "green";
+    case "B+":
+    case "B":
+    case "B-":
+      return "cyan";
+    case "C+":
+    case "C":
+      return "yellow";
+    case "D":
+      return "red";
+    case "F":
+      return "redBright";
+    default:
+      return "white";
+  }
+}
+
+/** Hex color codes for HTML reports */
+export function getGradeHexColor(grade: string): string {
+  switch (grade) {
+    case "A+":
+    case "A":
+      return "#00ff88";
+    case "B+":
+    case "B":
+    case "B-":
+      return "#22d3ee";
+    case "C+":
+    case "C":
+      return "#fbbf24";
+    case "D":
+      return "#ff6b6b";
+    case "F":
+      return "#ff3366";
+    default:
+      return "#818cf8";
+  }
+}