coderoast 0.1.0

package/Agents.md

@@ -0,0 +1,391 @@
+# Agents Architecture - CodeRoast
+
+This document describes the **agent-based architecture** used in CodeRoast.
+
+The goal of agents in this system is **separation of responsibility**, **hallucination control**, and **clear reasoning boundaries** between deterministic analysis and generative narration.
+
+---
+
+## Design Principles
+
+1. **Deterministic before Generative**
+   Agents that compute facts must run before agents that explain them.
+
+2. **Single Responsibility per Agent**
+   Each agent has one clear job and produces structured output.
+
+3. **Evidence-Bound Communication**
+   Agents communicate using schemas, not free text.
+
+4. **Graceful Degradation**
+   If an AI agent fails, deterministic agents still produce usable output.
+
+---
+
+## Agent Overview
+
+```
+CLI Agent
+  -> Repo Scanner Agent
+  -> Code Analysis Agent
+  -> Insight Aggregator Agent
+  -> Evidence Guard Agent
+  -> Fix-It Agent (optional --fix)
+  -> Fix-Apply Agent (optional --apply-fixes)
+  -> Roast Narrator Agent (Gemini API)
+  -> Output Formatter Agent
+```
+
+---
+
+## 1. CLI Agent
+
+**Type:** Deterministic  
+**Role:** Entry point and command orchestration
+
+### Responsibilities
+
+* Parse CLI commands and flags
+* Validate inputs
+* Select analysis mode (severity, focus, output format)
+* Trigger downstream agents in order
+
+### Inputs
+
+* Command arguments
+* Flags (e.g. `--severity`, `--focus`)
+
+### Outputs
+
+```json
+{
+  "path": ".",
+  "severity": "savage",
+  "focus": "architecture"
+}
+```
+
+---
+
+## 2. Repo Scanner Agent
+
+**Type:** Deterministic  
+**Role:** Repository discovery and metadata extraction
+
+### Responsibilities
+
+* Traverse filesystem
+* Respect `.gitignore`
+* Detect languages and file types
+* Identify entry points
+
+### Outputs
+
+```json
+{
+  "languages": ["ts", "js"],
+  "fileCount": 128,
+  "folders": 19,
+  "entryPoints": ["src/index.ts"]
+}
+```
+
+### Notes
+
+* No code semantics here
+* Pure structure and counts
+
+---
+
+## 3. Code Analysis Agent
+
+**Type:** Deterministic  
+**Role:** Static code analysis and signal extraction
+
+### Responsibilities
+
+* Parse ASTs
+* Compute metrics
+* Detect architectural and code smells
+* Capture line ranges to support evidence
+
+### Signals Produced
+
+* Long functions
+* Duplicate blocks
+* Direct circular dependencies
+* Test presence
+
+Planned: god files, layer violations, dependency direction.
+
+### Outputs
+
+```json
+{
+  "metrics": {
+    "maxFunctionLength": 311,
+    "avgFunctionLength": 42,
+    "duplicateBlocks": 7,
+    "totalFunctions": 128
+  },
+  "signals": {
+    "longFunctions": [
+      {
+        "file": "src/handlers/user.ts",
+        "name": "saveUser",
+        "length": 72,
+        "startLine": 10,
+        "endLine": 81
+      }
+    ],
+    "duplicateBlocks": [
+      {
+        "hash": "a1b2c3",
+        "length": 12,
+        "occurrences": [
+          { "file": "src/a.ts", "startLine": 20, "endLine": 31 }
+        ]
+      }
+    ],
+    "circularDependencies": [
+      {
+        "from": "src/a.ts",
+        "to": "src/b.ts",
+        "fromStartLine": 1,
+        "fromEndLine": 1,
+        "toStartLine": 1,
+        "toEndLine": 1
+      }
+    ],
+    "testPresence": {
+      "hasTests": true,
+      "testFiles": ["src/__tests__/smoke.test.ts"]
+    }
+  }
+}
+```
+
+### Notes
+
+* This agent does **not** interpret or judge
+* It only reports facts
+
+---
+
+## 4. Insight Aggregator Agent
+
+**Type:** Deterministic  
+**Role:** Prepare LLM-safe context
+
+### Responsibilities
+
+* Merge scanner and analysis outputs
+* Filter noise
+* Attach confidence levels
+* Build structured evidence entries
+
+### Outputs
+
+```json
+{
+  "issues": [
+    {
+      "type": "maintainability",
+      "signal": "longFunctions",
+      "confidence": "medium",
+      "evidence": [
+        {
+          "file": "src/handlers/user.ts",
+          "startLine": 10,
+          "endLine": 81,
+          "metrics": [{ "type": "loc", "value": 72 }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Notes
+
+* This agent defines what the narrator is *allowed* to talk about
+* Evidence entries must include file path, line range, and metrics
+
+---
+
+## 5. Evidence Guard Agent
+
+**Type:** Deterministic  
+**Role:** Validate evidence completeness and enforce narration boundaries
+
+### Responsibilities
+
+* Validate each issue has evidence entries with file path, line range, and metrics
+* Mark issues as incomplete with a reason
+* Gate what the narrator is allowed to say
+
+### Outputs
+
+```json
+{
+  "issues": [
+    {
+      "type": "testing",
+      "signal": "testPresence",
+      "confidence": "medium",
+      "evidence": [],
+      "evidenceComplete": false,
+      "missingEvidenceReason": "No evidence items provided."
+    }
+  ]
+}
+```
+
+### Notes
+
+* If evidence is incomplete, the narrator must respond with "not enough data"
+
+---
+
+## 6. Fix-It Agent (optional --fix)
+
+**Type:** Generative + Deterministic guard  
+**Role:** Evidence-locked patch preview and verification
+
+### Responsibilities
+
+* Generate patch suggestions with Gemini using evidence-only prompts
+* Reject any edit outside evidence line ranges
+* Re-run analysis on patched content to verify improvement
+* Emit unified diff previews only (no file writes)
+
+### Configuration
+
+* `GEMINI_API_KEY` or `GOOGLE_API_KEY` (required to enable fixes)
+* `--fix` (enable fix-it previews)
+
+### Hard Constraints
+
+* Only touch files and line ranges present in evidence
+* If verification fails, mark the suggestion as rejected
+
+---
+
+## 7. Fix-Apply Agent (optional --apply-fixes)
+
+**Type:** Deterministic  
+**Role:** Proof-locked application of fixes on a new git branch
+
+### Responsibilities
+
+* Apply verified Fix-It patches on a new git branch
+* Run tests and only mark the apply as successful if tests pass
+* Report branch name, test command, and pass/fail status
+
+### Configuration
+
+* `--apply-fixes` (enable apply)
+* `--fix-branch <name>` (optional branch name)
+* `--fix-test-cmd "<cmd>"` (optional test command override)
+
+### Hard Constraints
+
+* Must refuse to run on a dirty working tree
+* Must not modify files if patch application fails
+
+---
+
+## 8. Roast Narrator Agent (Gemini API)
+
+**Type:** Generative (Constrained)  
+**Role:** Human-readable explanation and humor
+
+### Responsibilities
+
+* Generate roast-style feedback
+* Explain issues using provided evidence
+* Match selected tone (gentle, savage, investor-demo)
+* Call Gemini API via the Google Gen AI SDK (`@google/genai`) with evidence-only prompts
+
+### Configuration
+
+* `GEMINI_API_KEY` or `GOOGLE_API_KEY` (required to enable Gemini)
+
+### Hard Constraints
+
+* Cannot introduce new issues
+* Cannot infer unseen code
+* Must reference provided evidence only
+* If evidence is incomplete, respond with "not enough data"
+
+### Prompt Guarantees
+
+* Evidence-bound
+* Structured sections
+* Tone without factual drift
+
+---
+
+## 9. Output Formatter Agent
+
+**Type:** Deterministic  
+**Role:** UX presentation
+
+### Responsibilities
+
+* Format output for terminal
+* Apply colors, emojis, scores
+* Render sections consistently
+
+### Output Example
+
+```
+Architecture Roast
+Repo Status: Recovering
+Score: 6.8 / 10
+```
+
+---
+
+## Hallucination Safeguards (Agent-Level)
+
+| Safeguard                         | Enforced By               |
+| --------------------------------- | ------------------------- |
+| No raw code to LLM                | Insight Aggregator        |
+| Evidence completeness validation  | Evidence Guard            |
+| Evidence-locked patch scope       | Fix-It Agent              |
+| Evidence-only narration           | Evidence Guard + Narrator |
+| Confidence labeling               | Aggregator                |
+| Deterministic fallback            | Output Formatter          |
+
+Worst case behavior:
+
+> Output becomes factual and boring - never incorrect. If evidence is missing, the narrator says "not enough data".
+
+---
+
+## Implementation Plan (Gemini Integration)
+
+1. Add a Gemini client module and strict evidence-only prompt builder.
+2. Use `GEMINI_API_KEY` or `GOOGLE_API_KEY` to enable the narrator, with deterministic fallback when missing or on API error.
+3. Wire Gemini into the pipeline using Evidence Guard output only.
+4. Add tests with mocked Gemini responses and failure-mode fallback.
+
+---
+
+## Judge-Ready Summary
+
+> CodeRoast uses a multi-agent pipeline where deterministic agents extract verifiable signals and a constrained generative agent narrates them. The Evidence Guard enforces evidence completeness, and the Fix-It Agent offers evidence-locked patch previews with verification.
+
+---
+
+## Future Agents (Post-Hackathon)
+
+* CI Agent (GitHub Actions)
+* Diff Agent (PR analysis)
+* Trend Agent (historical repo health)
+* Security Agent (OWASP-focused)
+
+---
+
+**End of Agents.md**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeRoast
+
+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,153 @@
+# CodeRoast
+
+CodeRoast is an agent-based architecture for generating evidence-bound code reviews and "roasts" with strong separation between deterministic analysis and constrained narration.
+
+## Overview
+
+This repository currently contains the architecture specification in `AGENTS.md`. The design focuses on deterministic data extraction first, followed by a tightly constrained generative step for human-readable output.
+
+## Architecture
+
+Pipeline:
+
+```
+CLI Agent
+  -> Repo Scanner Agent
+  -> Code Analysis Agent
+  -> Insight Aggregator Agent
+  -> Evidence Guard Agent
+  -> Roast Narrator Agent
+  -> Output Formatter Agent
+```
+
+## Agents at a Glance
+
+- CLI Agent: parses commands and orchestrates the pipeline
+- Repo Scanner Agent: discovers files, languages, and entry points
+- Code Analysis Agent: extracts structural signals and metrics
+- Insight Aggregator Agent: merges findings and ranks issues with confidence
+- Evidence Guard Agent: validates evidence completeness and gates narration
+- Roast Narrator Agent: generates explanation constrained to evidence
+- Output Formatter Agent: renders final output for the terminal
+
+## Design Principles
+
+- Deterministic before generative
+- Single responsibility per agent
+- Evidence-bound communication
+- Graceful degradation when generative steps fail
+
+## Hallucination Safeguards
+
+- No raw code is sent to the narrator
+- Narration is limited to known signals and evidence
+- Evidence completeness is validated before narration
+- Confidence is attached to every issue
+
+## Getting Started
+
+Prerequisite: Node.js 20+ (required by `@google/genai`).
+
+## Install (npm)
+
+```
+npm install -g coderoast
+```
+
+Run:
+
+```
+coderoast --path . --severity savage --focus architecture
+```
+
+1. Install dependencies:
+
+```
+npm install
+```
+
+2. Build the project:
+
+```
+npm run build
+```
+
+3. (Optional) Enable Gemini narration (Google Gen AI SDK):
+
+```
+set GEMINI_API_KEY=your_api_key
+```
+
+You can also add it to a `.env` file at the project root (see `.env.example`):
+
+```
+GEMINI_API_KEY=your_api_key
+```
+
+The Google Gen AI SDK also supports `GOOGLE_API_KEY` if you prefer that name.
+
+Optional overrides:
+
+```
+GEMINI_MODEL=gemini-2.5-flash
+GEMINI_API_VERSION=v1
+```
+
+If you see a model not found error, set `GEMINI_MODEL` to an available model (for example, `gemini-3-flash-preview` if your API access includes it) or specify `GEMINI_API_VERSION`. The SDK defaults to beta endpoints unless you set an API version.
+
+4. Run the CLI:
+
+```
+npm start -- --path . --severity savage --focus architecture
+```
+
+To include raw evidence and patch diffs in the output, add `--details`:
+
+```
+npm start -- --path . --severity savage --focus architecture --details
+```
+
+You can cap the evidence list with `--details-limit` (default is 3 when details are shown). Use `--details-limit=0` to show all evidence lines.
+
+5. (Optional) Preview evidence-locked fixes:
+
+```
+npm start -- --path . --fix
+```
+
+Fix-It only outputs patch previews and does not edit files.
+
+6. (Optional) Proof-locked apply (new branch + tests):
+
+```
+npm start -- --path . --fix --apply-fixes
+```
+
+Optional flags:
+
+- `--fix-branch <name>`: name the branch to create (default is `coderoast-fix-<timestamp>`).
+- `--fix-test-cmd "<cmd>"`: override the test command (default is `npm test`).
+- `--fix-debug`: save raw Gemini patch output to a temp file for debugging.
+- `--fix-limit <n>`: limit how many Fix-It attempts to run.
+
+## Scripts
+
+- `npm run lint` - run ESLint
+- `npm run lint:fix` - auto-fix lint issues
+- `npm run demo:fix` - create a demo repo and run Fix-It (requires `GEMINI_API_KEY` for suggestions)
+- `npm run demo:judge` - run a judge-style report on the current repo (`--details` + `--fix`)
+- `npm run typecheck` - run TypeScript in no-emit mode
+- `npm run build` - compile to `dist/`
+- `npm start` - run the compiled CLI
+- `npm test` - build and run the test suite
+
+## Project Structure
+
+- `src/index.ts` - CLI entry point
+- `src/pipeline.ts` - agent pipeline orchestrator
+- `src/agents/` - agent implementations
+- `src/types.ts` - shared types and schemas
+
+## Learn More
+
+See `AGENTS.md` for the full specification and detailed agent responsibilities.

package/dist/agents/cli-agent.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCliAgent = runCliAgent;
+const DEFAULT_CONFIG = {
+    path: ".",
+    severity: "gentle",
+    focus: "general",
+    showDetails: false,
+};
+const SEVERITIES = ["gentle", "savage", "investor-demo"];
+const FOCUS_AREAS = [
+    "architecture",
+    "performance",
+    "style",
+    "security",
+    "general",
+];
+function getArgValue(args, name) {
+    const flag = `--${name}`;
+    const prefix = `${flag}=`;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === flag) {
+            return args[i + 1];
+        }
+        if (arg.startsWith(prefix)) {
+            return arg.slice(prefix.length);
+        }
+    }
+    return undefined;
+}
+function coerceSeverity(value) {
+    if (value && SEVERITIES.includes(value)) {
+        return value;
+    }
+    return DEFAULT_CONFIG.severity;
+}
+function coerceFocus(value) {
+    if (value && FOCUS_AREAS.includes(value)) {
+        return value;
+    }
+    return DEFAULT_CONFIG.focus;
+}
+function parseNumber(value) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        return undefined;
+    }
+    return parsed;
+}
+function parseBooleanFlag(args, name) {
+    const flag = `--${name}`;
+    const prefix = `${flag}=`;
+    for (const arg of args) {
+        if (arg === flag) {
+            return true;
+        }
+        if (arg.startsWith(prefix)) {
+            const value = arg.slice(prefix.length).toLowerCase();
+            if (value === "" || value === "true" || value === "1") {
+                return true;
+            }
+            if (value === "false" || value === "0") {
+                return false;
+            }
+            return true;
+        }
+    }
+    return false;
+}
+function parseBooleanFlagWithAliases(args, names) {
+    return names.some((name) => parseBooleanFlag(args, name));
+}
+function runCliAgent(argv) {
+    return {
+        path: getArgValue(argv, "path") ?? DEFAULT_CONFIG.path,
+        severity: coerceSeverity(getArgValue(argv, "severity")),
+        focus: coerceFocus(getArgValue(argv, "focus")),
+        maxFileSizeMB: parseNumber(getArgValue(argv, "max-file-size-mb")),
+        scanTimeoutMs: parseNumber(getArgValue(argv, "scan-timeout-ms")),
+        enableFixes: parseBooleanFlag(argv, "fix"),
+        showDetails: parseBooleanFlag(argv, "details"),
+        detailsLimit: parseNumber(getArgValue(argv, "details-limit")),
+        applyFixes: parseBooleanFlagWithAliases(argv, ["apply-fixes", "apply"]),
+        fixDebug: parseBooleanFlag(argv, "fix-debug"),
+        fixBranch: getArgValue(argv, "fix-branch"),
+        fixTestCmd: getArgValue(argv, "fix-test-cmd"),
+        fixLimit: parseNumber(getArgValue(argv, "fix-limit")),
+    };
+}