zenith_cli/
json_types.rs

1//! Serialisable DTO types for JSON output.
2//!
3//! These types are defined in the CLI crate — we do NOT add serde to
4//! zenith-core.  Each type maps from zenith-core/zenith-scene types to a
5//! schema-versioned JSON shape.
6
7use serde::Serialize;
8
9/// JSON representation of a [`zenith_core::Diagnostic`].
10#[derive(Debug, Serialize)]
11pub struct DiagnosticJson {
12    pub code: String,
13    pub severity: String,
14    pub message: String,
15    #[serde(skip_serializing_if = "Option::is_none")]
16    pub subject_id: Option<String>,
17}
18
19impl From<&zenith_core::Diagnostic> for DiagnosticJson {
20    fn from(d: &zenith_core::Diagnostic) -> Self {
21        Self {
22            code: d.code.clone(),
23            severity: severity_str(&d.severity).to_owned(),
24            message: d.message.clone(),
25            subject_id: d.subject_id.clone(),
26        }
27    }
28}
29
30pub(crate) fn severity_str(s: &zenith_core::Severity) -> &'static str {
31    match s {
32        zenith_core::Severity::Error => "error",
33        zenith_core::Severity::Warning => "warning",
34        zenith_core::Severity::Advisory => "advisory",
35    }
36}
37
38/// Top-level JSON envelope for `validate`.
39#[derive(Debug, Serialize)]
40pub struct ValidateOutput {
41    pub schema: &'static str,
42    pub valid: bool,
43    pub diagnostics: Vec<DiagnosticJson>,
44}
45
46/// Top-level JSON envelope for `fmt`.
47#[derive(Debug, Serialize)]
48pub struct FmtOutput {
49    pub schema: &'static str,
50    pub changed: bool,
51    pub hash: String,
52}
53
54/// A single token entry for `tokens` output.
55#[derive(Debug, Serialize)]
56pub struct TokenEntry {
57    pub id: String,
58    pub token_type: String,
59    pub resolved_value: String,
60}
61
62/// Top-level JSON envelope for `tokens`.
63#[derive(Debug, Serialize)]
64pub struct TokensOutput {
65    pub schema: &'static str,
66    pub tokens: Vec<TokenEntry>,
67    pub diagnostics: Vec<DiagnosticJson>,
68}
69
70/// Top-level JSON envelope for `render`.
71#[derive(Debug, Serialize)]
72pub struct RenderOutput {
73    pub schema: &'static str,
74    pub diagnostics: Vec<DiagnosticJson>,
75}
76
77/// Top-level JSON envelope for `tx`.
78#[derive(Debug, Serialize)]
79pub struct TxOutputJson {
80    pub schema: &'static str,
81    pub status: String,
82    pub affected: Vec<String>,
83    pub diagnostics: Vec<DiagnosticJson>,
84    pub changed: bool,
85}
86
87/// Per-row result in the `merge --json` batch report.
88#[derive(Debug, Serialize)]
89pub struct MergeRowResult {
90    pub row: usize,
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub key: Option<String>,
93    pub status: &'static str,
94    pub outputs: Vec<String>,
95    pub diagnostics: Vec<DiagnosticJson>,
96}
97
98/// Top-level JSON envelope for `merge --json`.
99#[derive(Debug, Serialize)]
100pub struct MergeOutput {
101    pub schema: &'static str,
102    pub total_rows: usize,
103    pub written: usize,
104    pub failed: usize,
105    pub rows: Vec<MergeRowResult>,
106}
107
108/// One row entry in the generation manifest (successful rows only).
109#[derive(Debug, Serialize)]
110pub struct ManifestRow {
111    pub row: usize,
112    #[serde(skip_serializing_if = "Option::is_none")]
113    pub key: Option<String>,
114    pub outputs: Vec<String>,
115}
116
117/// Deterministic generation manifest for `zenith merge --manifest`.
118#[derive(Debug, Serialize)]
119pub struct MergeManifest {
120    pub schema: &'static str,
121    /// Manifest format version. Bumped only when the manifest structure changes
122    /// (never on a routine crate release), so identical inputs stay byte-identical.
123    pub generator: &'static str,
124    pub source_sha256: String,
125    pub data_sha256: String,
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub name_by: Option<String>,
128    pub rows: Vec<ManifestRow>,
129}
130
131// ── Variant JSON types ────────────────────────────────────────────────────────
132
133/// Per-variant result in the `variant --json` envelope.
134#[derive(Debug, Serialize)]
135pub struct VariantResultJson {
136    pub id: String,
137    pub source: String,
138    pub status: &'static str,
139    #[serde(skip_serializing_if = "Option::is_none")]
140    pub outputs_zen: Option<String>,
141    #[serde(skip_serializing_if = "Option::is_none")]
142    pub outputs_png: Option<String>,
143    pub diagnostics: Vec<DiagnosticJson>,
144}
145
146/// Top-level JSON envelope for `variant --json`.
147#[derive(Debug, Serialize)]
148pub struct VariantOutput {
149    pub schema: &'static str,
150    pub total_variants: usize,
151    pub generated: usize,
152    pub failed: usize,
153    pub variants: Vec<VariantResultJson>,
154}
155
156/// One target entry in the variant generation manifest (successful variants only).
157#[derive(Debug, Serialize)]
158pub struct VariantManifestTarget {
159    pub id: String,
160    pub source: String,
161    pub outputs_zen: String,
162    pub outputs_png: String,
163}
164
165/// Deterministic generation manifest for `zenith variant --manifest`.
166#[derive(Debug, Serialize)]
167pub struct VariantManifest {
168    pub schema: &'static str,
169    /// Manifest format version. Bumped only when the manifest structure changes
170    /// (never on a routine crate release), so identical inputs stays byte-identical.
171    pub generator: &'static str,
172    pub source_sha256: String,
173    pub targets: Vec<VariantManifestTarget>,
174}
175
176// ── Schema JSON types ─────────────────────────────────────────────────────────
177
178/// A single node-kind entry in the `schema nodes` JSON output.
179#[derive(Debug, Serialize)]
180pub struct SchemaNodeEntry {
181    pub kind: String,
182    pub summary: String,
183}
184
185/// A single attribute entry in the `schema node <kind>` and `schema page/asset/document` JSON output.
186#[derive(Debug, Serialize)]
187pub struct SchemaAttr {
188    pub name: String,
189    pub ty: String,
190}
191
192/// A single node-kind detail entry in the `schema node <kind>` JSON output.
193#[derive(Debug, Serialize)]
194pub struct SchemaNodeDetail {
195    pub kind: String,
196    pub summary: String,
197    pub attributes: Vec<SchemaAttr>,
198    /// Child-content descriptor for kinds that accept authorable children.
199    /// Absent from JSON for kinds with no authorable child content.
200    #[serde(skip_serializing_if = "Option::is_none")]
201    pub content: Option<SchemaNodeContent>,
202}
203
204/// Child-content descriptor embedded in [`SchemaNodeDetail`].
205#[derive(Debug, Serialize)]
206pub struct SchemaNodeContent {
207    pub description: String,
208    pub example: String,
209}
210
211/// A single op entry in the `schema ops` JSON output.
212#[derive(Debug, Serialize)]
213pub struct SchemaOpEntry {
214    pub op: String,
215    pub summary: String,
216}
217
218/// A single op field entry in the `schema op <name>` JSON output.
219#[derive(Debug, Serialize)]
220pub struct SchemaOpFieldEntry {
221    pub name: String,
222    pub ty: String,
223    pub required: bool,
224}
225
226/// Full detail entry in the `schema op <name>` JSON output.
227#[derive(Debug, Serialize)]
228pub struct SchemaOpDetail {
229    pub op: String,
230    pub summary: String,
231    pub fields: Vec<SchemaOpFieldEntry>,
232    pub example: String,
233}
234
235/// Top-level JSON envelope for `schema nodes`.
236#[derive(Debug, Serialize)]
237pub struct SchemaNodesOutput {
238    pub schema: &'static str,
239    pub nodes: Vec<SchemaNodeEntry>,
240}
241
242/// Top-level JSON envelope for `schema node <kind>`.
243#[derive(Debug, Serialize)]
244pub struct SchemaNodeOutput {
245    pub schema: &'static str,
246    pub node: SchemaNodeDetail,
247}
248
249/// Top-level JSON envelope for `schema ops`.
250#[derive(Debug, Serialize)]
251pub struct SchemaOpsOutput {
252    pub schema: &'static str,
253    pub ops: Vec<SchemaOpEntry>,
254}
255
256/// Top-level JSON envelope for `schema op <name>`.
257#[derive(Debug, Serialize)]
258pub struct SchemaOpOutput {
259    pub schema: &'static str,
260    pub op: SchemaOpDetail,
261}
262
263/// Top-level JSON envelope for bare `zenith schema` (overview).
264#[derive(Debug, Serialize)]
265pub struct SchemaOverviewOutput {
266    pub schema: &'static str,
267    pub node_kinds: usize,
268    pub tx_ops: usize,
269    pub token_types: usize,
270}
271
272/// A single token-type entry in the `schema tokens` JSON output.
273#[derive(Debug, Serialize)]
274pub struct SchemaTokenEntry {
275    pub ty: String,
276    pub summary: String,
277}
278
279/// Full detail for one token type in the `schema token <type>` JSON output.
280#[derive(Debug, Serialize)]
281pub struct SchemaTokenDetail {
282    pub ty: String,
283    pub summary: String,
284    pub value_form: String,
285    pub child_nodes: String,
286    pub example: String,
287}
288
289/// Top-level JSON envelope for `schema tokens`.
290#[derive(Debug, Serialize)]
291pub struct SchemaTokensOutput {
292    pub schema: &'static str,
293    pub token_types: Vec<SchemaTokenEntry>,
294}
295
296/// Top-level JSON envelope for `schema token <type>`.
297#[derive(Debug, Serialize)]
298pub struct SchemaTokenOutput {
299    pub schema: &'static str,
300    pub token: SchemaTokenDetail,
301}
302
303/// Top-level JSON envelope for `schema page`, `schema asset`, `schema document`.
304#[derive(Debug, Serialize)]
305pub struct SchemaSurfaceOutput {
306    pub schema: &'static str,
307    /// Which non-node surface this describes: `"page"`, `"asset"`, or `"document"`.
308    pub surface: &'static str,
309    pub summary: String,
310    pub attributes: Vec<SchemaAttr>,
311}
312
313/// A single governable diagnostic-code entry in the `schema diagnostics` JSON.
314#[derive(Debug, Serialize)]
315pub struct SchemaDiagnosticCode {
316    pub code: String,
317    /// `"error"`, `"warning"`, or `"advisory"`.
318    pub severity: String,
319    pub summary: String,
320    /// True when an `allow`/`deny`/`warn` entry can adjust this code (Warning /
321    /// Advisory). Error-severity codes are immutable and report `false`.
322    pub governable: bool,
323}
324
325/// Top-level JSON envelope for `schema diagnostics`.
326#[derive(Debug, Serialize)]
327pub struct SchemaDiagnosticsOutput {
328    pub schema: &'static str,
329    pub summary: String,
330    /// The policy verbs: `allow`, `deny`, `warn`.
331    pub verbs: Vec<String>,
332    /// Precedence note: in-file `diagnostics { … }` now; CLI flags/config later.
333    pub precedence: &'static str,
334    /// Every diagnostic code in the catalog (governable and always-Error).
335    pub codes: Vec<SchemaDiagnosticCode>,
336}
337
338/// One override property entry in the `schema variant` JSON output.
339#[derive(Debug, Serialize)]
340pub struct SchemaOverridePropEntry {
341    pub name: String,
342    pub ty: String,
343    pub required: bool,
344}
345
346/// Top-level JSON envelope for `schema variant`.
347#[derive(Debug, Serialize)]
348pub struct SchemaVariantOutput {
349    pub schema: &'static str,
350    pub summary: String,
351    pub block_structure: String,
352    pub variant_node: String,
353    pub override_entry: String,
354    pub override_props: Vec<SchemaOverridePropEntry>,
355    pub example: String,
356}
357
358/// Top-level JSON envelope for `schema brand`.
359#[derive(Debug, Serialize)]
360pub struct SchemaBrandOutput {
361    pub schema: &'static str,
362    pub summary: String,
363    pub placement: &'static str,
364    pub child_nodes: Vec<SchemaBrandChildNode>,
365    pub absent_means: &'static str,
366    pub diagnostic_codes: Vec<SchemaBrandDiagCode>,
367    pub example: &'static str,
368}
369
370/// One child-node descriptor in the `schema brand` JSON output.
371#[derive(Debug, Serialize)]
372pub struct SchemaBrandChildNode {
373    pub node: &'static str,
374    pub syntax: &'static str,
375    pub description: &'static str,
376}
377
378/// One diagnostic code entry in the `schema brand` JSON output.
379#[derive(Debug, Serialize)]
380pub struct SchemaBrandDiagCode {
381    pub code: &'static str,
382    pub severity: &'static str,
383    pub summary: &'static str,
384}
385
386// ── Fonts JSON types ──────────────────────────────────────────────────────────
387
388/// Top-level JSON envelope for `zenith fonts --json`.
389#[derive(Debug, Serialize)]
390pub struct FontsOutput {
391    pub schema: &'static str,
392    /// Family names bundled in the binary (lowercase, sorted). These are portable:
393    /// any machine with this Zenith binary will resolve them identically.
394    pub bundled: Vec<String>,
395    /// Family names found on this machine only (lowercase, sorted), after excluding
396    /// any family already in `bundled`. Using these trips a `font.local` advisory
397    /// and renders may differ on another machine.
398    pub local: Vec<String>,
399}
400
401// ── Recipe inspect JSON types ─────────────────────────────────────────────────
402
403/// A single `param` entry within a [`RecipeInspectJson`].
404#[derive(Debug, Serialize)]
405pub struct RecipeParamInspectJson {
406    pub name: String,
407    /// Canonical string representation of the parameter value: a token ref is
408    /// rendered as `"<id>"`, a literal as its raw string, a dimension as
409    /// `"(<unit>)<value>"`.
410    pub value: String,
411}
412
413/// A single recipe entry in the `recipes` array of [`crate::commands::inspect::InspectOutput`].
414#[derive(Debug, Serialize)]
415pub struct RecipeInspectJson {
416    pub id: String,
417    pub kind: String,
418    #[serde(skip_serializing_if = "Option::is_none")]
419    pub seed: Option<i64>,
420    #[serde(skip_serializing_if = "Option::is_none")]
421    pub generator: Option<String>,
422    #[serde(skip_serializing_if = "Option::is_none")]
423    pub bounds: Option<String>,
424    #[serde(skip_serializing_if = "Option::is_none")]
425    pub detached: Option<bool>,
426    pub params: Vec<RecipeParamInspectJson>,
427    pub palette: Vec<String>,
428    pub expanded: Vec<String>,
429}
zenith_cli/json_types.rs

zenith_cli/
json_types.rs
