backup

docs/features.md

@@ -254,3 +254,137 @@ tools:
 escalation:
   reason: "Validation failed"
   prompt: "Please inspect input data and retry."
+```
+
+---
+---
+
+# DREP — Documentation & Review Enhancement Platform
+
+**Version:** 1.1.0 (Production/Stable)
+
+AI-powered code review and documentation improvement tool for **Gitea**, **GitHub**, and **GitLab** repositories. DREP uses large language models to automatically analyze your Python codebase, review pull requests, generate documentation, and detect security vulnerabilities — saving developer time and catching issues before they reach production.
+
+---
+
+## CLI Commands
+
+### `drep init` — Interactive Configuration Wizard
+
+A guided setup experience that walks you through configuring DREP for your environment. The wizard asks you to choose your platform (GitHub, Gitea, or GitLab), select which repositories to monitor, pick an LLM provider, and configure documentation preferences. It supports enterprise and self-hosted instances. Secrets are never stored directly in the config file — instead, environment variable placeholders are used for all tokens and credentials.
+
+### `drep scan` — Repository Code Analysis
+
+Scans an entire repository for code quality issues and creates issues directly on your platform with the findings. DREP detects bugs, security vulnerabilities, best practice violations, and performance problems across all Python and Markdown files. It also generates missing docstrings for public functions. By default, only files that changed since the last scan are analyzed, making repeated scans fast and efficient. Duplicate findings are automatically prevented — if an issue was already reported, it won't be created again.
+
+### `drep review` — Pull Request / Merge Request Review
+
+Performs an AI-powered review of a pull request or merge request. DREP reads the diff, analyzes the changes using an LLM, and posts a summary comment along with inline comments on specific lines. Each comment includes a severity level so you can prioritize what to address first. At the end, it provides an approval or rejection recommendation based on the overall quality of the changes.
+
+### `drep check` — Local-Only Analysis
+
+Analyzes code on your local machine without needing any platform credentials. Ideal for pre-commit workflows — you can configure it to check only staged files so it runs before every commit. It can output results as plain text or JSON and integrates directly with pre-commit hooks. Use it to catch issues before pushing code, with the option to run in warning-only mode so it never blocks your commits.
+
+### `drep validate` — Configuration Validation
+
+Verifies that your configuration file is complete and valid before running any other commands. Catches misconfigurations early.
+
+---
+
+## Features
+
+### 1. Proactive Code Analysis
+
+DREP uses AI to deeply analyze your Python code and surface real issues across four key areas:
+
+- **Bugs & Logic Errors** — Catches incorrect logic, unhandled edge cases, potential crashes, undefined variables, and type mismatches that could cause runtime failures.
+- **Security Vulnerabilities** — Identifies dangerous patterns like SQL injection, command injection, path traversal, unsafe deserialization, hardcoded secrets, and weak cryptographic usage before they become exploitable.
+- **Best Practice Violations** — Flags PEP 8 violations, missing docstrings, poor naming conventions, code smells, and anti-patterns that make code harder to maintain.
+- **Performance Problems** — Spots inefficient algorithms, unnecessary loops, blocking I/O operations, and potential memory leaks that degrade application performance.
+
+Every finding includes a severity level (critical, high, medium, low, or info), a clear explanation of the problem, and a specific actionable suggestion for how to fix it. Findings are posted as issues on your platform with proper categorization.
+
+### 2. Docstring Intelligence
+
+Automatically generates and improves Google-style docstrings for your Python functions using AI. DREP intelligently targets the functions that need documentation most — those that are public-facing, sufficiently complex, or use special decorators like `@property` and `@classmethod`. It also detects poor-quality existing docstrings that are too short, contain placeholder text like "TODO" or "helper function," or are missing parameter and return value descriptions. Each generated docstring includes a quality rating and an explanation of the function's behavior, ensuring your API documentation is always accurate and complete.
+
+### 3. Automated Pull Request / Merge Request Reviews
+
+Provides thorough, AI-driven code reviews directly on your pull requests and merge requests. DREP posts inline comments on specific changed lines, making feedback easy to find and act on. Each comment is tagged with a severity level:
+
+- **Info** — Minor notes or style observations
+- **Suggestion** — Recommended improvements that aren't required
+- **Warning** — Potential issues that should be addressed before merging
+- **Critical** — Serious bugs, security problems, or blockers that must be fixed
+
+The review also includes an overall summary with an approval or rejection recommendation and a list of any major concerns that could block the merge.
+
+### 4. Documentation Analysis
+
+Lints your Markdown documentation files to enforce consistent formatting and readability. Catches common problems such as trailing whitespace, tab characters, empty headings, missing spaces after heading markers, overly long lines, excessive blank lines, bare URLs that should be wrapped in link syntax, broken link formatting, and unclosed code fences. Supports custom dictionaries for spell checking so that project-specific terms are not flagged as errors.
+
+### 5. Smart Caching
+
+Remembers previous analysis results so that unchanged code is not re-analyzed, dramatically reducing LLM costs and scan times. The cache is automatically invalidated when code changes, ensuring results are always up to date. Old entries expire after a configurable period and are evicted when the cache reaches its size limit. On incremental scans, caching typically reduces LLM costs by over 80%.
+
+### 6. Rate Limiting
+
+Prevents overloading your LLM provider and platform APIs with built-in multi-level rate limiting. Controls are applied at the global level, per-repository level, per-minute request count, and per-minute token count. This ensures DREP operates within your provider's limits even when scanning many repositories in parallel, avoiding throttling errors and unexpected costs.
+
+### 7. Circuit Breaker
+
+Protects your workflow when external services (LLM providers, platform APIs) experience outages. If a service starts failing repeatedly, DREP automatically stops sending requests to it and fails fast instead of hanging on timeouts. After a recovery period, it cautiously tests whether the service is back before resuming normal operation. This prevents cascading failures and keeps overall scan throughput stable even when one service is degraded.
+
+### 8. Incremental Scanning
+
+Only analyzes files that have changed since the last scan by tracking the most recent commit. This makes repeated scans fast, as unchanged files are skipped entirely. When running against a repository for the first time, or when no previous scan record exists, DREP falls back to a full scan of all files.
+
+### 9. Security Detection
+
+Provides a fast, pattern-based security scan that runs without requiring an LLM. Detects common vulnerability patterns including SQL injection, command injection, path traversal, unsafe deserialization, hardcoded secrets, and weak cryptographic usage. This acts as a first line of defense that catches well-known security anti-patterns instantly, complementing the deeper AI-powered analysis.
+
+### 10. Pre-Commit Hook Integration
+
+Integrates directly into your development workflow as a pre-commit hook. When configured, DREP checks only your staged files before each commit and reports any issues it finds. No platform token is required for local checks. Exit codes integrate with CI/CD pipelines — the hook can either block commits that have issues or run in warning-only mode where it reports findings without preventing the commit.
+
+### 11. Webhook Server
+
+Runs as a server that listens for events from your Git platform and automatically triggers analysis. When code is pushed to a repository, DREP runs a background scan. When a pull request is opened or updated, it automatically posts an inline review. This enables a fully hands-off workflow where every code change is reviewed without any manual intervention.
+
+### 12. LLM Metrics & Observability
+
+Tracks the cost, latency, and success rate of every LLM request. Provides a per-analyzer breakdown so you can see exactly how much each type of analysis (code quality, docstring generation, PR review) costs and how long it takes. This gives you full visibility into your AI usage and helps identify opportunities to optimize spending.
+
+### 13. Robust LLM Response Handling
+
+Gracefully handles malformed or incomplete responses from LLM providers. When an LLM returns imperfect output — such as responses wrapped in markdown code fences, broken JSON, or truncated text — DREP applies a series of increasingly aggressive recovery strategies to extract valid results. This ensures reliable operation even with less capable or occasionally unreliable LLM providers.
+
+---
+
+## Supported Platforms
+
+### Gitea
+
+Full support for Gitea instances, including creating issues, reading and reviewing pull requests with inline comments, and fetching file content. Works with both cloud-hosted and self-hosted Gitea installations.
+
+---
+
+## LLM Providers
+
+### OpenAI-Compatible (Local LLMs)
+
+Works with any OpenAI-compatible endpoint, including LM Studio, Ollama, and other local LLM servers. This allows you to run DREP entirely on your own hardware with no data leaving your network.
+
+### AWS Bedrock
+
+Connects to AWS Bedrock for access to models like Claude through your existing AWS credentials. Ideal for teams that already use AWS and want to keep everything within their cloud environment.
+
+### Anthropic
+
+Direct Anthropic API support is planned for a future release.
+
+---
+
+## Database
+
+DREP uses a database to track scan history and prevent duplicate issue creation. SQLite works out of the box with zero setup. For team or production deployments, PostgreSQL and MySQL are also supported.