zenith_cli/cli/schema.rs
1//! Argument types for `zenith schema` and its subcommands.
2
3use clap::{Args, Subcommand};
4
5/// Arguments for `zenith schema`.
6#[derive(Debug, Args)]
7#[command(after_help = "EXAMPLES:\n \
8zenith schema # overview: counts + drill-in hints\n \
9zenith schema nodes # list all node kinds with summaries\n \
10zenith schema node pattern # attributes for one node kind\n \
11zenith schema ops # list all transaction ops\n \
12zenith schema op set_fill # summary for one op\n \
13zenith schema tokens # list all token types with summaries\n \
14zenith schema token gradient # value form + children + example for one token type\n \
15zenith schema page # attributes for a page declaration\n \
16zenith schema asset # attributes for an asset declaration\n \
17zenith schema document # attributes for the document root\n \
18zenith schema variant # variants block and override entry structure\n \
19zenith schema diagnostics # diagnostic-policy verbs + governable codes\n \
20zenith schema brand # brand-contract block (allowed colors/fonts/weights)\n \
21zenith schema block # block role declaration: vocab, props, scopes, cascade\n \
22zenith schema nodes --json # machine-readable JSON")]
23pub struct SchemaArgs {
24 #[command(subcommand)]
25 pub command: Option<SchemaSub>,
26
27 /// Emit machine-readable JSON instead of human-readable text.
28 #[arg(long, global = true)]
29 pub json: bool,
30}
31
32/// Subcommands of `zenith schema`.
33#[derive(Debug, Subcommand)]
34pub enum SchemaSub {
35 /// List all authorable node kinds with their one-line summaries.
36 Nodes,
37
38 /// Show the summary and recognized attributes for one node kind.
39 Node {
40 /// The node kind to look up (e.g. `rect`, `text`, `pattern`).
41 kind: String,
42 },
43
44 /// List all transaction ops with their one-line summaries.
45 Ops,
46
47 /// Show the summary, JSON fields, and a working example for one transaction op.
48 Op {
49 /// The op name to look up (e.g. `set_fill`, `add_node`).
50 name: String,
51 },
52
53 /// Show the recognized attributes for a `page` declaration.
54 ///
55 /// Lists every attribute the parser recognises on a `page` node:
56 /// geometry (w, h), margins, bleed, baseline-grid, line-jumps, parity,
57 /// and master.
58 Page,
59
60 /// Show the recognized attributes for an `asset` declaration.
61 ///
62 /// Lists every attribute the parser recognises on an `asset` node inside
63 /// the `assets { … }` block: id, kind, src, sha256, and the full suite of
64 /// AI-provenance fields (ai-prompt, ai-model, ai-provider, …).
65 Asset,
66
67 /// Show the recognized attributes for the document root (`zenith` node).
68 ///
69 /// Lists every attribute the parser recognises on the top-level `zenith`
70 /// node and the `document { … }` child block: version, colorspace, doc-id,
71 /// mirror-margins, page-progression, spread-gutter, margin-*, and more.
72 Document,
73
74 /// List all authorable token types with their one-line summaries.
75 ///
76 /// Shows every recognized `type=` value for a token node (color, dimension,
77 /// fontFamily, fontWeight, gradient, shadow, filter, mask, number) with a
78 /// one-line description. Use `zenith schema token <type>` for the full
79 /// value form, child-node structure, and a working example.
80 Tokens,
81
82 /// Show the value form, child-node structure, and a working example for one token type.
83 ///
84 /// Describes exactly what to write for a given `type=` value: whether the
85 /// token takes an inline `value=` literal (color, dimension, number,
86 /// fontFamily, fontWeight) or is defined by child nodes (gradient, shadow,
87 /// filter, mask), including the exact syntax for each.
88 Token {
89 /// The token type to look up (e.g. `color`, `gradient`, `shadow`).
90 #[arg(value_name = "TYPE")]
91 ty: String,
92 },
93
94 /// Show the structure of the `variants` block and the `override` entry.
95 ///
96 /// Documents the `variants { variant id=… source=<page-id> w=(px)N h=(px)N { … } }`
97 /// block structure, the `override node="<id>" …` entry, and its recognised
98 /// properties: `node` (required, the target node id selector — NOT `id`),
99 /// `visible` (#true/#false), `text` (string), `fill` (token ref or color),
100 /// and geometry `x`/`y`/`w`/`h` (typed dimensions, e.g. `(px)100`).
101 /// Includes a concrete worked example.
102 Variant,
103
104 /// Show the in-file diagnostic-policy verbs and the governable diagnostic codes.
105 ///
106 /// Lists the three policy verbs (`allow`, `deny`, `warn`) usable inside a
107 /// root `diagnostics { … }` block, what each does, the precedence note
108 /// (in-file policy now; CLI flags/config resolve in a later unit), and the
109 /// full list of governable diagnostic codes (code · severity · summary).
110 /// Integrity Errors are listed as non-suppressible.
111 Diagnostics,
112
113 /// Show the structure and semantics of the top-level `brand { … }` block.
114 ///
115 /// Documents the three optional child nodes (`colors`, `fonts`, `weights`),
116 /// placement (top-level sibling of `tokens`/`assets`/`document` inside
117 /// `zenith version=1 { … }`), the absent-child = unconstrained rule, and
118 /// the three diagnostic codes emitted when resolved token values fall outside
119 /// the declared contract (`brand.color_off_palette`, `brand.font_not_allowed`,
120 /// `brand.weight_not_allowed`). Shows how to elevate these Warnings to
121 /// blocking Errors for a CI gate via `--deny` or an in-file `diagnostics`
122 /// policy. Includes a complete worked example.
123 Brand,
124
125 /// Show the `block role="…"` declaration: role vocabulary, properties, scopes, and cascade.
126 ///
127 /// Documents the `block` leaf declaration that maps a markdown block role
128 /// (h1–h6, p, blockquote, li, code-block, hr) to style and spacing overrides.
129 /// Declarable at three scopes: document body, page, and text node. The cascade
130 /// precedence is text > page > document (highest specificity wins). Block decls
131 /// are consumed only on text nodes with `format="markdown"`.
132 Block,
133}