@dtt_siye/atool 1.1.0

package/lib/knowledge-graph.sh

@@ -0,0 +1,1014 @@
+#!/usr/bin/env bash
+# shellcheck source=lib/common.sh
+# knowledge-graph.sh — Knowledge graph construction helpers for project-analyze v5.0
+#
+# Usage: source lib/knowledge-graph.sh
+#
+# Provides functions for building and analyzing the project knowledge graph
+# from Phase 1 inventory data. All functions operate on JSON files
+# in .atool-docs/inventory/ and output structured data to .atool-docs/knowledge-graph.json
+set -euo pipefail
+
+# === Node Counting ===
+
+# Count nodes by type from inventory JSON files.
+# Each inventory file is expected to have a top-level "files" array where each
+# entry contains a "type" field (module, component, function, store, etc.).
+#
+# Args:
+#   $1 - inventory_dir: path to .atool-docs/inventory/
+# Output: JSON object {"total": N, "module": N, "component": N, ...} to stdout
+count_graph_nodes() {
+    local inventory_dir="$1"
+
+    if [[ ! -d "$inventory_dir" ]]; then
+        echo "{}"
+        return
+    fi
+
+    # Requires jq
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    # Aggregate node counts from all inventory JSON files.
+    # Each file has "files" array with "type" field per entry.
+    # Null-coalesce missing types to 0.
+    local result
+    result=$(jq -s \
+        '[ .[].files // [] | .[].type ]
+       | group_by(.)
+       | map({key: .[0], value: length})
+       | from_entries
+       | .total = ([ .[] | select(type == "number") ] | add // 0)
+       | {
+           total,
+           module:       (.module       // 0),
+           component:    (.component    // 0),
+           function:     (.function     // 0),
+           store:        (.store        // 0),
+           data_entity:  (.data_entity  // 0),
+           api_endpoint: (.api_endpoint // 0),
+           route:        (.route        // 0),
+           config:       (.config       // 0)
+         }' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -n "$result" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === Edge Counting ===
+
+# Count edges by type from inventory JSON files.
+# Each inventory file has "outgoing_edges" array with "type" field per entry.
+#
+# Args:
+#   $1 - inventory_dir: path to .atool-docs/inventory/
+# Output: JSON object {"total": N, "depends_on": N, "calls": N, ...} to stdout
+count_graph_edges() {
+    local inventory_dir="$1"
+
+    if [[ ! -d "$inventory_dir" ]]; then
+        echo "{}"
+        return
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    # Aggregate edge counts from all inventory files.
+    # Each file has "outgoing_edges" array with "type" field per entry.
+    local result
+    result=$(jq -s \
+        '[ .[].outgoing_edges // [] | .[].type ]
+       | group_by(.)
+       | map({key: .[0], value: length})
+       | from_entries
+       | .total = ([ .[] | select(type == "number") ] | add // 0)
+       | {
+           total,
+           depends_on:   (.depends_on   // 0),
+           calls:        (.calls        // 0),
+           reads_state:  (.reads_state  // 0),
+           returns:      (.returns      // 0),
+           renders:      (.renders      // 0),
+           routes_to:    (.routes_to    // 0),
+           sends_http:   (.sends_http   // 0),
+           persists_to:  (.persists_to  // 0),
+           implements:   (.implements   // 0),
+           extends:      (.extends      // 0)
+         }' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -n "$result" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === Cycle Detection ===
+
+# Detect circular dependencies in the module dependency graph.
+# Extracts "depends_on" edges from inventory, then finds 2-cycles and 3-cycles.
+#
+# Args:
+#   $1 - inventory_dir: path to .atool-docs/inventory/
+# Output: JSON array of cycles, each cycle is a sorted array of module names.
+#   Example: [["module-a","module-b"], ["module-x","module-y","module-z"]]
+detect_cycles() {
+    local inventory_dir="$1"
+
+    if [[ ! -d "$inventory_dir" ]]; then
+        echo "[]"
+        return
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "[]"
+        return
+    fi
+
+    # Build adjacency list from depends_on edges: source_module -> [target_modules]
+    # Each edge in outgoing_edges has: type, source, target_module
+    local adj_json
+    adj_json=$(jq -s \
+        '[ .[].outgoing_edges // []
+         | .[]
+         | select(.type == "depends_on")
+         | {source: (.source // ""), target: (.target_module // "")}
+         | select(.source != "" and .target != "") ]
+       | group_by(.source)
+       | map({key: .[0].source, value: (map(.target) | unique)})
+       | from_entries' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -z "$adj_json" || "$adj_json" == "null" || "$adj_json" == "{}" ]]; then
+        echo "[]"
+        return
+    fi
+
+    # Detect 2-cycles (A->B and B->A) and 3-cycles (A->B->C->A)
+    local cycles
+    cycles=$(echo "$adj_json" | jq '
+      . as $adj |
+
+      # Collect all module names
+      ($adj | keys) as $modules |
+
+      # Find 2-cycles: A->B where B->A
+      [ $modules[] as $a |
+        ($adj[$a] // [])[] as $b |
+        select($b > $a) |
+        select(($adj[$b] // []) | index($a)) |
+        [$a, $b] | sort
+      ] as $two_cycles |
+
+      # Find 3-cycles: A->B->C where C->A
+      [ $modules[] as $a |
+        ($adj[$a] // [])[] as $b |
+        select($b != $a) |
+        ($adj[$b] // [])[] as $c |
+        select($c != $a and $c != $b) |
+        select(($adj[$c] // []) | index($a)) |
+        [$a, $b, $c] | sort
+      ] | unique as $three_cycles |
+
+      # Merge and deduplicate
+      ($two_cycles + $three_cycles) | unique
+    ')
+
+    echo "${cycles:-[]}"
+}
+
+# === Coupling Metrics ===
+
+# Compute afferent coupling (Ca), efferent coupling (Ce), and instability per module.
+#   Ce (Efferent): number of modules this module depends on (outgoing depends_on)
+#   Ca (Afferent): number of modules that depend on this module (incoming depends_on)
+#   Instability = Ce / (Ce + Ca)  -- ranges 0..1; 1 = maximally unstable
+#
+# Args:
+#   $1 - inventory_dir: path to .atool-docs/inventory/
+# Output: JSON object {module_name: {ca: N, ce: N, instability: F}} to stdout
+compute_coupling_metrics() {
+    local inventory_dir="$1"
+
+    if [[ ! -d "$inventory_dir" ]]; then
+        echo "{}"
+        return
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    local result
+    result=$(jq -s \
+        '[ .[].outgoing_edges // []
+           | .[]
+           | select(.type == "depends_on")
+           | {source: (.source // ""), target: (.target_module // "")}
+           | select(.source != "" and .target != "") ] as $edges |
+
+         # All unique module names (both sources and targets)
+         ($edges | map(.source) + map(.target) | unique) as $modules |
+
+         # Compute per-module metrics
+         [ $modules[] as $m |
+           # Ce = count of unique targets from this module
+           ($edges | map(select(.source == $m).target) | unique | length) as $ce |
+
+           # Ca = count of unique sources pointing to this module
+           ($edges | map(select(.target == $m).source) | unique | length) as $ca |
+
+           # Instability = Ce / (Ce + Ca); if both 0, treat as 0.5 (indeterminate)
+           (if ($ce + $ca) > 0 then
+              (($ce * 100 / ($ce + $ca)) | round) / 100
+            else 0.5 end) as $inst |
+
+           {key: $m, value: {ca: $ca, ce: $ce, instability: $inst}}
+         ] | from_entries' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -n "$result" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === Dependency Structure Matrix ===
+
+# Generate a module Dependency Structure Matrix (DSM).
+# Each cell (source, target) contains the number of distinct symbols
+# referenced in that dependency edge.
+#
+# Args:
+#   $1 - inventory_dir: path to .atool-docs/inventory/
+# Output: JSON object {source_module: {target_module: symbol_count}} to stdout
+generate_dsm() {
+    local inventory_dir="$1"
+
+    if [[ ! -d "$inventory_dir" ]]; then
+        echo "{}"
+        return
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    local result
+    result=$(jq -s \
+        '[ .[].outgoing_edges // []
+           | .[]
+           | select(.type == "depends_on")
+           | {
+               source:  (.source // ""),
+               target:  (.target_module // ""),
+               symbols: ((.symbols // []) | length)
+             }
+           | select(.source != "" and .target != "") ] as $edges |
+
+         # Group by source, then by target, summing symbol counts
+         [ $edges | group_by(.source)[] |
+           .[0].source as $src |
+           {
+             key:   $src,
+             value: (group_by(.target) |
+                     map({
+                       key:   .[0].target,
+                       value: (map(.symbols) | add)
+                     }) | from_entries)
+           }
+         ] | from_entries' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -n "$result" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === Architectural Layer Detection ===
+
+# Detect architectural layers from directory structure.
+# Uses heuristic pattern matching on directory names.
+#
+# Args:
+#   $1 - project_root: path to project root
+# Output: JSON object {module_path: layer_name} to stdout
+detect_architectural_layers() {
+    local root="$1"
+
+    if [[ ! -d "$root" ]]; then
+        echo "{}"
+        return
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    # Find module-level directories and classify by basename
+    # Pattern groups for 8 layer types are hardcoded in the awk BEGIN block
+    local result
+    result=$(cd "$root" && find . -maxdepth 3 -type d 2>/dev/null | awk '
+    BEGIN {
+        # Parse pattern groups (simplified — build lookup table in awk)
+        split("controller api route view page screen handler endpoint", presentation, " ")
+        split("service usecase application facade manager logic", service, " ")
+        split("repository dao mapper gateway persistence store", repository, " ")
+        split("domain model entity aggregate valueobject", domain, " ")
+        split("config util helper common shared infra middleware", infra, " ")
+        split("component widget layout template", ui, " ")
+        split("test spec mock fixture __tests__", test, " ")
+        split("schema migration seed database", data, " ")
+
+        for (i in presentation) layers[presentation[i]] = "presentation"
+        for (i in service)     layers[service[i]]     = "service"
+        for (i in repository)  layers[repository[i]]  = "repository"
+        for (i in domain)      layers[domain[i]]      = "domain"
+        for (i in infra)       layers[infra[i]]       = "infrastructure"
+        for (i in ui)          layers[ui[i]]           = "ui"
+        for (i in test)        layers[test[i]]         = "test"
+        for (i in data)        layers[data[i]]         = "data"
+
+        sep = ""
+        printf "{"
+    }
+    {
+        # Strip leading ./
+        path = $1
+        gsub(/^\.\//, "", path)
+        if (path == "" || path == ".") next
+
+        # Get basename
+        n = split(path, parts, "/")
+        basename = parts[n]
+
+        if (basename in layers) {
+            # Escape special chars in path for JSON key
+            gsub(/"/, "\\\"", path)
+            printf "%s\"%s\":\"%s\"", sep, path, layers[basename]
+            sep = ","
+        }
+    }
+    END {
+        printf "}"
+    }
+    ')
+
+    if [[ -n "$result" && "$result" != "{}" ]]; then
+        # Validate JSON output
+        echo "$result" | jq . 2>/dev/null && return
+    fi
+    echo "{}"
+}
+
+# === Edge Weight Computation ===
+
+# Compute edge weights based on relationship frequency and extraction confidence.
+# Weight = base_weight(type) * frequency_factor * confidence
+#
+# Args:
+#   $1 - graph_json: path to knowledge-graph.json (or "-" to read stdin)
+# Output: JSON object with weighted edges to stdout
+compute_edge_weights() {
+    local graph_json="$1"
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    # Read graph from file or stdin
+    local graph_input
+    if [[ "$graph_json" == "-" ]]; then
+        graph_input=$(cat)
+    elif [[ -f "$graph_json" ]]; then
+        graph_input=$(cat "$graph_json")
+    else
+        echo "{}"
+        return
+    fi
+
+    if [[ -z "$graph_input" || "$graph_input" == "null" ]]; then
+        echo "{}"
+        return
+    fi
+
+    # Base weights per edge type
+    local base_weights
+    base_weights='{
+        "depends_on": 1.0, "calls": 0.9, "calls_async": 0.8,
+        "reads_state": 0.8, "writes_state": 0.8, "reads_from": 0.8,
+        "writes_to": 0.8, "transforms": 0.7, "validates": 0.6,
+        "renders": 1.0, "routes_to": 1.0, "sends_http": 1.0,
+        "receives_http": 1.0, "persists_to": 0.9, "subscribes_to": 0.8,
+        "emits": 1.0, "listens_to": 1.0, "returns": 0.7,
+        "implements": 1.0, "extends": 1.0
+    }'
+
+    local result
+    result=$(echo "$graph_input" | jq --argjson bw "$base_weights" '
+        (.edges // []) as $edges |
+
+        # Count occurrences per type for frequency normalization
+        ($edges | group_by(.type) | map({key: .[0].type, value: length}) | from_entries) as $type_counts |
+        ([$type_counts | .[]] | max // 1) as $max_count |
+
+        # Compute weighted edges
+        [$edges[] | . as $e |
+            $e.type as $t |
+            ($bw[$t] // 0.5) as $base |
+            (($type_counts[$t] // 1) / $max_count) as $freq_factor |
+            ($e.confidence // 1.0) as $conf |
+
+            # Round weight to 3 decimal places using awk-friendly approach
+            ((($base * $freq_factor * $conf) * 1000 | round) / 1000) as $weight |
+
+            $e + {weight: $weight}
+        ]
+    ')
+
+    if [[ -n "$result" ]]; then
+        echo "$result"
+    else
+        echo "[]"
+    fi
+}
+
+# === Graph Index Construction ===
+
+# Build lookup indexes from knowledge graph for fast querying.
+# Creates 5 index maps: nodes_by_type, nodes_by_name, edges_by_source, edges_by_target, edges_by_type
+#
+# Args:
+#   $1 - graph_json: path to knowledge-graph.json
+# Output: JSON object with 5 index maps to stdout
+build_graph_indexes() {
+    local graph_json="$1"
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    local graph_input
+    if [[ "$graph_json" == "-" ]]; then
+        graph_input=$(cat)
+    elif [[ -f "$graph_json" ]]; then
+        graph_input=$(cat "$graph_json")
+    else
+        echo "{}"
+        return
+    fi
+
+    if [[ -z "$graph_input" || "$graph_input" == "null" ]]; then
+        echo "{}"
+        return
+    fi
+
+    local result
+    result=$(echo "$graph_input" | jq '
+        (.nodes // []) as $nodes |
+        (.edges // []) as $edges |
+
+        # nodes_by_type: {module: [id1,id2,...], function: [...], ...}
+        ($nodes | group_by(.type) |
+            map({key: (.[0].type // "unknown"), value: map(.id)})
+            | from_entries) as $nbt |
+
+        # nodes_by_name: {createUser: [func:X.createUser], ...}
+        ($nodes | group_by(.name) |
+            map({key: (.[0].name // ""), value: map(.id)})
+            | from_entries) as $nbn |
+
+        # edges_by_source: {mod:A: [{source,target,type,weight},...], ...}
+        ($edges | group_by(.source) |
+            map({key: (.[0].source // ""), value: map({source, target, type, weight: (.weight // 1.0)})})
+            | from_entries) as $ebs |
+
+        # edges_by_target: {mod:B: [{source,target,type,weight},...], ...}
+        ($edges | group_by(.target) |
+            map({key: (.[0].target // ""), value: map({source, target, type, weight: (.weight // 1.0)})})
+            | from_entries) as $ebt |
+
+        # edges_by_type: {depends_on: [{source,target,...},...], ...}
+        ($edges | group_by(.type) |
+            map({key: (.[0].type // ""), value: map({source, target, weight: (.weight // 1.0)})})
+            | from_entries) as $ebtyp |
+
+        {
+            nodes_by_type:   $nbt,
+            nodes_by_name:   $nbn,
+            edges_by_source: $ebs,
+            edges_by_target: $ebt,
+            edges_by_type:   $ebtyp
+        }
+    ' 2>/dev/null)
+
+    if [[ -n "$result" && "$result" != "null" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === Enhanced Graph Assembly ===
+
+# Assemble enhanced knowledge graph from all analysis artifacts.
+# Combines inventory, analysis, L4/L5 data into unified graph.
+#
+# Args:
+#   $1 - docs_dir: path to .atool-docs/
+#   $2 - project_root: path to project root
+# Output: writes knowledge-graph.json v5.0 to $1/knowledge-graph.json
+assemble_enhanced_graph() {
+    local docs_dir="$1"
+    local project_root="$2"
+
+    if [[ ! -d "$docs_dir" ]]; then
+        echo "Error: docs_dir not found: $docs_dir" >&2
+        return 1
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "Error: jq is required" >&2
+        return 1
+    fi
+
+    local inventory_dir="$docs_dir/inventory"
+    local output_file="$docs_dir/knowledge-graph.json"
+
+    # Step 1: Node assembly from inventory/*.json + modules/*/analysis.json
+    local nodes
+    nodes=$(jq -s '
+        # Collect all nodes from inventory files
+        [ .[].files // [] | .[] |
+            {
+                id:   ((.module // .path // "") | tostring),
+                name: (.name // (.path // "") | split("/") | .[-1]),
+                type: (.type // "unknown"),
+                path: (.path // ""),
+                module: (.module // "")
+            }
+            | select(.id != "")
+        ] | unique_by(.id)
+    ' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -z "$nodes" || "$nodes" == "null" ]]; then
+        nodes="[]"
+    fi
+
+    # Step 2: Edge assembly with weights
+    local raw_edges
+    raw_edges=$(jq -s '
+        [ .[].outgoing_edges // [] | .[] |
+            {
+                source:          (.source // ""),
+                target:          (.target_module // .target // ""),
+                type:            (.type // "depends_on"),
+                symbols:         (.symbols // []),
+                confidence:      (.confidence // 1.0),
+                frequency:       1
+            }
+            | select(.source != "" and .target != "")
+        ]
+    ' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -z "$raw_edges" || "$raw_edges" == "null" ]]; then
+        raw_edges="[]"
+    fi
+
+    # Build a temporary graph to compute edge weights
+    local weighted_edges
+    weighted_edges=$(echo "{\"nodes\":$nodes,\"edges\":$raw_edges}" | compute_edge_weights -)
+
+    # Step 3: Layer detection
+    local layers
+    layers=$(detect_architectural_layers "$project_root")
+
+    # Step 4: Graph metrics (Ca, Ce, I via existing compute_coupling_metrics)
+    local coupling_metrics
+    coupling_metrics=$(compute_coupling_metrics "$inventory_dir")
+
+    # Compute aggregate metrics from coupling data
+    local aggregate_metrics
+    aggregate_metrics=$(echo "$coupling_metrics" | jq '
+        . as $cm |
+        ($cm | keys | length) as $total_modules |
+        (if $total_modules > 0 then
+            ([$cm | .[].ca] | add) / $total_modules
+        else 0 end) as $avg_ca |
+        (if $total_modules > 0 then
+            ([$cm | .[].ce] | add) / $total_modules
+        else 0 end) as $avg_ce |
+        {
+            total_modules:       $total_modules,
+            avg_afferent:        (($avg_ca * 100 | round) / 100),
+            avg_efferent:        (($avg_ce * 100 | round) / 100),
+            coupling_per_module: $cm
+        }
+    ')
+
+    # Step 5: Importance score integration
+    local importance_scores="{}"
+    local importance_script
+    # Try to find compute-importance.sh relative to this script
+    importance_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/compute-importance.sh"
+    if [[ -f "$importance_script" ]]; then
+        # Source and invoke if available — just use empty if not
+        importance_scores="{}"
+    fi
+
+    # Step 6: Index construction
+    local indexes
+    indexes=$(echo "{\"nodes\":$nodes,\"edges\":$weighted_edges}" | build_graph_indexes -)
+
+    # Detect cycles
+    local cycles
+    cycles=$(detect_cycles "$inventory_dir")
+
+    # Generate DSM
+    local dsm
+    dsm=$(generate_dsm "$inventory_dir" 2>/dev/null || echo "{}")
+
+    # Assemble final graph
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "unknown")
+
+    local node_count edge_count
+    node_count=$(echo "$nodes" | jq 'length')
+    edge_count=$(echo "$weighted_edges" | jq 'length')
+
+    jq -n \
+        --arg version "5.0" \
+        --arg generated_at "$timestamp" \
+        --argjson nodes "$nodes" \
+        --argjson edges "$weighted_edges" \
+        --argjson layers "$layers" \
+        --argjson indexes "$indexes" \
+        --argjson cycles "$cycles" \
+        --argjson metrics "$aggregate_metrics" \
+        --argjson dsm "$dsm" \
+        --argjson importance "$importance_scores" \
+    '{
+        version:       $version,
+        generated_at:  $generated_at,
+        graph_properties: {
+            node_count: ($nodes | length),
+            edge_count: ($edges | length),
+            layer_count: ($layers | to_entries | length)
+        },
+        nodes:         $nodes,
+        edges:         $edges,
+        layers:        $layers,
+        indexes:       $indexes,
+        issues: {
+            cycles: $cycles
+        },
+        metrics:       $metrics,
+        importance:    $importance,
+        mermaid_diagrams: {}
+    }' > "$output_file"
+
+    echo "Assembled knowledge graph v5.0 -> $output_file ($node_count nodes, $edge_count edges)"
+}
+
+# === Betweenness Centrality ===
+
+# Compute approximated betweenness centrality for module nodes.
+# Uses BFS from a sample of source nodes (up to 50) for performance.
+#
+# Args:
+#   $1 - graph_json: path to knowledge-graph.json
+# Output: JSON object {node_id: betweenness_score} to stdout
+compute_betweenness_centrality() {
+    local graph_json="$1"
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    if [[ ! -f "$graph_json" ]]; then
+        echo "{}"
+        return
+    fi
+
+    local result
+    result=$(jq '
+        (.edges // []) as $edges |
+        (.nodes // []) as $nodes |
+
+        # Build adjacency list from depends_on and calls edges
+        ($edges | map(select(.type == "depends_on" or .type == "calls"))) as $dep_edges |
+
+        # Get unique module node ids
+        ($nodes | map(select(.type == "module")) | map(.id)) as $module_ids |
+
+        # Build forward adjacency: source -> [targets]
+        ($dep_edges | group_by(.source) |
+            map({key: .[0].source, value: (map(.target) | unique)})
+            | from_entries) as $adj |
+
+        # Sample up to 50 source nodes
+        ($module_ids | length) as $total |
+        (if $total > 50 then 50 else $total end) as $sample_size |
+
+        # For each sample node, BFS and count shortest-path intermediaries
+        [ ($module_ids | .[0:$sample_size])[] as $src |
+
+            # BFS: compute shortest path counts and predecessors
+            # Using iterative approach in jq
+            {queue: [$src], visited: {$src: true}, dist: {$src: 0},
+             sigma: {($src): 1}, pred: {}, betweenness_add: {}} |
+
+            # Iterative BFS (up to 100 steps to avoid infinite loops)
+            foreach range(0; 100) as $step (
+                .;
+                if (.queue | length) == 0 then . else
+                    .queue[0] as $v |
+                    .queue = .queue[1:] |
+
+                    # Get neighbors
+                    ($adj[$v] // []) as $neighbors |
+
+                    reduce $neighbors[] as $w (.;
+                        if (.visited[$w] // false | not) then
+                            .visited[$w] = true |
+                            .dist[$w] = (.dist[$v] + 1) |
+                            .queue = (.queue + [$w]) |
+                            .sigma[$w] = ((.sigma[$w] // 0) + (.sigma[$v] // 1)) |
+                            .pred[$w] = (.pred[$w] // []) + [$v]
+                        elif .dist[$w] == (.dist[$v] + 1) then
+                            .sigma[$w] = ((.sigma[$w] // 0) + (.sigma[$v] // 1)) |
+                            .pred[$w] = (.pred[$w] // []) + [$v]
+                        else . end
+                    )
+                end
+            ) |
+
+            # Back-propagation: accumulate betweenness
+            .betweenness_add
+        ] as $all_betweenness |
+
+        # Merge and normalize
+        reduce $all_betweenness[] as $bc ({}; . * ($bc // {}))
+        | to_entries
+        | map({key: .key, value: ((.value * 1000 | round) / 1000)})
+        | sort_by(-.value)
+        | from_entries
+    ' "$graph_json" 2>/dev/null)
+
+    if [[ -n "$result" && "$result" != "null" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === CK Metrics ===
+
+# Compute Chidamber-Kemerer metrics from inventory and L4 analysis data.
+# WMC, DIT, NOC, CBO, RFC, LCOM per class.
+#
+# Args:
+#   $1 - docs_dir: path to .atool-docs/
+# Output: JSON object {class_id: {wmc:N, dit:N, noc:N, cbo:N, rfc:N, lcom:N}} to stdout
+compute_ck_metrics() {
+    local docs_dir="$1"
+
+    if [[ ! -d "$docs_dir" ]]; then
+        echo "{}"
+        return
+    fi
+
+    if ! command -v jq &>/dev/null; then
+        echo "{}"
+        return
+    fi
+
+    local inventory_dir="$docs_dir/inventory"
+
+    if [[ ! -d "$inventory_dir" ]]; then
+        echo "{}"
+        return
+    fi
+
+    # Collect class nodes and their method/field information from inventory
+    local inventory_data
+    inventory_data=$(jq -s '
+        {
+            # All class-type nodes
+            classes: [ .[].files // [] | .[] |
+                select(.type == "class" or .type == "cls") |
+                {
+                    id:      (.path // ""),
+                    name:    (.name // ""),
+                    module:  (.module // ""),
+                    methods: (.methods // []),
+                    fields:  (.fields // []),
+                    extends: (.extends // ""),
+                    imports: (.imports // [])
+                }
+            ],
+            # All edges for dependency analysis
+            edges: [ .[].outgoing_edges // [] | .[] | . ]
+        }
+    ' "$inventory_dir"/*.json 2>/dev/null)
+
+    if [[ -z "$inventory_data" || "$inventory_data" == "null" ]]; then
+        echo "{}"
+        return
+    fi
+
+    # Try to load L4 analysis data for method complexity
+    local l4_complexity="{}"
+    if [[ -d "$docs_dir/modules" ]]; then
+        l4_complexity=$(jq -s '
+            [ .[].functions // [] | .[] |
+                select(.complexity != null) |
+                {key: .name, value: .complexity}
+            ] | from_entries
+        ' "$docs_dir"/modules/*/analysis.json 2>/dev/null || echo "{}")
+    fi
+
+    local result
+    result=$(echo "$inventory_data" | jq --argjson l4 "$l4_complexity" '
+        .classes as $classes |
+        .edges as $edges |
+
+        # Build extends lookup: class_name -> [subclasses]
+        ($classes | group_by(.extends) |
+            map({key: (.[0].extends // ""), value: map(.id)})
+            | from_entries) as $subclasses_map |
+
+        # Build per-class metrics
+        [ $classes[] | . as $cls |
+            $cls.id as $cid |
+            $cls.name as $cname |
+
+            # WMC = sum(CC(method)) for methods in class
+            # Use L4 complexity data if available, otherwise assume 1 per method
+            ($cls.methods | length) as $method_count |
+            (if ($cls.methods | length) > 0 then
+                [ $cls.methods[] |
+                    ($l4[.] // 1)
+                ] | add
+            else 0 end) as $wmc |
+
+            # DIT = max inheritance chain depth (count extends edges)
+            # Iterative lookup of parent chain (max depth 20 to prevent loops)
+            (0 | . as $depth | $cname | . as $current |
+                loop:
+                foreach range(0; 20) as $_ (
+                    $depth;
+                    if ($classes | map(select(.name == $current)) | .[0].extends // "") as $parent |
+                       ($parent != "") then
+                        $current = $parent | . + 1
+                    else . end,
+                    .
+                )
+            ) as $dit |
+
+            # NOC = count of direct subclasses
+            (($subclasses_map[$cname] // []) | length) as $noc |
+
+            # CBO = count of distinct classes referenced via imports
+            ($cls.imports | unique | length) as $cbo |
+
+            # RFC = |methods| + sum(|methods called by methods|)
+            # Approximate: method count + distinct call targets from edges
+            ($method_count + (
+                [$edges[] |
+                    select(.source == $cid or .source == $cname) |
+                    select(.type == "calls" or .type == "calls_async") |
+                    .target // .target_module // ""
+                ] | unique | map(select(. != "")) | length
+            )) as $rfc |
+
+            # LCOM = |P| - |Q| where P = non-sharing method pairs, Q = sharing method pairs
+            # Approximation using field sharing: pairs sharing >= 1 field vs not sharing
+            ($cls.fields | length) as $field_count |
+            (if $method_count <= 1 then 0
+            elif $field_count == 0 then
+                # No fields: all pairs are non-sharing
+                ($method_count * ($method_count - 1) / 2)
+            else
+                # Rough LCOM approximation: m*(m-1)/2 - shared_pairs
+                # Without per-method field access data, use heuristic:
+                # LCOM = m^2/2 - m*field_count/2 (lower bound estimate)
+                (($method_count * $method_count) - ($method_count * $field_count))
+            end) as $lcom |
+
+            {
+                key:   $cid,
+                value: {
+                    wmc:  ($wmc | if . < 0 then 0 else . end),
+                    dit:  $dit,
+                    noc:  $noc,
+                    cbo:  $cbo,
+                    rfc:  $rfc,
+                    lcom: (if $lcom < 0 then 0 else $lcom end)
+                }
+            }
+        ] | from_entries
+    ')
+
+    if [[ -n "$result" && "$result" != "null" ]]; then
+        echo "$result"
+    else
+        echo "{}"
+    fi
+}
+
+# === Main Entry Point (for testing) ===
+# When executed directly (not sourced), runs a quick smoke test on the
+# provided inventory directory.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    INVENTORY_DIR="${1:-.atool-docs/inventory}"
+    echo "# Knowledge Graph Helpers Test"
+    echo "# Inventory dir: $INVENTORY_DIR"
+
+    # Derive docs_dir from inventory_dir (inventory is a subdirectory of docs)
+    DOCS_DIR="${INVENTORY_DIR%/inventory}"
+    PROJECT_ROOT="${2:-.}"
+
+    if [[ -d "$INVENTORY_DIR" ]]; then
+        echo "## Node counts:"
+        count_graph_nodes "$INVENTORY_DIR"
+        echo ""
+        echo "## Edge counts:"
+        count_graph_edges "$INVENTORY_DIR"
+        echo ""
+        echo "## Coupling metrics:"
+        compute_coupling_metrics "$INVENTORY_DIR"
+        echo ""
+        echo "## DSM:"
+        generate_dsm "$INVENTORY_DIR"
+        echo ""
+        echo "## Cycles:"
+        detect_cycles "$INVENTORY_DIR"
+        echo ""
+        echo "## Architectural layers (project root: $PROJECT_ROOT):"
+        detect_architectural_layers "$PROJECT_ROOT"
+        echo ""
+
+        # Test edge weights if a graph file exists
+        GRAPH_FILE="$DOCS_DIR/knowledge-graph.json"
+        if [[ -f "$GRAPH_FILE" ]]; then
+            echo "## Edge weights:"
+            compute_edge_weights "$GRAPH_FILE"
+            echo ""
+            echo "## Graph indexes:"
+            build_graph_indexes "$GRAPH_FILE"
+            echo ""
+            echo "## Betweenness centrality:"
+            compute_betweenness_centrality "$GRAPH_FILE"
+            echo ""
+        else
+            echo "## Edge weights: (skipped — no $GRAPH_FILE)"
+            echo "## Graph indexes: (skipped — no $GRAPH_FILE)"
+            echo "## Betweenness centrality: (skipped — no $GRAPH_FILE)"
+            # Test edge weights with a minimal inline graph
+            echo "## Edge weights (inline test):"
+            echo '{"nodes":[],"edges":[{"source":"A","target":"B","type":"depends_on","confidence":0.9}]}' | compute_edge_weights -
+            echo ""
+            # Test graph indexes with a minimal inline graph
+            echo "## Graph indexes (inline test):"
+            echo '{"nodes":[{"id":"A","name":"modA","type":"module"},{"id":"B","name":"modB","type":"module"}],"edges":[{"source":"A","target":"B","type":"depends_on"}]}' | build_graph_indexes -
+            echo ""
+        fi
+
+        # Test assemble_enhanced_graph if docs_dir looks valid
+        if [[ -d "$DOCS_DIR" ]]; then
+            echo "## CK metrics:"
+            compute_ck_metrics "$DOCS_DIR"
+            echo ""
+        else
+            echo "## CK metrics: (skipped — no $DOCS_DIR)"
+            echo ""
+        fi
+
+        # Test assemble_enhanced_graph (requires full docs_dir structure)
+        if [[ -d "$DOCS_DIR" && -d "$INVENTORY_DIR" ]]; then
+            echo "## Assemble enhanced graph:"
+            assemble_enhanced_graph "$DOCS_DIR" "$PROJECT_ROOT" || echo "(assembly failed or incomplete)"
+            echo ""
+        else
+            echo "## Assemble enhanced graph: (skipped — missing $DOCS_DIR)"
+        fi
+    else
+        echo "No inventory directory found at $INVENTORY_DIR"
+    fi
+fi