Metadata-Version: 2.4
Name: graphrag-codeproperty-graph
Version: 0.4.4
Summary: Code Property Graphs — Joern/Semgrep extraction, AI vulnerability enrichment, risk scoring
Project-URL: Repository, https://github.com/kanjani-ai-research/codeproperty-graph
Author-email: Evan Erwee <evan@erwee.com>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: code-analysis,cpg,graph,joern,neptune,semgrep,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: graphrag-document-graph>=3.0.9
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Code Property Graph

[![PyPI version](https://img.shields.io/pypi/v/graphrag-codeproperty-graph.svg)](https://pypi.org/project/graphrag-codeproperty-graph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Code Property Graphs — Joern/Semgrep extraction, AI vulnerability enrichment, risk scoring.**

> **This package depends on AWS GraphRAG Toolkit (graphrag-toolkit-lexical-graph) for graph storage, vector indexing, and retrieval.**

## Installation

```bash
pip install graphrag-codeproperty-graph
```

## Dependencies

- `graphrag-document-graph>=3.0.8` — Document graph infrastructure (typed nodes, Cypher builders, multi-tenancy)

This package does **not** depend on `bona`.

## Dependency Chain

```
graphrag-codeproperty-graph
└── graphrag-document-graph>=3.0.8
    └── graphrag-toolkit-lexical-graph>=3.18.0  (AWS foundation)
        ├── Neptune graph storage
        ├── OpenSearch Serverless vector indexing
        └── Entity resolution & retrieval
```

## Quick Start

### Python API Example

```python
from codeproperty_graph import DeltaIngestor, CPGNode, CPGEdge, GraphDiff

# Delta ingestion — only writes to Neptune when code actually changed
ingestor = DeltaIngestor(bucket="graphrag-artifacts-705909755305")

result = await ingestor.ingest(
    repo="my-service",
    job_id="build-456",
    tenant_id="tenant_abc123",
    nodes_data=joern_nodes,
    edges_data=joern_edges,
    nodes_path="s3://bucket/cpg-exports/my-service/build-456/nodes.json",
    edges_path="s3://bucket/cpg-exports/my-service/build-456/edges.json",
    graph_store=neptune_store,
    write_fn=batch_write_function,
)

# result: {"status": "SKIPPED"} or {"status": "INGESTED", "delta": "+5 -2 ~3 =150"}
```

### Graph Diff — Compare CPG States

```python
from codeproperty_graph import GraphDiff, CPGNode

# Compare current vs previous code analysis
diff = GraphDiff.compare(
    current_nodes=current_cpg_nodes,
    previous_nodes=previous_cpg_nodes,
)

print(f"Added: {len(diff.added)}")
print(f"Removed: {len(diff.removed)}")
print(f"Modified: {len(diff.modified)}")
print(f"Unchanged: {len(diff.unchanged)}")
```

### Manifest Management

```python
from codeproperty_graph import ManifestManager

# Track CPG state per repository in S3
manager = ManifestManager(bucket="graphrag-artifacts-705909755305")

# Save manifest after successful ingestion
await manager.save(repo="my-service", job_id="build-456", signatures=method_signatures)

# Load previous manifest for diff comparison
previous = await manager.load(repo="my-service")
```

## Package Structure

```
src/codeproperty_graph/
├── __init__.py           # Public API: CPGNode, CPGEdge, DeltaIngestor, etc.
├── models.py             # CPGNode, CPGEdge, Manifest — Joern-specific types
├── graph_diff.py         # Compare two CPG states by method signature
├── manifest_manager.py   # S3-backed state tracking per repository
├── delta_ingestor.py     # Skip-or-replace orchestration with tenant purge
└── tenant_ops.py         # Clean lifecycle management (delete_tenant)
```

## Integration

### Architecture Stack

```
┌─────────────────────────────────────────────────────┐
│         codeproperty-graph (this package)            │
│  Joern/Semgrep CPG, delta ingestion, risk scoring   │
├─────────────────────────────────────────────────────┤
│              document-graph                          │
│  Node, Edge, CypherBuilder, PipelineExecutor        │
│  Multi-tenancy, batch operations                    │
├─────────────────────────────────────────────────────┤
│     graphrag-toolkit-lexical-graph (foundation)     │
│  GraphStore, Neptune writer, AOSS writer            │
│  Lexical indexing, entity resolution, retrieval     │
└─────────────────────────────────────────────────────┘
```

### Delta Logic

1. Joern exports CPG → `nodes.json` + `edges.json`
2. Extract METHOD node signatures: `{full_name: hash}`
3. Compare against previous manifest in S3
4. If identical → **SKIP** (no Neptune writes, saves cost)
5. If changed → **INGEST** full graph under new tenant, purge old tenant, update manifest

### With Document Graph

Code Property Graph uses document-graph for typed property graph primitives:

```python
# document-graph provides the graph write infrastructure
from graphrag_toolkit.document_graph.graph_build.cypher_builder import CypherBuilder
from graphrag_toolkit.document_graph import Node, Edge

# codeproperty-graph adds CPG-specific semantics on top
from codeproperty_graph import CPGNode, CPGEdge
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.

## License

MIT — see [LICENSE](LICENSE) for details.

See [NOTICE](NOTICE) for third-party acknowledgments.
