Skip to main content

appstruct_ir/
lib.rs

1//! Stable, serialization-friendly intermediate representation for `AppStruct`.
2mod compatibility;
3mod database;
4mod extension;
5mod seed;
6mod service;
7mod validation;
8mod views;
9pub use compatibility::{IrCompatibilityError, from_compatible_json};
10pub use database::{DatabaseDevMode, DatabaseIr, DatabaseMigrationPolicy, DatabaseProvider};
11pub use extension::{CommandIr, OperationTypeIr, PageIr, QueryIr, ValueFieldIr, ValueObjectIr};
12pub use seed::SeedIr;
13use serde::{Deserialize, Serialize};
14pub use service::{
15    AuditIr, FileIr, FileProviderIr, JobQueueIr, JobsIr, MailIr, MailProviderIr, MailTemplateIr,
16    PresetIr, TenantIr,
17};
18use std::fmt;
19pub use validation::{IrValidationError, IrValidationErrors, validate_app_ir};
20pub use views::EntityViewsIr;
21pub const IR_VERSION: u32 = appstruct_contracts::IR.current;
22
23#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
24pub struct AppIr {
25    pub ir_version: u32,
26    pub app: AppMeta,
27    pub database: DatabaseIr,
28    pub preset: Option<PresetIr>,
29    pub auth: AuthIr,
30    pub tenant: TenantIr,
31    pub audit: AuditIr,
32    pub mail: MailIr,
33    pub jobs: JobsIr,
34    pub file: FileIr,
35    pub enums: Vec<EnumIr>,
36    pub value_objects: Vec<ValueObjectIr>,
37    pub entities: Vec<EntityIr>,
38    #[serde(default, skip_serializing_if = "Vec::is_empty")]
39    pub seeds: Vec<SeedIr>,
40    pub relations: Vec<RelationIr>,
41    pub commands: Vec<CommandIr>,
42    pub queries: Vec<QueryIr>,
43    pub pages: Vec<PageIr>,
44    pub modules: Vec<ResolvedModule>,
45}
46
47/// Application-level metadata.
48#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
49pub struct AppMeta {
50    pub name: String,
51}
52
53/// Authentication facts known at compile time in the M0 compiler.
54#[allow(clippy::struct_excessive_bools)]
55#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
56pub struct AuthIr {
57    pub enabled: bool,
58    pub user_entity: Option<EntityId>,
59    pub registration_enabled: bool,
60    pub password_reset_enabled: bool,
61    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
62    pub oauth_enabled: bool,
63    pub roles: Vec<String>,
64    pub default_role: Option<String>,
65}
66
67/// Stable logical entity identifier. It never depends on vector position.
68#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
69#[serde(transparent)]
70pub struct EntityId(pub String);
71
72impl fmt::Display for EntityId {
73    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
74        self.0.fmt(formatter)
75    }
76}
77
78/// Stable logical field identifier.
79#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
80#[serde(transparent)]
81pub struct FieldId(pub String);
82
83impl fmt::Display for FieldId {
84    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
85        self.0.fmt(formatter)
86    }
87}
88
89#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
90#[serde(transparent)]
91pub struct RelationId(pub String);
92
93#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
94pub struct EntityIr {
95    pub id: EntityId,
96    pub rust_name: String,
97    pub api_name: String,
98    pub label: String,
99    pub table_name: String,
100    pub fields: Vec<FieldIr>,
101    #[serde(default, skip_serializing_if = "Vec::is_empty")]
102    pub indexes: Vec<IndexIr>,
103    pub access: CrudAccessIr,
104    pub views: EntityViewsIr,
105    pub hooks: HooksIr,
106    pub concurrency: ConcurrencyIr,
107    pub tenant_scoped: bool,
108    pub audit_enabled: bool,
109}
110
111#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
112pub struct IndexIr {
113    pub id: String,
114    pub entity: EntityId,
115    pub fields: Vec<FieldId>,
116    pub unique: bool,
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub predicate: Option<String>,
119}
120
121#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
122pub struct FieldIr {
123    pub id: FieldId,
124    pub entity: EntityId,
125    pub rust_name: String,
126    pub api_name: String,
127    pub column_name: String,
128    pub ty: FieldTypeIr,
129    pub nullable: bool,
130    pub primary_key: bool,
131    pub unique: bool,
132    pub generated: Option<GeneratedValueIr>,
133    pub default: Option<String>,
134    pub validation: ValidationIr,
135    pub capabilities: FieldCapabilities,
136    #[serde(default, skip_serializing_if = "Option::is_none")]
137    pub read_access: Option<AccessRuleIr>,
138    #[serde(default, skip_serializing_if = "Option::is_none")]
139    pub write_access: Option<AccessRuleIr>,
140    pub ui_component: Option<String>,
141}
142
143#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
144#[serde(tag = "kind", rename_all = "snake_case")]
145pub enum FieldTypeIr {
146    Uuid,
147    String,
148    Text,
149    Integer,
150    Bigint,
151    Decimal,
152    Boolean,
153    Date,
154    Datetime,
155    Json,
156    Enum { values: Vec<String> },
157    Relation { target: EntityId },
158}
159
160#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(rename_all = "snake_case")]
162pub enum GeneratedValueIr {
163    UuidV7,
164    Now,
165    AutoIncrement,
166    Revision,
167    Tenant,
168}
169
170#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
171pub struct ValidationIr {
172    pub min_length: Option<u64>,
173    pub max_length: Option<u64>,
174    pub minimum: Option<String>,
175    pub maximum: Option<String>,
176}
177
178#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
179pub struct FieldCapabilities {
180    pub searchable: bool,
181    pub filterable: bool,
182    pub sortable: bool,
183}
184
185/// Explicit relation edge resolved by the compiler.
186#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
187pub struct RelationIr {
188    pub id: RelationId,
189    pub source: EntityId,
190    pub target: EntityId,
191    pub cardinality: Cardinality,
192    pub foreign_key_owner: EntityId,
193    pub foreign_key_fields: Vec<FieldId>,
194    pub inverse: Option<RelationId>,
195    pub required: bool,
196    pub unique: bool,
197    pub on_delete: OnDeleteIr,
198}
199
200#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
201#[serde(rename_all = "snake_case")]
202pub enum Cardinality {
203    OneToOne,
204    ManyToOne,
205}
206
207#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
208#[serde(rename_all = "snake_case")]
209pub enum OnDeleteIr {
210    Restrict,
211    Cascade,
212    SetNull,
213}
214
215/// CRUD rules are always explicit in normalized IR.
216#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
217pub struct CrudAccessIr {
218    pub list: AccessRuleIr,
219    pub read: AccessRuleIr,
220    pub create: AccessRuleIr,
221    pub update: AccessRuleIr,
222    pub delete: AccessRuleIr,
223}
224
225#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
226#[serde(tag = "mode", rename_all = "snake_case")]
227pub enum AccessRuleIr {
228    Public,
229    Authenticated,
230    Role { role: String },
231    Owner { field: FieldId },
232    Any { rules: Vec<AccessRuleIr> },
233    All { rules: Vec<AccessRuleIr> },
234}
235
236/// M0 preserves the future IR shape while leaving hooks empty.
237#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
238pub struct HooksIr {}
239
240#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
241pub struct ConcurrencyIr {
242    pub enabled: bool,
243}
244
245#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
246pub struct EnumIr {
247    pub name: String,
248    pub values: Vec<String>,
249}
250
251#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
252pub struct ResolvedModule {
253    pub name: String,
254    pub version: String,
255    pub origin: ModuleOrigin,
256    /// Project-relative manifest path for a local module.
257    pub manifest_path: Option<String>,
258    /// SHA-256 of the exact local manifest bytes loaded by the compiler.
259    pub content_sha256: Option<String>,
260    pub provides: Vec<String>,
261    pub requires: Vec<String>,
262    pub startup_order: u32,
263    pub artifacts: Vec<ModuleArtifactIr>,
264}
265
266#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
267#[serde(rename_all = "snake_case")]
268pub enum ModuleOrigin {
269    Official,
270    Local,
271}
272
273#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
274pub struct ModuleArtifactIr {
275    pub path: String,
276    /// Project-relative source path, or `None` for migrated legacy IR.
277    pub source: Option<String>,
278    pub sha256: String,
279    pub byte_len: u64,
280    pub content: String,
281}
282
283/// Byte offsets plus user-facing line and column for a source range.
284#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
285pub struct SourceSpan {
286    pub file: String,
287    pub start: usize,
288    pub end: usize,
289    pub line: usize,
290    pub column: usize,
291    pub end_line: usize,
292    pub end_column: usize,
293}
294
295#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
296#[serde(rename_all = "lowercase")]
297pub enum Severity {
298    Error,
299    Warning,
300}
301
302#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
303pub struct Label {
304    pub span: SourceSpan,
305    pub message: String,
306}
307
308/// Stable diagnostic shared by text and JSON consumers.
309#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
310pub struct Diagnostic {
311    pub severity: Severity,
312    pub code: String,
313    pub message: String,
314    pub primary: Box<Label>,
315    pub secondary: Vec<Label>,
316    pub help: Option<String>,
317}
318
319impl Diagnostic {
320    #[must_use]
321    pub fn error(code: &str, message: impl Into<String>, span: SourceSpan) -> Self {
322        Self {
323            severity: Severity::Error,
324            code: code.to_owned(),
325            message: message.into(),
326            primary: Box::new(Label {
327                span,
328                message: String::new(),
329            }),
330            secondary: Vec::new(),
331            help: None,
332        }
333    }
334
335    #[must_use]
336    pub fn warning(code: &str, message: impl Into<String>, span: SourceSpan) -> Self {
337        Self {
338            severity: Severity::Warning,
339            code: code.to_owned(),
340            message: message.into(),
341            primary: Box::new(Label {
342                span,
343                message: String::new(),
344            }),
345            secondary: Vec::new(),
346            help: None,
347        }
348    }
349
350    #[must_use]
351    pub fn with_primary_message(mut self, message: impl Into<String>) -> Self {
352        self.primary.message = message.into();
353        self
354    }
355
356    #[must_use]
357    pub fn with_secondary(mut self, span: SourceSpan, message: impl Into<String>) -> Self {
358        self.secondary.push(Label {
359            span,
360            message: message.into(),
361        });
362        self
363    }
364
365    #[must_use]
366    pub fn with_help(mut self, help: impl Into<String>) -> Self {
367        self.help = Some(help.into());
368        self
369    }
370}
371
372/// Serialize normalized IR using deterministic field and collection order.
373///
374/// # Errors
375///
376/// Returns a serialization error only if the IR representation becomes unsupported by Serde.
377pub fn to_canonical_json(ir: &AppIr) -> Result<String, serde_json::Error> {
378    let mut output = serde_json::to_string_pretty(ir)?;
379    output.push('\n');
380    Ok(output)
381}