Ripwire Graph Query

---
name: ripwire-graph-query
description: >
  A call-graph question the fixed verbs can't phrase — 'which high-complexity functions can reach X?',
  'what has 10+ callers in src/?', 'untested symbols within one hop of main'. --graph-query: a small
  closed expression language — kind, complexity, fan-in, tested filters; a file or cluster; bounded
  hops; and/or/not.
allowed-tools: Bash, Read
---

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