hunyi 0.1.8

渾儀 (Hunyi) — Tianheng's semantic (AST/syn) observation dimension, the complement of the static import boundary. Declare in Rust how a module's public surface must behave: what its API must not expose (types — including named public re-exports and, opt-in, a trait impl's impl-site positions — and no dyn / impl Trait or async fn seam), where a trait may be implemented, that it declares no bare pub, and which markers a type must not acquire — observed via syn, reacted in CI. The heavy syn dependency is quarantined here, never in the core.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

//! Impl-trait-boundary declaration DSL — [`ImplTraitBoundary`] and its draft chain.

use xuanji::Severity;

/// An impl-trait boundary: a module's public API must not **return** a written `impl Trait`
/// (return-position `impl Trait` / RPIT). The **existential** complement of [`DynTraitBoundary`]:
/// where that forbids the *dynamic-dispatch* shape (`dyn`), this forbids the *existential* shape —
/// an unnameable type the caller cannot name, store without boxing, or rely on beyond its declared
/// bounds. Governs **return positions only**: argument-position `impl Trait` (APIT) is *universal*
/// (a caller-chosen generic), not an existential leak, and is never governed; `async fn`'s implicit
/// `impl Future` is a distinct compiler-inserted existential, out of scope. Declared in Rust and
/// composed with the other dimensions at the gate.
///
/// Two depths on one boundary type, selected by the builder (mirroring [`DynTraitBoundary`]):
/// - [`must_not_expose_impl_trait`](ImplTraitModuleDraft::must_not_expose_impl_trait) —
///   **shape-only**: an empty operand set, so *any* returned `impl Trait` reacts.
/// - [`must_not_expose_impl_trait_of`](ImplTraitModuleDraft::must_not_expose_impl_trait_of) —
///   **operand-scoped**: only a returned `impl Trait` whose principal trait resolves into the named
///   `forbidden_operands` set reacts.
///
/// [`DynTraitBoundary`]: crate::DynTraitBoundary
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImplTraitBoundary {
    pub(crate) crate_package: String,
    pub(crate) module: String,
    /// The forbidden trait operands. **Empty ⇒ shape-only** (any returned `impl Trait` reacts); a
    /// named set ⇒ only a returned `impl Trait` whose principal trait canonicalizes into the set.
    pub(crate) forbidden_operands: Vec<String>,
    pub(crate) reason: String,
    pub(crate) anchor: Option<String>,
    pub(crate) severity: Severity,
}

impl ImplTraitBoundary {
    /// Begin an impl-trait boundary in the crate named `package`.
    pub fn in_crate(package: &str) -> ImplTraitCrateDraft {
        ImplTraitCrateDraft {
            crate_package: package.to_string(),
        }
    }

    /// The crate this boundary governs.
    pub fn crate_package(&self) -> &str {
        &self.crate_package
    }

    /// The governed module path (e.g. `crate::core`).
    pub fn module(&self) -> &str {
        &self.module
    }

    /// The forbidden trait operands. Empty ⇒ shape-only (any returned `impl Trait` reacts); a named
    /// set ⇒ only a returned `impl Trait` whose principal trait resolves into the set reacts.
    pub fn forbidden_operands(&self) -> &[String] {
        &self.forbidden_operands
    }

    /// The human-readable reason recorded with the boundary (the repair hint).
    pub fn reason(&self) -> &str {
        &self.reason
    }

    /// Attach a durable governance anchor (e.g. `"ADR-014"`) — a stable pointer into the
    /// project's governance, distinct from the free-text `reason`. Optional; a boundary with
    /// none projects and reacts exactly as before.
    pub fn with_anchor(mut self, anchor: &str) -> Self {
        self.anchor = Some(anchor.to_string());
        self
    }

    /// The durable governance anchor recorded with the boundary, if any.
    pub fn anchor(&self) -> Option<&str> {
        self.anchor.as_deref()
    }

    /// The boundary's severity (`enforce` or `warn`).
    pub fn severity(&self) -> Severity {
        self.severity
    }
}

/// An impl-trait boundary awaiting its module anchor.
#[doc(hidden)]
pub struct ImplTraitCrateDraft {
    crate_package: String,
}

impl ImplTraitCrateDraft {
    /// Anchor the boundary to a module path within the crate (e.g. `crate::core`).
    pub fn module(self, module: &str) -> ImplTraitModuleDraft {
        ImplTraitModuleDraft {
            crate_package: self.crate_package,
            module: module.to_string(),
        }
    }
}

/// A module-anchored boundary awaiting the rule.
#[doc(hidden)]
pub struct ImplTraitModuleDraft {
    crate_package: String,
    module: String,
}

impl ImplTraitModuleDraft {
    /// Forbid the module's public API from **returning** a written `impl Trait` (RPIT) — any
    /// `impl Trait` at any depth in a public function/method return type (and a public trait
    /// method's declared return). Takes no trait operand — *any* returned `impl Trait` reacts
    /// (shape-only). Argument-position `impl Trait` (APIT) and `async fn`'s implicit `impl Future`
    /// are not governed (stated bounds — the former is universal, the latter a distinct form).
    pub fn must_not_expose_impl_trait(self) -> ImplTraitBoundaryDraft {
        ImplTraitBoundaryDraft {
            crate_package: self.crate_package,
            module: self.module,
            forbidden_operands: Vec::new(),
            severity: Severity::Enforce,
        }
    }

    /// Forbid the module's public API from **returning** a `impl Trait` of any **named trait** —
    /// the operand-scoped depth of [`must_not_expose_impl_trait`](Self::must_not_expose_impl_trait).
    /// A returned `impl Trait` whose **principal trait** (its first trait bound) canonicalizes into
    /// `operands` is a violation; a returned `impl Trait` of any other trait passes (so a seam may
    /// allow ergonomic existentials like `impl Iterator` while forbidding `impl crate::Port`). An
    /// `operands` entry may be an exact trait path or a module prefix, and a re-exported/aliased
    /// facade matches its defining path (the same 渾儀 resolver the forbidden-type rule uses).
    ///
    /// Bounds (stated): an **empty** `operands` set degenerates to shape-only (any returned
    /// `impl Trait`) — loud, never an inert no-op. Auto-trait/lifetime bounds are never operands
    /// (only the principal, first, trait). A principal that does not resolve — a bare std trait
    /// (`impl Iterator`/`impl Future` written bare), a macro/glob re-export — is out of the
    /// resolver's stated coverage and not matched; a *resolvable* operand is never silently passed.
    /// Return-position scoping is inherited (APIT and `async fn` are not governed).
    pub fn must_not_expose_impl_trait_of<I, S>(self, operands: I) -> ImplTraitBoundaryDraft
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        ImplTraitBoundaryDraft {
            crate_package: self.crate_package,
            module: self.module,
            forbidden_operands: operands.into_iter().map(Into::into).collect(),
            severity: Severity::Enforce,
        }
    }
}

/// A boundary awaiting severity (optional) and its reason.
#[doc(hidden)]
pub struct ImplTraitBoundaryDraft {
    crate_package: String,
    module: String,
    forbidden_operands: Vec<String>,
    severity: Severity,
}

impl ImplTraitBoundaryDraft {
    /// Make this an advisory (`warn`) boundary: violations are reported but do not fail the
    /// reaction — the first rung of adoption.
    pub fn warn(mut self) -> Self {
        self.severity = Severity::Warn;
        self
    }

    /// Finish the boundary with its human-readable reason (the repair hint).
    pub fn because(self, reason: &str) -> ImplTraitBoundary {
        ImplTraitBoundary {
            crate_package: self.crate_package,
            module: self.module,
            forbidden_operands: self.forbidden_operands,
            reason: reason.to_string(),
            anchor: None,
            severity: self.severity,
        }
    }
}