microdao-daarion/docs/tools/pr_reviewer_tool.md

PR Reviewer Tool - Documentation

Overview

PR Reviewer Tool analyzes code changes (diff/patch) and provides structured code review with blocking issues, security findings, regression risks, and recommendations.

Integration

Tool Definition

Registered in services/router/tool_manager.py:

{
    "type": "function",
    "function": {
        "name": "pr_reviewer_tool",
        "description": "🔍 Рев'ю коду з PR/diff...",
        "parameters": {...}
    }
}

RBAC Configuration

Added to FULL_STANDARD_STACK in services/router/agent_tools_config.py - available to all agents.

Request Format

POST /v1/tools/pr-review (via gateway dispatcher)

{
  "mode": "blocking_only | full_review",
  "context": {
    "repo": {
      "name": "microdao-daarion",
      "commit_base": "abc123",
      "commit_head": "def456"
    },
    "change_summary": "Added user authentication",
    "risk_profile": "default | security_strict | release_gate"
  },
  "diff": {
    "format": "unified",
    "text": "diff --git a/file.py b/file.py\n...",
    "max_files": 200,
    "max_chars": 400000
  },
  "options": {
    "include_tests_checklist": true,
    "include_deploy_risks": true,
    "include_migration_risks": true,
    "language_hint": "python"
  }
}

Response Format

{
  "status": "succeeded",
  "data": {
    "summary": "🚫 2 blocking issues found",
    "score": {
      "risk": 50,
      "maintainability": 50,
      "security": 40,
      "test_coverage": 30
    },
    "blocking_issues": [
      {
        "id": "PRR-001",
        "title": "Secret detected in diff",
        "severity": "critical",
        "file": "config.py",
        "lines": "L15",
        "evidence": "API_KEY=***",
        "why_it_matters": "Secrets in code can be exposed...",
        "fix_suggestion": "Use environment variables..."
      }
    ],
    "issues": [...],
    "regression_risks": [...],
    "security_findings": [...],
    "tests_checklist": [...],
    "deploy_checklist": [...],
    "questions_for_author": [...]
  }
}

Modes

blocking_only

• Returns only critical and high severity issues
• Fast feedback for quick gate decisions
• No non-blocking issues

full_review

• Complete analysis with all issues
• Includes recommendations and checklists
• Slower but thorough

Blocking Issue Categories

Category	Severity	Description
SECRETS	Critical	API keys, tokens, passwords in diff
RCE	Critical	eval, exec, subprocess with shell=True
SQL_INJECTION	Critical	String concatenation in queries
AUTH_BYPASS	High	Disabled auth checks
HARDCODED_CREDS	High	Hardcoded credentials
SECURITY_DISABLED	High	Security checks commented out
BREAKING_API	High	API changes without versioning

Non-Blocking Issue Categories

Category	Severity	Description
TODO	Medium	Technical debt markers
BROAD_EXCEPTION	Medium	Catching all exceptions
LOGGING	Low	Print statements
BLOCKING_SLEEP	Low	Synchronous sleep calls

Security Features

Logging Policy

• NEVER logs diff.text
• Only logs: hash (first 16 chars), file count, line count, char count, mode

Secret Masking

Evidence automatically masks:

• api_key = sk-live-***
• token = ***
• password = ***
• Private keys: -----BEGIN PRIVATE KEY----- → masked

Limits Enforced

• max_chars: Default 400KB, max configurable
• max_files: Default 200 files
• Timeout: 30 seconds for analysis

Example Usage

Blocking Only (Quick Gate)

{
  "mode": "blocking_only",
  "diff": {
    "text": "diff --git a/.env b/.env\n+API_KEY=sk-live-123\n"
  }
}

Expected: Returns blocking issue about secrets, evidence masked.

Full Review (Complete Analysis)

{
  "mode": "full_review",
  "context": {
    "repo": {"name": "microdao-daarion", "commit_base": "abc", "commit_head": "def"}
  },
  "diff": {
    "text": "diff --git a/services/api/main.py..."
  },
  "options": {
    "include_tests_checklist": true,
    "include_deploy_risks": true
  }
}

Expected: Full response with blocking issues, non-blocking issues, checklists, regression risks.

Scoring

Risk Score (0-100)

• 0-25: Low risk
• 26-50: Medium risk
• 51-75: High risk
• 76-100: Critical risk

Calculation: min(100, blocking_issues * 25 + issues * 5)

Security Score (0-100)

• Starts at 100
• Subtracts 30 per security finding

Integration with Other Tools

With RepoTool

If diff text not provided, can use:

{
  "source": "git_range",
  "base": "abc123",
  "head": "def456"
}

Tool will fetch diff via RepoTool or local git.

Testing

pytest tools/pr_reviewer_tool/tests/test_pr_reviewer.py -v

Test coverage:

• Diff size limits enforced
• File count limits enforced
• Secrets detection + masking
• RCE pattern detection
• SQL injection detection
• Auth bypass detection
• blocking_only vs full_review modes
• Scoring calculation
• Checklist generation

Error Responses

{
  "status": "failed",
  "error": {
    "code": "diff_too_large",
    "message": "Diff too large: 500000 chars (max: 400000)",
    "retryable": false
  }
}