Graph Evolution

When to Use

• Comparing two git refs to understand what structurally changed
• Auditing a range of commits for security-relevant evolution
• Detecting new attack paths created by code changes
• Finding functions whose blast radius or complexity grew silently
• Identifying taint propagation changes across refactors
• Pre-release structural comparison (tag-to-tag or branch-to-branch)

When NOT to Use

• Line-level code review (use differential-review for text-diff analysis)
• Single-snapshot analysis (use the trailmark skill directly)
• Diagram generation from a single snapshot (use the diagramming-code skill)
• Mutation testing triage (use the genotoxic skill)

Rationalizations to Reject

Prerequisites

uv pip install trailmark

Quick Start

# Compare two git refs (e.g., tags, branches, commits)
# 1. Build graphs at each snapshot
# 2. Run pre-analysis on both
# 3. Compute structural diff
# 4. Generate report

# Step-by-step: see Workflow below

Decision Tree

├─ Need to understand what each metric means?
│  └─ Read: references/evolution-metrics.md
│
├─ Need the report output format?
│  └─ Read: references/report-format.md
│
├─ Already have two graph JSON exports?
│  └─ Jump to Phase 3 (run native diff + graph_diff.py)
│
└─ Starting from two git refs?
   └─ Start at Phase 1

Workflow

Phase 1: Create Snapshots

# Create temp directories for worktrees
BEFORE_DIR=$(mktemp -d)
AFTER_DIR=$(mktemp -d)

# Create worktrees (run from repo root)
git worktree add "$BEFORE_DIR" {before_ref}
git worktree add "$AFTER_DIR" {after_ref}

Phase 2: Build Graphs and Run Pre-Analysis

from trailmark.query.api import QueryEngine

def build_and_export(target_dir, output_path, language="auto"):
    """Build graph, run pre-analysis, export JSON."""
    engine = QueryEngine.from_directory(target_dir, language=language)
    engine.preanalysis()
    json_str = engine.to_json()
    with open(output_path, "w") as f:
        f.write(json_str)
    return engine.summary()

import tempfile, os
work_dir = tempfile.mkdtemp(prefix="trailmark_evolution_")
before_json = os.path.join(work_dir, "before_graph.json")
after_json = os.path.join(work_dir, "after_graph.json")

before_summary = build_and_export(
    "{before_dir}", before_json
)
after_summary = build_and_export(
    "{after_dir}", after_json
)

Phase 3: Compute Structural Diff

1. Trailmark's native structural diff for nodes, edges, and entrypoints
2. The plugin's graph_diff.py helper for subgraph membership changes

trailmark diff --json "{before_dir}" "{after_dir}" > "{work_dir}/trailmark_diff.json" || \
  uv run trailmark diff --json "{before_dir}" "{after_dir}" > "{work_dir}/trailmark_diff.json"

uv run {baseDir}/scripts/graph_diff.py \
    --before "{before_json}" \
    --after "{after_json}" > "{work_dir}/subgraph_diff.json"

Phase 4: Interpret Diff and Generate Report

1. New tainted paths — nodes entering the tainted subgraph, especially if they also appear in added edges targeting sensitive functions
2. Privilege boundary changes — new or removed trust transitions from the native entrypoint/edge diff plus the subgraph diff
3. Attack surface growth — new entrypoints, especially untrusted_external, from trailmark_diff.json
4. Blast radius increases — nodes entering high_blast_radius
5. Complexity spikes — CC increases > 3 on tainted or entrypoint-reachable nodes
6. Structural additions — new nodes and edges (review needed)
7. Structural removals — verify removed security functions were replaced

Phase 5: Clean Up

git worktree remove "{before_dir}"
git worktree remove "{after_dir}"

Diff Reference

trailmark diff --json BEFORE AFTER
uv run {baseDir}/scripts/graph_diff.py [OPTIONS]

• Node/edge changes
• Added/removed/modified entrypoints
• Human-readable structural diff reports

• Subgraph membership changes derived from engine.preanalysis()
• tainted, high_blast_radius, privilege_boundary, and related sets

Quality Checklist

• Both graphs built successfully (check summaries)
• Pre-analysis ran on both snapshots
• Native Trailmark diff computed and non-empty (trailmark_diff.json)
• Subgraph diff computed and non-empty (subgraph_diff.json)
• All subgraph changes interpreted (tainted, blast radius, etc.)
• Critical findings include evidence (node IDs, edge diffs)
• Severity levels assigned to all findings
• Source-level context added via git diff cross-reference
• Worktrees cleaned up (or temp dirs removed)
• Report written to GRAPH_EVOLUTION_*.md

Integration

Supporting Documentation

• references/evolution-metrics.md [blocked] — What each structural metric means and why it matters for security
• references/report-format.md [blocked] — Report template, severity classification, and example findings