mastiff 0.1.0__tar.gz

mastiff-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run mypy src/

mastiff-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run mypy src/
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mastiff-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.env
+.mastiff-baseline.json
+.mastiff/
+.claude/

mastiff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mastiff Contributors
+
+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.

mastiff-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.4
+Name: mastiff
+Version: 0.1.0
+Summary: AI code review agent that detects dangerous patterns in LLM-generated code
+Project-URL: Homepage, https://github.com/yuuichieguchi/mastiff
+Project-URL: Repository, https://github.com/yuuichieguchi/mastiff
+Project-URL: Issues, https://github.com/yuuichieguchi/mastiff/issues
+Author: Mastiff Contributors
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anthropic<1.0,>=0.42
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<14.0,>=13.0
+Requires-Dist: tenacity<10.0,>=9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: lsp
+Requires-Dist: lsprotocol>=2024.0; extra == 'lsp'
+Requires-Dist: pygls<3.0,>=2.0; extra == 'lsp'
+Provides-Extra: tree-sitter
+Requires-Dist: tree-sitter-typescript<0.24,>=0.23; extra == 'tree-sitter'
+Requires-Dist: tree-sitter<0.24,>=0.23; extra == 'tree-sitter'
+Description-Content-Type: text/markdown
+
+# Mastiff
+
+[![PyPI version](https://img.shields.io/pypi/v/mastiff)](https://pypi.org/project/mastiff/)
+[![Python 3.12+](https://img.shields.io/pypi/pyversions/mastiff)](https://pypi.org/project/mastiff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+AI code review agent that detects dangerous patterns in LLM-generated code.
+
+Mastiff analyzes git diffs using the Claude API to detect production-risk patterns across four categories — blocking/deadlocks, race conditions, performance degradation, and resource leaks — scoring each finding by severity and confidence.
+
+## Why Mastiff?
+
+LLM-generated code often looks correct at first glance but can contain subtle patterns that only manifest in production:
+
+- **Event loop blocking** — synchronous calls in async contexts that freeze the application
+- **Race conditions** — shared mutable state accessed without proper synchronization
+- **O(n²) algorithms** — nested loops and unbounded queries that degrade with scale
+- **Resource leaks** — file handles, connections, and sockets opened but never closed
+
+Traditional linters catch syntax and style issues. Mastiff focuses specifically on the patterns LLMs tend to introduce — not to replace linters, but to complement them with production-risk awareness.
+
+## What It Detects
+
+| Category | Description | Examples |
+|---|---|---|
+| Blocking/Deadlock | Synchronous blocking calls in async contexts, potential deadlocks | `time.sleep()` in async, synchronous I/O in event loop, inconsistent lock ordering |
+| Race Condition | Shared mutable state without synchronization, TOCTOU | Global variable from multiple threads without locks, non-atomic read-modify-write |
+| Degradation | O(n²) algorithms, excessive allocations, unbounded growth | Nested loops, loading entire DB table into memory, missing pagination |
+| Resource Leak | Resources opened but not properly closed | `open()` without context manager, DB connection not returned to pool |
+
+## Quick Start
+
+```bash
+pip install mastiff
+export ANTHROPIC_API_KEY="sk-ant-..."
+mastiff review --staged
+```
+
+Alternative installation methods:
+
+```bash
+pipx install mastiff
+# or
+uv tool install mastiff
+```
+
+Get your API key at https://console.anthropic.com/
+
+## Output Example
+
+**Terminal (default):**
+
+```
+                    Review Findings
+┏━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ File         ┃ Line ┃ Severity ┃ Category      ┃ Title                      ┃ Confidence ┃
+┡━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ api/users.py │ 42   │ critical │ blocking      │ time.sleep in async handler │ 92%        │
+│ db/pool.py   │ 15   │ warning  │ resource_leak │ Connection not returned     │ 78%        │
+└──────────────┴──────┴──────────┴───────────────┴────────────────────────────┴────────────┘
+```
+
+**JSON (`--format json`):**
+
+```json
+{
+  "findings": [
+    {
+      "rule_id": "blocking-sync-sleep",
+      "category": "blocking",
+      "severity": "critical",
+      "file_path": "api/users.py",
+      "line_start": 42,
+      "title": "time.sleep in async handler",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Review staged changes
+mastiff review --staged
+
+# Review a commit range
+mastiff review HEAD~3..HEAD
+
+# Choose review depth
+mastiff review --staged --profile quick
+
+# JSON output
+mastiff review --staged --format json
+
+# Strict mode: exit 1 on any finding
+mastiff review --staged --strict
+```
+
+**Review profiles:**
+
+| Profile | Diff budget | Context budget | Use case |
+|---|---|---|---|
+| quick | 5,000 tokens | 3,000 tokens | Pre-commit, editor saves |
+| standard | 20,000 tokens | 15,000 tokens | PR review (default) |
+| deep | 50,000 tokens | 30,000 tokens | Release audits |
+
+### Pre-commit Hook
+
+```bash
+# Install the pre-commit hook
+mastiff install
+
+# Commits are automatically reviewed
+git commit -m "feat: add user endpoint"
+# → mastiff reviews staged changes
+```
+
+In CI environments (`CI=true`), the hook runs in strict mode and blocks on any finding. When a baseline exists, only new findings are reported.
+
+### LSP Server (Experimental)
+
+```bash
+mastiff server
+```
+
+Provides real-time diagnostics on file save (quick profile). Configure your editor's LSP client to connect to mastiff.
+
+### With Claude Code
+
+Mastiff is designed to review LLM-generated code. When using [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as your development agent, Mastiff acts as an automated safety net that catches production-risk patterns before they reach your codebase.
+
+**Pre-commit hook (recommended):**
+
+Install the hook once and every commit Claude Code creates is automatically reviewed:
+
+```bash
+mastiff install
+```
+
+Claude Code commits through git, so the pre-commit hook runs transparently on every commit. Critical findings block the commit, giving you a chance to review before the code lands.
+
+**CI integration:**
+
+Add Mastiff to your CI pipeline to review every pull request that Claude Code opens:
+
+```yaml
+# .github/workflows/ci.yml
+- run: pip install mastiff
+- run: mastiff review origin/main..HEAD --strict --format json
+```
+
+**Manual review after a session:**
+
+After Claude Code completes a task in a worktree, review all changes before merging:
+
+```bash
+mastiff review main..HEAD --profile deep
+```
+
+## Baseline
+
+```bash
+# Record current findings as baseline
+mastiff baseline
+
+# Only new findings are reported from now on
+
+# Regenerate after refactoring
+mastiff baseline --rebase
+```
+
+The baseline uses fingerprint-based stable IDs that are independent of line numbers, so minor code shifts don't invalidate existing suppressions.
+
+## Configuration
+
+Generate a config file:
+
+```bash
+mastiff init
+```
+
+This creates `mastiff.yaml` with documented defaults. Key settings:
+
+```yaml
+api:
+  model: claude-opus-4-20250514      # Claude model to use
+
+detection:
+  min_confidence: 0.6           # Minimum confidence to report
+
+security:
+  never_send_paths:             # Files never sent to the API
+    - .env
+    - "*.pem"
+    - "*.key"
+
+cost:
+  max_cost_usd_per_run: 1.00   # Per-run cost limit
+```
+
+All config models use Pydantic `extra="forbid"`, so typos in config keys are caught immediately.
+
+## Security & Privacy
+
+Mastiff sends code to the Claude API for analysis. Here is what it does to minimize exposure:
+
+- **What is sent**: Only the diff is sent — never complete source files. Import tracing may include small fragments from related files, bounded by a token budget.
+- **Automatic redaction**: Built-in regex patterns detect API keys, tokens, passwords, and private key headers. Detected values are replaced with `[REDACTED]` before sending. The Redactor also exposes Shannon entropy analysis for identifying high-entropy strings.
+- **File exclusion**: The `never_send_paths` setting excludes sensitive file patterns (`.env`, `*.pem`, `*.key`, etc.) by default. These files are filtered out before any API call.
+- **Output sanitization**: ANSI escape sequences and control characters are stripped from all output to prevent terminal injection.
+- **Prompt injection defense**: User-supplied data (diffs, context) is wrapped in delimiter tags (`<diff>`, `<context>`) and the system prompt establishes reviewer-only behavior.
+
+This is a best-effort approach to minimize sensitive data exposure. It does not guarantee that no secrets are sent. Review your `never_send_paths` configuration and consider the sensitivity of your codebase before use.
+
+## Cost Control
+
+Approximate cost per review (depends on diff size and Claude API pricing):
+
+| Profile | Estimated cost |
+|---|---|
+| quick | ~$0.01–0.05 |
+| standard | ~$0.05–0.30 |
+| deep | ~$0.10–0.50 |
+
+The `cost.max_cost_usd_per_run` setting (default: $1.00) enforces a per-run budget.
+
+## Requirements
+
+- Python >= 3.12
+- [Anthropic API key](https://console.anthropic.com/)
+- Git
+
+**Optional extras:**
+
+```bash
+pip install "mastiff[tree-sitter]"  # Enhanced import tracing
+pip install "mastiff[lsp]"          # LSP server support
+```
+
+## Development
+
+```bash
+git clone <repo> && cd mastiff
+uv sync --all-extras
+pytest                 # 277 tests
+ruff check .           # lint
+mypy src/              # type check
+```
+
+**Package structure:**
+
+```
+src/mastiff/
+├── _internal/       # Git and subprocess utilities
+├── analysis/        # Categories, prompt building, LLM client
+├── cli/             # Commands and terminal output
+├── config/          # Schema, loader, defaults
+├── context/         # Language parsers, import tracer, resolver
+├── core/            # Engine, models, fingerprinting, severity
+├── diff/            # Diff parsing, filtering, collection
+├── integrations/    # Pre-commit hook, LSP server
+├── observability/   # Logging and metrics
+└── security/        # Secret patterns, redactor, sanitizer
+```
+
+## License
+
+[MIT](LICENSE)