@drafthq/draft 3.1.5 → 3.2.0

package/scripts/tools/hotspot-rank.sh

@@ -1,27 +1,33 @@
 #!/usr/bin/env bash
-# hotspot-rank.sh — emit complexity/fan-in-ranked symbols from the knowledge graph.
+# hotspot-rank.sh — complexity-weighted hotspot ranking from the knowledge graph.
 #
-# Backed by the codebase-memory-mcp engine (get_architecture, server-computed
-# hotspot ranking by fan-in). Indexes the repo on demand if needed.
+# Backed by the codebase-memory-mcp engine. Fan-in alone is skewed by
+# name-collision generics (e.g. a logger `info` with fan_in 1022 but complexity 0),
+# so graph-tooling-v2 Phase 4 blends the engine's pre-computed complexity and
+# cognitive scores into the rank: score = fanIn + complexity + cognitive. Entry
+# points are annotated. fan_in still comes from the engine's server-computed
+# hotspot ranking; the per-symbol complexity/cognitive/is_entry_point come from a
+# node-property query and are merged in.
 #
 # Usage:
 #   scripts/tools/hotspot-rank.sh [--repo DIR] [--top N]
 #
-# Output: JSON {hotspots:[{id, name, fanIn}], source}.
+# Output: JSON {hotspots:[{id, name, fanIn, complexity, cognitive, score,
+#               isEntryPoint}], source}.
 #   source = "memory-graph" | "unavailable"
 #
 # 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="."
 TOP=0
 
 usage() {
     cat <<'EOF'
-hotspot-rank.sh — fan-in-ranked symbols from the knowledge graph.
+hotspot-rank.sh — complexity-weighted hotspot ranking from the knowledge graph.
 
 Usage:
   scripts/tools/hotspot-rank.sh [--repo DIR] [--top N]
@@ -31,8 +37,8 @@ Flags:
   --top N     Keep only top N hotspots (default: 0 = all).
   --help      Show this help.
 
-Output: JSON {hotspots:[{id, name, fanIn}], source}.
-  source = "memory-graph" | "unavailable"
+Output: JSON {hotspots:[{id, name, fanIn, complexity, cognitive, score,
+isEntryPoint}], source}. Ranked by score = fanIn + complexity + cognitive.
 
 Exit 0 with results, exit 2 with {"hotspots":[],"source":"unavailable"} when the
 graph engine is unavailable.
@@ -68,10 +74,31 @@ PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 
 ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"hotspots\"]}" || true)"
 [[ -n "$ARCH_JSON" ]] || unavailable
