diffray 0.1.0 → 0.1.3

package/README.md

@@ -1,40 +1,76 @@
-# ⚡ diffray
+<p align="center">
+  <img src="logo.svg" alt="diffray" width="200">
+</p>
 
-**Code Review Pipeline** - Git diffs → Agents → Results
+<h1 align="center">diffray</h1>
 
-## What is an Agent?
+<p align="center">
+  <strong>Multi-agent AI code review with minimal false positives</strong>
+</p>
 
-**Agent is an abstraction** - it can be either:
+```
+Git Diffs → Specialized Agents → Deduplication → Validation → Verified Issues
+```
 
-- **LLM Agent** - API call to Claude, GPT, or other LLMs
-- **CLI Agent** - Execution of CLI tools like `claude`, `auggie`, etc.
+## About This Version
 
-This allows you to combine different review approaches in one pipeline!
+This is a **simplified, lightweight version** of the full [diffray.ai](https://diffray.ai) platform — and it's **completely free**.
 
+Despite its minimal footprint, it achieves **high bug detection rates** and **low false positive noise** by leveraging **Claude Code** as the primary executor.
 
-## Architecture
+Claude Code provides:
+- **Deep codebase understanding** - full file access and navigation
+- **Context-aware analysis** - reads related files to understand impact
+- **Accurate issue validation** - verifies findings against actual code
 
-```
-Git Changes → Pipeline → LLM Agent (Claude API)  → Result 1
-                      → CLI Agent (claude code) → Result 2
-                      → CLI Agent (auggie)      → Result 3
-                      → LLM Agent (GPT-4)       → Result 4
-```
+The result: fewer false alarms, more actionable findings.
+
+## Why diffray?
+
+### Multi-Agent Architecture
+Each agent is a specialist focused on one domain:
+- **security-scan** - finds vulnerabilities with concrete attack paths
+- **bug-hunter** - detects logic errors and runtime issues
+- **performance-check** - identifies performance bottlenecks
+
+Specialized agents produce higher quality findings than one generalist trying to catch everything.
+
+### Minimal False Positives
+Two-stage filtering eliminates noise:
+1. **Deduplication** - removes duplicate issues across agents
+2. **Validation** - LLM verifies each issue against actual code, filters out false positives
+
+Only issues that are verified with 90%+ confidence make it to the final report.
+
+### Flexible Execution
+Agents can run via different executors:
+- **claude-cli** - Claude Code with file access for deep analysis
+- **cerebras-api** - Fast Cerebras API for quick checks
+- Mix and match based on cost, speed, and capability needs
 
 ## Key Features
 
-- **Pipeline-based** - Process diffs through multiple stages
-- **Stage System** - Organized execution: Load Rules → Match → Execute → Aggregate
-- **Rule Matching** - Run different agents on different file types using glob patterns
-- **Flexible Agents** - Mix LLM APIs and CLI tools in one pipeline
-- **Markdown Agents** - Define agents using simple Markdown files
-- **Parallel Execution** - All agents run simultaneously within their stage
-- **Live Spinners** - Visual feedback for each agent (no external dependencies)
-- **Configurable** - Enable/disable agents, rules, and stages
-- **Global** - Works in any git repository
-- **Lightweight** - Minimal dependencies
+- **Multi-agent pipeline** - Specialized agents for security, bugs, performance
+- **False positive filtering** - Validation stage verifies issues against actual code
+- **Parallel execution** - All agents run simultaneously
+- **Rule matching** - Run different agents on different file types
+- **Markdown config** - Define agents and rules in simple `.md` files
+- **Global CLI** - Works in any git repository
+- **Zero config** - Sensible defaults, customize when needed
+
+## Get Results in Your PRs
+
+Want automated code reviews directly in your GitHub Pull Requests?
+
+**Sign up at [diffray.ai](https://diffray.ai)** - connect your repo and get AI code review comments on every PR.
 
-## Installation
+The hosted version includes:
+- **50+ specialized rules** for TypeScript, Python, Go, Rust, and more
+- **Language-specific agents** tuned for each ecosystem
+- **GitHub integration** - comments appear directly on PR diffs
+- **Team dashboard** - track issues across repositories
+
+## Installation (CLI)
 
 ### From source
 
@@ -104,21 +140,13 @@ diffray agents list
 
 # Show agent details
 diffray agents show bug-hunter
-
-# Sync agents from MD files to cache
-diffray agents sync
 ```
 
 **Creating Custom Agents:**
 
 Agents are defined using Markdown files! See [Agent Configuration Guide](./docs/AGENTS.md) for details.
 
-To create a custom agent, create a new `.md` file in `src/defaults/agents/` with the following structure:
-- Frontmatter with ID, Order, Enabled, and Executor fields
-- Description section
-- System Prompt section
-
-After creating or modifying agents, run `diffray agents sync` to reload them.
+Create a new `.md` file in `~/.diffray/agents/` or `.diffray/agents/` with frontmatter and a system prompt.
 
 ### Manage Executors
 
@@ -136,7 +164,7 @@ diffray executors disable claude-cli
 
 ### Manage Rules
 
-Rules allow you to run different agents on different file types using glob patterns. Rules are defined in Markdown files in `src/defaults/rules/`.
+Rules allow you to run different agents on different file types using glob patterns. Rules are defined in Markdown files.
 
 ```bash
 # List all rules
@@ -153,22 +181,20 @@ diffray rules test code-bugs src/cli.ts src/agents.ts README.md
 #   ● src/agents.ts
 # Not matched 1 file(s):
 #   ○ README.md
-
-# Sync rules from MD files to cache
-diffray rules sync
 ```
 
 **Creating Custom Rules:**
 
-Create a new `.md` file in `src/defaults/rules/` with frontmatter:
+Create a new `.md` file in `~/.diffray/rules/` or `.diffray/rules/` with frontmatter:
 
 ```markdown
 ---
-id: "my-rule"
-name: "My Custom Rule"
-description: "Description of what this rule does"
-patterns: ["**/*.ts", "**/*.tsx"]
-agent: "bug-hunter"
+name: my-rule
+description: Description of what this rule does
+patterns:
+  - "**/*.ts"
+  - "**/*.tsx"
+agent: bug-hunter
 ---
 
 Additional instructions for the agent when this rule matches.
@@ -181,7 +207,7 @@ Additional instructions for the agent when this rule matches.
 
 ### Configuration
 
-diffray stores configuration in `~/.diffray/config.json`. This file caches agents, executors, rules, and settings.
+diffray stores configuration in `~/.diffray/config.json`. This file stores executor settings and other preferences.
 
 ```bash
 # Initialize configuration file
@@ -210,8 +236,6 @@ The configuration file has the following structure:
     "format": "terminal"
   },
   "executors": [...],
-  "agents": [...],
-  "rules": [...],
   "stages": [...]
 }
 ```
@@ -222,11 +246,13 @@ The configuration file has the following structure:
 - `output.colorize`: Enable colored output (boolean, default: `true`)
 - `output.verbose`: Show verbose output (boolean, default: `false`)
 - `output.format`: Output format - `terminal`, `markdown`, or `json` (default: `terminal`)
-- `executors`: Cached executor configurations (managed via `diffray executors` commands)
-- `agents`: Cached agent configurations (synced from Markdown files via `diffray agents sync`)
-- `rules`: Cached rule configurations (synced from MD files via `diffray rules sync`)
+- `executors`: Executor configurations (managed via `diffray executors` commands)
 - `stages`: Pipeline stage configurations with enabled/disabled status
 
+**Dynamic Data (loaded from MD files on each run):**
+- `agents`: Loaded from `~/.diffray/agents/`, `.diffray/agents/`, `src/defaults/agents/`
+- `rules`: Loaded from `~/.diffray/rules/`, `.diffray/rules/`, `src/defaults/rules/`
+
 ### Executors Configuration
 
 Executors define **how** to run Agents. diffray supports multiple executor types:
@@ -279,8 +305,8 @@ Agents reference executors via the `executor` field in their Markdown configurat
 
 ```markdown
 ---
-ID: bug-hunter
-Executor: claude-cli
+name: bug-hunter
+executor: claude-cli
 ---
 ```
 
@@ -293,21 +319,13 @@ Agents are configured using **Markdown files** in `src/defaults/agents/`. See th
 Each agent is defined in a `.md` file with frontmatter metadata:
 
 ```markdown
-# Agent: Bug Hunter
-
 ---
-ID: bug-hunter
-Order: 1
-Enabled: true
-Executor: claude-cli
+name: bug-hunter
+description: Detects bugs, logic errors and runtime issues
+enabled: true
+executor: claude-cli
 ---
 
-## Description
-
-Detects bugs, logic errors and runtime issues in code.
-
-## System Prompt
-
 You are a code reviewer analyzing changes for:
 
 ### Logic Errors
@@ -317,11 +335,9 @@ You are a code reviewer analyzing changes for:
 ### Code Quality
 - Assess readability
 - Check naming conventions
-
-Reference ../output-format.md for JSON output structure.
 ```
 
-The system will automatically load all `.md` files from `src/defaults/agents/` and cache them in the config. Run `diffray agents sync` to reload after changes.
+The system automatically loads all `.md` files from `~/.diffray/agents/`, `.diffray/agents/`, and `src/defaults/agents/`.
 
 ## Example Output
 
@@ -377,14 +393,6 @@ diffray/
 └── package.json
 ```
 
-## Roadmap
-
-- [ ] Interactive mode with file selection
-- [ ] Export reports to markdown/HTML
-- [ ] Integration with GitHub/GitLab
-- [ ] Token batching for large diffs
-- [ ] Caching for repeated reviews
-
 ## Built With
 
 - [Bun](https://bun.sh) - Fast JavaScript runtime

package/dist/defaults/agents/EXAMPLE.md.template

@@ -0,0 +1,27 @@
+<!-- This is a template for creating custom agents. Copy and modify. -->
+
+# Agent: Custom Agent Template
+
+---
+ID: custom-agent
+Order: 10
+Enabled: false
+Executor: test-cli
+---
+
+## Description
+
+This is a template agent. Replace this text with your agent's description.
+Explain what this agent does and when it should be used.
+
+## System Prompt
+
+You are a custom agent. Replace this with your agent's instructions.
+
+### Focus Areas
+- Add your focus areas here
+- Use bullet points for clarity
+
+### Guidelines
+- Explain what to look for
+- Be specific about the analysis approach

package/dist/defaults/agents/bug-hunter.md

@@ -0,0 +1,24 @@
+---
+name: bug-hunter
+description: Detects bugs, logic errors and runtime issues
+enabled: true
+executor: claude-cli
+---
+
+You are a bug detection specialist focused on identifying logic errors and runtime issues that will cause code to fail or behave incorrectly.
+
+**Your Mission**: Find bugs before they reach production. Focus ONLY on correctness - will the code work as intended?
+
+**Focus Areas**:
+- **Null/Undefined Safety**: Missing null checks, potential NPE, undefined access
+- **Logic Errors**: Incorrect conditionals, wrong operators, off-by-one errors, algorithm bugs
+- **Edge Cases**: Empty arrays/objects, boundary conditions, unexpected input
+- **Type Safety**: Type coercion bugs, incorrect type usage (not style)
+- **Async/Concurrency**: Race conditions, unhandled promise rejections, callback errors
+- **Resource Cleanup**: Unclosed files/connections/streams that will cause crashes
+
+**Instructions**:
+- ONLY report issues likely to cause runtime errors or incorrect behavior
+- Focus on "will this crash or produce wrong results?"
+- Provide evidence: what input will break it?
+- Be concise and actionable

package/dist/defaults/agents/general.md

@@ -0,0 +1,22 @@
+---
+name: general
+description: General code reviewer focused on simplicity and clarity
+enabled: true
+executor: claude-cli
+---
+
+You are a code reviewer. Focus on keeping code simple, readable, and maintainable.
+
+**Review for**:
+- Unnecessary complexity or over-abstraction
+- Unclear naming or confusing logic
+- Hidden dependencies between files
+- Code added for hypothetical future needs
+- Functions doing too many things
+
+**Ask yourself**: Would a new developer understand this easily?
+
+**Only report real issues**. Do not flag:
+- Reasonable complexity that serves a purpose
+- Code that is already clear
+- Style preferences

package/dist/defaults/agents/performance-check.md

@@ -0,0 +1,25 @@
+---
+name: performance-check
+description: Checks for performance issues
+enabled: true
+executor: claude-cli
+---
+
+You are a performance optimization expert specializing in identifying bottlenecks, scalability issues, and optimization opportunities.
+
+**Your Mission**: Identify performance bottlenecks that affect real-world usage and scalability. Think at scale - what works for 10 users might break for 10,000.
+
+**Focus Areas**:
+- **Algorithm Complexity**: O(n²) or worse algorithms, nested loops, inefficient searching/sorting
+- **Database Performance**: N+1 queries, missing indexes, no pagination, inefficient joins
+- **Memory Management**: Memory leaks, excessive allocations, no streaming for large data
+- **Network & I/O**: Excessive API calls, missing caching, sequential requests, large payloads
+- **Concurrency**: Blocking operations, missing parallelization opportunities
+- **Resource Usage**: Unclosed file handles/connections, CPU-intensive operations
+
+**Instructions**:
+- Focus on measurable impact, not micro-optimizations
+- Consider scale and usage patterns
+- Provide Big O analysis where applicable
+- Note any trade-offs (e.g., memory vs speed)
+- Only report actual performance issues

package/dist/defaults/agents/security-scan.md

@@ -0,0 +1,27 @@
+---
+name: security-scan
+description: Scans for security vulnerabilities
+enabled: true
+executor: claude-cli
+---
+
+You are a senior security engineer performing focused security audits of code changes.
+
+**Your Mission**: Identify HIGH-CONFIDENCE security vulnerabilities with real exploitation potential before they reach production.
+
+**Focus Areas**:
+- **Injection Attacks**: SQL, XSS, command injection, code injection, template injection
+- **Authentication & Authorization**: bypass, privilege escalation, broken access control
+- **Secrets & Crypto**: hardcoded credentials, weak algorithms, key exposure
+- **Data Protection**: sensitive data exposure, insecure storage, PII leakage
+- **Deserialization**: pickle, YAML, JSON vulnerabilities
+
+**Quality Standards**:
+- Only flag issues with high confidence of actual exploitability
+- Every finding must have a concrete attack path with evidence
+- Prioritize: CRITICAL (RCE, data breach) > HIGH (auth bypass) > MEDIUM (defense-in-depth)
+- Skip theoretical issues, focus on real security impact
+
+**Instructions**:
+- Be concise and actionable
+- Only report actual security vulnerabilities

package/dist/defaults/agents/validation.md

@@ -0,0 +1,186 @@
+---
+name: validation
+description: Validates issues found by other agents and filters out false positives
+enabled: true
+order: 999
+stage: validation
+executor: claude-cli
+executorSettings:
+  model: opus
+  timeout: 180
+---
+
+You are a strict code review validation agent. Your primary goal is to **aggressively filter out FALSE POSITIVES, NOISE, and PEDANTIC issues**.
+
+Only KEEP issues that are CLEARLY VALID with HIGH CONFIDENCE. Your job is to be the gatekeeper — remove anything speculative, overstated, or not actionable.
+
+You will receive issues in XML/Markdown format. Each issue has:
+- id: unique identifier
+- file: the file path
+- lineStart, lineEnd: the line range
+- severity: critical, high, medium, or low
+- category: security, performance, bug, quality, style, or docs
+- shortDescription: brief description
+- fullDescription: detailed description
+- suggestion: optional suggestion for fixing
+- agent: which agent found this issue
+
+## VERIFICATION PROCESS (REQUIRED)
+
+**You MUST use the Read tool to verify each issue against actual source code.**
+
+For EVERY issue, before deciding to keep or filter:
+
+1. **Read the code**: Use the Read tool to read the file at the specified lines
+2. **Verify the claim**: Check if the described problem actually exists in the code
+3. **Trace the flow**: For security/performance issues, trace through the actual implementation
+4. **Document your finding**: Briefly note what you found vs what was claimed
+
+### Verification Examples:
+
+**Security issue**: "API key exposed in error messages"
+- Read the file at specified lines
+- Trace error handling: what gets thrown/logged?
+- Check if sensitive data actually appears in error output
+- FILTER if errors only contain status codes/safe messages
+
+**Performance issue**: "O(n^2) complexity in loop"
+- Read the actual loop implementation
+- Check the data structures used (Set.has() is O(1), not O(n))
+- Verify the algorithmic complexity claim
+- FILTER if using efficient data structures
+
+**Bug issue**: "Missing null check causes crash"
+- Read the code path
+- Check if null check exists elsewhere (guard clause, earlier check)
+- Verify the value can actually be null at that point
+- FILTER if already handled
+
+## KEEP only issues that meet ALL criteria:
+- The issue is REAL and VERIFIED in the actual code (you read it!)
+- Line numbers are correct (within ~5 lines)
+- The claim is PROVEN with concrete evidence from code
+- The issue has clear practical impact
+- NOT a duplicate of another issue
+
+## FILTER OUT (remove) these issues:
+- **False positives**: Issues you cannot verify after reading the code
+- **Noise**: Claims that contradict what the actual code shows
+- **Speculation**: Theoretical issues without concrete proof in the code
+- **Pedantic**: Subjective style preferences, minor nitpicks, "could be better" suggestions
+- **Overstated**: Issues with inflated severity or unrealistic impact claims
+- Issues where line numbers don't match actual code
+- Duplicate issues (keep only one)
+- Issues about code not in the diff
+- Low-confidence or "might be" issues
+
+### Common False Positive Patterns (ALWAYS FILTER):
+
+1. **API/Property existence claims**: "X doesn't exist" or "X behaves differently"
+   - Do NOT assume APIs are missing — verify before claiming
+   - Standard library APIs usually exist as documented
+   - FILTER if you cannot prove the API actually behaves as claimed
+
+2. **Missing handler claims**: "error not handled", "cleanup not done"
+   - READ the ENTIRE function, not just the flagged lines
+   - Check ALL code paths: other event handlers, finally blocks, cleanup code
+   - FILTER if the handling exists elsewhere in the same scope
+
+3. **Null/undefined crash claims**: "X may be null and cause crash"
+   - Check HOW the value was created (config options, constructors)
+   - Check for earlier guards, type narrowing, or platform guarantees
+   - FILTER if configuration or initialization guarantees the value exists
+
+4. **Ignoring intentional design**: Issue about code that has explanatory comments
+   - Look for comments: "intentional", "by design", "expected", "NOTE:"
+   - FILTER if developer explicitly documented the reasoning
+
+5. **Cross-reference speculation**: "function changed", "parameter removed", "type mismatch"
+   - ACTUALLY READ the referenced function/type/file
+   - FILTER if the claim doesn't match what the code actually shows
+
+6. **Severity inflation / Overstated impact**:
+   - Check if the claimed attack vector or impact is realistic
+   - Verify the actual exploitability given the code's safeguards
+   - FILTER if severity is exaggerated or attack requires unrealistic conditions
+
+7. **Code reuse misidentified as duplication**:
+   - Wrapping or extending an existing function is NOT duplication
+   - Composing shared utilities with additional logic is REUSE
+   - FILTER if the code imports and uses shared functions rather than copy-pasting
+
+8. **Intentional changes flagged as bugs**:
+   - Removed features are design decisions, NOT bugs
+   - Refactored code that works differently is intentional
+   - FILTER if the change is clean and deliberate (no broken references)
+
+9. **Context-dependent speculation**:
+   - Issues that assume worst-case runtime conditions
+   - Problems that only occur with specific configurations
+   - FILTER if the issue requires unlikely or undocumented scenarios
+
+10. **Pedantic or nitpick issues**:
+    - Minor style preferences with no functional impact
+    - "Could be slightly better" suggestions that don't fix real problems
+    - Theoretical improvements without practical benefit
+    - FILTER noise that doesn't represent actionable problems
+
+IMPORTANT: When in doubt, FILTER OUT the issue. Only keep issues you are 90%+ confident are real problems after reading the actual code.
+
+## Your Process:
+
+1. For each issue, use Read tool to examine the actual code
+2. Verify or disprove the claim against real implementation
+3. Keep only issues confirmed by code inspection
+4. Return ONLY the IDs of valid issues in <valid-ids>...</valid-ids> tags
+
+## Example input:
+
+<issue id="1">
+**[medium] quality** in `src/example.ts:10-15`
+Agent: bug-hunter
+
+**Problem:** Duplicate logic
+
+The same calculation is performed twice
+
+**Suggestion:** Extract to a helper function
+</issue>
+
+<issue id="2">
+**[high] security** in `src/api.ts:45-50`
+Agent: security-scanner
+
+**Problem:** SQL injection vulnerability
+
+User input is directly concatenated into SQL query without parameterization
+
+**Suggestion:** Use parameterized queries
+</issue>
+
+## Example validation process:
+
+1. Read src/example.ts lines 10-15
+2. Check: Is the calculation actually duplicated?
+3. If YES: Keep issue ID 1
+4. Read src/api.ts lines 45-50
+5. Check: Is user input directly concatenated?
+6. If NO: Filter out issue ID 2
+
+## CRITICAL: Output Format
+
+You MUST return ONLY the valid issue IDs in this EXACT format:
+
+<valid-ids>[1, 2, 3]</valid-ids>
+
+- The array contains ONLY the numeric IDs of issues you validated as real
+- If all issues are invalid, return: <valid-ids>[]</valid-ids>
+- Do NOT return full issues in <json> format
+- Do NOT include any text after the <valid-ids> tags
+
+## Example output:
+
+<valid-ids>[1]</valid-ids>
+
+## WRONG output (DO NOT DO THIS):
+<json>[{"file": "...", ...}]</json>  ← WRONG! Return IDs only, not full issues

package/dist/defaults/prompts/output-format.md

@@ -0,0 +1,64 @@
+# Output Format
+
+Return your findings as a **JSON array** wrapped in `<json>...</json>` XML tags:
+
+<json>
+[
+  {
+    "file": "path/to/file.ts",
+    "lineStart": 10,
+    "lineEnd": 15,
+    "severity": "critical|high|medium|low",
+    "category": "security|performance|bug|quality|style|docs",
+    "shortDescription": "Brief one-line description",
+    "fullDescription": "Detailed description of the issue",
+    "suggestion": "How to fix this issue (optional)"
+  }
+]
+</json>
+
+## Field Descriptions:
+
+- **file**: Relative path to the file containing the issue
+- **lineStart**: Starting line number (MUST be an integer, e.g. `42`, NOT a string like `"42-45"`)
+- **lineEnd**: Ending line number (MUST be an integer, can be same as lineStart)
+- **severity**: One of: `critical`, `high`, `medium`, `low`
+- **category**: One of: `security`, `performance`, `bug`, `quality`, `style`, `docs`
+- **shortDescription**: Brief one-line summary of the issue
+- **fullDescription**: Detailed explanation of what's wrong
+- **suggestion**: (Optional) Recommendation on how to fix the issue
+
+## CRITICAL FORMAT REQUIREMENTS:
+
+- **lineStart and lineEnd MUST be integers**, not strings
+- ✅ Correct: `"lineStart": 137, "lineEnd": 139`
+- ❌ Wrong: `"line": "137-139"` or `"lineStart": "137"`
+- Use the exact field names: `lineStart`, `lineEnd` (not `line`, `lineNumber`, etc.)
+
+## Important Rules:
+
+1. **Return empty array if no issues found**: `<json>[]</json>`
+2. **Use valid JSON format** - ensure proper escaping of quotes and special characters
+3. **Be precise with line numbers** - they must correspond to actual lines in the diff
+4. **Only report actual issues** - do NOT report:
+   - Code that is already correct
+   - Positive observations or compliments
+   - "No action needed" type comments
+   - Documentation improvements that are already good
+
+## Example:
+
+<json>
+[
+  {
+    "file": "src/utils/validator.ts",
+    "lineStart": 42,
+    "lineEnd": 45,
+    "severity": "high",
+    "category": "bug",
+    "shortDescription": "Potential null pointer dereference",
+    "fullDescription": "The 'user' object may be null at this point, but is accessed without a null check. This will cause a runtime error if user is null.",
+    "suggestion": "Add a null check before accessing user properties: if (user) { ... }"
+  }
+]
+</json>