diffray 0.1.0 → 0.1.3

package/package.json

@@ -1,31 +1,32 @@
 {
   "name": "diffray",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "AI-powered code review CLI for git changes",
   "author": "Ilya Strelov <strelov1@gmail.com>",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "diffray": "./bin/diffray-wrapper.js"
+    "diffray": "./dist/diffray.js"
   },
   "files": [
-    "bin/diffray-wrapper.js",
-    "scripts/postinstall.js",
+    "dist/diffray.js",
+    "dist/defaults",
     "src/defaults"
   ],
   "scripts": {
-    "postinstall": "node scripts/postinstall.js",
     "dev": "bun run ./bin/diffray.ts",
-    "build": "bun build ./bin/diffray.ts --compile --target=bun --minify --outfile dist/diffray",
-    "build:all": "bash scripts/build-all.sh",
+    "build": "bun build ./bin/diffray.ts --outfile dist/diffray.js --target node --minify && node -e \"const fs=require('fs');const f='dist/diffray.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r src/defaults dist/",
+    "link:local": "node -e \"const p=require('./package.json');p.bin.diffray='./bin/diffray.ts';require('fs').writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n')\" && bun link",
+    "link:publish": "node -e \"const p=require('./package.json');p.bin.diffray='./dist/diffray.js';require('fs').writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n')\"",
     "link": "bun link",
     "unlink": "bun unlink",
+    "test": "bun test",
     "ts-check": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepublishOnly": "echo 'Run build:all and create GitHub release first!'"
+    "prepublishOnly": "npm run build && npm run link:publish"
   },
   "repository": {
     "type": "git",
@@ -75,6 +76,7 @@
     "citty": "^0.1.6",
     "diff": "^8.0.2",
     "glob": "^13.0.0",
+    "yaml": "^2.8.2",
     "zod": "^3.22.4"
   }
 }

package/src/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/src/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/src/defaults/prompts/output-format.md

@@ -1,8 +1,8 @@
 # Output Format
 
-Return your findings as a **JSON array** with the following structure:
+Return your findings as a **JSON array** wrapped in `<json>...</json>` XML tags:
 
-```json
+<json>
 [
   {
     "file": "path/to/file.ts",
@@ -15,22 +15,29 @@ Return your findings as a **JSON array** with the following structure:
     "suggestion": "How to fix this issue (optional)"
   }
 ]
-```
+</json>
 
 ## Field Descriptions:
 
 - **file**: Relative path to the file containing the issue
-- **lineStart**: Starting line number of the issue
-- **lineEnd**: Ending line number of the issue (can be same as lineStart)
+- **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**: `[]`
+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:
@@ -41,7 +48,7 @@ Return your findings as a **JSON array** with the following structure:
 
 ## Example:
 
-```json
+<json>
 [
   {
     "file": "src/utils/validator.ts",
@@ -54,4 +61,4 @@ Return your findings as a **JSON array** with the following structure:
     "suggestion": "Add a null check before accessing user properties: if (user) { ... }"
   }
 ]
-```
+</json>

package/src/defaults/prompts/validation.md

@@ -12,34 +12,129 @@ You will receive a JSON array of issues. Each issue has:
 - 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²) 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 VERIFIABLE in the code
+- The issue is REAL and VERIFIED in the actual code (you read it!)
 - Line numbers are correct (within ~5 lines)
-- The claim can be proven with concrete evidence
+- 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:
+- Issues you cannot verify after reading the code
+- Claims that contradict what the actual code shows
 - Speculative or theoretical issues without proof
 - Issues where line numbers don't match actual code
 - Subjective style preferences
-- Issues that cannot be verified
 - Duplicate issues (keep only one)
 - Issues about code not in the diff
 - Low-confidence or "might be" issues
+- **INTENTIONAL TRADE-OFFS: Changes that are documented as deliberate decisions**
+- **FIXES DISGUISED AS ISSUES: When the "problem" is actually a fix for something else**
+
+IMPORTANT: When in doubt, FILTER OUT the issue. Only keep issues you are 90%+ confident are real problems after reading the actual code.
 
-IMPORTANT: When in doubt, FILTER OUT the issue. Only keep issues you are 90%+ confident are real problems.
+## CRITICAL: Recognize INTENTIONAL DESIGN DECISIONS
 
