trace_doc/lib.rs
1//! # trace-doc
2//!
3//! A library for documenting, modeling, and linking requirements, architecture, test specifications,
4//! and realization elements directly in Rust's type system.
5//!
6//! By expressing traceability using structs, traits, and attributes, we allow the Rust compiler itself
7//! to act as a unified tool for compiling source code and verifying formal traceability in safety-critical
8//! software lifecycles.
9//!
10//! ## Core Concepts
11//!
12//! - **Artifact**: Any item in the development lifecycle (requirement, realization, test, etc.).
13//! - **Requirement**: A specification or constraint for the system.
14//! - **Realization**: An artifact that fulfills a requirement.
15//! - **Test**: An artifact that validates a requirement.
16//! - **DependsOn**: A relationship between two artifacts.
17//! - **Realizes**: A realization fulfilling a requirement.
18//! - **Tests**: A test validating a requirement.
19//!
20//! ## Example
21//!
22//! ```rust
23//! use trace_doc::{Artifact, Requirement, Realization, Realizes, Test, Tests};
24//!
25//! struct Req;
26//! impl Artifact for Req {}
27//! impl Requirement for Req { const TITLE: &str = "A requirement"; }
28//!
29//! struct Real;
30//! impl Artifact for Real {}
31//! impl Realization for Real {}
32//! impl Realizes<Req> for Real {}
33//!
34//! struct T;
35//! impl Artifact for T {}
36//! impl Test for T {}
37//! impl Tests<Req> for T {}
38//! ```
39
40#![deny(missing_docs)]
41
42/// The status of an artifact in the development lifecycle.
43#[derive(Debug, Clone, Copy, PartialEq, Eq)]
44pub enum Status {
45 /// The artifact is in the initial stages of development.
46 Draft,
47 /// The artifact has been reviewed and is ready for use.
48 Accepted,
49}
50
51/// Represents any artifact in the development lifecycle (requirement, realization, test, etc.).
52pub trait Artifact {
53 /// The status of the artifact in the development lifecycle.
54 const STATUS: Status = Status::Draft;
55}
56
57/// Represents a dependency relationship between any two artifacts.
58pub trait DependsOn<A>
59where
60 A: Artifact,
61 Self: Artifact,
62{
63}
64
65/// Represents a requirement artifact of a system.
66/// The description of the requirement can be provided as a doc comment on the implementing type.
67pub trait Requirement: Artifact {
68 /// A short title for the requirement.
69 const TITLE: &str;
70}
71
72/// Represents a realization artifact of a system.
73/// The description of the Realization can be provided as a doc comment on the realizing type.
74pub trait Realization: Artifact {}
75
76/// Represents a test specification artifact of a system.
77/// The description of the Test can be provided as a doc comment on the implementing type.
78pub trait Test: Artifact {}
79
80/// Represents the traceability of a realization to a requirement.
81/// This trait is implemented by the realizations that fulfill specific requirements.
82pub trait Realizes<R>
83where
84 R: Requirement,
85 Self: Realization,
86{
87}
88
89/// Represents the traceability of a test specification to a requirement.
90/// This trait is implemented by the test specifications that validate specific requirements.
91pub trait Tests<R>
92where
93 R: Requirement,
94 Self: Test,
95{
96}