-
-echo "$ARCH_JSON" | jq --argjson top "$TOP" '
-    {
-      hotspots: ([ (.hotspots // [])[] | {id: .qualified_name, name: .name, fanIn: .fan_in} ]
-                 | if $top > 0 then .[0:$top] else . end),
-      source: "memory-graph"
-    }'
+echo "$ARCH_JSON" | jq -e . >/dev/null 2>&1 || unavailable
+
+# Pre-computed complexity/cognitive/is_entry_point per symbol (merged onto fan-in).
+PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props)" || echo '{"rows":[]}')"
+echo "$PROPS_JSON" | jq -e . >/dev/null 2>&1 || PROPS_JSON='{"rows":[]}'
+
+# Merge via temp files (the props row set can exceed argv limits on large repos).
+TMP_ARCH="$(mktemp)"; TMP_PROPS="$(mktemp)"
+trap 'rm -f "$TMP_ARCH" "$TMP_PROPS"' EXIT
+printf '%s' "$ARCH_JSON" > "$TMP_ARCH"
+printf '%s' "$PROPS_JSON" > "$TMP_PROPS"
+
+jq -n --slurpfile arch "$TMP_ARCH" --slurpfile props "$TMP_PROPS" --argjson top "$TOP" '
+    (($props[0].rows) // []) as $prows
+    | (reduce $prows[] as $r ({};
+          .[$r[0]] = {c:((($r[1]) // "0") | tonumber? // 0),
+                      cog:((($r[2]) // "0") | tonumber? // 0),
+                      ep:((($r[3]) | tostring) == "true")})) as $pmap
+    | [ (($arch[0].hotspots) // [])[]
+        | (.qualified_name) as $q
+        | ($pmap[$q] // {c:0, cog:0, ep:false}) as $p
+        | {id:$q, name:.name, fanIn:(.fan_in // 0),
+           complexity:$p.c, cognitive:$p.cog,
+           score:((.fan_in // 0) + $p.c + $p.cog),
+           isEntryPoint:$p.ep} ]
+    | sort_by(-.score)
+    | (if $top > 0 then .[0:$top] else . end) as $h
+    | {hotspots:$h, source:"memory-graph"}'

package/scripts/tools/mermaid-from-graph.sh

@@ -1,21 +1,27 @@
 #!/usr/bin/env bash
 # mermaid-from-graph.sh — emit Mermaid diagrams from the knowledge graph.
 #
-# Backed by the codebase-memory-mcp engine. Two diagrams:
-#   module-deps : file co-change coupling (FILE_CHANGES_WITH edges) as a flowchart.
+# Backed by the codebase-memory-mcp engine. Diagrams:
+#   module-deps : real file/module dependency graph (IMPORTS edges) as a flowchart.
+#                 This is the auto-derived dependency diagram for architecture.md
+#                 §9 (graph-tooling-v2 Phase 4) — it replaces the prior co-change
+#                 proxy with actual import edges.
+#   co-change   : file co-change coupling (FILE_CHANGES_WITH edges) — the hidden,
+#                 git-history dependency proxy (the prior module-deps behavior,
+#                 still available explicitly).
 #   proto-map   : detected service routes (Route nodes) as a flowchart.
 #
 # When the engine is unavailable, emits an empty diagram stub and exits 2 so
 # consuming skills can degrade gracefully.
 #
 # Usage:
-#   scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|proto-map]
+#   scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|co-change|proto-map]
 #
 # 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="."
 DIAGRAM="module-deps"
@@ -25,11 +31,12 @@ usage() {
 mermaid-from-graph.sh — emit Mermaid diagrams from the knowledge graph.
 
 Usage:
-  scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|proto-map]
+  scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|co-change|proto-map]
 
 Flags:
   --repo DIR      Repository root (default: cwd).
-  --diagram NAME  module-deps (default) or proto-map.
+  --diagram NAME  module-deps (default, IMPORTS edges), co-change
+                  (FILE_CHANGES_WITH coupling), or proto-map (routes).
   --help          Show this help.
 
 Exit 0 with diagram output, exit 2 with an empty stub when the engine is unavailable.
@@ -70,9 +77,22 @@ command -v jq >/dev/null 2>&1 || stub
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || stub
 
+# module-deps: real IMPORTS edges (the auto-derived dependency graph). Self-imports
+# (src == dst) are dropped so the diagram is a true cross-file graph. Capped at 40
+# edges for readability.
 render_module_deps() {
-    local q="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"
-    local res; res="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$q\"}" || echo '{}')"
+    local res; res="$(gq_run "$PROJECT" "$(gq_q_imports)" || echo '{}')"
+    local edges; edges="$(echo "${res:-{\}}" | jq -r '
+        [ (.rows // [])[] | {s:(.[0]|tostring), d:(.[1]|tostring)}
+          | select(.s != "" and .d != "" and .s != .d) ]
+        | unique | .[0:40][] | "    \"" + .s + "\" --> \"" + .d + "\""' 2>/dev/null || true)"
+    if [[ -z "$edges" ]]; then return 1; fi
+    printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"
+}
+
+# co-change: FILE_CHANGES_WITH coupling (the prior module-deps proxy).
+render_co_change() {
+    local res; res="$(gq_run "$PROJECT" "$(gq_q_co_change)" || echo '{}')"
     local edges; edges="$(echo "${res:-{\}}" | jq -r '(.rows // [])[] | "    \"" + (.[0]|tostring) + "\" --> \"" + (.[1]|tostring) + "\""' 2>/dev/null || true)"
     if [[ -z "$edges" ]]; then return 1; fi
     printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"
@@ -87,6 +107,7 @@ render_proto_map() {
 
 case "$DIAGRAM" in
     module-deps) render_module_deps || stub ;;
+    co-change)   render_co_change || stub ;;
     proto-map)   render_proto_map || stub ;;
-    *) echo "Unknown --diagram '$DIAGRAM' (expected module-deps|proto-map)" >&2; exit 1 ;;
+    *) echo "Unknown --diagram '$DIAGRAM' (expected module-deps|co-change|proto-map)" >&2; exit 1 ;;
 esac