Skip to main content

Crate shallguard_macros

Crate shallguard_macros 

Source
Expand description

Implementation of ShallGuard’s requirement-traceability anchor macros.

A repository keeps numbered system requirements (REQ-<AREA>-<NNN>, e.g. REQ-HRS-002) in its configured requirements documents. These attributes anchor code and tests to those requirements so the link between document and implementation is machine-checkable instead of living only in developers’ heads:

Consumers use these macros through the shallguard crate’s public namespace; they do not need to depend on this implementation crate.

  • enforces marks an item as an enforcement site of one or more requirements — “this code exists because this contract exists”.
  • verifies marks a test as verification evidence for one or more requirements — it backs a ✅ entry in a requirement’s Verified: line.

All anchor forms are compile-time no-ops: the annotated item is emitted unchanged and nothing is added at runtime. What the macros do check, at compile time, is the anchor itself — a malformed or duplicated requirement ID is a build error, so typos cannot survive as dead anchors. Whether a well-formed ID actually exists in the requirements documents is deliberately out of scope here (a macro cannot detect missing anchors either); that is the job of the external ShallGuard checker, which scans anchors syntactically. Comments are never anchors.

Placement conventions:

  • #[shallguard::enforces] attaches to items — and, inside a struct or enum that itself carries #[shallguard::enforces] (with IDs, or bare as a container marker), to individual fields and variants: the container attribute validates and strips the field-level anchors before the compiler or any derive sees them.
  • A contract living on a specific branch, match arm, or statement is anchored with the statement-position shallguard::enforces_here! macro, which expands to nothing.
  • #[shallguard::verifies] goes on test functions only, above the #[test] / #[tokio::test] attribute; it rejects non-test placements and #[ignore]d tests at compile time.
  • The relation is many-to-many: one item may enforce several requirements, and one requirement may be enforced or verified at several sites.

#[shallguard::enforces("REQ-RD-006", "REQ-RD-007")]
fn resolve_identity_claim() {}

#[shallguard::verifies("REQ-RD-006")]
#[test]
fn req_rd_006_exact_worker_claim_wins() {}

Malformed IDs and invalid placements fail the build:

ⓘ

#[shallguard::enforces("REQ-hrs-2")]
fn broken() {}
ⓘ

#[shallguard::verifies()]
fn missing_id() {}
ⓘ

// Not a test function.
#[shallguard::verifies("REQ-RD-006")]
fn not_a_test() {}
ⓘ

// Not a function at all.
#[shallguard::verifies("REQ-RD-006")]
struct NotAFunction;
ⓘ

// Ignored tests are not evidence.
#[shallguard::verifies("REQ-RD-006")]
#[test]
#[ignore]
fn ignored_test() {}

Macros§

enforces_here
Statement-position enforcement anchor: marks the surrounding branch, match arm, or statement sequence as an enforcement site of the listed requirements. Expands to nothing; the IDs are validated for form and uniqueness at compile time exactly like enforces.

Attribute Macros§

enforces
Marks an item as an enforcement site of the listed requirements.
verifies
Marks a test as verification evidence for the listed requirements.