Keys and Output Contract

SCC Keys and Output Contract

This page documents the SCC metric contract for integrations, policies, and CI tooling.

Config Options

Set config under the scc metric entry (metrics[].config).

metrics:
  - id: scc
    config:
      use_git_history: false
      emit_findings: true
      emit_function_findings: true
      max_cycles_in_ui: 50
      edge_mode: all
      max_findings: 100

Key	Type	Default	Notes
`use_git_history`	bool	`false`	Load git history for `churn`/`hotspot_score` in cycle node tables
`emit_findings`	bool	`true`	Emit cycle findings in `results[].findings`
`emit_function_findings`	bool	`true`	Emit function-level cycle findings when call graph exists
`max_cycles_in_ui`	number	`50`	Max cycles included in `ui_schemas.scc.scc_details`
`edge_mode`	string	`all`	One of `all`, `runtime_only`, `structural_only`
`max_findings`	number	unset	Truncates emitted SCC findings

Canonical Numeric Keys

Module-Level

scc.component_count
scc.cycle_count
scc.max_cycle_size
scc.total_nodes_in_cycles

Function-Level (when call graph exists)

scc.function.component_count
scc.function.cycle_count
scc.function.max_cycle_size
scc.function.total_nodes_in_cycles
scc.function.call_mass
scc.function.cycle_cut_candidates_count

Internal Timing and Debug

scc.phase.deps_ms
scc.phase.values_ms
scc.phase.details_ms
scc.phase.ui_ms
scc.debug.use_git_history
scc.debug.git_history_loaded

These are useful for diagnostics and performance tracking, but most policies should gate on module/function health keys.

Structured Result Entries (`results[].data`)

scc.cycle_summary (table)
scc.cut_candidates (table)
scc.function.cycle_cut_candidates (table, if call graph exists)
scc.condensed_dag (graph)
scc.cycles (json list)
scc.config (json echo of active SCC config)
scc.top_cycles_by_risk (top-k)
scc.top_cut_candidates (top-k)

Example extraction:

arxo analyze --format json | jq '.results[] | select(.id=="scc") | .data[] | .key'

UI Schema Contract (`ui_schemas.scc`)

Typical fields used by UIs and custom dashboards:

health and summary
issues.categories.cycles
issues.categories.cycle_cut_candidates
scc_details[] (cycle microscope payload)
charts[] (cycle size chart)
graphs[] (scc_condensed_dag)
explanations for key scalar metrics

`scc_details[]` shape

Each item includes:

cycle_id, scc_idx
nodes, edges
boundary_in, boundary_out
witness_path
risk_score
cut_candidates[] (from, to, score, rationale)
node_table[] (node_id, centrality, churn, hotspot_score)

Findings Contract

When emit_findings: true, SCC can emit FindingType::CyclicDependency findings with rule IDs:

scc.cycle (module-level cycles)
scc.cycle.function (function-level cycles)

Controls:

emit_findings: false disables all SCC findings.
emit_function_findings: false suppresses function-level findings only.
max_findings truncates final SCC findings count.

Key Naming Notes

Canonical keys emitted by SCC are scc.* and scc.function.*.

Some downstream systems may expose compatibility aliases like scc.module.*. Prefer canonical scc.* keys in new policy and automation code.