diffguard 0.1.3__tar.gz

diffguard-0.1.3/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What Changed
+
+## Test Evidence
+
+## Schema Impact
+- [ ] No schema changes
+- [ ] Schema changed — migration notes below:
+
+## Performance Impact
+- [ ] No performance impact
+- [ ] Benchmark results:

diffguard-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy src/
+      - run: uv run pytest

diffguard-0.1.3/.github/workflows/deploy-docs.yml

@@ -0,0 +1,21 @@
+name: Deploy Docs
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

diffguard-0.1.3/.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Deploy docs
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**', 'mkdocs.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

diffguard-0.1.3/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,102 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Validate version against tag
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match pyproject.toml version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Version validated: $PKG_VERSION"
+
+      - name: Install dev dependencies & run tests
+        run: |
+          pip install -e .
+          pip install pytest pytest-cov pytest-benchmark ruff mypy
+          pytest
+        timeout-minutes: 5
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build  # TestPyPI is optional; don't block production publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  smoke-test:
+    name: Smoke Test
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install and verify
+        run: |
+          sleep 30  # allow PyPI index to propagate
+          pip install diffguard
+          diffguard --version

diffguard-0.1.3/.gitignore

@@ -0,0 +1,11 @@
+.coverage
+*.pyc
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.venv/
+site/
+STRESS_TEST_RESULTS.md

diffguard-0.1.3/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: diffguard-review
+  name: DiffGuard Review
+  description: Run diffguard review to detect breaking API changes
+  entry: diffguard review HEAD
+  language: python
+  pass_filenames: false
+  stages: [pre-push]
+  always_run: true

diffguard-0.1.3/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md — DiffGuard v2
+
+## Module Boundaries
+- `engine/parser.py` — tree-sitter parsing ONLY. No git logic, no matching.
+- `engine/matcher.py` — symbol matching ONLY. Takes old+new symbol lists, returns matches.
+- `engine/classifier.py` — change classification ONLY. Takes matches, returns classified changes.
+- `engine/signatures.py` — signature comparison ONLY. Takes old+new signatures, detects breaking.
+- `engine/summarizer.py` — summary generation ONLY. Takes classified changes, produces tiered text.
+- `schema.py` — Pydantic models. THE contract. Changes require migration notes in PR.
+- `git.py` — all git subprocess calls live here. Nothing else touches git.
+- `languages/{lang}/` — per-language tree-sitter config + queries.scm.
+
+## Conventions
+- Type hints everywhere. `mypy --strict` must pass.
+- Tests mirror source: `test_parser.py` tests `parser.py`, etc.
+- Fixtures: synthetic for unit tests, real-world for integration tests. Both live in `tests/fixtures/`.
+- All JSON output must validate against schema.py models.
+- No print statements — use structured logging (logging module).
+- Functions over classes unless state is genuinely needed.
+
+## What NOT to Do
+- Don't import across engine modules horizontally (parser doesn't import matcher).
+- Don't shell out to git anywhere except `git.py`.
+- Don't add dependencies without justification in PR description.
+- Don't modify schema.py without migration notes.
+- Don't write tests that depend on network or external repos — use fixtures.

diffguard-0.1.3/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-02-15
+
+### Fixed
+- Updated package description to match current positioning
+- Changed license field format for hatchling compatibility
+
+### Added
+- GitHub Action for CI integration
+
+## [0.1.1] - 2026-02-11
+
+### Fixed
+- Fixed fabricated README example
+
+### Added
+- Added content verification to release process
+
+## [0.1.0] - 2026-02-11
+
+### Added
+- Initial PyPI release
+- `review` and `summarize` commands
+- Python, TypeScript, and Go support via tree-sitter

diffguard-0.1.3/LICENSE

@@ -0,0 +1,53 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             ostehost
+Licensed Work:        DiffGuard v0.1.1 (and all subsequent versions)
+Additional Use Grant: You may use the Licensed Work for any purpose other
+                      than offering the functionality of the Licensed Work
+                      to third parties as a managed or hosted service.
+Change Date:          2029-02-11
+Change License:       Apache License 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

