Crate code_ranker_plugin_api 

code-ranker-plugin-api

The contract everything in Code Ranker builds on: a generic property-graph model plus the LanguagePlugin trait. This crate is the foundation — it depends on nothing else from Code Ranker and re-exports nothing. Every other crate (graph operations, complexity, language plugins, viewer, cli) depends on this.

Model

Analysis produces a Graph of **Node**s connected by **Edge**s. A node is anything we analyze: today a source file (kind == "file"), tomorrow a folder, module, function, variable or line — with no model change. kind is a free-form String (the plugin’s own vocabulary); the core never interprets it, it only stores and projects.

Both nodes and edges carry free-form Attributes (string key → scalar AttrValue). There is no fixed, file/language-specific field set: the plugin chooses keys (path, loc, visibility, version, or language-specific ones), the orchestrator adds computed keys (metrics, cycle), and the core reads only the keys it understands. Each level describes its keys with an AttributeSpec dictionary (type + label/hint), so the UI knows what each key means and what it can do with it.

Responsibilities

A LanguagePlugin is a pure parser: it turns a workspace into nodes + edges at a requested level (by name; see Level). It does not compute metrics — complexity / cycles / Henry-Kafura / stats are filled in centrally, for all languages, by the orchestrator. The plugin also describes its edge kinds (EdgeKindSpec) and attribute keys (AttributeSpec), so the core scores, draws and labels unknown kinds/keys without hardcoding their names.

Re-exports

pub use attrs::AttrValue;

pub use attrs::Attributes;

pub use attrs::ValueType;

pub use detection::detect_with_marker;

pub use edge::Edge;

pub use graph::Graph;

pub use level::AttributeGroup;

pub use level::AttributeSpec;

pub use level::CycleKindSpec;

pub use level::Direction;

pub use level::EdgeKindSpec;

pub use level::Level;

pub use level::NodeKindSpec;

pub use level::SpecRow;

pub use level::Thresholds;

pub use level::attr_dict;

pub use level::group;

pub use metrics::FunctionUnit;

pub use metrics::MetricInputs;

pub use node::Node;

pub use node::NodeId;

pub use plugin::LanguagePlugin;

pub use plugin::PluginInput;

pub use plugin::PluginRegistration;

pub use plugin::registry;

pub use preset::Preset;

pub use preset::PromptTemplate;

pub use report::ListPatch;

pub use report::ReportOverride;

Modules

attrs

Free-form attributes for nodes and edges — a string-keyed map of scalar values — plus the value-type tag used by the attribute dictionaries.

detection

Generic, language-agnostic project-detection helpers shared by plugins.

edge

A Edge — a directed edge between two nodes (an import, a call, a containment, …). The kind is the plugin’s own vocabulary; its semantics (flow vs structural, label, hint) come from a matching EdgeKindSpec.

graph

Graph — what a plugin’s analyze returns: pure structure, nodes + edges, and nothing computed.

level

Level descriptors + the semantics dictionaries that let the core handle unknown kinds/keys without hardcoding their names, and let the UI render any language/metric set purely from data: edge kinds (EdgeKindSpec), node/edge attributes (AttributeSpec, grouped via AttributeGroup), node kinds (NodeKindSpec) and cycle kinds (CycleKindSpec).

list_override

The report list-override DSL: parse a [report] section into a ReportOverride of per-list ListPatches, plus the generic op-table primitives is_list_op_table / patch_value_list reused by the TOML inheritance merge (crate::toml_merge::deep_merge).

log

Shared stderr progress/timing log.

metrics

The plugin↔orchestrator metric contract: the raw tier-1 counts a language plugin measures for one unit (MetricInputs) and a sub-file unit carrying them (FunctionUnit).

node

The Node — anything we analyze. Today a source file (kind == "file"), later a folder / module / function / variable / line, with no model change.

plugin

The LanguagePlugin trait + its PluginInput.

preset

The Prompt-Generator Preset DTO.

report

Per-language overrides of the global report view/stat lists.

toml_merge

Generic TOML table inheritance merge — the primitive both the language plugins (defaults.toml ⊕ [base] ⊕ <lang>.toml) and the CLI (built-in defaults ⊕ a project code-ranker.toml) layer config with. Lives in code-ranker-plugin-api so neither consumer reaches into a sibling crate.

Functions

default_cycle_kinds

The generic cycle-kind keys (mutual / chain) a file-based plugin’s level declares. The diagnostic vocabulary (label / description = why / remediation = fix) is data, not code: it is filled centrally by the orchestrator from code-ranker-graph’s cycle_specs (the builtin.toml [cycles.*] catalog), so no cycle prose lives here.

default_node_kinds

The generic node-kind palette every file-based plugin seeds its level with: file (a project source unit, blue) and external (a third-party library, amber, flagged external). A plugin may recolor or add kinds.