Metadata-Version: 2.4
Name: rubberduck-cpg-contract
Version: 0.1.0.dev2
Summary: Shared, versioned CPG contract (I1): canonical node/edge/provenance/capability model both RubberDuck repos import through adapters.
Project-URL: Source, https://github.com/RubberDuck-com/rubberduck-cpg-contract
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# rubberduck-cpg-contract

A single, versioned contract for code-property-graph (CPG) records: canonical
**node**, **edge**, **provenance** and **capability** types plus a producer-neutral
adapter, so different graph producers describe code with one shared vocabulary.
Consumers import this package through adapters instead of duplicating the types.

Changing the meaning of an existing field requires a major version and full
invalidation.

## Install

```bash
pip install rubberduck-cpg-contract
```

## Usage

```python
from rubberduck_cpg_contract import to_canonical, contract_fingerprint

# `layers` is a mapping of {layer_name: graph}, where each graph exposes
# .nodes(data=True) / .edges(data=True) (e.g. a networkx DiGraph).
nodes, edges, capabilities = to_canonical(layers, producer)

print(contract_fingerprint())   # stable digest of version + vocabulary
```

`to_canonical` returns `CanonicalNode` / `CanonicalEdge` records and a
`CapabilityReport` describing what the producer could and could not resolve.
Unmapped kinds surface in `capabilities.unknown_regions` — never silently dropped.

## What's in the package

- `vocab` — canonical edge / DDG-node kinds and the producer→canonical alias maps
- `node`, `edge`, `identity`, `provenance`, `capability`, `revision` — the dataclasses
- `fingerprint` — `contract_fingerprint()` for cache keys / manifests
- `compat` — version-compatibility check + boundary validators
- `adapters.to_canonical` — the producer-neutral adapter

## Status

Pre-release (`0.1.x`, draft). The vocabulary may change until `1.0.0`.
