semantic-diff 0.1.0__tar.gz → 0.3.0__tar.gz

semantic_diff-0.3.0/LICENSE

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

semantic_diff-0.3.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: semantic-diff
+Version: 0.3.0
+Summary: AI-powered semantic analysis of git commits
+Author-email: Kenaz GmbH <hello@kenaz.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tkenaz/semantic_diff
+Project-URL: Repository, https://github.com/tkenaz/semantic_diff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: gitpython>=3.1.58
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.40.0; extra == "openai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: openai>=1.40.0; extra == "dev"
+Requires-Dist: mutmut>=3.0.0; extra == "dev"
+Requires-Dist: pyyaml; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file
+
+# semantic-diff
+
+[![PyPI version](https://badge.fury.io/py/semantic-diff.svg)](https://pypi.org/project/semantic-diff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+AI-powered semantic analysis of git commits. Goes beyond `git diff` to show **intent**, **impact**, **risk**, and **review questions**.
+
+## What it does
+
+Regular `git diff` shows *what* changed. `semantic-diff` shows:
+
+| | git diff | semantic-diff |
+|---|---|---|
+| **What** | Lines added/removed | Same |
+| **Why** | - | Intent behind the change |
+| **Risk** | - | What could break, edge cases |
+| **Impact** | - | Direct and indirect effects |
+| **Review** | - | Questions to ask the author |
+
+## Installation
+
+```bash
+pip install semantic-diff
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Analyze a commit
+semantic-diff HEAD
+
+# Enable automatic analysis before every push
+semantic-diff init
+```
+
+That's it! Now every `git push` will automatically analyze your commits and save reports.
+
+## How It Works
+
+### Manual Analysis
+
+```bash
+# Analyze HEAD commit
+semantic-diff
+
+# Analyze specific commit
+semantic-diff abc123
+
+# Save report to file
+semantic-diff HEAD --save
+
+# Output as JSON
+semantic-diff HEAD --json
+```
+
+### Automatic Analysis (Pre-Push Hook)
+
+```bash
+# Install the hook (once per project)
+semantic-diff init
+
+# Now every push triggers analysis automatically
+git push  # → runs semantic-diff, saves report, then pushes
+```
+
+### Reports
+
+Reports are saved to `semantic_diff_reports/` in your project root:
+
+```
+my-project/
+├── semantic_diff_reports/
+│   ├── abc12345_20240115_143022.md
+│   ├── def67890_20240115_152341.md
+│   └── ...
+├── src/
+└── ...
+```
+
+Each report includes:
+- Commit metadata
+- Intent analysis with confidence score
+- Impact map (direct and indirect effects)
+- Risk assessment with mitigations
+- Review questions prioritized by importance
+
+### GitHub Action
+
+Add to your workflow to analyze PRs automatically:
+
+```yaml
+# .github/workflows/semantic-diff.yml
+name: Semantic Diff
+
+on: [pull_request]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: tkenaz/semantic_diff@v0.3.0
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          comment_on_pr: true
+          fail_on_risk: high  # optional: block merge on high risk
+```
+
+## Example Output
+
+### Analysis Overview
+
+![Example Output](assets/example-output.png)
+
+*Intent analysis with 98% confidence, risk assessment, and review questions*
+
+### What It Finds
+
+![Risk Assessment](assets/risk-assessment.png)
+
+*Real example: semantic-diff analyzing itself found XSS vulnerabilities, CI issues, and security misconfigurations*
+
+## Configuration
+
+Create a `.env` file in your project or set environment variables:
+
+```bash
+# Required
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Optional
+SEMANTIC_DIFF_MODEL=claude-sonnet-5-5  # or claude-opus-5-5
+```
+
+### OpenAI-compatible gateways
+
+Any gateway that speaks the OpenAI Chat Completions protocol (LiteLLM, vLLM,
+corporate LLM hubs, OpenAI itself) works through the `openai` provider:
+
+```bash
+pip install 'semantic-diff[openai]'
+
+SEMANTIC_DIFF_PROVIDER=openai
+SEMANTIC_DIFF_BASE_URL=https://your-gateway.example/v1
+SEMANTIC_DIFF_API_KEY=...
+SEMANTIC_DIFF_MODEL=claude-sonnet-4.6   # required: model ids differ per gateway
+```
+
+Retries (rate limits honour `Retry-After`, timeouts, 5xx) are handled once for
+all providers: `SEMANTIC_DIFF_MAX_RETRIES` (attempts, default 3) and
+`SEMANTIC_DIFF_MAX_WAIT` (seconds, default 30).
+
+### Diff budget
+
+Large changes are not cut blindly. Diffs are packed into a token budget
+(`--max-diff-tokens` / `SEMANTIC_DIFF_MAX_DIFF_TOKENS`, default 60,000):
+code first, then migrations, CI/infra, tests, docs. A file that does not fit
+whole is trimmed at hunk boundaries, never mid-line. Lock files, generated
+output and binaries are listed but never shown. The model is told which files
+it did not see, and every report states the coverage, e.g.
+`Diff coverage: 87% of changed lines` plus the trimmed/not-shown files.
+
+### Agentic review
+
+`semantic-diff review` goes further than `mr`: instead of one call over the
+diff, an agent reads around the change - whole functions, callers, the file
+before the change, history - with read-only tools, and submits findings tied
+to lines.
+
+```bash
+semantic-diff review --base origin/dev --save
+semantic-diff review --gitlab-env --json   # inside a GitLab MR pipeline
+```
+
+- Tools read git objects at the merge request's head and base, never the
+  working tree: uncommitted files are invisible to the model.
+- Every review is bounded: `--max-turns` (`SEMANTIC_DIFF_MAX_TURNS`, default
+  25), `--max-input-tokens` (`SEMANTIC_DIFF_MAX_INPUT_TOKENS`, default
+  1,000,000, cached tokens included) and the diff shown up front
+  (`--max-diff-tokens` / `SEMANTIC_DIFF_REVIEW_DIFF_TOKENS`, default 30,000).
+  When a limit is reached the model gets one last turn to submit what it has,
+  and the report says which limit cut the review short.
+- Each finding is checked in code: does the cited line exist (after the
+  change, or only before it), and did the model actually see the file. The
+  report flags findings that fail either check.
+- Needs a provider with tool calling: `SEMANTIC_DIFF_PROVIDER=openai`
+  (any OpenAI-compatible gateway). Prompt caching is used where the gateway
+  supports it, so each turn re-reads the conversation from cache.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `semantic-diff` | Analyze HEAD commit |
+| `semantic-diff <hash>` | Analyze specific commit |
+| `semantic-diff --save` | Save report to `semantic_diff_reports/` |
+| `semantic-diff --json` | Output as JSON |
+| `semantic-diff mr --base origin/main` | Analyze a whole merge request (merge-base..HEAD) |
+| `semantic-diff mr --gitlab-env` | Same, inside a GitLab MR pipeline (reads `CI_MERGE_REQUEST_*`) |
+| `--max-diff-tokens N` | Diff budget for the prompt (default 60000) |
+| `--max-output-tokens N` | Room for the model's answer (default 32000; env `SEMANTIC_DIFF_MAX_OUTPUT_TOKENS`) |
+| `semantic-diff review --base origin/main` | Agentic review of a merge request (see above) |
+| `semantic-diff init` | Install pre-push hook |
+| `semantic-diff uninstall` | Remove pre-push hook |
+
+## Development
+
+```bash
+git clone https://github.com/tkenaz/semantic_diff.git
+cd semantic_diff
+pip install -e ".[dev]"
+pytest
+```
+
+## Support
+
+- **Bug reports & features**: [GitHub Issues](https://github.com/tkenaz/semantic_diff/issues)
+- **Custom integrations or enterprise**: [hello@kenaz.ai](mailto:hello@kenaz.ai)
+
+## License
+
+MIT — [Kenaz GmbH](https://kenaz.ai)
+
+---
+
+*Built with 🖤 by [Kenaz GmbH](https://kenaz.ai) — AI tools for developers*

semantic_diff-0.3.0/README.md

@@ -0,0 +1,232 @@
+# semantic-diff
+
+[![PyPI version](https://badge.fury.io/py/semantic-diff.svg)](https://pypi.org/project/semantic-diff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+AI-powered semantic analysis of git commits. Goes beyond `git diff` to show **intent**, **impact**, **risk**, and **review questions**.
+
+## What it does
+
+Regular `git diff` shows *what* changed. `semantic-diff` shows:
+
+| | git diff | semantic-diff |
+|---|---|---|
+| **What** | Lines added/removed | Same |
+| **Why** | - | Intent behind the change |
+| **Risk** | - | What could break, edge cases |
+| **Impact** | - | Direct and indirect effects |
+| **Review** | - | Questions to ask the author |
+
+## Installation
+
+```bash
+pip install semantic-diff
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Analyze a commit
+semantic-diff HEAD
+
+# Enable automatic analysis before every push
+semantic-diff init
+```
+
+That's it! Now every `git push` will automatically analyze your commits and save reports.
+
+## How It Works
+
+### Manual Analysis
+
+```bash
+# Analyze HEAD commit
+semantic-diff
+
+# Analyze specific commit
+semantic-diff abc123
+
+# Save report to file
+semantic-diff HEAD --save
+
+# Output as JSON
+semantic-diff HEAD --json
+```
+
+### Automatic Analysis (Pre-Push Hook)
+
+```bash
+# Install the hook (once per project)
+semantic-diff init
+
+# Now every push triggers analysis automatically
+git push  # → runs semantic-diff, saves report, then pushes
+```
+
+### Reports
+
+Reports are saved to `semantic_diff_reports/` in your project root:
+
+```
+my-project/
+├── semantic_diff_reports/
+│   ├── abc12345_20240115_143022.md
+│   ├── def67890_20240115_152341.md
+│   └── ...
+├── src/
+└── ...
+```
+
+Each report includes:
+- Commit metadata
+- Intent analysis with confidence score
+- Impact map (direct and indirect effects)
+- Risk assessment with mitigations
+- Review questions prioritized by importance
+
+### GitHub Action
+
+Add to your workflow to analyze PRs automatically:
+
+```yaml
+# .github/workflows/semantic-diff.yml
+name: Semantic Diff
+
+on: [pull_request]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: tkenaz/semantic_diff@v0.3.0
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          comment_on_pr: true
+          fail_on_risk: high  # optional: block merge on high risk
+```
+
+## Example Output
+
+### Analysis Overview
+
+![Example Output](assets/example-output.png)
+
+*Intent analysis with 98% confidence, risk assessment, and review questions*
+
+### What It Finds
+
+![Risk Assessment](assets/risk-assessment.png)
+
+*Real example: semantic-diff analyzing itself found XSS vulnerabilities, CI issues, and security misconfigurations*
+
+## Configuration
+
+Create a `.env` file in your project or set environment variables:
+
+```bash
+# Required
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Optional
+SEMANTIC_DIFF_MODEL=claude-sonnet-5-5  # or claude-opus-5-5
+```
+
+### OpenAI-compatible gateways
+
+Any gateway that speaks the OpenAI Chat Completions protocol (LiteLLM, vLLM,
+corporate LLM hubs, OpenAI itself) works through the `openai` provider:
+
+```bash
+pip install 'semantic-diff[openai]'
+
+SEMANTIC_DIFF_PROVIDER=openai
+SEMANTIC_DIFF_BASE_URL=https://your-gateway.example/v1
+SEMANTIC_DIFF_API_KEY=...
+SEMANTIC_DIFF_MODEL=claude-sonnet-4.6   # required: model ids differ per gateway
+```
+
+Retries (rate limits honour `Retry-After`, timeouts, 5xx) are handled once for
+all providers: `SEMANTIC_DIFF_MAX_RETRIES` (attempts, default 3) and
+`SEMANTIC_DIFF_MAX_WAIT` (seconds, default 30).
+
+### Diff budget
+
+Large changes are not cut blindly. Diffs are packed into a token budget
+(`--max-diff-tokens` / `SEMANTIC_DIFF_MAX_DIFF_TOKENS`, default 60,000):
+code first, then migrations, CI/infra, tests, docs. A file that does not fit
+whole is trimmed at hunk boundaries, never mid-line. Lock files, generated
+output and binaries are listed but never shown. The model is told which files
+it did not see, and every report states the coverage, e.g.
+`Diff coverage: 87% of changed lines` plus the trimmed/not-shown files.
+
+### Agentic review
+
+`semantic-diff review` goes further than `mr`: instead of one call over the
+diff, an agent reads around the change - whole functions, callers, the file
+before the change, history - with read-only tools, and submits findings tied
+to lines.
+
+```bash
+semantic-diff review --base origin/dev --save
+semantic-diff review --gitlab-env --json   # inside a GitLab MR pipeline
+```
+
+- Tools read git objects at the merge request's head and base, never the
+  working tree: uncommitted files are invisible to the model.
+- Every review is bounded: `--max-turns` (`SEMANTIC_DIFF_MAX_TURNS`, default
+  25), `--max-input-tokens` (`SEMANTIC_DIFF_MAX_INPUT_TOKENS`, default
+  1,000,000, cached tokens included) and the diff shown up front
+  (`--max-diff-tokens` / `SEMANTIC_DIFF_REVIEW_DIFF_TOKENS`, default 30,000).
+  When a limit is reached the model gets one last turn to submit what it has,
+  and the report says which limit cut the review short.
+- Each finding is checked in code: does the cited line exist (after the
+  change, or only before it), and did the model actually see the file. The
+  report flags findings that fail either check.
+- Needs a provider with tool calling: `SEMANTIC_DIFF_PROVIDER=openai`
+  (any OpenAI-compatible gateway). Prompt caching is used where the gateway
+  supports it, so each turn re-reads the conversation from cache.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `semantic-diff` | Analyze HEAD commit |
+| `semantic-diff <hash>` | Analyze specific commit |
+| `semantic-diff --save` | Save report to `semantic_diff_reports/` |
+| `semantic-diff --json` | Output as JSON |
+| `semantic-diff mr --base origin/main` | Analyze a whole merge request (merge-base..HEAD) |
+| `semantic-diff mr --gitlab-env` | Same, inside a GitLab MR pipeline (reads `CI_MERGE_REQUEST_*`) |
+| `--max-diff-tokens N` | Diff budget for the prompt (default 60000) |
+| `--max-output-tokens N` | Room for the model's answer (default 32000; env `SEMANTIC_DIFF_MAX_OUTPUT_TOKENS`) |
+| `semantic-diff review --base origin/main` | Agentic review of a merge request (see above) |
+| `semantic-diff init` | Install pre-push hook |
+| `semantic-diff uninstall` | Remove pre-push hook |
+
+## Development
+
+```bash
+git clone https://github.com/tkenaz/semantic_diff.git
+cd semantic_diff
+pip install -e ".[dev]"
+pytest
+```
+
+## Support
+
+- **Bug reports & features**: [GitHub Issues](https://github.com/tkenaz/semantic_diff/issues)
+- **Custom integrations or enterprise**: [hello@kenaz.ai](mailto:hello@kenaz.ai)
+
+## License
+
+MIT — [Kenaz GmbH](https://kenaz.ai)
+
+---
+
+*Built with 🖤 by [Kenaz GmbH](https://kenaz.ai) — AI tools for developers*

{semantic_diff-0.1.0 → semantic_diff-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "semantic-diff"
-version = "0.1.0"
+version = "0.3.0"
 description = "AI-powered semantic analysis of git commits"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,20 +25,28 @@ dependencies = [
     "click>=8.1.0",
     "rich>=13.0.0",
     "python-dotenv>=1.0.0",
-    "gitpython>=3.1.0",
+    "gitpython>=3.1.58",  # CVE-2026-42215, -44243 and later fixes
     "pydantic>=2.0.0",
 ]
 
 [project.optional-dependencies]
+openai = [
+    "openai>=1.40.0",
+]
 dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "black>=23.0.0",
     "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "openai>=1.40.0",
+    "mutmut>=3.0.0",
+    "pyyaml",  # tests execute action.yml steps
+    "httpx",  # tests build SDK errors from real responses; newer SDKs ship httpx2
 ]
 
 [project.scripts]
-semantic-diff = "semantic_diff.cli:main"
+semantic-diff = "semantic_diff.cli:cli"
 
 [project.urls]
 Homepage = "https://github.com/tkenaz/semantic_diff"
@@ -53,5 +61,15 @@ target-version = ["py310", "py311", "py312"]
 
 [tool.ruff]
 line-length = 100
+
+[tool.ruff.lint]
 select = ["E", "F", "I", "N", "W"]
 ignore = ["E501"]
+
+[tool.mutmut]
+paths_to_mutate = ["semantic_diff/"]
+tests_dir = ["tests/"]
+also_copy = ["action.yml", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]