@drafthq/draft 4.0.0 → 5.0.1

package/scripts/tools/graph-impact.sh

@@ -1,24 +1,28 @@
 #!/usr/bin/env bash
 # graph-impact.sh — blast radius for a file or symbol, from the knowledge graph.
 #
-# Replaces `graph --query --file <path> --mode impact`. Backed by the
-# codebase-memory-mcp engine: combines detect_changes (git-diff → impacted
-# symbols, when querying the working tree) with trace_path callers for a named
-# function (transitive upstream dependents).
+# Everything that depends on the target, up to --depth CALLS hops: callers of the
+# symbol, or callers of anything defined in the file plus the files that import
+# it. Callers inside the target file are not downstream and are skipped.
 #
 # Usage:
 #   scripts/tools/graph-impact.sh --repo DIR (--file PATH | --symbol NAME) [--depth N]
 #
-# Output: JSON {target, kind, impacted:[{name,file,qualified,hop}], source}.
-#   `file` is always a path (empty when the engine carries none); the qualified
-#   name has its own field rather than being emitted as if it were a path.
+# Output: JSON {target, kind, impacted:[{name,file,qualified,hop}], downstream_files,
+#   affected_modules, max_depth, by_category:{code,test}, status, truncated, source}.
+#   `impacted` lists each dependent once at its nearest hop, capped at 200; the
+#   aggregates always cover the full set. `truncated` is true when the list was
+#   capped or the engine row limit was hit. A module is a file's top-level path
+#   segment ("." for root files), as in classify-files.sh.
+#   status = ok | no-edges (target known, nothing depends on it) | no-match
+#            (target unknown to the graph)
 #   source = "memory-graph" | "unavailable"
 #
 # 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="."
 FILE=""
@@ -34,12 +38,13 @@ Usage:
 
 Flags:
   --repo DIR     Repository root (default: cwd).
-  --file PATH    Size impact of a changed file (uses git working-tree diff).
-  --symbol NAME  Transitive callers of a function (default depth 3).
-  --depth N      Caller traversal depth for --symbol (default: 3).
+  --file PATH    Dependents of a file (repo-relative, ./-prefixed, or absolute).
+  --symbol NAME  Dependents (transitive callers) of a function.
+  --depth N      Caller traversal depth (default: 3).
   --help         Show this help.
 
-Output: JSON {target, kind, impacted, source}. Exit 2 when engine unavailable.
+Output: JSON {target, kind, impacted, downstream_files, affected_modules,
+max_depth, by_category, status, truncated, source}. Exit 2 when engine unavailable.
 EOF
 }
 
@@ -70,29 +75,50 @@ if [[ -n "$SYMBOL" ]]; then TARGET="$SYMBOL"; KIND="symbol"; else TARGET="$FILE"
 graph_bootstrap "$REPO" || unavailable "$TARGET" "$KIND"
 
 if [[ -n "$SYMBOL" ]]; then
-    # direction:"both" is the reliable form (the "callers" value returns empty in this engine);
-    # we read the .callers array from it. Payload built with jq so a quote in
-    # --symbol can never corrupt the JSON; an engine failure is unavailable,
-    # never a fabricated empty-impact success.
-    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 'has("callers") and (.callers | type == "array")' >/dev/null 2>&1 \
-        || unavailable "$TARGET" "$KIND"
-    echo "$RES" | jq --arg t "$TARGET" '
-        {target:$t, kind:"symbol",
-         impacted: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
-         source:"memory-graph"}'
+    T_ESC="$(gq_escape "$SYMBOL")"
+    DEPENDENTS=gq_q_dependents_symbol; EXISTS=gq_q_exists
 else
