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