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.
enforcesmarks an item as an enforcement site of one or more requirements — “this code exists because this contract exists”.verifiesmarks 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.