PCResolve

Project-level Python static analysis for API ownership and library usage provenance.

News

• 2026-09-03 - PCResolve 1.0.5 standardizes on lexical scope analysis and expands context-sensitive parameter, return, call, and receiver provenance.
• 2026-05-28 - PCResolve 1.0.4 released: stable provenance JSON contract, scope_model="v2" by default, --json full output, expanded real-project regression baselines, and Windows-safe audit/gate tooling.

What is PCResolve?

PCResolve is a project-level Python static analyzer for API ownership and library usage provenance. It classifies Python API call expressions and traces the symbols that feed them to their owner: an import-backed library, Python-provided API, project-local definition, or unknown.

It answers questions such as:

• Which import-backed libraries and Python APIs does this project call?
• Which call expression belongs to numpy, requests, json, pathlib, flask, or another top-level library owner?
• Which calls are library-owned, Python-provided, local, or unknown?
• How did a local symbol, return value, attribute, parameter, or container element acquire library 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 dependencies and supports Python 3.9+.

Quick Start

pip install pcresolve
pcresolve /path/to/project

For machine-readable output:

pcresolve /path/to/project --json

Usage

CLI

pcresolve /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 df

Python API

from 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)

Output

PCResolve 1.0.4 is the first stable provenance contract release. --json returns the full provenance schema.

The main output sections are:

For the complete JSON contract, see docs/output-contract.md.

Analysis Capabilities

PCResolve reports two connected views: API call ownership and symbol provenance. API calls are the primary classification target. Symbol provenance explains the imports, aliases, assignments, parameters, returns, attributes, containers, and decorators that support each classification.

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_by evidence;
• ambiguous flows reported through alternatives instead 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.

Validation

The current analyzer is validated against locked call-site ground truth from 42 real-world projects:

ground-truth records:  5,788
primary hits:          5,548
primary misses:          240
primary recall:        0.959
false positives:       0

The regression gate checks complete AST call coverage, locked annotations, stable snapshots, clean library keys, and golden JSON output.

Limitations

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 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.

Documentation

• Output Contract
• Architecture
• Trace Contract
• Source Semantics
• Real-Project Validation
• Ground Truth Evaluation

Development

pip install -e .
python -m pytest tests/ -v
python scripts/evaluate_ground_truth.py --view all
python scripts/verify_ground_truth_calls.py --coverage-only
python scripts/refresh_ground_truth_snapshots.py --all --check

PCResolve uses only the Python standard library at runtime. Tests use pytest.

License

PCResolve is licensed under the MIT License. See LICENSE for details.