dev-context-code-graph

What this skill does

# Code Graph

Build a deterministic, machine-readable code graph for a single repository. Treat the graph as a machine-readable substrate for an LLM-maintained repo wiki or context hub, not just a terminal-only report. This skill mirrors the `dev-context-multi-repo` artifact workflow, but works at file and symbol level instead of portfolio level.

Use this skill when you need:

- a committable `graphs/code-graph.json` artifact
- file and symbol maps for one repo
- import, call, inheritance, and test-link analysis
- graph-theory review signals such as articulation points, bridges, cycles, topological order, and alternate paths
- blast radius and minimal review context for changed files or symbols
- budget-bounded context retrieval around 1–3 hot symbols via Personalized PageRank
- a grounded repo description or module description generated from graph data instead of ad hoc codebase prose

Do not use this skill for:

- portfolio-wide repo discovery or cross-repo system maps
- architecture or migration planning across many repos
- prose documentation cleanup without graph generation

Use related skills instead:

- [dev-context-multi-repo](../dev-context-multi-repo/SKILL.md) for repo portfolios and hub-level knowledge graphs
- [dev-context-engineering](../dev-context-engineering/SKILL.md) for deciding when code graph vs context graph vs repo graph is the right artifact
- [docs-ai-prd](../docs-ai-prd/SKILL.md) for code-graph specs and acceptance criteria
- [docs-codebase](../docs-codebase/SKILL.md) for publishing graph-backed docs and reports

## Quick Reference

| Need | Start here |
|------|------------|
| Generate the base artifact set | `## Workflow` |
| Validate schema and graph integrity | `### Phase 3: Validate` |
| Query blast radius or symbol neighborhoods | `### Phase 4: Query` |
| Surface structural graph risk | `query_code_graph.py --articulation-points`, `--bridges`, `--cycles`, `--topo-sort`, `--from ... --to ... --k N` |
| Run hot-symbol PPR retrieval | `query_code_graph.py --ppr --seed <id> [--seed <id> ...] --top N` |
| Detect modules via communities | `query_code_graph.py --communities [--resolution γ] [--community-seed N]` |
| Pick the right query for a review | [references/query-recipes.md](references/query-recipes.md) |
| Load scripts, schemas, and reports | `## Navigation` |

## Standard Outputs

Every run should target the same output model:

- `code-profiles/<repo>.json`
  Machine-readable code profile conforming to `schemas/code-profile.schema.json`.
- `graphs/code-graph.json`
  Primary machine-readable artifact. Queryable symbol graph conforming to `schemas/code-graph.schema.json`.
- `reports/code-graph-validation.json` *(optional but recommended)*
  Output of `scripts/validate_code_graph.py --output ...`.
- `reports/code-graph-report.md` *(optional but recommended)*
  Human-readable summary report generated from the graph.
- `reports/query-*.md` *(optional but recommended)*
  Persisted blast-radius, neighborhood, and relationship answers worth filing back into a repo knowledge base.
- `reports/code-graph-report.html` *(optional)*
  Static HTML report for local review.
- `reports/code-graph.mmd` *(optional)*
  Mermaid diagram export for graph neighborhoods or impact views.

## Workflow

### Phase 1: Scan

1. Identify supported source files by extension while skipping generated and vendored build trees.
2. Classify files as `source`, `test`, `config`, or `unknown`.
3. Parse each file with the best deterministic strategy available.
4. Record parse status explicitly: `parsed`, `heuristic`, `unsupported`, `error`, or `skipped`.

Primary helper: [scripts/scan_code_repo.py](scripts/scan_code_repo.py)

## ASCII Flow

```text
single-repo code graph request
  -> scan files and classify source, test, config, or unknown
  -> parse symbols with deterministic or heuristic parser
  -> build nodes and edges into graphs/code-graph.json
  -> validate schema, references, duplicates, orphans, and parse confidence
  -> query neighborhoods, impact, paths, PPR, communities, or structural risk
  -> persist useful reports back into repo context
  -> use findings for review, docs, onboarding, or blast-radius planning
```

