@dtt_siye/atool 1.1.0

package/lib/multi-dimensional-analysis.sh

@@ -0,0 +1,413 @@
+#!/usr/bin/env bash
+# shellcheck source=lib/common.sh
+# multi-dimensional-analysis.sh — Five-dimensional analysis over knowledge graph v5.0
+#
+# Usage: source lib/multi-dimensional-analysis.sh
+#        run_multi_dimensional_analysis <docs_dir> <project_root>
+#
+# Reads .atool-docs/knowledge-graph.json and produces
+# .atool-docs/multi-dimensional-analysis.json with 5 analysis dimensions:
+#   1. Structural — layer violations, architectural health
+#   2. Behavioral — call graph SCCs, call depth, entry points
+#   3. Data — flow rates, schema coupling, data hotspots
+#   4. Quality — CK Metrics integration, composite coupling index
+#   5. Semantic — TF-IDF domain vocabulary, design pattern detection
+set -euo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+# Layer order for violation detection (higher index = lower layer)
+# Presentation depends on Service, Service depends on Repository, etc.
+LAYER_ORDER=("presentation" "ui" "service" "repository" "domain" "infrastructure" "data" "test")
+
+# === Dimension 1: Structural Analysis ===
+
+# Analyze architectural layer violations and module health.
+#
+# Args:
+#   $1 - graph_json: path to knowledge-graph.json
+# Output: JSON object with structural analysis results to stdout
+analyze_structural() {
+    local graph_json="$1"
+
+    if ! command -v jq &>/dev/null || [[ ! -f "$graph_json" ]]; then
+        echo '{}'
+        return
+    fi
+
+    jq '{
+        layer_violation_ratio: (
+            # Count edges that violate layer order
+            [.edges // [] | .[] | select(.type == "depends_on")] as $deps |
+            (.nodes // []) as $nodes |
+            # Build layer lookup
+            ($nodes | map(select(.layer != null and .layer != "")) | map({(.id): .layer}) | add // {}) as $layer_map |
+            # Count violations: source layer should be higher than target layer
+            [$deps[] | select(
+                ($layer_map[.source] // "") as $src_layer |
+                ($layer_map[.target] // "") as $tgt_layer |
+                $src_layer != "" and $tgt_layer != "" and
+                # Check if source depends on a lower layer (violation)
+                ($src_layer == "domain" and ($tgt_layer == "service" or $tgt_layer == "presentation")) or
+                ($src_layer == "repository" and ($tgt_layer == "presentation")) or
+                ($src_layer == "data_entity" and ($tgt_layer != "" and $tgt_layer != "data"))
+            )] | length
+        ),
+        total_cross_layer_edges: (
+            [.edges // [] | .[] | select(.type == "depends_on")] as $deps |
+            (.nodes // []) as $nodes |
+            ($nodes | map(select(.layer != null and .layer != "")) | map({(.id): .layer}) | add // {}) as $layer_map |
+            [$deps[] | select(
+                ($layer_map[.source] // "") != "" and
+                ($layer_map[.target] // "") != "" and
+                ($layer_map[.source] // "") != ($layer_map[.target] // "")
+            )] | length
+        ),
+        god_modules: (
+            [.nodes // [] | .[] | select(.type == "module" and .metrics.Ca > ((.nodes // [] | length) * 0.3)))] | length
+        ),
+        orphan_modules: (
+            [.nodes // [] | .[] | select(.type == "module" and (.metrics.Ca // 0) == 0 and (.metrics.Ce // 0) == 0)] | length
+        ),
+        unstable_cores: (
+            [.nodes // [] | .[] | select(
+                .type == "module" and
+                (.importance // 0) > 0.7 and
+                ((.metrics.instability // 0) > 0.7)
+            )] | map(.id)
+        ),
+        layer_distribution: (
+            [.nodes // [] | .[] | select(.layer != null and .layer != "")] |
+            group_by(.layer) |
+            map({key: .[0].layer, value: length}) |
+            from_entries
+        )
+    }' "$graph_json" 2>/dev/null || echo '{}'
+}
+
+# === Dimension 2: Behavioral Analysis ===
+
+# Analyze call graph structure: SCCs, call depths, entry points.
+#
+# Args:
+#   $1 - graph_json: path to knowledge-graph.json
+# Output: JSON object with behavioral analysis results to stdout
+analyze_behavioral() {
+    local graph_json="$1"
+
+    if ! command -v jq &>/dev/null || [[ ! -f "$graph_json" ]]; then
+        echo '{}'
+        return
+    fi
+
+    jq '{
+        call_edges: ([.edges // [] | .[] | select(.type == "calls" or .type == "calls_async")] | length),
+        entry_points: (
+            # Functions with zero in-degree in call graph
+            [.edges // [] | .[] | select(.type == "calls" or .type == "calls_async")] as $call_edges |
+            [.nodes // [] | .[] | select(.type == "function" or .type == "api_endpoint")] as $funcs |
+            [$funcs[] | select(
+                (($call_edges | map(select(.target == .id)) | length) == 0)
+            )] | map({id: .id, label: .label})
+        ),
+        max_fan_out: (
+            [.edges // [] | .[] | select(.type == "calls" or .type == "calls_async")] |
+            group_by(.source) |
+            map({source: .[0].source, count: length}) |
+            sort_by(-.count) |
+            .[0]
+        ),
+        max_fan_in: (
+            [.edges // [] | .[] | select(.type == "calls" or .type == "calls_async")] |
+            group_by(.target) |
+            map({target: .[0].target, count: length}) |
+            sort_by(-.count) |
+            .[0]
+        ),
+        async_edges: ([.edges // [] | .[] | select(.type == "calls_async")] | length),
+        event_edges: ([.edges // [] | .[] | select(.type == "emits" or .type == "listens_to")] | length),
+        dispatchers: (
+            # Functions with high fan-out (>5 callees) are dispatchers/orchestrators
+            [.edges // [] | .[] | select(.type == "calls")] |
+            group_by(.source) |
+            map({id: .[0].source, callees: length}) |
+            map(select(.callees > 5)) |
+            sort_by(-.callees)
+        ),
+        utilities: (
+            # Functions with high fan-in (>5 callers) are utilities
+            [.edges // [] | .[] | select(.type == "calls")] |
+            group_by(.target) |
+            map({id: .[0].target, callers: length}) |
+            map(select(.callers > 5)) |
+            sort_by(-.callers)
+        )
+    }' "$graph_json" 2>/dev/null || echo '{}'
+}
+
+# === Dimension 3: Data Analysis ===
+
+# Analyze data flow rates, schema coupling, and data hotspots.
+#
+# Args:
+#   $1 - graph_json: path to knowledge-graph.json
+# Output: JSON object with data analysis results to stdout
+analyze_data() {
+    local graph_json="$1"
+
+    if ! command -v jq &>/dev/null || [[ ! -f "$graph_json" ]]; then
+        echo '{}'
+        return
+    fi
+
+    jq '{
+        data_entities: ([.nodes // [] | .[] | select(.type == "data_entity" or .type == "store")] | length),
+        data_edges: ([.edges // [] | .[] | select(
+            .type == "reads_from" or .type == "writes_to" or
+            .type == "transforms" or .type == "validates" or
+            .type == "reads_state" or .type == "writes_state" or
+            .type == "persists_to"
+        )] | length),
+        hotspots: (
+            # Data entities with highest flow rate (writers * readers)
+            [.edges // [] | .[] | select(
+                .type == "reads_from" or .type == "writes_to" or
+                .type == "reads_state" or .type == "writes_state"
+            )] as $data_edges |
+            [.nodes // [] | .[] | select(.type == "data_entity" or .type == "store")] as $data_nodes |
+            [$data_nodes[] | {
+                id: .id,
+                label: .label,
+                writers: ([$data_edges[] | select(.target == .id and (.type == "writes_to" or .type == "writes_state"))] | length),
+                readers: ([$data_edges[] | select(.source == .id and (.type == "reads_from" or .type == "reads_state"))] | length),
+                flow_rate: (
+                    ([$data_edges[] | select(.target == .id and (.type == "writes_to" or .type == "writes_state"))] | length) *
+                    ([$data_edges[] | select(.source == .id and (.type == "reads_from" or .type == "reads_state"))] | length)
+                )
+            }] | sort_by(-.flow_rate) | .[0:10]
+        ),
+        state_mutations: (
+            # Store writes analysis
+            [.edges // [] | .[] | select(.type == "writes_state")] |
+            group_by(.target) |
+            map({store: .[0].target, writers: length}) |
+            sort_by(-.writers)
+        ),
+        persistence_flows: (
+            # Data → DB persistence chains
+            [.edges // [] | .[] | select(.type == "persists_to")] |
+            map({source: .source, target: .target})
+        )
+    }' "$graph_json" 2>/dev/null || echo '{}'
+}
+
+# === Dimension 4: Quality Analysis ===
+
+# Integrate CK Metrics and compute composite coupling index.
+#
+# Args:
+#   $1 - docs_dir: path to .atool-docs/ directory
+# Output: JSON object with quality analysis results to stdout
+analyze_quality() {
+    local docs_dir="$1"
+    local graph_json="$docs_dir/knowledge-graph.json"
+
+    if ! command -v jq &>/dev/null || [[ ! -f "$graph_json" ]]; then
+        echo '{}'
+        return
+    fi
+
+    # Compute composite coupling index per module
+    jq '{
+        modules_analyzed: ([.nodes // [] | .[] | select(.type == "module")] | length),
+        classes_analyzed: ([.nodes // [] | .[] | select(.type == "class")] | length),
+        coupling_index: (
+            # CI(M) = 0.4 * I(M) + 0.3 * CBO/max_CBO + 0.3 * (1 - LCOM_norm)
+            [.nodes // [] | .[] | select(.type == "module" and .metrics != null)] |
+            map({
+                id: .id,
+                label: .label,
+                instability: (.metrics.instability // 0),
+                coupling_index: (
+                    (0.4 * (.metrics.instability // 0)) +
+                    (0.3 * ((.metrics.Ce // 0) / 20)) +  # Normalize Ce by threshold
+                    (0.3 * (1 - 0.5))  # Default LCOM_norm if unknown
+                )
+            }) |
+            sort_by(-.coupling_index) |
+            .[0:10]
+        ),
+        complexity_distribution: (
+            # Distribution of cyclomatic complexity across functions
+            [.nodes // [] | .[] | select(.type == "function" and .metrics.cyclomatic_complexity != null)] |
+            map(.metrics.cyclomatic_complexity) |
+            if length > 0 then {
+                min: min,
+                max: max,
+                avg: ((add / length) * 100 | round / 100),
+                p95: (sort | .[((length * 0.95) | ceil)] // max)
+            } else {} end
+        ),
+        maintainability_distribution: (
+            [.nodes // [] | .[] | select(.type == "module" and .metrics.maintainability_index != null)] |
+            map(.metrics.maintainability_index) |
+            if length > 0 then {
+                min: min,
+                max: max,
+                avg: ((add / length) * 100 | round / 100)
+            } else {} end
+        ),
+        debt_summary: (
+            [.nodes // [] | .[] | select(.metrics.technical_debt_ratio != null)] |
+            map(.metrics.technical_debt_ratio) |
+            if length > 0 then {
+                total_debt_ratio: ((add / length) * 100 | round / 100),
+                high_debt_modules: ([.[] | select(. > 0.20)] | length)
+            } else {} end
+        )
+    }' "$graph_json" 2>/dev/null || echo '{}'
+}
+
+# === Dimension 5: Semantic Analysis ===
+
+# Extract domain vocabulary using TF-IDF and detect design patterns.
+#
+# Args:
+#   $1 - docs_dir: path to .atool-docs/ directory
+# Output: JSON object with semantic analysis results to stdout
+analyze_semantic() {
+    local docs_dir="$1"
+    local graph_json="$docs_dir/knowledge-graph.json"
+
+    if ! command -v jq &>/dev/null || [[ ! -f "$graph_json" ]]; then
+        echo '{}'
+        return
+    fi
+
+    # Domain vocabulary extraction using word frequency from node labels
+    # (Simplified TF-IDF: term frequency across modules)
+    jq '{
+        domain_vocabulary: (
+            # Extract words from function/class/data_entity labels
+            [.nodes // [] | .[] | select(
+                .type == "function" or .type == "class" or .type == "data_entity"
+            ) | .label // "" | split(/(?=[A-Z])|[_\-\s]/) | .[] | select(length > 2)] |
+            group_by(.) |
+            map({term: .[0], frequency: length}) |
+            sort_by(-.frequency) |
+            .[0:30]
+        ),
+        cross_cutting_concerns: (
+            # Detect cross-cutting concerns from tags and edge patterns
+            [.nodes // [] | .[] | select(.tags != null and (.tags | length > 0))] |
+            map(.tags[]) |
+            group_by(.) |
+            map({concern: .[0], count: length}) |
+            sort_by(-.count)
+        ),
+        design_patterns: (
+            # Heuristic pattern detection from node relationships
+            # Strategy: class with multiple implementations of same interface
+            # Observer: emits/listens_to edge patterns
+            # Repository: class implements interface in repository layer
+            # Factory: function returning different types based on input
+            {
+                strategy_candidates: (
+                    [.edges // [] | .[] | select(.type == "implements")] |
+                    group_by(.target) |
+                    map(select(length >= 2)) |
+                    map({interface: .[0].target, implementations: length})
+                ),
+                observer_candidates: (
+                    [.edges // [] | .[] | select(.type == "emits" or .type == "listens_to")] |
+                    group_by(.source) |
+                    map(select(length >= 2)) |
+                    map({emitter: .[0].source, listeners: length})
+                ),
+                repository_pattern: (
+                    [.nodes // [] | .[] | select(
+                        .type == "class" and
+                        (.layer == "repository" or (.label | test("Repository|Repo"; "i")))
+                    )] | map(.id)
+                )
+            }
+        ),
+        tag_cloud: (
+            [.nodes // [] | .[] | select(.tags != null) | .tags[]] |
+            group_by(.) |
+            map({tag: .[0], count: length}) |
+            sort_by(-.count) |
+            .[0:20]
+        )
+    }' "$graph_json" 2>/dev/null || echo '{}'
+}
+
+# === Main Entry Point ===
+
+# Run all 5 analysis dimensions and produce combined output.
+#
+# Args:
+#   $1 - docs_dir: path to .atool-docs/ directory
+#   $2 - project_root: path to project root
+# Output: writes multi-dimensional-analysis.json in docs_dir
+run_multi_dimensional_analysis() {
+    local docs_dir="$1"
+    local project_root="$2"
+    local graph_json="$docs_dir/knowledge-graph.json"
+    local output_file="$docs_dir/multi-dimensional-analysis.json"
+
+    if [[ ! -f "$graph_json" ]]; then
+        log_warn "knowledge-graph.json not found, skipping multi-dimensional analysis"
+        return 0
+    fi
+
+    log_info "Running multi-dimensional analysis..."
+
+    # Run each dimension
+    log_info "  [1/5] Structural analysis..."
+    local structural
+    structural=$(analyze_structural "$graph_json")
+
+    log_info "  [2/5] Behavioral analysis..."
+    local behavioral
+    behavioral=$(analyze_behavioral "$graph_json")
+
+    log_info "  [3/5] Data analysis..."
+    local data
+    data=$(analyze_data "$graph_json")
+
+    log_info "  [4/5] Quality analysis..."
+    local quality
+    quality=$(analyze_quality "$docs_dir")
+
+    log_info "  [5/5] Semantic analysis..."
+    local semantic
+    semantic=$(analyze_semantic "$docs_dir")
+
+    # Combine into single output
+    jq -n \
+        --argjson structural "$structural" \
+        --argjson behavioral "$behavioral" \
+        --argjson data "$data" \
+        --argjson quality "$quality" \
+        --argjson semantic "$semantic" \
+        '{
+            version: "5.0",
+            generated_at: (now | todate),
+            structural: $structural,
+            behavioral: $behavioral,
+            data: $data,
+            quality: $quality,
+            semantic: $semantic
+        }' > "$output_file"
+
+    log_info "Multi-dimensional analysis complete: $output_file"
+}
+
+# === Standalone Execution ===
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    DOCS_DIR="${1:-.atool-docs}"
+    PROJECT_ROOT="${2:-.}"
+    run_multi_dimensional_analysis "$DOCS_DIR" "$PROJECT_ROOT"
+fi