Visibility

Visibility

visibility measures public API boundary leakage and structural concentration risk. This page documents the current v2 key contract (visibility.*).

What It Measures

• Public API exposure from externally visible modules into internal modules
• Structural concentration (hub concentration, entropy, cutpoints, bridges)
• Optional temporal and runtime weighting channels
• Composite risk and confidence score for triage

Output Keys (v2)

Public API channel (visibility.public_api.*)

Key	Meaning
visibility.public_api.available	1 when public API signals are available
visibility.public_api.public_module_count	Number of modules classified as public
visibility.public_api.public_symbol_count	Total public symbols across public modules
visibility.public_api.public_surface_ratio	Share of modules with public surface
visibility.public_api.internal_exposure_ratio	Public -> internal exposure leakage ratio
visibility.public_api.max_public_module_exposure_ratio	Worst public module internal exposure ratio
visibility.public_api.reexport_ratio	Share of public symbols that are re-exports

Structural channel (visibility.structure.*)

Key	Meaning
visibility.structure.out_reach_gini	Concentration of outbound reachability (higher = more concentrated)
visibility.structure.in_reach_gini	Concentration of inbound reachability
visibility.structure.out_reach_entropy	Diversity of outbound reachability (lower = more concentrated)
visibility.structure.cutpoint_ratio	Share of articulation-point modules (single-point structure breaks)
visibility.structure.bridge_ratio	Share of bridge edges (single-link bottlenecks)

Optional channels and composite score

Key	Meaning
visibility.temporal.available	1 when git-history channel is available
visibility.temporal.public_exposure_churn_weighted	Exposure weighted by code churn
visibility.runtime.available	1 when telemetry channel is available
visibility.runtime.telemetry_coverage	Share of modules with mapped runtime activity
visibility.runtime.public_exposure_traffic_weighted	Exposure weighted by runtime traffic
visibility.risk_score	Composite visibility risk score (0..1, higher is worse)
visibility.risk_score.confidence	Confidence in risk score (0..1) based on available channels

Drill-Down Outputs

• visibility.public_api.leakage_edges (table)
• visibility.public_api.top_exposure_modules (top-k)
• visibility.structure.top_out_hubs (top-k)
• visibility.structure.top_in_hubs (top-k)
• visibility.temporal.top_churn_exposure_modules (top-k, when available)
• visibility.runtime.top_traffic_exposure_modules (top-k, when available)

visibility.public_api.leakage_edges columns:

• from_module
• to_module
• from_path
• to_path
• exposure_ratio

Findings Emitted

This metric emits deterministic findings with rule IDs:

• arxo/visibility/high-internal-exposure
• arxo/visibility/public-hub-concentration
• arxo/visibility/brittle-structure-cutpoints
• arxo/visibility/high-churn-public-exposure
• arxo/visibility/high-traffic-public-exposure

Core Formulas

• visibility.public_api.public_surface_ratio = public_module_count / module_count
• visibility.public_api.internal_exposure_ratio = leaked_public_internal_pairs / (public_module_count * internal_module_count)
• visibility.public_api.max_public_module_exposure_ratio = max_public_module(internal_reachable / internal_module_count)

Configuration

metrics:
  - id: visibility
    enabled: true
    config:
      top_k: 10
      channels:
        temporal_mode: auto   # off | auto | force
        runtime_mode: auto    # off | auto | force

Option	Default	Purpose
top_k	10	Limit rows/items for top lists and leakage table
channels.temporal_mode	auto	Git-history channel mode (off, auto, force)
channels.runtime_mode	auto	Telemetry channel mode (off, auto, force)

Channel mode behavior:

• off: do not load channel; emit *.available = 0
• auto: best-effort load; missing prerequisites keep channel unavailable
• force: missing prerequisites fail the metric run

Interpretation

• Lower is better for visibility.risk_score and visibility.public_api.internal_exposure_ratio.
• Check visibility.temporal.available and visibility.runtime.available before acting on channel-weighted keys.
• Prioritize visibility.public_api.leakage_edges and top exposure modules first; they provide actionable boundaries.

Policy Examples

Strict gate

metrics:
  - id: visibility
    enabled: true

policy:
  invariants:
    - metric: visibility.public_api.internal_exposure_ratio
      op: "<="
      value: 0.15
      message: "Public API modules must not leak deeply into internal modules"
    - metric: visibility.structure.cutpoint_ratio
      op: "<="
      value: 0.10
      message: "Avoid brittle articulation-point concentration"
    - metric: visibility.risk_score
      op: "<="
      value: 0.40
      message: "Visibility risk score too high"

Incremental hardening

policy:
  invariants:
    - metric: visibility.public_api.max_public_module_exposure_ratio
      op: "<="
      value: 0.60
    - metric: visibility.runtime.public_exposure_traffic_weighted
      op: "<="
      value: 0.45

Report Walkthrough (JSON excerpt)

{
  "id": "visibility",
  "data": [
    { "key": "visibility.public_api.internal_exposure_ratio", "value": 0.21 },
    { "key": "visibility.structure.cutpoint_ratio", "value": 0.08 },
    { "key": "visibility.risk_score", "value": 0.47 },
    {
      "key": "visibility.public_api.leakage_edges",
      "columns": ["from_module", "to_module", "from_path", "to_path", "exposure_ratio"],
      "rows": [["api/user", "core/auth", "src/api/user.ts", "src/core/auth.ts", 0.72]]
    }
  ],
  "findings": [
    {
      "rule_id": "arxo/visibility/high-internal-exposure",
      "title": "High internal exposure through public API modules"
    }
  ]
}

Migration from Legacy Keys

Legacy reachability summary keys were removed in v2:

• visibility.mean_reachable
• visibility.max_reachable
• visibility.min_reachable
• visibility.median_reachable
• visibility.p90_reachable
• visibility.total_reachable_pairs
• visibility.top_hubs

No compatibility aliases are emitted; update policy invariants to the current visibility.public_api.*, visibility.structure.*, and visibility.risk_score keys.

Related Metrics

• Flow Analysis
• Package Metrics
• Critical Modules
• Change Impact
• Cross-Metric Insights