ripwire-graph-query

Graph queries with ripwire

One-hop questions have cheaper verbs — ripwire-navigate (--callers, --callees, --uses, --path, --impact). Reach for --graph-query only when you need to COMBINE conditions. Repo-wide architecture health (not one query) → ripwire-layers.

Planning a refactor: find the cluster AND its blast radius

The refactor-planning question is always two conditions at once — "what's messy" AND "what would touching it affect" — which is exactly what a single fixed verb can't phrase:

# the refactor short-list: high-complexity functions in the target area
ripwire <dir> --graph-query='and(cx(all,15),file(all,"src/"))' --legend=compact

# now the blast radius: everyone who transitively calls into that cluster (≤3 hops)
ripwire <dir> --graph-query='callers(and(cx(all,15),file(all,"src/")),3)' --legend=compact

(Verified on this repo's shape, not its exact numbers — count= drifts every commit: the first query returns the high-cx symbols under src/, each <s t= n= p=> (kind/name/path); the second returns the transitive caller set, typically smaller than the cluster itself because many hits are leaf-ish or call each other. Read the header's own count=/shown= on your run, don't trust a number pasted here. Narrow file(...) to your actual target directory before trusting the numbers.)

Run the first to size the cluster, the second to size the risk — a small high-cx cluster with a huge callers() closure is a refactor that needs a compatibility shim or a staged rollout, not a rewrite in place; a small cluster with a small closure is safe to just rewrite.

ripwire <dir> --graph-query='EXPR' --legend=compact evaluates a small functional expression to a deterministic, ranked node set (capped at --top-k, default 200). It is a fixed, closed operator set — not Datalog: no user rules, no unbounded recursion.

The operators

Kind	Form	Meaning
source	name("X")	symbols named X (unions same-name defs)
source	all	every INDEXED symbol
filter	kind(EXPR, K)	keep kind K: fn method cls struct iface var sec
filter	cx(EXPR, N)	keep cyclomatic complexity ≥ N
filter	fanin(EXPR, N)	keep in-degree (caller count) ≥ N
filter	file(EXPR, "RE")	keep symbols whose file path matches the ECMAScript regex RE
closure	callers(EXPR [, D=1])	nodes that transitively (≤ D hops) CALL anything in EXPR
closure	callees(EXPR [, D=1])	nodes transitively (≤ D hops) CALLED BY anything in EXPR
join	and(A, B) / or(A, B)	intersection / union
join	not(A, B)	difference (A minus B)

Verified examples (single-quote the whole expression for the shell)

# the functions that transitively (≤2 hops) call buildGraph
ripwire <dir> --graph-query='and(callers(name("buildGraph"),2),kind(all,fn))' --legend=compact

# high-complexity symbols in src/  (the refactor short-list)
ripwire <dir> --graph-query='and(cx(all,15),file(all,"src/"))' --legend=compact

# heavily-depended-on symbols (10+ callers) — the de-facto API surface
ripwire <dir> --graph-query='fanin(all,10)' --legend=compact

# everything main can reach within 2 hops
ripwire <dir> --graph-query='callees(name("main"),2)' --legend=compact

# functions NOT reachable from main's callers  (difference)
ripwire <dir> --graph-query='not(kind(all,fn),callers(name("main")))' --legend=compact

# a two-symbol watchlist
ripwire <dir> --graph-query='or(name("buildGraph"),name("rankGraph"))' --legend=compact

Calibration

• Results come back importance-ranked and capped at top-k — count= vs shown= in the header tells you if the cap bit; narrow the query or raise --top-k.
• Closures walk the same name-based edges as --callers — dynamic dispatch / callbacks / macros can be missing, and amb edges were guessed. Verify in source when which-target matters.
• A malformed expression (unknown operator, bad file() regex) reports the parse error and yields nothing — it never half-answers.