### Phase 2: Build

1. Read one or more `code-profiles/*.json` files.
2. Materialize canonical nodes and edges into `graphs/code-graph.json`.
3. Add structural edges from repo to file and from parent symbol or file to child symbol.
4. Synthesize `external_symbol` nodes for unresolved or third-party import/call targets.

Primary helper: [scripts/build_code_graph.py](scripts/build_code_graph.py)

### Phase 3: Validate

Run validation after every build:

```bash
python3 scripts/validate_code_graph.py graphs/code-graph.json \
  --output reports/code-graph-validation.json
```

The validator checks:

- schema and enum compliance
- dangling references
- orphan nodes
- duplicate IDs
- containment / parent edge consistency
- circular imports
- stale verification metadata
- parse-status and confidence bounds

### Phase 4: Query

Common query patterns:

```bash
# Neighborhood around a file or symbol
python3 scripts/query_code_graph.py graphs/code-graph.json --node <id> --hops 1

# Blast radius from a file or symbol
python3 scripts/query_code_graph.py graphs/code-graph.json --impact <id> --hops 2

# Path between two nodes
python3 scripts/query_code_graph.py graphs/code-graph.json --from <id> --to <id>

# Up to three node-disjoint shortest paths
python3 scripts/query_code_graph.py graphs/code-graph.json --from <id> --to <id> --k 3

# Personalized PageRank from one or more hot symbols
python3 scripts/query_code_graph.py graphs/code-graph.json --ppr --seed <id> --top 30

# Module detection via Louvain communities (γ=1 default; >1 = smaller modules, <1 = larger)
python3 scripts/query_code_graph.py graphs/code-graph.json --communities --format table
python3 scripts/query_code_graph.py graphs/code-graph.json --communities --resolution 1.4 --top 25

# Search by label, path, summary, or tags
python3 scripts/query_code_graph.py graphs/code-graph.json --search "invoice service"

# Structural risk
python3 scripts/query_code_graph.py graphs/code-graph.json --articulation-points --relations imports --top 20
python3 scripts/query_code_graph.py graphs/code-graph.json --bridges --relations imports --top 20
python3 scripts/query_code_graph.py graphs/code-graph.json --cycles --relations imports,inherits,calls
python3 scripts/query_code_graph.py graphs/code-graph.json --topo-sort imports

# Mermaid diagram export
python3 scripts/query_code_graph.py graphs/code-graph.json --diagram --output reports/code-graph.mmd
```

Primary helper: [scripts/query_code_graph.py](scripts/query_code_graph.py)

When a query produces durable knowledge, write it to markdown or Mermaid instead of leaving it only in chat output.

Use query outputs to generate:
- repo-area descriptions
- module summaries
- change-impact notes
- review packets for risky symbols or subsystems

### Phase 5: Publish

Generate static reports for humans:

```bash
python3 scripts/export_code_graph_report.py graphs/code-graph.json \
  --output-dir reports/
```

Prefer markdown, Mermaid, or HTML outputs that can be reviewed in Obsidian or filed back into a broader context hub.

### Phase 6: Enhance

Run lightweight health checks over the graph-backed knowledge:

1. Review validation results for missing edges, parse gaps, and unsupported areas that need explanation.
2. Ask the LLM to suggest reusable reports, concept pages, or follow-up questions based on dense or weakly connected graph regions.
3. File durable findings back into `reports/` or a higher-level repo knowledge base instead of repeating the same exploration later.

If the graph is feeding repo descriptions, keep the generation bounded:
- summarize only what the graph can support
- call out parse gaps explicitly
- do not invent ownership, runtime behavior, or architectural roles from symbol names alone

## Supported V1 Scope

The v1 parser pipeline is de