@drafthq/draft 3.1.5 → 3.2.0

package/scripts/tools/_graph_queries.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# _graph_queries.sh — canonical Cypher builders + fail-loud runner for the
+# codebase-memory-mcp engine. Sourced by the graph-*.sh wrappers; never executed.
+#
+# Single source of query truth (graph-tooling-v2 Guardrail 2): no Cypher literal
+# should live in a wrapper entrypoint. A label or dialect fix is a one-line edit
+# here, not a hunt across N scripts (the Phase 0 :Function bug was duplicated
+# across two files precisely because the Cypher was inlined).
+#
+# Dialect notes (engine v0.8.x, verified live against this engine):
+#   SAFE   : fixed-length patterns, single/multi-hop explicit patterns, `=`, `<`,
+#            `STARTS WITH`, `NOT x STARTS WITH`, `AND`, `OR`, relationship-type
+#            alternation `[:A|B]`, simple `count(x)`.
+#   UNSAFE : coalesce(), `<>` / `!=` / `<=` / `>=`, `NOT EXISTS(...)`,
+#            `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern joins.
+#            Every builder below stays inside the SAFE set.
+#
+# Label-agnostic on name matches: code units are :Method ⪢ :Function in OO repos;
+# pinning :Function silently returns [] (the graph-tooling-v2 Phase 0 bug). CALLS
+# edges only connect callables, so dropping the label stays precise.
+
+# shellcheck shell=bash
+
+# Pull in memory_cli / find_memory_bin / MEMORY_BIN if a wrapper sourced only us.
+_GQ_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ "$(type -t memory_cli 2>/dev/null)" != function ]]; then
+    # shellcheck source=_lib.sh
+    source "$_GQ_DIR/_lib.sh"
+fi
+
+# Escape single quotes for embedding inside a Cypher single-quoted string literal.
+gq_escape() {
+    local s="$1"
+    printf '%s' "${s//\'/\\\'}"
+}
+
+# ── Cypher builders. Each echoes one query string. $1 = pre-escaped symbol. ──
+
+gq_q_exists()            { printf "MATCH (f {name:'%s'}) RETURN f.name AS name LIMIT 1" "$1"; }
+gq_q_callers()           { printf "MATCH (c)-[:CALLS]->(f {name:'%s'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
+gq_q_callers_prod()      { printf "MATCH (c)-[:CALLS]->(f {name:'%s'}) WHERE c.is_test=false AND NOT c.file_path STARTS WITH 'tests/' RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
+gq_q_callers_qualified() { printf "MATCH (c)-[:CALLS]->(f {qualified_name:'%s'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
+gq_q_cycles2()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(a) WHERE a.qualified_name < b.qualified_name RETURN a.qualified_name AS a, b.qualified_name AS b LIMIT 100"; }
+gq_q_cycles3()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(c)-[:CALLS]->(a) RETURN a.qualified_name AS a, b.qualified_name AS b, c.qualified_name AS c LIMIT 100"; }
+gq_q_tests()             { printf "MATCH (t)-[:TESTS]->(f {name:'%s'}) RETURN t.qualified_name AS test, t.file_path AS file LIMIT 200" "$1"; }
+gq_q_tested_all()        { printf "MATCH (t)-[:TESTS]->(f) RETURN f.qualified_name AS symbol LIMIT 2000"; }
+gq_q_exported()          { printf "MATCH (f) WHERE f.is_exported=true RETURN f.qualified_name AS symbol, f.file_path AS file LIMIT 2000"; }
+gq_q_imports()           { printf "MATCH (a)-[:IMPORTS]->(b) RETURN a.file_path AS src, b.file_path AS dst LIMIT 1000"; }
+gq_q_co_change()         { printf "MATCH (a:File)-[r:FILE_CHANGES_WITH]->(b:File) RETURN a.name AS src, b.name AS dst, r.coupling_score AS score ORDER BY r.coupling_score DESC LIMIT 40"; }
+gq_q_inherits()          { printf "MATCH (c)-[:INHERITS]->(p) RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 500"; }
+gq_q_inherits_sym()      { printf "MATCH (c)-[:INHERITS]->(p) WHERE c.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
+gq_q_derived_sym()       { printf "MATCH (c)-[:INHERITS]->(p) WHERE p.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
+gq_q_writes()            { printf "MATCH (f {name:'%s'})-[:WRITES]->(v) RETURN v.name AS target, v.file_path AS file LIMIT 200" "$1"; }
+gq_q_raises()            { printf "MATCH (f {name:'%s'})-[:RAISES|THROWS]->(e) RETURN e.name AS error, e.qualified_name AS qualified LIMIT 200" "$1"; }
+gq_q_raisers()           { printf "MATCH (f)-[:RAISES|THROWS]->(e {name:'%s'}) RETURN f.qualified_name AS raiser, f.file_path AS file LIMIT 200" "$1"; }
+gq_q_node_props()        { printf "MATCH (f) RETURN f.qualified_name AS q, f.complexity AS c, f.cognitive AS cog, f.is_entry_point AS ep LIMIT 10000"; }
+gq_q_risk()              { printf "MATCH (f) WHERE f.unguarded_recursion=true OR f.alloc_in_loop=true OR f.recursion_in_loop=true OR f.linear_scan_in_loop=true RETURN f.qualified_name AS symbol, f.file_path AS file, f.complexity AS complexity, f.unguarded_recursion AS unguarded_recursion, f.alloc_in_loop AS alloc_in_loop, f.recursion_in_loop AS recursion_in_loop, f.linear_scan_in_loop AS linear_scan_in_loop LIMIT 200"; }
+
+# ── Runner + classifier ──
+
+# gq_run <project> <cypher>
+# Runs query_graph and echoes the validated raw engine JSON. Builds the JSON
+# payload with jq so a quote/backslash in the query can never produce invalid
+# JSON. Requires MEMORY_BIN (set by find_memory_bin) and jq. Returns:
+#   0  valid JSON emitted on stdout
+#   3  engine unavailable / no binary / non-JSON output  (FAIL-LOUD: the caller
+#      must NOT treat this as an empty true-negative result)
+gq_run() {
+    local project="$1" query="$2"
+    [[ -n "${MEMORY_BIN:-}" ]] || return 3
+    command -v jq >/dev/null 2>&1 || return 3
+    local payload res
+    payload="$(jq -n --arg p "$project" --arg q "$query" '{project:$p, query:$q}')" || return 3
+    res="$(memory_cli query_graph "$payload" 2>/dev/null || true)"
+    [[ -n "$res" ]] || return 3
+    printf '%s' "$res" | jq -e . >/dev/null 2>&1 || return 3
+    printf '%s' "$res"
+}
+
+# gq_rows_len <json> -> integer row count (0 on parse failure).
+gq_rows_len() {
+    printf '%s' "$1" | jq -r '(.rows // []) | length' 2>/dev/null || printf '0'
+}
+
+# gq_symbol_status <project> <sym_esc> <result_json> -> ok | no-edges | no-match
+# Fail-loud disambiguation (Guardrail 4): an empty result is only a true negative
+# ("no-edges") when the node actually exists; otherwise it is "no-match". An
+# existence probe runs only when the primary result is empty (hot path stays one
+# query).
+gq_symbol_status() {
+    local project="$1" sym="$2" result="$3"
+    if [[ "$(gq_rows_len "$result")" -gt 0 ]]; then
+        printf 'ok'; return
+    fi
+    local ex
+    ex="$(gq_run "$project" "$(gq_q_exists "$sym")" || true)"
+    if [[ -n "$ex" && "$(gq_rows_len "$ex")" -gt 0 ]]; then
+        printf 'no-edges'
+    else
+        printf 'no-match'
+    fi
+}

package/scripts/tools/cycle-detect.sh

@@ -15,8 +15,8 @@
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine/data unavailable.
 set -euo pipefail
 
-# shellcheck source=_lib.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
 
 REPO="."
 
@@ -31,8 +31,10 @@ Flags:
   --repo DIR  Repository root (default: cwd).
   --help      Show this help.
 
-Output: JSON {cycles:[[a,b],[a,b,c]], source}. Fallback when the engine is
-unavailable: {"cycles":[],"source":"unavailable"}, exit 2.
+Output: JSON {cycles:[[a,b],[a,b,c]], truncated, source}. `truncated` is true
+when either cycle query hit its LIMIT (results are a sample, not exhaustive).
+Fallback when the engine is unavailable: {"cycles":[],"source":"unavailable"},
+exit 2.
 EOF
 }
 
@@ -60,20 +62,21 @@ command -v jq >/dev/null 2>&1 || unavailable
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || unavailable
 
-# 2-cycles: a -> b -> a (dedup with a.qualified_name < b.qualified_name).
-Q2="MATCH (a:Function)-[:CALLS]->(b:Function)-[:CALLS]->(a) WHERE a.qualified_name < b.qualified_name RETURN a.qualified_name AS a, b.qualified_name AS b LIMIT 100"
-# 3-cycles: a -> b -> c -> a.
-Q3="MATCH (a:Function)-[:CALLS]->(b:Function)-[:CALLS]->(c:Function)-[:CALLS]->(a) RETURN a.qualified_name AS a, b.qualified_name AS b, c.qualified_name AS c LIMIT 100"
-
-R2="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q2\"}" || echo '{}')"
-R3="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q3\"}" || echo '{}')"
+# 2- and 3-node CALLS cycles. Cypher lives in _graph_queries.sh (label-agnostic;
+# the Phase 0 fix — code units are mostly :Method, and CALLS only connects
+# callables). LIMIT 100 caps each, so results are a sample, not exhaustive.
+R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)" || echo '{}')"
+R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)" || echo '{}')"
 
 # Guard against empty/non-JSON engine output so --argjson never aborts the script.
 echo "$R2" | jq -e . >/dev/null 2>&1 || R2='{}'
 echo "$R3" | jq -e . >/dev/null 2>&1 || R3='{}'
 
 jq -n --argjson r2 "$R2" --argjson r3 "$R3" '
