Skip to main content

provable_contracts/
generate.rs

1//! End-to-end codegen — generates all artifacts to disk.
2//!
3//! Combines scaffold, kani, and probar generators into a single
4//! operation that writes files to a target directory.
5
6use std::path::{Path, PathBuf};
7
8use crate::binding::BindingRegistry;
9use crate::book_gen::generate_contract_page;
10use crate::coq_gen::generate_coq_spec;
11use crate::graph::{dependency_graph, DependencyGraph};
12use crate::invariant_gen::generate_invariants;
13use crate::kani_gen::generate_kani_harnesses;
14use crate::probar_gen::{generate_probar_tests, generate_wired_probar_tests};
15use crate::scaffold::generate_trait;
16use crate::schema::Contract;
17
18/// Manifest of generated files.
19#[derive(Debug, Clone)]
20pub struct GeneratedFiles {
21    /// Files that were generated.
22    pub files: Vec<GeneratedFile>,
23}
24
25/// A single generated file.
26#[derive(Debug, Clone)]
27pub struct GeneratedFile {
28    /// Path relative to the output directory.
29    pub relative_path: PathBuf,
30    /// Absolute path where the file was written.
31    pub absolute_path: PathBuf,
32    /// What kind of artifact this is.
33    pub kind: ArtifactKind,
34    /// Number of bytes written.
35    pub bytes: usize,
36}
37
38/// The kind of generated artifact.
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum ArtifactKind {
41    Scaffold,
42    KaniHarness,
43    ProbarTest,
44    WiredProbarTest,
45    BookPage,
46    Invariants,
47    CoqSpec,
48}
49
50impl std::fmt::Display for ArtifactKind {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        match self {
53            Self::Scaffold => write!(f, "scaffold"),
54            Self::KaniHarness => write!(f, "kani"),
55            Self::ProbarTest => write!(f, "probar"),
56            Self::WiredProbarTest => write!(f, "wired-probar"),
57            Self::BookPage => write!(f, "book-page"),
58            Self::Invariants => write!(f, "invariants"),
59            Self::CoqSpec => write!(f, "coq"),
60        }
61    }
62}
63
64/// Generate all artifacts from a contract and write to `output_dir`.
65///
66/// Creates the output directory if it doesn't exist. Generates:
67/// - `scaffold.rs` — trait + test stubs
68/// - `kani.rs` — `#[kani::proof]` harnesses
69/// - `probar.rs` — property-based tests
70/// - `wired_probar.rs` — wired tests (only if binding provided)
71///
72/// # Errors
73///
74/// Returns `io::Error` if directory creation or file writes fail.
75pub fn generate_all(
76    contract: &Contract,
77    stem: &str,
78    output_dir: &Path,
79    binding: Option<&BindingRegistry>,
80) -> Result<GeneratedFiles, std::io::Error> {
81    let rendered = render_all(contract, stem, binding);
82    std::fs::create_dir_all(output_dir)?;
83    let mut files = Vec::with_capacity(rendered.len());
84    for (relative_path, kind, content) in rendered {
85        let absolute_path = output_dir.join(&relative_path);
86        std::fs::write(&absolute_path, &content)?;
87        files.push(GeneratedFile {
88            relative_path,
89            absolute_path,
90            kind,
91            bytes: content.len(),
92        });
93    }
94    Ok(GeneratedFiles { files })
95}
96
97/// The files `generate_all` writes, rendered in memory: no directory is created and no file is
98/// written (`pv generate --dry-run`, #6395). `output_dir` only prefixes `absolute_path`.
99#[must_use]
100pub fn plan_all(
101    contract: &Contract,
102    stem: &str,
103    output_dir: &Path,
104    binding: Option<&BindingRegistry>,
105) -> GeneratedFiles {
106    let files = render_all(contract, stem, binding)
107        .into_iter()
108        .map(|(relative_path, kind, content)| GeneratedFile {
109            absolute_path: output_dir.join(&relative_path),
110            relative_path,
111            kind,
112            bytes: content.len(),
113        })
114        .collect();
115    GeneratedFiles { files }
116}
117
118/// Render every artifact `generate_all` emits, in emission order. Pure: touches no filesystem.
119fn render_all(
120    contract: &Contract,
121    stem: &str,
122    binding: Option<&BindingRegistry>,
123) -> Vec<(PathBuf, ArtifactKind, String)> {
124    let mut out = vec![
125        (
126            PathBuf::from(format!("{stem}_scaffold.rs")),
127            ArtifactKind::Scaffold,
128            generate_trait(contract),
129        ),
130        (
131            PathBuf::from(format!("{stem}_kani.rs")),
132            ArtifactKind::KaniHarness,
133            generate_kani_harnesses(contract),
134        ),
135        (
136            PathBuf::from(format!("{stem}_probar.rs")),
137            ArtifactKind::ProbarTest,
138            generate_probar_tests(contract),
139        ),
140    ];
141    if let Some(reg) = binding {
142        let contract_file = format!("{stem}.yaml");
143        out.push((
144            PathBuf::from(format!("{stem}_wired_probar.rs")),
145            ArtifactKind::WiredProbarTest,
146            generate_wired_probar_tests(contract, &contract_file, reg),
147        ));
148    }
149    let invariant_content = generate_invariants(contract);
150    if !invariant_content.is_empty() {
151        out.push((
152            PathBuf::from(format!("{stem}_invariants.rs")),
153            ArtifactKind::Invariants,
154            invariant_content,
155        ));
156    }
157    out.push((
158        PathBuf::from(format!("{stem}.v")),
159        ArtifactKind::CoqSpec,
160        generate_coq_spec(contract, stem),
161    ));
162    let single_graph = build_single_contract_graph(contract, stem);
163    out.push((
164        PathBuf::from(format!("{stem}_book.md")),
165        ArtifactKind::BookPage,
166        generate_contract_page(contract, stem, &single_graph),
167    ));
168    out
169}
170
171/// Build a minimal dependency graph for a single contract.
172/// Used by `generate_all` when the full graph isn't available.
173fn build_single_contract_graph(contract: &Contract, stem: &str) -> DependencyGraph {
174    let refs = vec![(stem.to_string(), contract)];
175    dependency_graph(&refs)
176}
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181    use crate::schema::parse_contract_str;
182
183    fn minimal_contract() -> Contract {
184        parse_contract_str(
185            r#"
186metadata:
187  version: "1.0.0"
188  description: "Test"
189  references: ["Paper"]
190equations:
191  f:
192    formula: "f(x) = x"
193proof_obligations:
194  - type: invariant
195    property: "output finite"
196falsification_tests:
197  - id: FALSIFY-001
198    rule: "finiteness"
199    prediction: "output is always finite"
200    if_fails: "overflow"
201kani_harnesses:
202  - id: KANI-001
203    obligation: OBL-001
204    bound: 16
205"#,
206        )
207        .unwrap()
208    }
209
210    #[test]
211    fn generate_all_without_binding() {
212        let c = minimal_contract();
213        let dir = tempfile::tempdir().unwrap();
214        let result = generate_all(&c, "test-kernel-v1", dir.path(), None).unwrap();
215        assert_eq!(result.files.len(), 5); // scaffold + kani + probar + coq + book
216        assert!(result
217            .files
218            .iter()
219            .any(|f| f.kind == ArtifactKind::Scaffold));
220        assert!(result
221            .files
222            .iter()
223            .any(|f| f.kind == ArtifactKind::KaniHarness));
224        assert!(result
225            .files
226            .iter()
227            .any(|f| f.kind == ArtifactKind::ProbarTest));
228        assert!(result
229            .files
230            .iter()
231            .any(|f| f.kind == ArtifactKind::BookPage));
232        for f in &result.files {
233            assert!(f.absolute_path.exists());
234            assert!(f.bytes > 0);
235        }
236    }
237
238    #[test]
239    fn generate_all_with_binding() {
240        let c = minimal_contract();
241        let binding = crate::binding::parse_binding_str(
242            r#"
243version: "1.0.0"
244target_crate: test
245bindings:
246  - contract: test-kernel-v1.yaml
247    equation: f
248    module_path: "test::f"
249    function: f
250    signature: "fn f(x: &[f32]) -> Vec<f32>"
251    status: implemented
252"#,
253        )
254        .unwrap();
255        let dir = tempfile::tempdir().unwrap();
256        let result = generate_all(&c, "test-kernel-v1", dir.path(), Some(&binding)).unwrap();
257        assert_eq!(result.files.len(), 6); // scaffold + kani + probar + wired + coq + book
258        assert!(result
259            .files
260            .iter()
261            .any(|f| f.kind == ArtifactKind::WiredProbarTest));
262    }
263
264    #[test]
265    fn generates_into_subdir() {
266        let c = minimal_contract();
267        let dir = tempfile::tempdir().unwrap();
268        let sub = dir.path().join("deep").join("nested");
269        let result = generate_all(&c, "test-kernel-v1", &sub, None).unwrap();
270        assert_eq!(result.files.len(), 5); // scaffold + kani + probar + coq + book
271        assert!(sub.exists());
272    }
273
274    #[test]
275    fn artifact_kind_display() {
276        assert_eq!(ArtifactKind::Scaffold.to_string(), "scaffold");
277        assert_eq!(ArtifactKind::KaniHarness.to_string(), "kani");
278        assert_eq!(ArtifactKind::ProbarTest.to_string(), "probar");
279        assert_eq!(ArtifactKind::WiredProbarTest.to_string(), "wired-probar");
280        assert_eq!(ArtifactKind::BookPage.to_string(), "book-page");
281    }
282
283    #[test]
284    fn file_names_use_stem() {
285        let c = minimal_contract();
286        let dir = tempfile::tempdir().unwrap();
287        let result = generate_all(&c, "softmax-kernel-v1", dir.path(), None).unwrap();
288        let names: Vec<String> = result
289            .files
290            .iter()
291            .map(|f| f.relative_path.to_string_lossy().to_string())
292            .collect();
293        assert!(names.contains(&"softmax-kernel-v1_scaffold.rs".to_string()));
294        assert!(names.contains(&"softmax-kernel-v1_kani.rs".to_string()));
295        assert!(names.contains(&"softmax-kernel-v1_probar.rs".to_string()));
296    }
297}