fallow_output/audit_focus.rs
1//! Audit focus-map output contracts.
2
3use serde::Serialize;
4
5/// The focus label for a review unit. `Skip` is the SAFE explicit-skip label and
6/// is runtime-backed ONLY: it is producible solely on the paid runtime path
7/// and solely for a unit runtime-proves cold with zero risk signals. Free mode
8/// (no runtime evidence) emits only `ReviewHere` / `NotPrioritized`, never `Skip`
9/// (the build-focus-map labeller cannot reach the `Skip` arm without runtime
10/// input), so the free-tier "rank but never skip" stance holds by construction.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
12#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
13#[serde(rename_all = "kebab-case")]
14pub enum FocusLabel {
15 /// Review this unit.
16 ReviewHere,
17 /// Not prioritized, but still visible in the escape-hatch list.
18 NotPrioritized,
19 /// Safe to skip: runtime evidence proves the unit cold (only `safe_to_delete`
20 /// findings, no hot path) AND it carries no risk signal. Runtime-backed only.
21 Skip,
22}
23
24impl FocusLabel {
25 /// The wire token.
26 #[must_use]
27 pub const fn token(self) -> &'static str {
28 match self {
29 Self::ReviewHere => "review-here",
30 Self::NotPrioritized => "not-prioritized",
31 Self::Skip => "skip",
32 }
33 }
34}
35
36/// A per-unit confidence flag. The EXACT panel-decided strings: a dynamically-
37/// wired or re-export-heavy unit carries one so its static-reachability signal is
38/// not trusted as complete (the anti-silent-de-prioritization guard). The flag
39/// NEVER lowers the score; it is advisory provenance.
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
41#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
42#[serde(rename_all = "kebab-case")]
43pub enum ConfidenceFlag {
44 /// The unit is dynamically wired.
45 DynamicDispatch,
46 /// The unit's reachability runs through re-export barrels.
47 ReExportIndirection,
48}
49
50impl ConfidenceFlag {
51 /// The wire message for this flag.
52 #[must_use]
53 pub const fn message(self) -> &'static str {
54 match self {
55 Self::DynamicDispatch => "low: dynamic dispatch detected",
56 Self::ReExportIndirection => "low: re-export indirection",
57 }
58 }
59}
60
61/// The composite attention score, with the deterministic component sub-scores
62/// kept on the wire so the runtime layer adds its weight without recomputing the
63/// signals.
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
65#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
66pub struct FocusScore {
67 /// Fan-in/out blast-radius component.
68 pub fan_io: u32,
69 /// Security source -> sink taint-touch component (0 until a security pass is
70 /// threaded onto the brief path; the seam is built and tested).
71 pub security_taint: u32,
72 /// Risk-zone component (boundary / public-API / security-sensitive).
73 pub risk_zone: u32,
74 /// Change-shape component (new/widened export, signature change proxy).
75 pub change_shape: u32,
76 /// Runtime-weight component (paid): a hot path (runtime evidence of high
77 /// invocation) adds an invocation-bucketed weight so it amplifies the blast
78 /// and outranks an otherwise-equal cold unit. `0` in free mode (no runtime
79 /// input), so the free-tier total stays the four deterministic components and
80 /// is byte-identical to the no-runtime baseline.
81 #[serde(default, skip_serializing_if = "is_zero")]
82 #[cfg_attr(feature = "schema", schemars(default))]
83 pub runtime: u32,
84 /// The summed total of every present component (the four deterministic ones
85 /// plus the runtime weight).
86 pub total: u32,
87}
88
89/// Whether a `u32` is zero (serde skip predicate so the `runtime` component is
90/// omitted from the wire in free mode, keeping the no-runtime JSON byte-identical).
91#[expect(
92 clippy::trivially_copy_pass_by_ref,
93 reason = "serde skip predicate signature"
94)]
95fn is_zero(value: &u32) -> bool {
96 *value == 0
97}
98
99/// One review unit on the focus map: its file, composite score, label, human
100/// reason, and any confidence flags.
101#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
102#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
103pub struct FocusUnit {
104 /// Root-relative path of the changed file this unit covers.
105 pub file: String,
106 /// The composite attention score and its component breakdown.
107 pub score: FocusScore,
108 /// The focus label (`review-here` / `not-prioritized`, or the runtime-backed
109 /// `skip` on the paid path).
110 pub label: FocusLabel,
111 /// A human-readable reason for the label, built from the present signals.
112 pub reason: String,
113 /// Confidence flags (advisory; never lower the score). Sorted, deduped.
114 #[serde(default, skip_serializing_if = "Vec::is_empty")]
115 pub confidence: Vec<ConfidenceFlag>,
116}
117
118/// The weighted focus map: the ranked `review-here` units plus the FULL
119/// `deprioritized` escape-hatch list, so nothing is hidden.
120///
121/// Completeness invariant (the escape-hatch done-condition): the two lists
122/// partition the unit set, so `review_here.len() + deprioritized.len()` equals
123/// the total unit count by construction.
124#[derive(Debug, Clone, Default, Serialize)]
125#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
126pub struct FocusMap {
127 /// Units labeled `review-here`, ranked by composite score (descending), ties
128 /// broken by path for determinism.
129 pub review_here: Vec<FocusUnit>,
130 /// EVERY de-prioritized unit (`not-prioritized`, plus runtime-backed `skip`
131 /// units on the paid path) -- the escape hatch. Always present and fully
132 /// enumerated so a reviewer can always "show me what you de-prioritized"; the
133 /// human brief collapses it by default and re-expands under
134 /// `--show-deprioritized`. Nothing is ever hidden, including a `skip`.
135 pub deprioritized: Vec<FocusUnit>,
136}
137
138impl FocusMap {
139 /// Total number of units.
140 #[must_use]
141 pub fn total_units(&self) -> usize {
142 self.review_here.len() + self.deprioritized.len()
143 }
144}