-    {
-      cycles: (((($r2.rows) // []) + (($r3.rows) // []))),
-      source: "memory-graph"
-    }'
+    ( ((($r2.rows) // []) | length) >= 100
+      or ((($r3.rows) // []) | length) >= 100 ) as $trunc
+    | {
+        cycles: (((($r2.rows) // []) + (($r3.rows) // []))),
+        truncated: $trunc,
+        source: "memory-graph"
+      }'

package/scripts/tools/graph-callers.sh

@@ -1,38 +1,54 @@
 #!/usr/bin/env bash
-# graph-callers.sh — enumerate direct callers of a function, from the knowledge graph.
+# graph-callers.sh — enumerate callers of a function, from the knowledge graph.
 #
 # Replaces `graph --query --symbol <name> --mode callers`. Backed by the
-# codebase-memory-mcp engine via a single-hop CALLS openCypher pattern (the
-# dialect handles fixed-length patterns reliably).
+# codebase-memory-mcp engine. All Cypher lives in _graph_queries.sh (single
+# source of query truth); this entrypoint only parses args and shapes JSON.
 #
 # Usage:
 #   scripts/tools/graph-callers.sh --repo DIR --symbol NAME
+#                                  [--transitive[=N]] [--prod-only] [--qualified]
 #
-# Output: JSON {symbol, callers:[{name,file}], source}.
+# Output: JSON {symbol, callers:[{name,file[,hop]}], status, source}.
 #   source = "memory-graph" | "unavailable"
+#   status = "ok" | "no-edges" | "no-match" | "unavailable"
+#            (fail-loud: distinguishes node-not-found from node-has-no-callers
+#             from engine-unavailable — never a bare [] that reads as a true
+#             negative).
 #
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
 set -euo pipefail
 
-# shellcheck source=_lib.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
 
 REPO="."
 SYMBOL=""
+TRANSITIVE=0
+DEPTH=3
+PROD_ONLY=0
+QUALIFIED=0
 
 usage() {
     cat <<'EOF'
-graph-callers.sh — direct callers of a function.
+graph-callers.sh — callers of a function from the knowledge graph.
 
 Usage:
-  scripts/tools/graph-callers.sh --repo DIR --symbol NAME
+  scripts/tools/graph-callers.sh --repo DIR --symbol NAME [options]
 
 Flags:
-  --repo DIR     Repository root (default: cwd).
-  --symbol NAME  Function name to find callers of (required).
-  --help         Show this help.
+  --repo DIR      Repository root (default: cwd).
+  --symbol NAME   Function name to find callers of (required).
+  --transitive[=N] Transitive (upstream) callers via the trace_path expander,
+                  depth N (default 3). Adds a `hop` field per caller.
+  --prod-only     Best-effort exclude test/mock callers (is_test=false AND not
+                  under tests/). is_test is partial in the engine, so this is a
+                  heuristic, not a guarantee. Ignored with --transitive.
+  --qualified     Match SYMBOL against qualified_name instead of name (use to
+                  disambiguate same-named nodes). Ignored with --transitive.
+  --help          Show this help.
 
-Output: JSON {symbol, callers, source}. Exit 2 when engine unavailable.
+Output: JSON {symbol, callers, status, source}. Exit 2 when engine unavailable.
 EOF
 }
 
@@ -40,6 +56,10 @@ while [[ $# -gt 0 ]]; do
     case "$1" in
         --repo) REPO="$2"; shift 2;;
         --symbol) SYMBOL="$2"; shift 2;;
+        --transitive) TRANSITIVE=1; shift;;
+        --transitive=*) TRANSITIVE=1; DEPTH="${1#*=}"; shift;;
+        --prod-only) PROD_ONLY=1; shift;;
+        --qualified) QUALIFIED=1; shift;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -47,13 +67,14 @@ done
 
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$SYMBOL" ]] || { echo "ERROR: --symbol is required" >&2; usage >&2; exit 1; }
+[[ "$DEPTH" =~ ^[0-9]+$ ]] || { echo "ERROR: --transitive depth must be a non-negative integer" >&2; exit 1; }
 
 REPO_ABS="$(cd "$REPO" && pwd)"
 SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
 
 unavailable() {
-    jq -n --arg s "$SYMBOL" '{symbol:$s, callers:[], source:"unavailable"}' 2>/dev/null \
-        || echo '{"callers":[],"source":"unavailable"}'
+    jq -n --arg s "$SYMBOL" '{symbol:$s, callers:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
+        || echo '{"callers":[],"status":"unavailable","source":"unavailable"}'
     exit 2
 }
 
@@ -63,12 +84,42 @@ command -v jq >/dev/null 2>&1 || unavailable
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || unavailable
 
-# Escape single quotes in the symbol for the Cypher string literal.
-SYM_ESC="${SYMBOL//\'/\\\'}"
-Q="MATCH (c)-[:CALLS]->(f:Function {name:'$SYM_ESC'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200"
-RES="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q\"}" || echo '{}')"
+SYM_ESC="$(gq_escape "$SYMBOL")"
 
-echo "${RES:-{\}}" | jq --arg s "$SYMBOL" '
+if [[ "$TRANSITIVE" -eq 1 ]]; then
+    # Transitive upstream callers via the trace_path depth-bounded expander.
+    # direction:"both" is the reliable form; we read its .callers array.
+    PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
+        '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
+    RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
+    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+    N="$(echo "$RES" | jq -r '(.callers // []) | length' 2>/dev/null || echo 0)"
+    if [[ "$N" -gt 0 ]]; then STATUS="ok"; else
+        EX="$(gq_run "$PROJECT" "$(gq_q_exists "$SYM_ESC")" || true)"
+        if [[ -n "$EX" && "$(gq_rows_len "$EX")" -gt 0 ]]; then STATUS="no-edges"; else STATUS="no-match"; fi
+    fi
+    echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
+        {symbol:$s,
+         callers: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         status:$st, source:"memory-graph"}'
+    exit 0
+fi
+
+# Direct (single-hop) callers. Pick the builder by mode.
+if [[ "$QUALIFIED" -eq 1 ]]; then
+    Q="$(gq_q_callers_qualified "$SYM_ESC")"
+elif [[ "$PROD_ONLY" -eq 1 ]]; then
+    Q="$(gq_q_callers_prod "$SYM_ESC")"
+else
+    Q="$(gq_q_callers "$SYM_ESC")"
+fi
+
+RES="$(gq_run "$PROJECT" "$Q" || true)"
+[[ -n "$RES" ]] || unavailable
+
+STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
+
+echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
     {symbol:$s,
      callers: [ (.rows // [])[] | {name:.[0], file:.[1]} ],
-     source:"memory-graph"}'
+     status:$st, source:"memory-graph"}'

package/scripts/tools/graph-deps.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# graph-deps.sh — real file/module import graph from the knowledge graph (IMPORTS).
+#
+# graph-tooling-v2 Phase 3/4. The authoritative module-dependency graph, derived
+# from actual IMPORTS edges — not the directory-stub `fan_in` heuristic. Feeds the
+# architecture.md §9 dependency diagram (mermaid-from-graph.sh module-deps) and
+# blast-radius reasoning.
+#
+# Self-imports (src == dst, an artifact of how some languages attribute a file's
+# own symbols) are filtered out so the result is a true cross-file graph.
+#
+# Usage:
+#   scripts/tools/graph-deps.sh --repo DIR [--file PATH]
+#
+# Output: JSON {imports:[{src,dst}], total, truncated, source}. With --file, only
+# edges whose src ends with PATH are kept (a file's outgoing dependencies).
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+FILE=""
+
+usage() {
+    cat <<'EOF'
+graph-deps.sh — real module/file import graph (IMPORTS edges).
+
+Usage:
+  scripts/tools/graph-deps.sh --repo DIR [--file PATH]
+
+Flags:
+  --repo DIR   Repository root (default: cwd).
+  --file PATH  Keep only edges whose source file ends with PATH.
+  --help       Show this help.
+
+Output: JSON {imports:[{src,dst}], total, truncated, source}. Self-imports are
+filtered. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --file) FILE="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"imports":[],"total":0,"source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+RES="$(gq_run "$PROJECT" "$(gq_q_imports)" || true)"
+[[ -n "$RES" ]] || unavailable
+
+echo "$RES" | jq --arg f "$FILE" '
+    [ (.rows // [])[]
+      | {src:.[0], dst:.[1]}
+      | select(.src != null and .dst != null and .src != .dst)
+      | select($f == "" or (.src | endswith($f))) ] as $e
+    | {imports: $e, total: ($e | length),
+       truncated: (((.rows // []) | length) >= 1000),
+       source:"memory-graph"}'

package/scripts/tools/graph-errors.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# graph-errors.sh — error-propagation paths from the knowledge graph (RAISES/THROWS).
+#
+# graph-tooling-v2 Phase 3. Two modes:
+#   --symbol NAME  what error types NAME raises/throws.
+#   --type NAME    who raises/throws error type NAME (fail-closed audits: confirm
+#                  every site that can emit a given error).
+#
+# Usage:
+#   scripts/tools/graph-errors.sh --repo DIR (--symbol NAME | --type NAME)
+#
+# Output (--symbol): {symbol, raises:[{error,qualified}], status, source}
+# Output (--type):   {type, raisers:[{symbol,file}], status, source}
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+SYMBOL=""
+TYPE=""
+
+usage() {
+    cat <<'EOF'
+graph-errors.sh — error propagation (RAISES/THROWS edges).
+
+Usage:
+  scripts/tools/graph-errors.sh --repo DIR (--symbol NAME | --type NAME)
+
+Flags:
+  --repo DIR     Repository root (default: cwd).
+  --symbol NAME  Error types raised/thrown by NAME.
+  --type NAME    Symbols that raise/throw error type NAME.
+  --help         Show this help.
+
+Output: --symbol → {symbol, raises, status, source}; --type → {type, raisers,
+status, source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --symbol) SYMBOL="$2"; shift 2;;
+        --type) TYPE="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+if [[ -n "$SYMBOL" && -n "$TYPE" ]]; then
+    echo "ERROR: use either --symbol or --type, not both" >&2; exit 1
+fi
+[[ -n "$SYMBOL" || -n "$TYPE" ]] || { echo "ERROR: provide --symbol or --type" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    if [[ -n "$TYPE" ]]; then
+        jq -n --arg t "$TYPE" '{type:$t, raisers:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
+            || echo '{"raisers":[],"status":"unavailable","source":"unavailable"}'
+    else
+        jq -n --arg s "$SYMBOL" '{symbol:$s, raises:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
+            || echo '{"raises":[],"status":"unavailable","source":"unavailable"}'
+    fi
+    exit 2
+}
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+if [[ -n "$TYPE" ]]; then
+    SYM_ESC="$(gq_escape "$TYPE")"
+    RES="$(gq_run "$PROJECT" "$(gq_q_raisers "$SYM_ESC")" || true)"
+    [[ -n "$RES" ]] || unavailable
+    STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
+    echo "$RES" | jq --arg t "$TYPE" --arg st "$STATUS" '
+        {type:$t,
+         raisers: [ (.rows // [])[] | {symbol:.[0], file:.[1]} ],
+         status:$st, source:"memory-graph"}'
+else
+    SYM_ESC="$(gq_escape "$SYMBOL")"
+    RES="$(gq_run "$PROJECT" "$(gq_q_raises "$SYM_ESC")" || true)"
+    [[ -n "$RES" ]] || unavailable
+    STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
+    echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
+        {symbol:$s,
+         raises: [ (.rows // [])[] | {error:.[0], qualified:.[1]} ],
+         status:$st, source:"memory-graph"}'
+fi

package/scripts/tools/graph-hierarchy.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# graph-hierarchy.sh — class inheritance from the knowledge graph (INHERITS edges).
+#
+# graph-tooling-v2 Phase 3. Answers base/derived relationships and the impact of a
+# base-class change.
+#   (default)        all INHERITS edges (child → parent).
+#   --symbol NAME    bases of class NAME (what NAME inherits from).
+#   --derived NAME   subclasses of class NAME (who inherits from NAME — the blast
+#                    radius of changing NAME).
+#
+# Usage:
+#   scripts/tools/graph-hierarchy.sh --repo DIR [--symbol NAME | --derived NAME]
+#
+# Output: JSON {edges:[{child,parent}], status, source}.
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+SYMBOL=""
+DERIVED=""
+
+usage() {
+    cat <<'EOF'
+graph-hierarchy.sh — class inheritance (INHERITS edges).
+
+Usage:
+  scripts/tools/graph-hierarchy.sh --repo DIR [--symbol NAME | --derived NAME]
+
+Flags:
+  --repo DIR      Repository root (default: cwd).
+  --symbol NAME   Bases of class NAME (what it inherits from).
+  --derived NAME  Subclasses of class NAME (impact of changing NAME).
+  --help          Show this help.
+
+Output: JSON {edges:[{child,parent}], status, source}. With no class filter,
+emits the full hierarchy. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --symbol) SYMBOL="$2"; shift 2;;
+        --derived) DERIVED="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+if [[ -n "$SYMBOL" && -n "$DERIVED" ]]; then
+    echo "ERROR: use either --symbol or --derived, not both" >&2; exit 1
+fi
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"edges":[],"status":"unavailable","source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+if [[ -n "$SYMBOL" ]]; then
+    SYM_ESC="$(gq_escape "$SYMBOL")"; Q="$(gq_q_inherits_sym "$SYM_ESC")"; PROBE="$SYM_ESC"
+elif [[ -n "$DERIVED" ]]; then
+    SYM_ESC="$(gq_escape "$DERIVED")"; Q="$(gq_q_derived_sym "$SYM_ESC")"; PROBE="$SYM_ESC"
+else
+    Q="$(gq_q_inherits)"; PROBE=""
+fi
+
+RES="$(gq_run "$PROJECT" "$Q" || true)"
+[[ -n "$RES" ]] || unavailable
+
+if [[ -n "$PROBE" ]]; then
+    STATUS="$(gq_symbol_status "$PROJECT" "$PROBE" "$RES")"
+else
+    STATUS="ok"
+fi
+
+echo "$RES" | jq --arg st "$STATUS" '
+    {edges: [ (.rows // [])[] | {child:.[0], parent:.[1]} ],
+     status:$st, source:"memory-graph"}'