spec_driven_docs/domain/
rule_id.rs

1//! Rule identifiers: one variant per requirement the specs define.
2//!
3//! A rule ID is an address — `domain:rule` — that a failure message cites and
4//! a reader follows to the sentence that binds. This enum is the compile-time
5//! form of every `` ### `domain:rule` `` heading under the canon's specs; a
6//! parity test in `embedded` holds the two sets equal. Rule prose lives in
7//! the specs, never here.
8
9use std::fmt;
10
11macro_rules! rule_ids {
12    ($($variant:ident => $id:literal,)+) => {
13        /// A `domain:rule` requirement address defined by a spec.
14        #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
15        pub enum RuleId {
16            $(
17                #[doc = $id]
18                $variant,
19            )+
20        }
21
22        impl RuleId {
23            /// Every rule the specs define, in slug order.
24            pub const ALL: &'static [Self] = &[$(Self::$variant),+];
25
26            /// The `domain:rule` slug pair this variant addresses.
27            #[must_use]
28            pub const fn as_str(self) -> &'static str {
29                match self {
30                    $(Self::$variant => $id),+
31                }
32            }
33        }
34    };
35}
36
37rule_ids! {
38    RecordedDimensionOnlyShrinks => "budget-debt:a-recorded-dimension-only-shrinks",
39    DebtIsCreatedByAnExplicitAct => "budget-debt:debt-is-created-by-an-explicit-act",
40    CellCarriesOneReference => "comparison-docs:a-cell-carries-one-reference",
41    ComparisonCarriesALegend => "comparison-docs:a-comparison-carries-a-legend",
42    VerdictCarriesItsWord => "comparison-docs:a-verdict-carries-its-word",
43    EveryTableIsDated => "comparison-docs:every-table-is-dated",
44    TablePipesAreEscaped => "comparison-docs:table-pipes-are-escaped",
45    CitationResolvesToARule => "decision-records:a-citation-resolves-to-a-rule",
46    BodyStaysWithinWordCap => "decision-records:body-stays-within-350-words",
47    FilenameCarriesNoDigit => "decision-records:filename-carries-no-digit",
48    MergedRecordIsPermanent => "decision-records:merged-record-is-permanent",
49    RecordIsNotRevised => "decision-records:record-is-not-revised",
50    DeclaredLocationIsNamedByItsVariable => "distribution:a-declared-location-is-named-by-its-variable",
51    LandingClassifiesItsTargetFirst => "distribution:a-landing-classifies-its-target-first",
52    SeededRuleRunsNoCanonCommand => "distribution:a-seeded-rule-runs-no-canon-command",
53    SkillChecksItsHostBeforeItPlans => "distribution:a-skill-checks-its-host-before-it-plans",
54    SkillHasOneOwner => "distribution:a-skill-has-one-owner",
55    SkillInstallRestoresOnFailure => "distribution:a-skill-install-restores-on-failure",
56    SkillObeysThePortableFormat => "distribution:a-skill-obeys-the-portable-format",
57    SkillPlansBeforeItActs => "distribution:a-skill-plans-before-it-acts",
58    StaleSkillIsNotAConflict => "distribution:a-stale-skill-is-not-a-conflict",
59    InstallSweepsWhatThePayloadDropped => "distribution:an-install-sweeps-what-the-payload-dropped",
60    InitializationPreservesProjectContent => "distribution:initialization-preserves-project-content",
61    InstancesOperateOffline => "distribution:instances-operate-offline",
62    ManifestIdentifiesEveryOwnedFile => "distribution:manifest-identifies-every-owned-file",
63    DeclarationIsSeededOnceAndThenOwned => "distribution:the-declaration-is-seeded-once-and-then-owned",
64    SharedSkillArtifactsHaveOneHome => "distribution:shared-skill-artifacts-have-one-home",
65    SkillInstallPreviewsBeforeWriting => "distribution:skill-install-previews-before-writing",
66    SkillUninstallRemovesOnlyWhatItWrote => "distribution:skill-uninstall-removes-only-what-it-wrote",
67    SkillsArePartOfThePayload => "distribution:skills-are-part-of-the-payload",
68    TheDoctorAnswersForTheInstalledSkills => "distribution:the-doctor-answers-for-the-installed-skills",
69    ThePayloadNamesNoOtherProject => "distribution:the-payload-names-no-other-project",
70    ThePayloadNamesNoPlanningTool => "distribution:the-payload-names-no-planning-tool",
71    ThePayloadRootsAreDeclaredOnce => "distribution:the-payload-roots-are-declared-once",
72    UpgradeConflictsAreAtomic => "distribution:upgrade-conflicts-are-atomic",
73    UserScopeFilesStayUnrecorded => "distribution:user-scope-files-stay-unrecorded",
74    AuthorInstructionsStayWithinBudget => "docs-format:author-instructions-stay-within-budget",
75    ChapterStaysWithinLineCap => "docs-format:chapter-stays-within-200-lines",
76    DocumentStatesThePresent => "docs-format:document-states-the-present",
77    DocumentUsesStructuralMarkdownOnly => "docs-format:document-uses-structural-markdown-only",
78    EveryBudgetCarriesAGate => "docs-format:every-budget-carries-a-gate",
79    FenceDeclaresALanguage => "docs-format:fence-declares-a-language",
80    ProseStaysUnwrapped => "docs-format:prose-stays-unwrapped",
81    DocumentCarriesNoPersonalPath => "docs-foundations:a-document-carries-no-personal-path",
82    DocumentDirectoryExplainsItself => "docs-foundations:a-document-directory-explains-itself",
83    DocumentOwnsWhatItGoverns => "docs-foundations:a-document-owns-what-it-governs",
84    KindPrefixCarriesASlug => "docs-foundations:a-kind-prefix-carries-a-slug",
85    ArtifactFilenamesCarryAKindPrefix => "docs-foundations:artifact-filenames-carry-a-kind-prefix",
86    CompanionArtifactsShareTheSpecName => "docs-foundations:companion-artifacts-share-the-spec-name",
87    SpecStatesThePresent => "docs-foundations:spec-states-the-present",
88    SpecWinsOverRecord => "docs-foundations:spec-wins-over-record",
89    SpecsAreCentralized => "docs-foundations:specs-are-centralized",
90    ProhibitionsAreCapped => "docs-specs:prohibitions-are-capped",
91    RequirementCarriesAVerification => "docs-specs:requirement-carries-a-verification",
92    RequirementCarriesFiveParts => "docs-specs:requirement-carries-five-parts",
93    RuleIdIsUniqueAndSlugged => "docs-specs:rule-id-is-unique-and-slugged",
94    RuleIdOutlivesItsSentence => "docs-specs:rule-id-outlives-its-sentence",
95    SpecStaysWithinLineCap => "docs-specs:spec-stays-within-300-lines",
96    StatementUsesAnEarsPattern => "docs-specs:statement-uses-an-ears-pattern",
97    UnenforcedRulesAreDeclared => "docs-specs:unenforced-rules-are-declared",
98    VerificationNamesALiveHook => "docs-specs:verification-names-a-live-hook",
99    DivergentResultNamesItsDestination => "guides:a-divergent-result-names-its-destination",
100    ManualStepEnumeratesItsInteraction => "guides:a-manual-step-enumerates-its-interaction",
101    StepFollowsItsProducers => "guides:a-step-follows-its-producers",
102    StepIsOneImperativeAction => "guides:a-step-is-one-imperative-action",
103    ExternalFactIsVerifiedUpstream => "guides:an-external-fact-is-verified-upstream",
104    CitationsLiveInTheReferenceZone => "guides:citations-live-in-the-reference-zone",
105    EveryStepCarriesItsCheck => "guides:every-step-carries-its-check",
106    PreconditionsOpenAndVerificationCloses => "guides:preconditions-open-and-verification-closes",
107    TheManifestStaysReadable => "instance:the-manifest-stays-readable",
108    AgentsBlockStaysManaged => "instance:the-agents-block-stays-managed",
109    TrackingRegistryStaysValid => "instance:the-tracking-registry-stays-valid",
110    ProjectDeclaresWhatItsGatesJudge => "instance:the-project-declares-what-its-gates-judge",
111    ManagedBlockAgreesWithTheDeclaration => "instance:the-managed-block-agrees-with-the-declaration",
112    BugzillaReportBodyFitsReportWidth => "known-issues:a-bugzilla-report-body-fits-in-79-columns",
113    FiledRecordCarriesItsReport => "known-issues:a-filed-record-carries-its-report",
114    RecordCarriesItsRetirementCondition => "known-issues:a-record-carries-its-retirement-condition",
115    RecordCarriesOneFilingState => "known-issues:a-record-carries-one-filing-state",
116    RecordCarriesOneState => "known-issues:a-record-carries-one-state",
117    RecordRecordsItsLastCheck => "known-issues:a-record-records-its-last-check",
118    RecordWalksTheMechanism => "known-issues:a-record-walks-the-mechanism",
119    CaseIdIsASlug => "known-issues:case-id-is-a-slug",
120    CanonGateIsNotDelivered => "release:a-canon-gate-is-not-delivered",
121    DeliveredGateReadsWhatTheConventionOwns => "release:a-delivered-gate-reads-what-the-convention-owns",
122    ReleasedVersionIsNotReAuthored => "release:a-released-version-is-not-re-authored",
123    TagDerivesFromTheVersionFile => "release:a-tag-derives-from-the-version-file",
124    LicenseDeclaresBothHalves => "release:license-declares-both-halves",
125    CanonRecordDescribesItsTree => "release:the-canon-record-describes-its-tree",
126    RkPinHasTwoFactsAndOneMover => "release:the-rk-pin-has-two-facts-and-one-mover",
127    DeliveredGateSetIsDeclaredOnce => "release:the-delivered-gate-set-is-declared-once",
128    ThirdPartyNoticesTravelWithThePayload => "release:third-party-notices-travel-with-the-payload",
129    VersionsAreSemanticAndAligned => "release:versions-are-semantic-and-aligned",
130    CommentCitesTheRule => "spec-to-code:a-comment-cites-the-rule",
131    CommentNamesNoRecord => "spec-to-code:a-comment-names-no-record",
132    GateMessageCitesTheRule => "spec-to-code:a-gate-message-cites-the-rule",
133    SpecChangeIsTyped => "spec-to-code:a-spec-change-is-typed",
134    SpecMayLeadItsCode => "spec-to-code:a-spec-may-lead-its-code",
135    SuppressionNamesItsCase => "spec-to-code:a-suppression-names-its-case",
136    EntryDocumentCitesRuleIds => "spec-to-code:an-entry-document-cites-rule-ids",
137    UnenactedRulesAreTheBacklog => "spec-to-code:unenacted-rules-are-the-backlog",
138    DeclaredDependentExists => "tracking:a-declared-dependent-exists",
139    PerishableSourceIsRegistered => "tracking:a-perishable-source-is-registered",
140    EntryDeclaresHowToRevalidate => "tracking:an-entry-declares-how-to-revalidate",
141    OverdueEntryBlocks => "tracking:an-overdue-entry-blocks",
142    UpstreamCheckDoesNotEditTheTree => "tracking:an-upstream-check-does-not-edit-the-tree",
143    UpstreamDerivationPinsARevision => "tracking:an-upstream-derivation-pins-a-revision",
144    RegistryHasOneReadableShape => "tracking:the-registry-has-one-readable-shape",
145    ExistingDocumentConvertsWhenEdited => "writing-style:an-existing-document-converts-when-edited",
146    NoDeliveredGateJudgesProse => "writing-style:no-delivered-gate-judges-prose",
147    SourcesNameTheRevisionRead => "writing-style:sources-name-the-revision-read",
148    DocumentationBlockRoutesToTheStyle => "writing-style:the-documentation-block-routes-to-the-style",
149    StyleLivesInOneDocument => "writing-style:the-style-lives-in-one-document",
150    NoneImposesNoObligation => "writing-policy:none-imposes-no-obligation",
151    ProjectSelectsOneSource => "writing-policy:the-project-selects-one-source",
152}
153
154impl fmt::Display for RuleId {
155    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
156        f.write_str(self.as_str())
157    }
158}
159
160#[cfg(test)]
161mod tests {
162    use super::*;
163
164    #[test]
165    fn slugs_are_well_formed_and_unique() {
166        let mut seen = std::collections::BTreeSet::new();
167        for rule in RuleId::ALL {
168            let id = rule.as_str();
169            let (domain, name) = id.split_once(':').unwrap();
170            let assert_slug = |part: &str| {
171                assert!(!part.is_empty(), "{id} has an empty half");
172                assert!(
173                    part.bytes()
174                        .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-'),
175                    "{id} is not a slug pair"
176                );
177            };
178            assert_slug(domain);
179            assert_slug(name);
180            assert!(seen.insert(id), "{id} is duplicated");
181        }
182    }
183
184    #[test]
185    fn display_renders_the_slug_pair() {
186        assert_eq!(
187            RuleId::ChapterStaysWithinLineCap.to_string(),
188            "docs-format:chapter-stays-within-200-lines"
189        );
190    }
191}
spec_driven_docs/domain/rule_id.rs

spec_driven_docs/domain/
rule_id.rs
