- 2026-05-28 - PCResolve 1.0.4 released: stable provenance JSON contract,
scope_model="v2"by default,--jsonfull output, expanded real-project regression baselines, and Windows-safe audit/gate tooling.
PCResolve is a Python project-level third-party library usage provenance analyzer. It is an explainable static analysis tool for tracing Python API call expressions to their most likely origin library.
It answers questions such as:
- Which third-party libraries does this project call?
- Which call expression belongs to
numpy,requests,flask,sklearn, or another top-level library? - How did a local symbol, return value, attribute, parameter, or container element acquire third-party provenance?
- Where is the analysis certain, and where are there multiple possible origins?
PCResolve is designed for CI pipelines, audit workflows, IDE integration, and large-scale codebase scanning. It has zero runtime third-party dependencies and supports Python 3.9+.
pip install pcresolve
pcresolve /path/to/projectFor machine-readable output:
pcresolve /path/to/project --jsonpcresolve /path/to/project # human-readable summary
pcresolve /path/to/project --json # full provenance JSON
pcresolve /path/to/project --json-summary # compact JSON summary
pcresolve /path/to/project --explain-library numpy
pcresolve /path/to/project --explain-call "np.array"
pcresolve /path/to/project --explain-symbol dffrom pcresolve import analyze_project
result = analyze_project("/path/to/project")
for call in result.all_api_calls:
print(call.expression, "->", call.top_library)
print("reason:", call.reason)
print("confidence:", call.confidence)PCResolve 1.0.4 is the first stable provenance contract release. The default scope model is v2, and --json returns the full provenance schema.
The main output sections are:
| Section | Description |
|---|---|
all_api_calls |
Every call expression with source location, resolved owner, reason, confidence, alternatives, and decorator evidence. |
all_symbol_provenance |
Provenance records for imports, variables, parameters, return values, attributes, container items, and decorators. |
library_usage |
Per-library aggregation of calls, symbols, files, reason counts, and confidence ranges. |
diagnostics |
Non-fatal parse, encoding, and tracing diagnostics. |
For the complete JSON contract, see docs/output-contract.md.
PCResolve tracks both API call provenance and symbol provenance.
Supported patterns include:
- direct imports, aliases, wildcard imports, and re-exports;
- cross-file symbol tracing through local modules;
- function return propagation and parameter binding;
- class construction, instance attributes, and method call provenance;
- dict/list/tuple/set container items and iteration;
- decorator calls and
decorated_byevidence; - ambiguous flows reported through
alternativesinstead of silent guessing.
top_library represents the primary owner of the callable or receiver object for a call expression. Additional evidence is reported separately through fields such as alternatives, decorated_by, and symbol provenance records.
The 1.0.4 release was validated with:
pytest: 557 passed
hard baselines: 21 projects, 0 exceeded
full audit: 42 real-world projects, 0 crashes, 0 illegal keys
The regression gate checks that library keys stay clean, golden JSON output remains stable, and real-project baseline counts do not exceed the recorded contract.
PCResolve is static by design. It does not execute project code and does not model arbitrary runtime reflection, monkey patching, dynamic imports, descriptors, or full third-party library internals.
When a single origin cannot be determined confidently, PCResolve reports conservative results and preserves alternative evidence rather than choosing an unsupported library owner.
pip install -e .
python -m pytest tests/ -v
python scripts/diff_v1_v2.py tests/fixtures/tested_projects/
python scripts/audit_tested_projects.pyPCResolve uses only the Python standard library at runtime. Tests use pytest.
PCResolve is licensed under the MIT License. See LICENSE for details.