-    # File impact: detect_changes maps the working-tree diff to impacted symbols.
-    PAYLOAD="$(jq -n --arg p "$PROJECT" '{project:$p}')"
-    RES="$(memory_cli detect_changes "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e 'has("impacted_symbols") and (.impacted_symbols | type == "array")' >/dev/null 2>&1 \
-        || unavailable "$TARGET" "$KIND"
-    echo "$RES" | jq --arg t "$TARGET" '
-        {target:$t, kind:"file",
-         impacted: [ (.impacted_symbols // [])[]
-                     | select((.file // "") | endswith($t) or (. == $t))
-                     | {name:.name, file:(.file // ""), hop:1} ],
-         source:"memory-graph"}'
+    # The graph keys files by repo-relative path.
+    REL="${FILE#"$REPO_ABS"/}"; REL="${REL#./}"
+    T_ESC="$(gq_escape "$REL")"
+    DEPENDENTS=gq_q_dependents_file; EXISTS=gq_q_file_exists
 fi
+
+# Accumulate {q,name,file,test,hop} JSONL in a temp file: the row sets of a hot
+# target can exceed argv limits.
+ROWS="$(mktemp)"
+trap 'rm -f "$ROWS"' EXIT
+TRUNC=false
+for ((k = 1; k <= DEPTH; k++)); do
+    R="$(gq_run "$PROJECT" "$("$DEPENDENTS" "$T_ESC" "$k")")" || unavailable "$TARGET" "$KIND"
+    [[ "$(gq_rows_len "$R")" -lt "$GQ_DEP_LIMIT" ]] || TRUNC=true
+    jq -c --argjson k "$k" '.rows[] | {q:(.[0] // ""), name:(.[1] // ""), file:(.[2] // ""),
+        test:((.[3] | tostring) == "true"), hop:$k}' <<< "$R" >> "$ROWS"
+done
+if [[ -n "$FILE" ]]; then
+    R="$(gq_run "$PROJECT" "$(gq_q_importers "$T_ESC")")" || unavailable "$TARGET" "$KIND"
+    [[ "$(gq_rows_len "$R")" -lt "$GQ_DEP_LIMIT" ]] || TRUNC=true
+    jq -c '.rows[] | {q:"", name:.[0], file:.[0], test:false, hop:1}' <<< "$R" >> "$ROWS"
+fi
+
+# Nothing depends on it: a true negative only if the graph knows the target.
+STATUS=ok
+if [[ ! -s "$ROWS" ]]; then
+    EX="$(gq_run "$PROJECT" "$("$EXISTS" "$T_ESC")")" || unavailable "$TARGET" "$KIND"
+    if [[ "$(gq_rows_len "$EX")" -gt 0 ]]; then STATUS=no-edges; else STATUS=no-match; fi
+fi
+
+jq -s --arg t "$TARGET" --arg kind "$KIND" --arg status "$STATUS" --argjson trunc "$TRUNC" '
+    (group_by([.q, .file]) | map(min_by(.hop))) as $u
+    | ($u | map(.file) | map(select(. != "")) | unique) as $files
+    | ($u | map(select(.test) | .file) | unique) as $tests
+    | {target:$t, kind:$kind,
+       impacted: ($u | sort_by(.hop, .file, .name) | .[:200]
+                  | map({name, file, qualified:.q, hop})),
+       downstream_files: $files,
+       affected_modules: ($files | map(if test("/") then split("/")[0] else "." end) | unique),
+       max_depth: ($u | map(.hop) | max // 0),
+       by_category: {code: ($files - $tests | length), test: ($tests | length)},
+       status: $status,
+       truncated: ($trunc or ($u | length) > 200),
+       source: "memory-graph"}' "$ROWS"

package/scripts/tools/graph-init.sh

@@ -62,7 +62,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 [[ -d "$SCOPE" ]] || { echo "ERROR: --scope '$SCOPE' is not a directory" >&2; exit 1; }
-SCOPE_ABS="$(cd "$SCOPE" && pwd)"
+SCOPE_ABS="$(cd "$SCOPE" && pwd -P)"
 SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
 
 # --- Resolve ROOT (bounded by the git toplevel; never escapes the repo) ---
@@ -127,22 +127,17 @@ write_root_link() {
     local status="$1"
     local mod_graph="$SCOPE_ABS/draft/graph"
     mkdir -p "$mod_graph"
-    local rel root_project="unknown" root_commit ts schema="$ROOT_ABS/draft/graph/schema.yaml"
+    local rel root_commit ts
     rel="$(root_link_relpath)"
-    if [[ -f "$schema" ]]; then
-        root_project="$(grep -m1 '^project:' "$schema" 2>/dev/null | sed 's/^project:[[:space:]]*//; s/^"//; s/"$//' || true)"
-        [[ -n "$root_project" ]] || root_project="unknown"
-    fi
     root_commit="$(git -C "$ROOT_ABS" rev-parse --verify --quiet HEAD 2>/dev/null || echo none)"
     ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-    # Every interpolated value goes through json_escape: a repo path or engine
-    # project name carrying a quote or backslash would otherwise emit a
-    # root-link.json that no consumer can parse.
+    # Every interpolated value goes through json_escape: a repo path carrying a
+    # quote or backslash would otherwise emit a root-link.json that no consumer
+    # can parse.
     cat > "$mod_graph/root-link.json" <<EOF
 {
   "root_graph": "$(json_escape "$rel")",
   "root_abs": "$(json_escape "$ROOT_ABS/draft/graph")",
-  "root_project": "$(json_escape "${root_project:-unknown}")",
   "root_commit": "$(json_escape "$root_commit")",
   "status": "$(json_escape "$status")",
   "linked_at": "$ts",

package/scripts/tools/graph-preflight.sh

@@ -47,7 +47,7 @@ while [[ $# -gt 0 ]]; do
 done
 REPO="${REPO:-.}"
 [[ -d "$REPO" ]] || { echo "ERROR: '$REPO' is not a directory" >&2; exit 2; }
-REPO_ABS="$(cd "$REPO" && pwd)"
+REPO_ABS="$(cd "$REPO" && pwd -P)"
 
 # --- formatting (color only on a tty, and never in --json) ---
 if [[ -t 1 && "$JSON_MODE" -eq 0 ]]; then B=$'\e[1m'; G=$'\e[32m'; Y=$'\e[33m'; R=$'\e[31m'; D=$'\e[0m'; else B=""; G=""; Y=""; R=""; D=""; fi
@@ -168,6 +168,10 @@ if find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
   ENGINE_FOUND=true
   VER="$("$ENGINE" --version 2>/dev/null | head -1 || echo '?')"
   ok "Engine: $ENGINE ($VER)"
+  PINNED="$(sed -n 's/^DEFAULT_VERSION="v\{0,1\}\([^"]*\)".*/\1/p' "$SELF_REPO/scripts/fetch-memory-engine.sh" 2>/dev/null | head -1)"
+  if [[ -n "$PINNED" && "${VER##* }" != "$PINNED" ]]; then
+    warn "Engine version ${VER##* } differs from the pinned $PINNED the graph tools are verified against — scripts/fetch-memory-engine.sh --force"
+  fi
   # Numeric-only: the value is emitted bare into the --json report, so a
   # non-numeric field (engine output format drift) would produce invalid JSON.
   LIMIT="$("$ENGINE" config list 2>/dev/null | awk '/auto_index_limit/{print $3}' || true)"
@@ -255,8 +259,7 @@ cat <<EOF
 
 Next step (when ready, from the git root):
   scripts/tools/graph-init.sh --scope . --json &     # or: /draft:init --graph-only
-  ${ENGINE:-codebase-memory-mcp} cli list_projects '{}'
-  ${ENGINE:-codebase-memory-mcp} cli index_status '{"project":"<name>"}'
+  scripts/tools/graph-query.sh --repo . --tool index_status
 EOF
 hr
 exit "$VEXIT"

package/scripts/tools/graph-query.sh

@@ -12,11 +12,12 @@
 #                                a `query` field in --json is scanned for write
 #                                verbs exactly like --cypher.
 #
-# Dialect limits (engine v0.8.x — see _graph_queries.sh for the full list):
-#   SAFE   : fixed-length patterns, `=`, `<`, `STARTS WITH`, `NOT x STARTS WITH`,
-#            `AND`, `OR`, rel-type alternation `[:A|B]`, `count(x)`.
-#   UNSAFE : coalesce(), `<>`/`!=`/`<=`/`>=`, NOT EXISTS(...), NOT (pattern),
-#            WITH-grouping aggregation, multi-pattern joins.
+# Dialect limits (engine v0.9.0 — see _graph_queries.sh for the full list):
+#   SAFE   : comparisons against a literal, `STARTS WITH`, `AND`/`OR`,
+#            variable-length `[:R*1..3]`, rel-type alternation `[:A|B]`,
+#            `coalesce()`, `DISTINCT`, `count(...)`, WITH-aggregation.
+#   UNSAFE : property-to-property comparison, NOT EXISTS(...), NOT (pattern),
+#            path variables, multi-pattern joins. LIMIT applies before DISTINCT.
 # Passthrough returns the engine's raw error, not a silent empty result.
 #
 # Usage:
@@ -52,8 +53,8 @@ Flags:
                  `query` field is write-verb checked like --cypher.
   --help         Show this help.
 
-Dialect: avoid coalesce(), <>, NOT EXISTS, NOT(pattern), WITH-aggregation,
-multi-pattern joins. Use =, <, STARTS WITH, AND/OR, [:A|B] alternation.
+Dialect: avoid property-to-property comparison, NOT EXISTS, NOT(pattern), path
+variables, multi-pattern joins. LIMIT applies before DISTINCT.
 
 Output: raw engine JSON on success; {"source":"unavailable"} (exit 2) when the
 engine is unavailable; exit 1 on invocation error or a rejected write verb.

package/scripts/tools/graph-snapshot.sh

@@ -11,7 +11,7 @@
 # truth; the engine is the structural index over it.
 #
 # Writes one file under <repo>/draft/graph/:
-#   schema.yaml   engine + project metadata + index counts. Its presence is the
+#   schema.yaml   engine metadata + index counts. Its presence is the
 #                 GATE that tells skills the graph engine is wired for this repo
 #                 (see core/shared/graph-query.md Pre-Check). It carries no graph
 #                 data — every structural query goes to the live engine.
@@ -61,30 +61,18 @@ done
 
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
+REPO_ABS="$(cd "$REPO" && pwd -P)"
 SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
 OUT="${OUT_DIR:-$REPO_ABS/draft/graph}"
 
 find_memory_bin "$REPO_ABS" "$SELF_REPO" || { echo "graph engine unavailable — nothing written" >&2; exit 2; }
 command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 2; }
 
-# Index on demand; this is the valuable side-effect — it ensures the engine holds
-# a current index of the repo so live queries resolve.
+# Refresh the engine index (incremental; indexes from scratch when absent). This is
+# the valuable side-effect — live queries resolve against a current index. A failed
+# refresh writes nothing: a fresh `generated_at` over a frozen index would lie.
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || { echo "could not index repo — nothing written" >&2; exit 2; }
-
-# ...then ALWAYS re-index. memory_ensure_index calls index_repository only when the
-# project is ABSENT — correct for the graph-*.sh query wrappers, which must stay
-# cheap — so on an already-indexed repo this tool used to write a gate marker with a
-# fresh `generated_at` over a frozen index: a deleted symbol stayed resolvable, a new
-# one never appeared, and nothing in the output said so. Refreshing is this tool's
-# entire job. The engine indexes incrementally, so the repeat call is cheap.
-REFRESHED="$(memory_index_bounded "$REPO_ABS" 2>/dev/null | jq -r '.project // empty' 2>/dev/null || true)"
-if [[ -z "$REFRESHED" ]]; then
-    echo "index refresh failed — nothing written" >&2
-    exit 2
-fi
-PROJECT="$REFRESHED"
+[[ -n "$PROJECT" ]] || { echo "index refresh failed — nothing written" >&2; exit 2; }
 
 mkdir -p "$OUT"
 
@@ -120,32 +108,29 @@ VER="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}' || echo unknown)"
 
 # Incremental-refresh provenance (graph-tooling-v2 Phase 5): the engine indexes
 # incrementally (content-based, git-aware), so re-indexing only touches changed
-# files. detect_changes reports that working-tree delta — recorded as provenance
-# and echoed so a refresh shows what moved. Best-effort: never aborts the write.
+# files. detect_changes reports that working-tree delta — echoed so a refresh
+# shows what moved, but kept out of the committed marker (it differs per machine
+# and per run, like the path-derived project name and a timestamp would).
+# Best-effort: never aborts the write.
 CHANGES_JSON="$(memory_cli detect_changes "$(jq -n --arg p "$PROJECT" '{project:$p}')" 2>/dev/null || echo '{}')"
 echo "$CHANGES_JSON" | jq -e . >/dev/null 2>&1 || CHANGES_JSON='{}'
 CHANGED_FILES="$(echo "$CHANGES_JSON" | jq -r '.changed_count // (.changed_files | length?) // 0' 2>/dev/null || echo 0)"
 IMPACTED="$(echo "$CHANGES_JSON" | jq -r '(.impacted_symbols | length?) // 0' 2>/dev/null || echo 0)"
 
-# YAML double-quoted scalars: escape backslashes then quotes so an unusual
-# project name or engine version string can never corrupt the marker.
-PROJECT_Y="${PROJECT//\\/\\\\}"; PROJECT_Y="${PROJECT_Y//\"/\\\"}"
+# YAML double-quoted scalar: escape backslashes then quotes so an unusual
+# engine version string can never corrupt the marker.
 VER_Y="${VER//\\/\\\\}"; VER_Y="${VER_Y//\"/\\\"}"
 
 cat > "$OUT/schema.yaml" <<EOF
 # Draft graph gate marker — written by scripts/tools/graph-snapshot.sh
 # Draft is engine-only: this file carries NO graph data. Its presence signals that
 # the local codebase-memory-mcp engine is wired for this repo. Query the engine
-# live via the graph-*.sh wrappers (or \`codebase-memory-mcp cli <tool>\`).
+# live via the graph-*.sh wrappers (graph-query.sh --tool covers the rest).
 # Counts below are point-of-index provenance; the live engine is authoritative.
 engine: codebase-memory-mcp
 engine_version: "$VER_Y"
-project: "$PROJECT_Y"
-generated_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 indexed_nodes: $NODES
 indexed_edges: $EDGES
-changed_files: $CHANGED_FILES
-impacted_symbols: $IMPACTED
 access: engine-live
 EOF
 

package/scripts/tools/graph-traces.sh

@@ -4,7 +4,7 @@
 # graph-tooling-v2 Phase 6. Wraps the engine's ingest_traces to close the
 # static/dynamic gap — dynamic dispatch the static graph misses (e.g. closures,
 # reflection, virtual calls). This is a WRITE path and is gated behind
-# --experimental. NOTE: in engine v0.8.x ingest_traces is accepted but runtime
+# --experimental. NOTE: in engine v0.9.0 ingest_traces is accepted but runtime
 # edge creation is "not yet implemented" — the engine returns its status verbatim.
 #
 # Usage:
@@ -39,7 +39,7 @@ Flags:
   --experimental  Required acknowledgement — this is a write/experimental path.
   --help          Show this help.
 
-NOTE: engine v0.8.x accepts traces but runtime edge creation is not yet
+NOTE: engine v0.9.0 accepts traces but runtime edge creation is not yet
 implemented; the engine's status is returned verbatim.
 
 Output: raw engine JSON; {"source":"unavailable"} (exit 2) when unavailable.

package/scripts/tools/hotspot-rank.sh

@@ -79,7 +79,16 @@ echo "$ARCH_JSON" | jq -e . >/dev/null 2>&1 || unavailable
 # and still reported source:"memory-graph", so a fan-in-only ranking was
 # indistinguishable from a fully measured one. Record the outcome instead, and
 # omit the fields rather than emitting measurements that were never taken.
-if PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props)")"; then
+# Ask for the hotspots by name: a capped scan of every node missed hotspots past
+# the window on large repos and scored them 0 under enrichment "ok".
+NAMES=""
+while IFS= read -r q; do
+    NAMES+="${NAMES:+,}'$(gq_escape "$q")'"
+done < <(jq -r '(.hotspots // [])[].qualified_name // empty' <<< "$ARCH_JSON")
+if [[ -z "$NAMES" ]]; then
+    PROPS_JSON='{"rows":[]}'
+    ENRICHMENT="ok"
+elif PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props "$NAMES")")"; then
     ENRICHMENT="ok"
 else
     PROPS_JSON='{"rows":[]}'

package/scripts/tools/verify-graph-binary.sh

@@ -137,12 +137,24 @@ fi
 
 STATUS="ok"
 
+# The wrappers are verified against the pinned DEFAULT_VERSION. Another version
+# (e.g. a global install on PATH, which outranks the managed one) stays usable,
+# but may speak a different dialect or CLI — say so rather than run it silently.
+VERSION="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}')"
+PINNED="$(sed -n 's/^DEFAULT_VERSION="v\{0,1\}\([^"]*\)".*/\1/p' "$SELF_REPO/scripts/fetch-memory-engine.sh" 2>/dev/null | head -1)"
+if [[ -n "$PINNED" && "$VERSION" != "$PINNED" ]]; then
+  echo "WARNING: engine version $VERSION differs from the pinned $PINNED that Draft's graph tools are verified against." >&2
+  echo "         Install the pinned engine: scripts/fetch-memory-engine.sh --force" >&2
+fi
+
 if [[ $EMIT_JSON -eq 1 ]]; then
-  printf '{"status":"%s","engine_bin":"%s","source":"%s","arch":"%s"}\n' \
-    "$(json_escape "$STATUS")" "$(json_escape "$MEMORY_BIN")" "$(json_escape "$SOURCE")" "$(json_escape "$ARCH")"
+  printf '{"status":"%s","engine_bin":"%s","source":"%s","arch":"%s","version":"%s","pinned_version":"%s"}\n' \
+    "$(json_escape "$STATUS")" "$(json_escape "$MEMORY_BIN")" "$(json_escape "$SOURCE")" "$(json_escape "$ARCH")" \
+    "$(json_escape "$VERSION")" "$(json_escape "$PINNED")"
 else
   echo "Draft graph engine: $MEMORY_BIN"
   echo "  source: $SOURCE (arch=$ARCH)"
+  echo "  version: $VERSION (pinned: ${PINNED:-unknown})"
   echo "  status: $STATUS"
 fi
 

package/skills/implement/SKILL.md

@@ -671,7 +671,7 @@ After a phase passes review, refresh `metadata.json.impact` so future tracks can
    "$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>
    ```
 
-   Aggregate across all files: `downstream_files` = total unique downstream files (deduped), `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.
+   Aggregate across all files: `downstream_files` = count of the union of each query's `downstream_files` array, `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.
 
 3. **Write metadata.json** with the populated `impact` block and `computed_at` set to the current timestamp.