Graph Evolution

Graph Evolution

Builds Trailmark code graphs at two source snapshots and computes a structural diff. Surfaces security-relevant changes that text-level diffs miss: new attack paths, complexity shifts, blast radius growth, taint propagation changes, and privilege boundary modifications.

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

trailmark must be installed. If uv run trailmark fails, run:

uv tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)

DO NOT fall back to "manual comparison" or reading source files as a substitute for running trailmark. The tool must be installed and used programmatically. If installation fails, report the error.

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

Graph Evolution Progress:
- [ ] Phase 1: Create snapshots (git worktrees)
- [ ] Phase 2: Build graphs + pre-analysis on both snapshots
- [ ] Phase 3: Compute structural diff
- [ ] Phase 4: Interpret diff and generate report
- [ ] Phase 5: Clean up worktrees

Phase 1: Create Snapshots

Use git worktrees to get clean copies of each ref without disturbing the working tree.

# 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}

If comparing two directories instead of git refs, skip this phase and use the directory paths directly in Phase 2.

Phase 2: Build Graphs and Run Pre-Analysis

Build Trailmark graphs for both snapshots and run pre-analysis on each. Pre-analysis computes blast radius, taint propagation, privilege boundaries, and entrypoint enumeration.

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
)

Verify both graphs built successfully by checking the summary output. If either fails, rerun with an explicit language or comma-separated list instead of auto.

Phase 3: Compute Structural Diff

Run both:

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

Use the same work_dir from Phase 2, and pass the same --language value Phase 2 built with. trailmark diff defaults that flag to python, so on any other target the default exits 0 and writes empty arrays rather than reporting a mismatch.

trailmark diff --json --language auto "{before_dir}" "{after_dir}" > "{work_dir}/trailmark_diff.json" || \
  uv run trailmark diff --json --language auto "{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"

If Phase 2 needed an explicit language or a comma-separated list instead of auto, use that same value here.

If either diff command fails or writes an empty JSON file, stop and report the error instead of continuing to Phase 4.

A trailmark_diff.json whose nodes, edges, and entrypoints arrays are all empty means either nothing changed structurally or both snapshots parsed to (near-)empty graphs. Decide which using Phase 2's graph summaries: if either snapshot's node count is zero or implausibly small for the target, the parse missed the code — name the language set explicitly (rust, solidity, python,rust) and re-run. Healthy node counts on both snapshots plus an empty diff is genuine structural stability.

The native Trailmark diff contains:

The subgraph diff contains:

Phase 4: Interpret Diff and Generate Report

Read both diff JSON files and generate a security-focused markdown report. See references/report-format.md for the full template.

Interpretation priorities (highest to lowest):

1. New tainted paths — nodes entering the tainted subgraph, especially if they also appear in added edges targeting sensitive functions