hunyi 0.4.0

渾儀 (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

//! Unsafe-confinement declaration DSL — [`UnsafeBoundary`] and its draft chain.

use xuanji::{RuleKey, Severity};

/// An unsafe-confinement boundary: within a target crate, `unsafe` (blocks, `unsafe fn`/`impl`/
/// `trait`, `unsafe extern`) may appear **only under** the declared subtree(s); a site outside all
/// of them reacts. Declared in Rust (the single source of truth), composed at the gate.
///
/// It governs *where* `unsafe` lives (architectural intent), never *whether* it may exist — the
/// crate-wide "no `unsafe`" case is `#![forbid(unsafe_code)]`'s (stronger, compile-time). An empty
/// allowed set or one naming the crate root is a constitution error, keeping this confinement-only
/// (declarative), not a lint.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnsafeBoundary {
    pub(crate) crate_package: String,
    pub(crate) allowed_locations: Vec<String>,
    pub(crate) reason: String,
    pub(crate) anchor: Option<String>,
    pub(crate) severity: Severity,
}

impl UnsafeBoundary {
    /// Stable semantic identity for this unsafe-confinement rule.
    pub fn rule_key(&self) -> RuleKey {
        RuleKey::of(
            "tianheng.rule/hunyi/unsafe-confinement",
            [(
                "allowed",
                super::canonical_path_set(&self.allowed_locations),
            )],
        )
    }

    /// Begin an unsafe-confinement boundary in the crate named `package`.
    pub fn in_crate(package: &str) -> UnsafeCrateDraft {
        UnsafeCrateDraft {
            crate_package: package.to_string(),
        }
    }

    /// The allowed subtree module paths where `unsafe` MAY appear.
    pub fn allowed_locations(&self) -> &[String] {
        &self.allowed_locations
    }

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

crate::dsl::boundary_common!(UnsafeBoundary, UnsafeBoundaryDraft);

/// An unsafe-confinement boundary awaiting its allowed subtree(s).
#[doc(hidden)]
pub struct UnsafeCrateDraft {
    crate_package: String,
}

impl UnsafeCrateDraft {
    /// Confine `unsafe` to the given subtree module path(s) (`::`-delimited containment, so
    /// `crate::ffi` also allows `crate::ffi::raw`). A site outside all of them reacts. An **empty**
    /// set, or one naming the crate root, is a constitution error (exit 2) — use
    /// `#![forbid(unsafe_code)]` for a crate-wide ban.
    pub fn only_under<I, S>(self, locations: I) -> UnsafeBoundaryDraft
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        UnsafeBoundaryDraft {
            crate_package: self.crate_package,
            allowed_locations: locations.into_iter().map(Into::into).collect(),
            severity: Severity::Enforce,
        }
    }
}

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

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