diffguard-0.1.3/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: diffguard
+Version: 0.1.3
+Summary: Catches the structural breaks that pass code review
+Project-URL: Homepage, https://github.com/ostehost/diffguard
+Project-URL: Repository, https://github.com/ostehost/diffguard
+Project-URL: Issues, https://github.com/ostehost/diffguard/issues
+Author: ostehost
+License: BSL-1.1
+License-File: LICENSE
+Keywords: agents,ai,code-intelligence,code-review,git,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tree-sitter-go
+Requires-Dist: tree-sitter-javascript
+Requires-Dist: tree-sitter-python
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.24
+Description-Content-Type: text/markdown
+
+[![PyPI](https://img.shields.io/pypi/v/diffguard)](https://pypi.org/project/diffguard/)
+[![License](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/diffguard/)
+
+# DiffGuard
+
+**Catches the structural breaks that pass code review.**
+
+## A real bug, in one line
+
+This diff shipped in Flask ([PR #5898](https://github.com/pallets/flask/pull/5898)):
+
+```diff
+-def redirect(location, code=302, ...):
++def redirect(location, code=303, ...):
+```
+
+One line. Looks fine. A reviewer approves it.
+
+**The real impact:** 7 endpoints silently change HTTP behavior. POST-to-POST redirects become POST-to-GET. No errors. No warnings. Just broken APIs in production.
+
+**DiffGuard catches it:**
+
+```
+$ diffguard review eca5fd1d~1..eca5fd1d
+
+⚠ DiffGuard: 2 changes need review
+
+  DEFAULT VALUE CHANGED: redirect(location, code=302) → redirect(location, code=303)
+  src/flask/helpers.py:241 — 7 callers rely on the default
+
+  DEFAULT VALUE CHANGED: App.redirect(self, location, code=302) → App.redirect(self, location, code=303)
+  src/flask/sansio/app.py:935 — 7 callers rely on the default
+```
+
+Tree-sitter AST analysis. No LLM. No network calls. Runs in seconds.
+
+## What it catches
+
+Function signature changes, removed/renamed symbols, default value changes — and shows you every caller affected.
+
+## What it doesn't catch
+
+Logic bugs, behavioral changes beyond signatures, performance issues, security vulnerabilities. DiffGuard detects **structural breaks**, not all bugs.
+
+When there's nothing structural to report, it stays silent (exit code 0, no output).
+
+## Quick Start
+
+```bash
+pip install diffguard
+diffguard review main..feature
+```
+
+Exit codes: `0` = nothing noteworthy, `1` = findings, `2` = error.
+
+## How It Works
+
+1. **Parses the diff** using tree-sitter AST analysis (not regex)
+2. **Extracts symbols** — functions, classes, signatures
+3. **Detects high-signal changes** — signature changes, removed symbols, default value changes
+4. **Scans for callers** — finds every file that references changed symbols
+5. **Outputs actionable context** — or stays silent if nothing matters
+
+## Agent Integration
+
+Works with **Claude Code**, **Cursor**, **GitHub Actions**, or any agent that can run a CLI command.
+
+Add one line to your agent config — DiffGuard is silent when nothing matters.
+
+See the full [Agent Integration Guide](docs/agent-integration.md) for hooks, CI patterns, and snippets for [Claude Code](docs/claude-md-snippet.md) and [Cursor](docs/cursor-rule-snippet.md).
+
+## GitHub Action
+
+```yaml
+# .github/workflows/diffguard.yml
+name: DiffGuard PR Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  diffguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ostehost/diffguard@main
+```
+
+## Languages
+
+- **Python** (most mature — extensive real-world validation)
+- TypeScript / JavaScript
+- Go
+- More planned (Rust, Java, C#)
+
+## Philosophy
+
+1. **Silence is a feature.** No findings? No output. Most diffs don't need structural analysis.
+2. **Local-first.** Your code never leaves your machine. No SaaS, no API keys, no accounts.
+3. **Agent-native.** CLI + JSON output. `pip install` and go.
+4. **Precision over recall.** We'd rather miss a minor issue than cry wolf on every PR.
+
+## License
+
+BSL 1.1 — see [LICENSE](LICENSE) for details.

diffguard-0.1.3/README.md

@@ -0,0 +1,110 @@
+[![PyPI](https://img.shields.io/pypi/v/diffguard)](https://pypi.org/project/diffguard/)
+[![License](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/diffguard/)
+
+# DiffGuard
+
+**Catches the structural breaks that pass code review.**
+
+## A real bug, in one line
+
+This diff shipped in Flask ([PR #5898](https://github.com/pallets/flask/pull/5898)):
+
+```diff
+-def redirect(location, code=302, ...):
++def redirect(location, code=303, ...):
+```
+
+One line. Looks fine. A reviewer approves it.
+
+**The real impact:** 7 endpoints silently change HTTP behavior. POST-to-POST redirects become POST-to-GET. No errors. No warnings. Just broken APIs in production.
+
+**DiffGuard catches it:**
+
+```
+$ diffguard review eca5fd1d~1..eca5fd1d
+
+⚠ DiffGuard: 2 changes need review
+
+  DEFAULT VALUE CHANGED: redirect(location, code=302) → redirect(location, code=303)
+  src/flask/helpers.py:241 — 7 callers rely on the default
+
+  DEFAULT VALUE CHANGED: App.redirect(self, location, code=302) → App.redirect(self, location, code=303)
+  src/flask/sansio/app.py:935 — 7 callers rely on the default
+```
+
+Tree-sitter AST analysis. No LLM. No network calls. Runs in seconds.
+
+## What it catches
+
+Function signature changes, removed/renamed symbols, default value changes — and shows you every caller affected.
+
+## What it doesn't catch
+
+Logic bugs, behavioral changes beyond signatures, performance issues, security vulnerabilities. DiffGuard detects **structural breaks**, not all bugs.
+
+When there's nothing structural to report, it stays silent (exit code 0, no output).
+
+## Quick Start
+
+```bash
+pip install diffguard
+diffguard review main..feature
+```
+
+Exit codes: `0` = nothing noteworthy, `1` = findings, `2` = error.
+
+## How It Works
+
+1. **Parses the diff** using tree-sitter AST analysis (not regex)
+2. **Extracts symbols** — functions, classes, signatures
+3. **Detects high-signal changes** — signature changes, removed symbols, default value changes
+4. **Scans for callers** — finds every file that references changed symbols
+5. **Outputs actionable context** — or stays silent if nothing matters
+
+## Agent Integration
+
+Works with **Claude Code**, **Cursor**, **GitHub Actions**, or any agent that can run a CLI command.
+
+Add one line to your agent config — DiffGuard is silent when nothing matters.
+
+See the full [Agent Integration Guide](docs/agent-integration.md) for hooks, CI patterns, and snippets for [Claude Code](docs/claude-md-snippet.md) and [Cursor](docs/cursor-rule-snippet.md).
+
+## GitHub Action
+
+```yaml
+# .github/workflows/diffguard.yml
+name: DiffGuard PR Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  diffguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ostehost/diffguard@main
+```
+
+## Languages
+
+- **Python** (most mature — extensive real-world validation)
+- TypeScript / JavaScript
+- Go
+- More planned (Rust, Java, C#)
+
+## Philosophy
+
+1. **Silence is a feature.** No findings? No output. Most diffs don't need structural analysis.
+2. **Local-first.** Your code never leaves your machine. No SaaS, no API keys, no accounts.
+3. **Agent-native.** CLI + JSON output. `pip install` and go.
+4. **Precision over recall.** We'd rather miss a minor issue than cry wolf on every PR.
+
+## License
+
+BSL 1.1 — see [LICENSE](LICENSE) for details.

diffguard-0.1.3/RELEASE.md

@@ -0,0 +1,67 @@
+# Release Process
+
+## Roles
+
+**Release owner:** Oste (manager). Tags, pushes, monitors CI, verifies install.
+When a release agent exists, it takes over this role.
+
+## Release Blockers
+
+A release MUST NOT ship if any of these are true:
+- Tests fail (`pytest`)
+- Linting fails (`ruff check src/ tests/`)
+- Version not bumped in `pyproject.toml`
+- README.md is stale or misaligned with current positioning
+
+## Pre-release Checklist
+
+- [ ] All tests pass (`pytest`)
+- [ ] Linting passes (`ruff check src/ tests/`)
+- [ ] Version bumped in `pyproject.toml`
+- [ ] README.md examples verified against real tool output (run every example command, diff against what's written)
+- [ ] Docs examples verified against real tool output
+- [ ] CHANGELOG updated (if maintained)
+
+## Cutting a Release
+
+```bash
+# 1. Bump version in pyproject.toml
+#    e.g. version = "0.2.0"
+
+# 2. Commit the version bump
+git commit -am "release: v0.2.0"
+
+# 3. Create the tag
+git tag v0.2.0
+
+# 4. Push commit and tag
+git push origin main --tags
+
+# 5. GitHub Actions handles:
+#    build & test → TestPyPI → PyPI → smoke test
+
+# 6. Verify the release
+pip install diffguard && diffguard --version
+```
+
+The workflow uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) — no API tokens needed.
+
+## Post-release Checklist
+
+- [ ] Verify package on [pypi.org/project/diffguard](https://pypi.org/project/diffguard/)
+- [ ] Test install in a clean venv:
+  ```bash
+  python -m venv /tmp/test-diffguard && source /tmp/test-diffguard/bin/activate
+  pip install diffguard
+  diffguard --version
+  deactivate && rm -rf /tmp/test-diffguard
+  ```
+- [ ] Create a [GitHub Release](https://github.com/ostehost/diffguard/releases/new) from the tag (optional)
+
+## Rollback
+
+PyPI does not allow re-uploading the same version. If a broken package ships:
+
+1. **Yank the version:** `pip install diffguard` won't grab yanked versions by default
+2. **Bump to patch version** (e.g., v0.1.0 → v0.1.1) with the fix
+3. **Cut a patch release** following the same process above