Skip to main content

clm_rust_core/layer0/
ast.rs

1//! Layer 0: Strongly-typed AST grammar for Cubical Logic Model specifications.
2//! Canonical Path: kernel/clm_rust_core/src/layer0/ast.rs
3//!
4//! Provides serde-serializable AST structures for chapters, abstract specifications,
5//! concrete implementations, balanced expectations, and full CLM manifests.
6
7use serde::{Deserialize, Serialize};
8use serde_json::Value;
9use std::collections::HashMap;
10
11/// Chapter metadata block in a CLM specification.
12#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
13pub struct ClmChapter {
14    #[serde(default)]
15    pub name: Option<String>,
16    #[serde(default)]
17    pub number: Option<u32>,
18    #[serde(default)]
19    pub id: Option<u32>,
20    #[serde(default)]
21    pub title: Option<String>,
22    #[serde(default)]
23    pub mvp_card: Option<String>,
24    #[serde(default)]
25    pub pkc_task: Option<String>,
26    #[serde(default)]
27    pub description: Option<String>,
28    #[serde(default)]
29    pub narrative: Option<String>,
30}
31
32/// Abstract component specification (A-MCard domain concept).
33#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
34pub struct AbstractComponent {
35    #[serde(default)]
36    pub concept: Option<String>,
37    #[serde(default)]
38    pub description: Option<String>,
39    #[serde(default)]
40    pub signature: Option<Value>,
41    #[serde(default)]
42    pub invariants: Option<Value>,
43    #[serde(flatten)]
44    pub extra: HashMap<String, Value>,
45}
46
47/// Concrete component manifestation (C-MCard runtime implementation).
48#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
49pub struct ConcreteComponent {
50    #[serde(default)]
51    pub manifestation: Option<String>,
52    #[serde(default)]
53    pub description: Option<String>,
54    #[serde(default)]
55    pub runtime: Option<String>,
56    #[serde(default)]
57    pub operation: Option<String>,
58    #[serde(default)]
59    pub code: Option<String>,
60    #[serde(default)]
61    pub input_type: Option<String>,
62    #[serde(default)]
63    pub output_type: Option<String>,
64    #[serde(default)]
65    pub process_type: Option<String>,
66    #[serde(flatten)]
67    pub extra: HashMap<String, Value>,
68}
69
70/// Balanced component expectation (V-MCard validation & test cases).
71#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
72pub struct BalancedComponent {
73    #[serde(default)]
74    pub expectation: Option<String>,
75    #[serde(default)]
76    pub description: Option<String>,
77    #[serde(default)]
78    pub expected_results: Option<Value>,
79    #[serde(default)]
80    pub test_cases: Option<Vec<Value>>,
81    #[serde(flatten)]
82    pub extra: HashMap<String, Value>,
83}
84
85/// Fully parsed canonical CLM AST representing a chapter or component specification.
86#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
87pub struct ParsedClmAst {
88    #[serde(default)]
89    pub version: Option<String>,
90    #[serde(default)]
91    pub chapter: Option<ClmChapter>,
92    pub abstract_spec: AbstractComponent,
93    pub concrete_spec: ConcreteComponent,
94    pub balanced_spec: BalancedComponent,
95    #[serde(default)]
96    pub preconditions: Vec<String>,
97    #[serde(default)]
98    pub postconditions: Vec<String>,
99    #[serde(default)]
100    pub content_hash: Option<String>,
101    #[serde(default)]
102    pub raw: Value,
103}
104
105impl ParsedClmAst {
106    /// Returns the chapter title or name if available.
107    pub fn display_name(&self) -> String {
108        if let Some(ref ch) = self.chapter {
109            if let Some(ref title) = ch.title {
110                return title.clone();
111            }
112            if let Some(ref name) = ch.name {
113                return name.clone();
114            }
115        }
116        if let Some(ref concept) = self.abstract_spec.concept {
117            return concept.clone();
118        }
119        "Unnamed CLM Component".to_string()
120    }
121}