impactguard 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- impactguard-0.1.0/.gitignore +50 -0
- impactguard-0.1.0/LICENSE +21 -0
- impactguard-0.1.0/PKG-INFO +587 -0
- impactguard-0.1.0/README.md +545 -0
- impactguard-0.1.0/pyproject.toml +123 -0
- impactguard-0.1.0/src/impactguard/__init__.py +164 -0
- impactguard-0.1.0/src/impactguard/__main__.py +788 -0
- impactguard-0.1.0/src/impactguard/analyze_module.py +184 -0
- impactguard-0.1.0/src/impactguard/baseline.py +135 -0
- impactguard-0.1.0/src/impactguard/compare_signatures.py +153 -0
- impactguard-0.1.0/src/impactguard/config.py +165 -0
- impactguard-0.1.0/src/impactguard/cst_patch.py +90 -0
- impactguard-0.1.0/src/impactguard/enforce_gate.py +116 -0
- impactguard-0.1.0/src/impactguard/extract_calls.py +47 -0
- impactguard-0.1.0/src/impactguard/extract_signatures.py +142 -0
- impactguard-0.1.0/src/impactguard/generate_report.py +230 -0
- impactguard-0.1.0/src/impactguard/impact_analysis.py +222 -0
- impactguard-0.1.0/src/impactguard/patch_confidence.py +84 -0
- impactguard-0.1.0/src/impactguard/patch_generator.py +66 -0
- impactguard-0.1.0/src/impactguard/pipeline.py +570 -0
- impactguard-0.1.0/src/impactguard/py.typed +0 -0
- impactguard-0.1.0/src/impactguard/risk_gate.py +107 -0
- impactguard-0.1.0/src/impactguard/risk_model.py +86 -0
- impactguard-0.1.0/src/impactguard/semver.py +113 -0
- impactguard-0.1.0/src/impactguard/suggest_fixes.py +159 -0
- impactguard-0.1.0/src/impactguard/trace_calls.py +55 -0
- impactguard-0.1.0/src/impactguard/trace_calls_prod.py +79 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
develop-eggs/
|
|
9
|
+
dist/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
|
|
23
|
+
# Virtual environments
|
|
24
|
+
venv/
|
|
25
|
+
ENV/
|
|
26
|
+
env/
|
|
27
|
+
|
|
28
|
+
# IDEs
|
|
29
|
+
.vscode/
|
|
30
|
+
.idea/
|
|
31
|
+
*.swp
|
|
32
|
+
*.swo
|
|
33
|
+
|
|
34
|
+
# Build artifacts
|
|
35
|
+
*.egg
|
|
36
|
+
*.egg-info/
|
|
37
|
+
dist/
|
|
38
|
+
build/
|
|
39
|
+
|
|
40
|
+
# OS
|
|
41
|
+
.DS_Store
|
|
42
|
+
Thumbs.db
|
|
43
|
+
|
|
44
|
+
# ImpactGuard generated files
|
|
45
|
+
.signatures.txt
|
|
46
|
+
.signatures.json
|
|
47
|
+
.calls.json
|
|
48
|
+
.runtime_calls.json
|
|
49
|
+
impact_report.html
|
|
50
|
+
out.json
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ImpactGuard Dev
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,587 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: impactguard
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Lightweight API impact analyzer for Python projects
|
|
5
|
+
Project-URL: Homepage, https://github.com/daedalus/ImpactGuard
|
|
6
|
+
Project-URL: Repository, https://github.com/daedalus/ImpactGuard
|
|
7
|
+
Project-URL: Issues, https://github.com/daedalus/ImpactGuard/issues
|
|
8
|
+
Author-email: Darío Clavijo <clavijodario@gmail.com>
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Python: >=3.11
|
|
12
|
+
Requires-Dist: libcst>=0.4.0
|
|
13
|
+
Provides-Extra: all
|
|
14
|
+
Requires-Dist: hatchling; extra == 'all'
|
|
15
|
+
Requires-Dist: hypothesis; extra == 'all'
|
|
16
|
+
Requires-Dist: mypy; extra == 'all'
|
|
17
|
+
Requires-Dist: pip-api; extra == 'all'
|
|
18
|
+
Requires-Dist: prospector; extra == 'all'
|
|
19
|
+
Requires-Dist: pytest; extra == 'all'
|
|
20
|
+
Requires-Dist: pytest-asyncio; extra == 'all'
|
|
21
|
+
Requires-Dist: pytest-cov; extra == 'all'
|
|
22
|
+
Requires-Dist: pytest-mock; extra == 'all'
|
|
23
|
+
Requires-Dist: ruff; extra == 'all'
|
|
24
|
+
Requires-Dist: semgrep; extra == 'all'
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: hatchling; extra == 'dev'
|
|
27
|
+
Requires-Dist: mypy; extra == 'dev'
|
|
28
|
+
Requires-Dist: pip-api; extra == 'dev'
|
|
29
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
30
|
+
Provides-Extra: lint
|
|
31
|
+
Requires-Dist: mypy; extra == 'lint'
|
|
32
|
+
Requires-Dist: prospector; extra == 'lint'
|
|
33
|
+
Requires-Dist: ruff; extra == 'lint'
|
|
34
|
+
Requires-Dist: semgrep; extra == 'lint'
|
|
35
|
+
Provides-Extra: test
|
|
36
|
+
Requires-Dist: hypothesis; extra == 'test'
|
|
37
|
+
Requires-Dist: pytest; extra == 'test'
|
|
38
|
+
Requires-Dist: pytest-asyncio; extra == 'test'
|
|
39
|
+
Requires-Dist: pytest-cov; extra == 'test'
|
|
40
|
+
Requires-Dist: pytest-mock; extra == 'test'
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
# **ImpactGuard** — Lightweight API impact analyzer for Python projects
|
|
44
|
+
|
|
45
|
+
<img src="logo.png" width="300px">
|
|
46
|
+
|
|
47
|
+
[](https://pypi.org/project/impactguard/)
|
|
48
|
+
[](https://pypi.org/project/impactguard/)
|
|
49
|
+
[](https://codecov.io/gh/daedalus/ImpactGuard)
|
|
50
|
+
[](https://github.com/astral-sh/ruff)
|
|
51
|
+
[](https://deepwiki.com/daedalus/ImpactGuard)
|
|
52
|
+
|
|
53
|
+
## Overview
|
|
54
|
+
|
|
55
|
+
ImpactGuard is a lightweight API impact analyzer for Python projects designed to maintain API stability by tracking function signatures across commits, detecting breaking changes, and analyzing call-site impact using both static and runtime techniques.
|
|
56
|
+
|
|
57
|
+
It provides a quantitative risk framework to help developers understand the consequences of code changes before they are merged.
|
|
58
|
+
|
|
59
|
+
### Core Capabilities
|
|
60
|
+
|
|
61
|
+
- **AST-based Extraction**: Automatically extracts function signatures, including `async def`, decorators, and type hints
|
|
62
|
+
- **Semantic API Diffing**: Classifies changes into a taxonomy of breaking (e.g., removing positional arguments) vs. non-breaking (e.g., adding optional keyword-only arguments)
|
|
63
|
+
- **Impact Analysis**: Correlates signature changes with static call-site extraction and optional runtime tracing to identify affected downstream code
|
|
64
|
+
- **Risk Assessment**: Quantifies the danger of a change using the **S × E × C** (Severity × Exposure × Confidence) model
|
|
65
|
+
- **Automated Remediation**: Generates format-preserving patches using LibCST to fix broken call sites
|
|
66
|
+
|
|
67
|
+
### System Components
|
|
68
|
+
|
|
69
|
+
| Component | Module | Description |
|
|
70
|
+
|-----------|--------|-------------|
|
|
71
|
+
| Signature Extraction | `extract_signatures.py` | AST-based extraction of function metadata |
|
|
72
|
+
| Signature Comparison | `compare_signatures.py` | Semantic diffing of API changes |
|
|
73
|
+
| Call-Site Analysis | `extract_calls.py`, `analyze_module.py` | Static call-site extraction and resolution |
|
|
74
|
+
| Impact Analysis | `impact_analysis.py` | Correlates changes with call sites |
|
|
75
|
+
| Risk Model | `risk_model.py` | S × E × C risk scoring |
|
|
76
|
+
| Risk Gate | `risk_gate.py`, `enforce_gate.py` | CI enforcement engine |
|
|
77
|
+
| Runtime Tracing | `trace_calls.py`, `trace_calls_prod.py` | Development and production tracers |
|
|
78
|
+
| Patch Generation | `cst_patch.py`, `patch_generator.py` | Format-preserving automated fixes |
|
|
79
|
+
| Reporting | `generate_report.py` | Static HTML report generation |
|
|
80
|
+
| CLI | `cli.py` | Command-line interface |
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Quick Start
|
|
85
|
+
|
|
86
|
+
### Installation
|
|
87
|
+
|
|
88
|
+
**Prerequisites:**
|
|
89
|
+
- Python 3.11 or higher
|
|
90
|
+
- Dependencies: `libcst` for concrete syntax tree manipulations
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
# Install from PyPI
|
|
94
|
+
pip install impactguard
|
|
95
|
+
|
|
96
|
+
# Or install for development
|
|
97
|
+
git clone https://github.com/daedalus/ImpactGuard.git
|
|
98
|
+
cd ImpactGuard
|
|
99
|
+
pip install -e ".[test]"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Project Layout
|
|
103
|
+
|
|
104
|
+
| Path | Description |
|
|
105
|
+
|------|-------------|
|
|
106
|
+
| `src/impactguard/` | Core package containing the analysis logic, risk model, and CLI |
|
|
107
|
+
| `extract_signatures.py` | Utility for extracting function metadata into JSON/Text |
|
|
108
|
+
| `extract_calls.py` | AST-based call site extractor |
|
|
109
|
+
| `impact_analysis.py` | Logic for correlating signatures with call sites |
|
|
110
|
+
| `risk_gate.py` | The CI-ready enforcement engine |
|
|
111
|
+
| `trace_calls.py` | Runtime instrumentation for capturing live execution data |
|
|
112
|
+
| `SPEC.md` | Technical specification and public API |
|
|
113
|
+
|
|
114
|
+
The full pipeline can be executed using the `impactguard` CLI:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
# 1. Extract signatures and calls
|
|
118
|
+
impactguard extract $(git ls-files '*.py') > .signatures.json
|
|
119
|
+
impactguard extract-calls $(git ls-files '*.py') > .calls.json
|
|
120
|
+
|
|
121
|
+
# 2. Capture runtime exposure (optional)
|
|
122
|
+
impactguard trace dump .runtime_calls.json
|
|
123
|
+
|
|
124
|
+
# 3. Compare and analyze risk
|
|
125
|
+
impactguard risk diff.txt .runtime_calls.json report.json
|
|
126
|
+
|
|
127
|
+
# 4. Generate the report
|
|
128
|
+
impactguard report report.json api_report.html
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Or use the Python API:
|
|
132
|
+
```python
|
|
133
|
+
from impactguard import run_pipeline
|
|
134
|
+
|
|
135
|
+
result = run_pipeline(
|
|
136
|
+
old_path="old_version/",
|
|
137
|
+
new_path="new_version/",
|
|
138
|
+
runtime_path="runtime.json", # optional
|
|
139
|
+
output_path="report.html" # optional
|
|
140
|
+
)
|
|
141
|
+
print(f"Breaking changes: {len(result['comparison']['breaking'])}")
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Core Analysis Pipeline
|
|
147
|
+
|
|
148
|
+
ImpactGuard operates as a **pipe-and-filter architecture** where artifacts from one stage inform the next.
|
|
149
|
+
|
|
150
|
+
### 1. Signature Extraction
|
|
151
|
+
|
|
152
|
+
The first stage involves deep inspection of Python source files using the `ast` module. The `extract` function walks the Abstract Syntax Tree to identify all function and method definitions. It generates a "fingerprint" for every callable, including its Fully Qualified Name (FQN), parameters, defaults, and decorators.
|
|
153
|
+
|
|
154
|
+
- **Key Component:** `extract_signatures.py`
|
|
155
|
+
- **Output:** `.signatures.json`
|
|
156
|
+
- **Role:** Establishes the baseline of the API surface
|
|
157
|
+
|
|
158
|
+
### 2. Signature Comparison
|
|
159
|
+
|
|
160
|
+
Once two snapshots of a codebase exist (e.g., `HEAD` vs `main`), the `compare` utility performs a semantic diff. Unlike a standard text-based diff, this stage understands Python's parameter rules. It categorizes changes into **Breaking** (e.g., removing a parameter, reordering positional arguments) and **Non-breaking** (e.g., adding an optional keyword argument).
|
|
161
|
+
|
|
162
|
+
- **Key Component:** `compare_signatures.py`
|
|
163
|
+
- **Output:** A structured list of semantic changes
|
|
164
|
+
- **Role:** Identifies exactly how the API contract has evolved
|
|
165
|
+
|
|
166
|
+
### 3. Call-Site and Module Analysis
|
|
167
|
+
|
|
168
|
+
To understand the "blast radius" of a change, ImpactGuard must find where the modified functions are actually used. This is achieved through two complementary approaches:
|
|
169
|
+
|
|
170
|
+
1. **Lightweight Extraction:** Rapidly finding call nodes in the AST
|
|
171
|
+
2. **Deep Module Analysis:** Tracking imports and assignments to resolve method calls to their actual definitions (FQN resolution)
|
|
172
|
+
|
|
173
|
+
- **Key Components:** `extract_calls.py` and `analyze_module.py`
|
|
174
|
+
- **Output:** `.calls.json`
|
|
175
|
+
- **Role:** Maps the internal dependency graph of the codebase
|
|
176
|
+
|
|
177
|
+
### 4. Impact Analysis
|
|
178
|
+
|
|
179
|
+
The final stage of the core pipeline, `analyze`, correlates the detected API changes with the discovered call sites. It validates whether the arguments passed at a specific call site still satisfy the requirements of the new function signature. If runtime data is available, it is integrated here to provide context on how often a specific impacted path is actually executed.
|
|
180
|
+
|
|
181
|
+
- **Key Component:** `impact_analysis.py`
|
|
182
|
+
- **Input:** Signature diffs, call-site data, and optional runtime traces
|
|
183
|
+
- **Role:** Pinpoints exactly which lines of code are broken by a change
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
### Examples of Changes
|
|
188
|
+
|
|
189
|
+
#### Non-Breaking Changes
|
|
190
|
+
These changes do NOT break existing callers:
|
|
191
|
+
- **Adding optional parameters**: `def foo(a, b=1)` → `def foo(a, b=1, c=0)` (no callers need to change)
|
|
192
|
+
- **Adding keyword-only arguments**: `def foo(a)` → `def foo(a, *, debug=False)` (existing callers unaffected)
|
|
193
|
+
- **Adding new functions/classes**: Entirely new APIs that don't affect existing code
|
|
194
|
+
- **Adding `*args` or `**kwargs`**: `def foo(a)` → `def foo(a, *args)` (backward compatible)
|
|
195
|
+
|
|
196
|
+
#### Breaking Changes
|
|
197
|
+
These changes WILL break existing callers:
|
|
198
|
+
- **Removing required parameters**: `def foo(a, b)` → `def foo(a)` (callers passing `b` will fail)
|
|
199
|
+
- **Reordering positional arguments**: `def foo(a, b)` → `def foo(b, a)` (callers' positional args swap)
|
|
200
|
+
- **Removing functions/methods**: Any callable that's removed entirely
|
|
201
|
+
- **Changing parameter types**: `def foo(a: int)` → `def foo(a: str)` (type safety breaks)
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## Risk Model and Enforcement
|
|
206
|
+
|
|
207
|
+
The **Risk Model and Enforcement** subsystem is the decision-making engine of ImpactGuard. It transforms raw signature changes and runtime telemetry into actionable risk levels (`HIGH`, `MEDIUM`, `LOW`, or `UNKNOWN`). These levels are then used to automatically block or permit CI/CD pipelines based on the potential impact on consumers.
|
|
208
|
+
|
|
209
|
+
### The S × E × C Risk Framework
|
|
210
|
+
|
|
211
|
+
The core logic resides in `risk_model.py`. It quantifies risk by evaluating three distinct dimensions:
|
|
212
|
+
|
|
213
|
+
| Component | Code Entity | Description |
|
|
214
|
+
|-----------|-------------|-------------|
|
|
215
|
+
| **Severity (S)** | `get_severity()` | Score (0.1 to 1.0) based on change type (e.g., `REMOVED` = 1.0, `ADDED` = 0.1) |
|
|
216
|
+
| **Exposure (E)** | `exposure()` | Logarithmic scale mapping call counts to a 0.0-1.0 range |
|
|
217
|
+
| **Confidence (C)** | `confidence()` | Measures data reliability based on sample size against a threshold |
|
|
218
|
+
| **Classification** | `classify()` | Uses a decision tree to assign the final risk label |
|
|
219
|
+
|
|
220
|
+
**Exposure Calculation:** `min(1.0, log(1 + count) / log(1 + max_count))`
|
|
221
|
+
|
|
222
|
+
### CI Enforcement
|
|
223
|
+
|
|
224
|
+
The risk assessment is operationalized through `risk_gate.py` and `enforce_gate.py`:
|
|
225
|
+
|
|
226
|
+
1. **Risk Gate Execution**: `risk_gate.py` contains the `run()` function which parses the diff and runtime data to generate a comprehensive `report.json`
|
|
227
|
+
2. **Gate Enforcement**: `enforce_gate.py` consumes this report:
|
|
228
|
+
- If any item is flagged as `HIGH` risk → exits with code `1` (blocks build)
|
|
229
|
+
- If `UNKNOWN` risks are detected → issues a warning but allows build (exit code `0`)
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Runtime Tracing
|
|
234
|
+
|
|
235
|
+
The **Runtime Tracing** subsystem provides dynamic analysis capabilities to complement ImpactGuard's static analysis pipeline. By observing actual execution patterns, the system captures "Exposure" data which is used by the `risk_model.py` to weight the impact of breaking changes.
|
|
236
|
+
|
|
237
|
+
### Development Tracer (`trace_calls.py`)
|
|
238
|
+
|
|
239
|
+
Designed for test suites and local execution where performance is less critical than data accuracy. It uses an `@trace` decorator to capture not just call counts, but also signature metadata like argument counts and keyword argument names.
|
|
240
|
+
|
|
241
|
+
- **Key Mechanism:** Uses `inspect.signature(func).bind_partial(*args, **kwargs)` to validate and record invocations
|
|
242
|
+
- **Integration:** Commonly used via `install_tracer()` in test fixtures
|
|
243
|
+
|
|
244
|
+
### Production Sampler (`trace_calls_prod.py`)
|
|
245
|
+
|
|
246
|
+
Optimized for minimal overhead in live environments. It employs a probabilistic sampling strategy (default 1%) to capture a representative subset of traffic.
|
|
247
|
+
|
|
248
|
+
- **Sampling Logic:** Only records data if `random.random() < SAMPLE_RATE`
|
|
249
|
+
- **Background Flushing:** Periodically flushes captured counts to disk (default every 10 seconds)
|
|
250
|
+
|
|
251
|
+
| Feature | Development Tracer | Production Sampler |
|
|
252
|
+
|---------|-------------------|-------------------|
|
|
253
|
+
| **Primary Goal** | Deep visibility / Test coverage | Low overhead monitoring |
|
|
254
|
+
| **Data Captured** | Counts + Arg structure | Call Counts only |
|
|
255
|
+
| **Sampling** | 100% (No sampling) | 1% (Adjustable) |
|
|
256
|
+
| **Storage Trigger** | Manual `dump()` call | Periodic `flush()` (10s interval) |
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## Patch Generation and Remediation
|
|
261
|
+
|
|
262
|
+
The Patch Generation subsystem transforms identified impact risks into actionable code fixes. It provides a multi-tiered approach to remediation, ranging from high-level suggestions to precise, format-preserving code transformations using Concrete Syntax Trees (CST).
|
|
263
|
+
|
|
264
|
+
### Patch Suggestion and Diff-Based Patching
|
|
265
|
+
|
|
266
|
+
The system first generates high-level suggestions based on the nature of the breaking change. For simple scenarios, it employs a naive line-based patching strategy using Python's `difflib`.
|
|
267
|
+
|
|
268
|
+
- **Logic Location**: `suggest_fixes.py` analyzes issues to recommend actions
|
|
269
|
+
- **Naive Patching**: `patch_generator.py` uses `difflib.unified_diff` for simple string replacement
|
|
270
|
+
|
|
271
|
+
### CST-Based Patching (`cst_patch.py`)
|
|
272
|
+
|
|
273
|
+
To handle complex code structures, ImpactGuard utilizes `LibCST`. Unlike standard AST, a Concrete Syntax Tree preserves formatting, comments, and whitespace.
|
|
274
|
+
|
|
275
|
+
- **Transformers**: Uses `AddDefaultTransformer` to modify function signatures and `FixCallTransformer` to inject missing arguments into call sites
|
|
276
|
+
- **Safety**: Gracefully falls back to simpler methods if `libcst` is not installed
|
|
277
|
+
|
|
278
|
+
### Patch Confidence Scoring
|
|
279
|
+
|
|
280
|
+
Every generated patch is assigned a confidence score (0.0 to 1.0) to determine if it can be auto-applied:
|
|
281
|
+
|
|
282
|
+
1. **Target Certainty (T)**: How sure we are that we found the correct line
|
|
283
|
+
2. **Structural Safety (S)**: Is the change a simple default addition or a risky positional reorder?
|
|
284
|
+
3. **Semantic Risk (R)**: Does the change affect required parameters?
|
|
285
|
+
4. **Complexity Penalty (C)**: Is the code heavily decorated or nested?
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## CLI Reference
|
|
290
|
+
|
|
291
|
+
The `impactguard` command-line tool is the primary entry point for developers and automation scripts.
|
|
292
|
+
|
|
293
|
+
### Pipeline Mode (Recommended)
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
# Compare two versions of your code
|
|
297
|
+
impactguard old_version/ new_version/
|
|
298
|
+
|
|
299
|
+
# Compare two git commits directly
|
|
300
|
+
impactguard check-commits HEAD~1 HEAD
|
|
301
|
+
|
|
302
|
+
# Compare specific files between commits
|
|
303
|
+
impactguard check-commits HEAD~1 HEAD --files src/module.py src/utils.py
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
### Individual Commands (Advanced)
|
|
307
|
+
|
|
308
|
+
```bash
|
|
309
|
+
impactguard extract file1.py file2.py
|
|
310
|
+
impactguard compare old_sigs.json new_sigs.json
|
|
311
|
+
impactguard analyze signatures.json calls.json runtime.json
|
|
312
|
+
impactguard risk diff.txt runtime.json output.json
|
|
313
|
+
impactguard report risk.json output.html
|
|
314
|
+
impactguard trace install mypackage
|
|
315
|
+
impactguard trace dump runtime.json
|
|
316
|
+
impactguard install-hooks . --both # Install git hooks
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Git Hooks Installation
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
# Install both pre-commit and post-commit hooks
|
|
323
|
+
impactguard install-hooks .
|
|
324
|
+
|
|
325
|
+
# Install only pre-commit hook
|
|
326
|
+
impactguard install-hooks . --pre
|
|
327
|
+
|
|
328
|
+
# Install only post-commit hook (updates signature tracking)
|
|
329
|
+
impactguard install-hooks . --post
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## Python Library API
|
|
335
|
+
|
|
336
|
+
The `impactguard` package exports its core functionality for programmatic integration.
|
|
337
|
+
|
|
338
|
+
### Pipeline (Recommended)
|
|
339
|
+
|
|
340
|
+
```python
|
|
341
|
+
from impactguard import run_pipeline, quick_check, run_pipeline_git, ImpactGuard
|
|
342
|
+
|
|
343
|
+
# Full pipeline - extract, compare, analyze, risk, report
|
|
344
|
+
result = run_pipeline(
|
|
345
|
+
old_path="src/",
|
|
346
|
+
new_path="src/",
|
|
347
|
+
runtime_path="runtime.json",
|
|
348
|
+
output_path="report.html"
|
|
349
|
+
)
|
|
350
|
+
|
|
351
|
+
# Quick comparison only (extract + compare)
|
|
352
|
+
changes = quick_check("old/", "new/")
|
|
353
|
+
print(f"Breaking: {len(changes['comparison']['breaking'])}")
|
|
354
|
+
|
|
355
|
+
# Compare git commits
|
|
356
|
+
result = run_pipeline_git(
|
|
357
|
+
old_ref="HEAD~1",
|
|
358
|
+
new_ref="HEAD",
|
|
359
|
+
files=["src/module.py"]
|
|
360
|
+
)
|
|
361
|
+
|
|
362
|
+
# Use ImpactGuard class for more control
|
|
363
|
+
guard = ImpactGuard()
|
|
364
|
+
report = guard.check("old/", "new/", output="report.html")
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
### Individual Components (Advanced)
|
|
368
|
+
|
|
369
|
+
```python
|
|
370
|
+
from impactguard import extract, compare, analyze_impact
|
|
371
|
+
|
|
372
|
+
# Extract signatures from Python files
|
|
373
|
+
signatures = extract(["src/module.py", "src/other.py"])
|
|
374
|
+
|
|
375
|
+
# Compare two signature snapshots
|
|
376
|
+
result = compare("old_sigs.json", "new_sigs.json")
|
|
377
|
+
print(f"Breaking changes: {len(result['breaking'])}")
|
|
378
|
+
|
|
379
|
+
# Analyze impact on call sites
|
|
380
|
+
issues = analyze_impact("signatures.json", "calls.json", "runtime.json")
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
---
|
|
384
|
+
|
|
385
|
+
## Git Hooks and Workflow Integration
|
|
386
|
+
|
|
387
|
+
ImpactGuard is designed to be deeply integrated into the standard Git development workflow.
|
|
388
|
+
|
|
389
|
+
### Post-Commit Hook
|
|
390
|
+
|
|
391
|
+
This hook ensures that every commit is accompanied by updated signature tracking. It includes a `SKIP_SIGNATURE_HOOK` environment variable check to prevent infinite recursion when the hook itself creates a new commit.
|
|
392
|
+
|
|
393
|
+
### Pre-Push Hook
|
|
394
|
+
|
|
395
|
+
This acts as the final safety gate. It typically runs `compare_signatures.py` to evaluate the delta between the local branch and `origin/master`. If the risk gate detects high-risk breaking changes without appropriate mitigations, the push is blocked.
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## CI/CD and Release Infrastructure
|
|
400
|
+
|
|
401
|
+
### CI Pipeline
|
|
402
|
+
|
|
403
|
+
The CI pipeline is defined in `.github/workflows/ci.yml` and executes on all pushes and pull requests targeting the `master` branch. It consists of three parallel jobs:
|
|
404
|
+
|
|
405
|
+
- **Test Matrix:** Executes `pytest` across Python versions 3.11, 3.12, and 3.13
|
|
406
|
+
- **Static Analysis (Linting):** Runs `ruff`, `prospector`, `semgrep`, and `mypy`
|
|
407
|
+
- **Build Verification:** Ensures the package can be successfully built via `twine check`
|
|
408
|
+
|
|
409
|
+
### Packaging and Release
|
|
410
|
+
|
|
411
|
+
ImpactGuard uses modern Python packaging standards with `hatchling` as the build backend.
|
|
412
|
+
|
|
413
|
+
**Dependency Groups:**
|
|
414
|
+
| Group | Purpose | Key Tools |
|
|
415
|
+
|-------|---------|-----------|
|
|
416
|
+
| `dev` | General development | `hatch`, `pip-api` |
|
|
417
|
+
| `test` | Automated testing | `pytest`, `hypothesis` |
|
|
418
|
+
| `lint` | Static analysis | `ruff`, `mypy`, `semgrep` |
|
|
419
|
+
|
|
420
|
+
**Release Automation:**
|
|
421
|
+
- **Version Management:** Uses `bumpversion` to maintain consistency across `pyproject.toml` and `src/impactguard/__init__.py`
|
|
422
|
+
- **Automated Publishing:** The `pypi-publish.yml` workflow triggers on GitHub Release events to build and publish to PyPI using Trusted Publishers (OIDC)
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## Testing
|
|
427
|
+
|
|
428
|
+
The ImpactGuard test suite ensures the reliability of the signature extraction pipeline, the accuracy of the risk model, and the stability of the CLI. The project maintains a strict quality gate, requiring a minimum of 80% code coverage.
|
|
429
|
+
|
|
430
|
+
### Test Architecture
|
|
431
|
+
|
|
432
|
+
1. **Unit Tests**: Isolated testing of individual modules (extraction, comparison, patching)
|
|
433
|
+
2. **Integration Tests**: End-to-end CLI flows and public API surface validation
|
|
434
|
+
3. **Coverage Enforcement**: Automated checks to ensure the codebase meets the 80% threshold
|
|
435
|
+
|
|
436
|
+
### Test Fixtures
|
|
437
|
+
|
|
438
|
+
| Fixture | Description |
|
|
439
|
+
|---------|-------------|
|
|
440
|
+
| `sample_signature_data` | Returns a list of dictionaries representing serialized function signatures |
|
|
441
|
+
| `sample_signatures_file` | Creates a temporary `.json` file containing signature data |
|
|
442
|
+
| `sample_python_file` | Generates a temporary `.py` file with functions and classes |
|
|
443
|
+
| `runtime_data_file` | Provides a temporary JSON file simulating tracer output |
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## How It Works
|
|
448
|
+
|
|
449
|
+
1. **Signature Extraction** — Parses Python AST to extract function signatures with full structural information
|
|
450
|
+
2. **API Diff** — Compares signature snapshots to detect removed functions, added required args, positional reordering, and other breaking changes
|
|
451
|
+
3. **Call-Site Analysis** — Combines signature data with call-site extraction to predict which callers will break
|
|
452
|
+
4. **Runtime Validation** — Instruments functions during test runs to record actual call patterns
|
|
453
|
+
5. **Pipeline Orchestrator** — Connects all components in one unified workflow (`run_pipeline()`)
|
|
454
|
+
6. **Git Integration** — Compare any two git commits directly (`run_pipeline_git()`)
|
|
455
|
+
|
|
456
|
+
---
|
|
457
|
+
|
|
458
|
+
## Intermediate Artifacts
|
|
459
|
+
|
|
460
|
+
The pipeline relies on standardized JSON schemas to pass data between filters:
|
|
461
|
+
|
|
462
|
+
| Artifact | Producer | Consumer | Description |
|
|
463
|
+
|----------|-----------|----------|-------------|
|
|
464
|
+
| `.signatures.json` | `extract_signatures.py` | `compare_signatures.py`, `impact_analysis.py` | Function metadata including arguments, defaults, and line numbers |
|
|
465
|
+
| `.calls.json` | `extract_calls.py` | `impact_analysis.py` | Static call sites mapped by caller and callee |
|
|
466
|
+
| `.runtime_calls.json` | `trace_calls.py` | `impact_analysis.py`, `risk_gate.py` | Frequency and argument data from execution |
|
|
467
|
+
| `report.json` | `risk_gate.py` | `generate_report.py`, `suggest_fixes.py` | Final risk classifications (HIGH/MEDIUM/LOW) |
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Self-Testing (Dogfooding)
|
|
472
|
+
|
|
473
|
+
ImpactGuard has been **tested on itself** to validate its own API changes:
|
|
474
|
+
|
|
475
|
+
```bash
|
|
476
|
+
# Extract signatures from own codebase
|
|
477
|
+
$ impactguard extract src/impactguard/*.py
|
|
478
|
+
✓ Extracted 98 function signatures
|
|
479
|
+
|
|
480
|
+
# Detect non-breaking change (added optional parameter)
|
|
481
|
+
✓ Correctly classified as "Non-breaking changes: 1"
|
|
482
|
+
|
|
483
|
+
# Detect breaking change (removed required parameter)
|
|
484
|
+
✓ Correctly classified as "Breaking changes: 1"
|
|
485
|
+
|
|
486
|
+
# Run full pipeline on itself
|
|
487
|
+
$ impactguard check-commits HEAD~5 HEAD
|
|
488
|
+
✓ Pipeline orchestrator completed successfully
|
|
489
|
+
✓ Generated HTML report with risk analysis
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
---
|
|
493
|
+
|
|
494
|
+
## Quality Standards
|
|
495
|
+
|
|
496
|
+
ImpactGuard follows strict quality gates:
|
|
497
|
+
- **Ruff** — 0 issues (formatting + linting)
|
|
498
|
+
- **MyPy** — 0 errors (strict mode)
|
|
499
|
+
- **Prospector** — 0 warnings
|
|
500
|
+
- **Semgrep** — 0 findings
|
|
501
|
+
- **Coverage** — ≥80% (target)
|
|
502
|
+
- **Tests** — All passing
|
|
503
|
+
|
|
504
|
+
---
|
|
505
|
+
|
|
506
|
+
## Glossary
|
|
507
|
+
|
|
508
|
+
### Core Concepts
|
|
509
|
+
|
|
510
|
+
- **Signature**: A structured representation of a Python function's interface, including positional arguments, keyword-only arguments, and variadic arguments
|
|
511
|
+
- **FQName (Fully Qualified Name)**: A unique identifier in `file_path:function_name` format (e.g., `src/auth.py:login`)
|
|
512
|
+
- **Breaking Change**: A modification that prevents existing callers from executing correctly (e.g., `REMOVED`, `REQUIRED_POSITIONAL_ADDED`, `POSITIONAL_REORDER`)
|
|
513
|
+
|
|
514
|
+
### Risk Framework (S × E × C)
|
|
515
|
+
|
|
516
|
+
- **Severity (S)**: The technical impact of the change type (0.1 to 1.0)
|
|
517
|
+
- **Exposure (E)**: How often the function is called, calculated logarithmically
|
|
518
|
+
- **Confidence (C)**: The reliability of runtime data based on sample size
|
|
519
|
+
|
|
520
|
+
### Patching
|
|
521
|
+
|
|
522
|
+
- **CST (Concrete Syntax Tree)**: Unlike AST, preserves formatting, comments, and whitespace
|
|
523
|
+
- **Patch Confidence**: A score from 0.0 to 1.0 representing the likelihood that an automated fix is correct
|
|
524
|
+
|
|
525
|
+
---
|
|
526
|
+
|
|
527
|
+
## Direct Competitors (Python API analysis space)
|
|
528
|
+
|
|
529
|
+
The table below compares ImpactGuard against the tools most commonly used for Python API change management, static analysis, and release automation. As of 2026-05, to our knowledge:
|
|
530
|
+
|
|
531
|
+
| Feature | **ImpactGuard** | **griffe** | **python-semantic-release** | **commitizen** | **pyright / mypy** |
|
|
532
|
+
|---|---|---|---|---|---|
|
|
533
|
+
| AST-based signature extraction | ✅ Full (positional, kwonly, vararg, return type, decorators, async) | ✅ Full | ❌ | ❌ | ✅ (internal only) |
|
|
534
|
+
| Breaking-change detection | ✅ Semantic diff (added / removed / modified) | ✅ | ❌ Code-unaware | ❌ Code-unaware | ⚠️ Type errors only |
|
|
535
|
+
| Call-site impact analysis | ✅ Static call-site traversal | ❌ | ❌ | ❌ | ❌ |
|
|
536
|
+
| Runtime call tracing | ✅ (test + production sampler) | ❌ | ❌ | ❌ | ❌ |
|
|
537
|
+
| Risk scoring (S × E × C model) | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
538
|
+
| Transitive impact tracking | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
539
|
+
| Semver bump recommendation | ✅ From code diff | ⚠️ Partial (griffe-diff) | ✅ From commit msgs | ✅ From commit msgs | ❌ |
|
|
540
|
+
| Changelog generation | ✅ From signature diff | ⚠️ Via mkdocs plugin | ✅ From commit msgs | ✅ From commit msgs | ❌ |
|
|
541
|
+
| HTML report | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
542
|
+
| Patch generation (CST-based) | ✅ Formatting-preserving | ❌ | ❌ | ❌ | ⚠️ Quickfix only |
|
|
543
|
+
| Patch confidence scoring | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
544
|
+
| Baseline management | ✅ Save / compare / diff | ⚠️ Via snapshots | ❌ | ❌ | ❌ |
|
|
545
|
+
| CI enforcement gate | ✅ Blocks on HIGH / UNKNOWN | ❌ | ✅ (release gate) | ✅ (lint gate) | ✅ (type gate) |
|
|
546
|
+
| Git hook integration | ✅ Pre + post commit | ❌ | ❌ | ✅ | ❌ |
|
|
547
|
+
| Config file (TOML) | ✅ `impactguard.toml` | ✅ | ✅ | ✅ | ✅ |
|
|
548
|
+
| Watch mode (live re-run) | ✅ `--watch` | ❌ | ❌ | ❌ | ✅ |
|
|
549
|
+
| No network required | ✅ | ✅ | ❌ (PyPI / git) | ❌ (git) | ✅ |
|
|
550
|
+
|
|
551
|
+
### Ecosystem-adjacent tools
|
|
552
|
+
|
|
553
|
+
| Tool | Domain | Overlap with ImpactGuard | What ImpactGuard adds |
|
|
554
|
+
|---|---|---|---|
|
|
555
|
+
| **griffe** | Python API docs + diff | Closest alternative — extracts signatures, detects breaking changes | Call-site analysis, runtime tracing, risk model, patch generation |
|
|
556
|
+
| **python-semantic-release** | Automated releases + semver | Semver bumps from conventional commits | Code-level proof, not just commit message convention |
|
|
557
|
+
| **commitizen** | Conventional commits + changelog | Changelog generation, git hooks | Actual API-level analysis and enforcement |
|
|
558
|
+
| **bump2version / bumpversion** | Version string management | Version bumping | All analysis features |
|
|
559
|
+
| **mypy / pyright** | Static type checking | Detects type-incompatible changes | Call-site impact, risk scoring, runtime data integration |
|
|
560
|
+
| **japicmp / apidiff (Go/Java)** | API compatibility in Java / Go | Direct conceptual analog in other languages | Python-specific, runtime tracing, patch generation |
|
|
561
|
+
|
|
562
|
+
### ImpactGuard's unique differentiators
|
|
563
|
+
|
|
564
|
+
1. **Risk scoring (S × E × C)** — No competitor combines severity, exposure (call count), and confidence into a single risk score.
|
|
565
|
+
2. **Runtime + static fusion** — Merges static call-site analysis with actual runtime call counts from test runs to give empirically grounded risk levels.
|
|
566
|
+
3. **Transitive impact** — Tracks callers of callers, not just direct call sites.
|
|
567
|
+
4. **CST-based patch generation** — Suggests and previews source patches that preserve original formatting; no competitor does this in the API-change domain.
|
|
568
|
+
5. **Patch confidence scoring** — Quantifies how safe an automated fix is before applying it.
|
|
569
|
+
6. **Fully offline** — No network access, no database; embeds entirely in a Python project.
|
|
570
|
+
|
|
571
|
+
---
|
|
572
|
+
|
|
573
|
+
## Further Documentation
|
|
574
|
+
|
|
575
|
+
For deeper exploration of specific subsystems, refer to the [DeepWiki documentation](https://deepwiki.com/daedalus/ImpactGuard):
|
|
576
|
+
|
|
577
|
+
- [Getting Started](https://deepwiki.com/daedalus/ImpactGuard/1.1-getting-started)
|
|
578
|
+
- [Architecture and Data Flow](https://deepwiki.com/daedalus/ImpactGuard/1.2-architecture-and-data-flow)
|
|
579
|
+
- [Core Analysis Pipeline](https://deepwiki.com/daedalus/ImpactGuard/2-core-analysis-pipeline)
|
|
580
|
+
- [Risk Model and Enforcement](https://deepwiki.com/daedalus/ImpactGuard/3-risk-model-and-enforcement)
|
|
581
|
+
- [Runtime Tracing](https://deepwiki.com/daedalus/ImpactGuard/4-runtime-tracing)
|
|
582
|
+
- [Patch Generation and Remediation](https://deepwiki.com/daedalus/ImpactGuard/5-patch-generation-and-remediation)
|
|
583
|
+
- [CLI and Public API](https://deepwiki.com/daedalus/ImpactGuard/6-cli-and-public-api)
|
|
584
|
+
- [Git Hooks and Workflow Integration](https://deepwiki.com/daedalus/ImpactGuard/7-git-hooks-and-workflow-integration)
|
|
585
|
+
- [CI/CD and Release Infrastructure](https://deepwiki.com/daedalus/ImpactGuard/8-cicd-and-release-infrastructure)
|
|
586
|
+
- [Testing](https://deepwiki.com/daedalus/ImpactGuard/9-testing)
|
|
587
|
+
- [Glossary](https://deepwiki.com/daedalus/ImpactGuard/10-glossary)
|