-Your job is to:
-1. Analyze each issue carefully
-2. Only filter out CLEAR false positives as defined above
-3. Return the valid issues in JSON format
+Many "issues" are actually INTENTIONAL trade-offs. Before keeping an issue, check if it's a deliberate choice:
 
-You may include your analysis and reasoning, but MUST include a JSON array of valid issues somewhere in your response. The JSON array can be wrapped in markdown code blocks.
+### Signs of INTENTIONAL trade-offs (FILTER these):
+
+1. **COMMIT MESSAGES (provided in context above) - CHECK THESE FIRST!**
+   - Commit messages explain WHY changes were made
+   - Look for keywords: "fixes", "prevents", "to avoid", "speed up", "instead of"
+   - If commit says "X to fix Y" and issue complains about X → FILTER
+   - Example: Commit "Init at startup to fix context cancelled" + Issue "Startup delays" → FILTER
+
+2. **Code comments explaining the choice**:
+   - "// Using eager init to avoid context timeouts"
+   - "// Fine-grained locking for better parallelism"
+   - TODO comments acknowledging the trade-off
+
+3. **Common architectural trade-off patterns**:
+
+| Pattern You See | Likely FIXES | FILTER if issue complains about |
+|-----------------|--------------|--------------------------------|
+| Eager init in constructor | Timeout/context errors | "Startup delays" |
+| Fine-grained locking | Slow performance | "Possible race condition" (if TODO exists) |
+| Coarse locking | Race conditions | "Performance bottleneck" |
+| Sync instead of async | Complexity/ordering bugs | "Blocking operation" |
+| Defensive copying | Mutation bugs | "Memory overhead" |
+
+4. **The issue describes the INTENDED behavior**:
+   - If code deliberately does X for reason Y, and issue complains about X → FILTER
+   - The "problem" IS the solution to a different problem
+
+### Example: FILTER as intentional trade-off (commit message)
+```
+Commit message: "Init at startup to fix context cancelled errors. Use finer-grained locking to speed things up."
+Issue: "Blocking initialization causes startup delays"
+→ FILTER: The commit EXPLICITLY says init at startup was to fix context errors
+```
+
+### Example: FILTER as intentional trade-off (code comment)
+```
+Code: Init() called in constructor (not lazily)
+Comment nearby: "// Initialize at startup to prevent gRPC context timeouts"
+Issue: "Blocking initialization causes startup delays"
+→ FILTER: The delay is INTENTIONAL to prevent runtime errors
+```
+
+### Example: KEEP as unintentional side-effect
+```
+Commit message: "Use finer-grained locking to speed things up"
+Code: Lock only protects cache write, not entire operation
+No TODO or comment acknowledging the race condition risk
+Issue: "Race condition - multiple goroutines can build same index"
+→ KEEP: Commit wanted speed, but likely didn't realize the race condition. No acknowledgment.
+```
+
+### Key question: Did the author KNOW about this trade-off?
+- YES (commit message explains it, comment, TODO) → FILTER
+- NO (no acknowledgment anywhere, likely oversight) → KEEP
+
+## 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 the valid issues in JSON format
+
+You may include your analysis and reasoning, but MUST wrap your final JSON array in `<json>...</json>` XML tags.
 
 ## Example input:
 
-```json
+<json>
 [
   {
     "file": "src/example.ts",
@@ -53,11 +148,18 @@ You may include your analysis and reasoning, but MUST include a JSON array of va
     "agent": "bug-hunter"
   }
 ]
-```
+</json>
+
+## Example validation process:
 
-## Example output (KEEP - this is a valid code quality issue):
+1. Read src/example.ts lines 10-15
+2. Check: Is the calculation actually duplicated?
+3. If YES: Keep the issue
+4. If NO (e.g., calculations are different, or one is cached): Filter out
 
-```json
+## Example output:
+
+<json>
 [
   {
     "file": "src/example.ts",
@@ -71,10 +173,4 @@ You may include your analysis and reasoning, but MUST include a JSON array of va
     "agent": "bug-hunter"
   }
 ]
-```
-
-## Example of what to FILTER OUT:
-
-- "Variable 'foo' is unused" but the variable IS used later in the code
-- "Missing null check" but there's already a null check
-- Issue about line 50 but the file only has 30 lines
+</json>

package/src/defaults/rules/code-general.md

