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.
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/impactguard.svg)](https://pypi.org/project/impactguard/)
48
+ [![Python](https://img.shields.io/pypi/pyversions/impactguard.svg)](https://pypi.org/project/impactguard/)
49
+ [![Coverage](https://codecov.io/gh/daedalus/ImpactGuard/branch/master/graph/badge.svg)](https://codecov.io/gh/daedalus/ImpactGuard)
50
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
51
+ [![Ask DeepWiki](https://deepwiki.com/badge.svg)](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)