code_ranker_graph/
lib.rs

1//! Operations over the generic property-graph model defined in
2//! `code-ranker-plugin-api`: cycle detection, Henry-Kafura coupling, aggregate
3//! stats, id relativization, and the serializable [`Snapshot`] artifact.
4//!
5//! Everything here is language-agnostic. Plugins emit a pure
6//! [`api::Graph`](code_ranker_plugin_api::graph::Graph) (structure only); this crate
7//! and the orchestrator enrich it (writing computed values into node `attrs`
8//! by id) and assemble the snapshot. Which edge kinds count as information
9//! flow is read from the level's `edge_kinds` (`EdgeKindSpec.flow`), passed in
10//! as a `flow_kinds` set — there is no hardcoded `uses`/`contains` knowledge.
11
12pub mod attrs;
13pub mod cycles;
14pub mod finalize;
15pub mod hk;
16pub mod level_graph;
17pub mod relativize;
18pub mod serialize;
19pub mod snapshot;
20pub mod stats;
21
22pub use attrs::{num_attr, round_sig3};
23pub use cycles::annotate_cycles;
24pub use finalize::finalize_graph;
25pub use hk::annotate_hk;
26pub use level_graph::{CycleGroup, LevelGraph, LevelUi};
27pub use relativize::{relativize_graph, relativize_level};
28pub use serialize::{to_canonical_string, to_canonical_string_pretty};
29pub use snapshot::{GitInfo, Snapshot, StageTime};
30pub use stats::compute_stats;
31
32use code_ranker_plugin_api::{
33    attrs::ValueType,
34    level::{AttributeGroup, AttributeSpec, Direction, SpecRow, attr_dict, group},
35};
36use std::collections::BTreeMap;
37
38/// The coupling/cycle attribute dictionary produced by [`annotate_hk`](hk::annotate_hk) /
39/// [`annotate_cycles`](cycles::annotate_cycles), plus the `coupling` group. The orchestrator merges these
40/// into each level's `node_attributes` / `attribute_groups`.
41pub fn coupling_specs() -> (
42    BTreeMap<String, AttributeSpec>,
43    BTreeMap<String, AttributeGroup>,
44) {
45    let specs = attr_dict(vec![
46        // No direction: raw fan-in is neutral — broad reuse (good) and bottleneck
47        // risk (bad) pull opposite ways, so a growing/shrinking count carries no
48        // clear verdict.
49        (
50            "fan_in",
51            SpecRow {
52                group: "coupling",
53                label: "Fan-in",
54                name: "Fan-in",
55                short: "Fan-in",
56                description: "Number of nodes that depend on this one. High fan-in means broadly reused.",
57                ..Default::default()
58            },
59        ),
60        // Also neutral: like fan-in, high fan-out is dual — a tangled unit (bad) or
61        // a legitimate coordinator/composition root (fine). The directional coupling
62        // signal lives in `hk`, which already folds in fan_out.
63        (
64            "fan_out",
65            SpecRow {
66                group: "coupling",
67                label: "Fan-out",
68                name: "Fan-out",
69                short: "Fan-out",
70                description: "Number of nodes this one depends on. High fan-out means many \
71                              dependencies. External-library edges are counted separately.",
72                ..Default::default()
73            },
74        ),
75        (
76            "fan_out_external",
77            SpecRow {
78                group: "coupling",
79                label: "Fan-out (external)",
80                description: "Number of distinct external libraries this node depends on.",
81                ..Default::default()
82            },
83        ),
84        (
85            "hk",
86            SpecRow {
87                group: "coupling",
88                value_type: ValueType::Float,
89                label: "HK",
90                name: "Henry–Kafura",
91                short: "HK",
92                description: "Henry–Kafura — combines unit size with incoming/outgoing coupling \
93                              (internal edges only).",
94                formula: "sloc × (fan_in × fan_out)²",
95                calc: "sloc * (fan_in * fan_out) ** 2",
96                direction: Direction::LowerBetter,
97                abbreviate: true,
98            },
99        ),
100        (
101            "cycle",
102            SpecRow {
103                value_type: ValueType::Str,
104                label: "Cycle",
105                short: "Cycle",
106                description: "Cycle kind this node participates in.",
107                ..Default::default()
108            },
109        ),
110    ]);
111
112    let mut groups = BTreeMap::new();
113    groups.insert(
114        "coupling".to_string(),
115        group("Coupling", "Internal coupling (Henry-Kafura)"),
116    );
117    (specs, groups)
118}
code_ranker_graph/lib.rs

code_ranker_graph/
lib.rs