@@ -0,0 +1,46 @@
+---
+name: code-general
+description: General code quality review for all source files
+patterns:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.rb"
+  - "**/*.php"
+  - "**/*.c"
+  - "**/*.cpp"
+  - "**/*.h"
+  - "**/*.cs"
+  - "**/*.swift"
+  - "**/*.kt"
+  - "**/*.scala"
+agent: general
+---
+
+Perform a general code quality review. Focus on:
+
+1. **Readability** - Is the code easy to understand?
+2. **Simplicity** - Is there unnecessary complexity or over-engineering?
+3. **Naming** - Are variables, functions, and classes named clearly?
+4. **Structure** - Is the code organized logically? Are functions doing too much?
+5. **Dependencies** - Are there hidden or circular dependencies?
+6. **DRY violations** - Is there obvious code duplication?
+7. **API design** - Are interfaces intuitive and consistent?
+
+Do NOT review (covered by other agents):
+- Bugs, logic errors, edge cases → bug-hunter
+- Security vulnerabilities → security-scan
+- Performance issues → performance-check
+
+Be direct and actionable. Only report issues that genuinely need attention.
+
+IMPORTANT: Do NOT report:
+- Code that is already good
+- Minor style preferences
+- Compliments or positive observations
+- Suggestions for hypothetical future improvements

package/bin/diffray-wrapper.js

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from 'child_process';
-import { existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const isWindows = process.platform === 'win32';
-const binaryName = isWindows ? 'diffray.exe' : 'diffray';
-const binaryPath = join(__dirname, '..', '.bin', binaryName);
-
-if (!existsSync(binaryPath)) {
-  console.error(`Error: diffray binary not found at ${binaryPath}`);
-  console.error('Try reinstalling: npm install -g diffray');
-  process.exit(1);
-}
-
-const child = spawn(binaryPath, process.argv.slice(2), {
-  stdio: 'inherit',
-  windowsHide: true,
-});
-
-child.on('error', (err) => {
-  console.error('Failed to start diffray:', err.message);
-  process.exit(1);
-});
-
-child.on('close', (code) => {
-  process.exit(code ?? 0);
-});

package/scripts/postinstall.js

@@ -1,75 +0,0 @@
-#!/usr/bin/env node
-
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import process from 'process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-async function main() {
-  try {
-    if (process.env.DIFFRAY_SKIP_DOWNLOAD === '1') {
-      console.log('Skipping diffray binary download (DIFFRAY_SKIP_DOWNLOAD=1)');
-      process.exit(0);
-    }
-
-    const packageJsonPath = path.join(__dirname, '..', 'package.json');
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-    const version = packageJson.version;
-
-    const platform = process.platform;
-    const arch = process.arch;
-
-    const platformArchMap = {
-      'darwin-arm64': 'diffray-darwin-arm64',
-      'darwin-x64': 'diffray-darwin-x64',
-      'linux-arm64': 'diffray-linux-arm64',
-      'linux-x64': 'diffray-linux-x64',
-      'win32-x64': 'diffray-win-x64.exe'
-    };
-
-    const platformArch = `${platform}-${arch}`;
-    const binaryName = platformArchMap[platformArch];
-
-    if (!binaryName) {
-      console.error(`Unsupported platform: ${platformArch}`);
-      process.exit(1);
-    }
-
-    console.log(`Downloading diffray v${version} for ${platformArch}...`);
-
-    const url = `https://github.com/diffray/diffray/releases/download/v${version}/${binaryName}`;
-    const response = await fetch(url);
-
-    if (!response.ok) {
-      console.error(`Failed to download binary: ${response.status} ${response.statusText}`);
-      process.exit(1);
-    }
-
-    const binDir = path.join(__dirname, '..', '.bin');
-    if (!fs.existsSync(binDir)) {
-      fs.mkdirSync(binDir, { recursive: true });
-    }
-
-    const outputPath = platform === 'win32' 
-      ? path.join(binDir, 'diffray.exe')
-      : path.join(binDir, 'diffray');
-
-    const buffer = await response.arrayBuffer();
-    fs.writeFileSync(outputPath, new Uint8Array(buffer));
-
-    if (platform !== 'win32') {
-      fs.chmodSync(outputPath, 0o755);
-    }
-
-    console.log('Successfully installed diffray binary');
-    process.exit(0);
-  } catch (error) {
-    console.error('Error installing diffray binary:', error.message);
-    process.exit(1);
-  }
-}
-
-main();