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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
//! `fig-schema` — the schema layer: what a field *expects* — its type, its
//! allowed values, and how to present it — layered over [`fig`]'s schema-free
//! value tree.
//!
//! fig parses bytes → [`fig::Value`] and edits losslessly; it has no notion of
//! "what is valid here". This crate adds that knowledge as a **generic,
//! embedder-agnostic** engine. It never learns the word "prov" or "flower": a
//! consumer (prov, for frontmatter fields; flower, for a metadata editor)
//! defines its own constraint type — an enum covering whatever kinds of
//! constraint it needs (a controlled vocabulary, a reference into a
//! workspace, …) — and implements [`Validate`] on it. [`FieldRule`]/[`Schema`]
//! are generic over that type, so the path-matching and commit-time
//! validation plumbing is written once, here, and reused by every embedder.
//!
//! A schema is also **a document**. [`load_schema`] reads one written to the
//! schema document format — `docs/schema-format.md`, a fig document in any of
//! fig's languages, composed from others by `include` and from vocabulary
//! documents by `constraint.from` — into a [`Schema<Constraint>`], where
//! [`Constraint`] is this crate's own type: a vocabulary, or an
//! [`Other`](Constraint::Other) kind it does not know, which validates to
//! *unchecked* rather than pretending. An embedder maps that into its own
//! constraint type with [`Schema::map_constraints`] and keeps the seam; the
//! `fig-schema` binary checks documents against it with no embedder at all.
//!
//! What's genuinely reusable, and lives here as concrete types rather than
//! being left to the embedder:
//!
//! - [`PathPat`] / [`SegPat`] — pattern-matching a fig path, including "every
//! item of this list" ([`SegPat::EachItem`]) and "this subtree"
//! ([`SegPat::AnyDepth`]); [`PathPat::parse`] reads one from the format's
//! grammar (`audience[]`, `meta.**`) and [`render_path`] is its inverse.
//! - [`FieldType`] — the expected type, type-directed coercion of an edit
//! buffer ([`FieldType::coerce`]), whether a parsed value already has the
//! type ([`FieldType::admits`]), and the name the format spells it by
//! ([`FieldType::from_name`]).
//! - [`Term`] / [`Cardinality`] / [`validate_enum`] — a controlled vocabulary
//! and the logic to check a value against one (closed-vocabulary rejection,
//! open-vocabulary near-miss warnings). Cardinality (one vs. many) is pure
//! data shape, useful even to a constraint this crate doesn't otherwise model
//! (a relation/reference field, for instance).
//! - [`VocabularyDoc`] / [`parse_vocabulary`] — load a term set from the
//! shared `vocabulary: { field, values }` / `terms:` document convention, so
//! independent embedders can point at the same vocabulary document without
//! either depending on the other.
//! - [`lint_vocabulary`] / [`Finding`] — judge such a document rather than read
//! it. [`parse_vocabulary`] is permissive by design (a key it cannot read is
//! a key it skips), which leaves a set of ways a document can say something
//! nothing acts on — `values: cloesd` loading as an *open* vocabulary being
//! the one with teeth. This is where an author is told. [`load_schema`]
//! reports the same kind of finding over a schema document, and the
//! `fig-schema` binary in this crate is a front end for both, reachable as
//! `fig schema lint` wherever fig is installed.
//! - [`load_schema`] / [`Loaded`] / [`LoadError`] — a [`Schema`] from a
//! document, with an [`Origin`] on every rule saying which document and
//! which entry it was read from, so the precedence include order decided is
//! visible rather than inferred.
//! - [`Presentation`] / [`Icon`] / [`Tint`] — renderer-neutral display hints,
//! carried on every rule but never interpreted here.
//! - [`Consequence`] / [`Severity`] — what changing a field *costs*, so a host
//! can warn before committing an expensive or irreversible edit. A separate
//! fact from a [`Tint`], which says only how loudly to draw the field.
//!
//! - [`Issue`] / [`IssueKind`] — why a value failed, as data rather than
//! prose, so the embedder owns the wording. [`Issue`]'s `Display` renders a
//! reasonable English default for embedders that don't care.
//! [`IssueKind::Unchecked`] is the one that says a value was *not checked*
//! rather than that it is wrong — a constraint of a kind the validator does
//! not know fails closed, and this is how a reader tells the two apart.
//! - [`Schema::check`] / [`Verdict`] — the whole-document check: every node
//! against the rule that governs it, its shape against the rule's type
//! ([`FieldType::admits`]) and its value against the rule's constraint.
//! What `fig check` does not answer: not whether a file parses, but whether
//! what it parsed is valid. `fig-schema check` is this over a file and a
//! discovered schema; `explain` and `complete` are [`Schema::rules_for`]
//! and a rule's terms, rendered.
//!
//! The public structs are `#[non_exhaustive]`, so they are built from a
//! constructor plus chainable setters ([`FieldRule::new`], [`Term::value`],
//! [`Presentation::default`]) rather than a struct literal. That is what lets a
//! later release add a hint without costing every embedder a major version.
//!
//! # Example
//!
//! ```
//! use fig::Value;
//! use fig_schema::{
//! Consequence, FieldRule, FieldType, PathPat, Presentation, Schema, Seg, Severity,
//! Term, Validate, Validation, validate_enum,
//! };
//!
//! // The embedder's own constraint type — the seam this crate is built around.
//! struct Vocabulary { values: Vec<Term>, closed: bool }
//!
//! impl Validate for Vocabulary {
//! fn validate(&self, value: &Value) -> Validation {
//! validate_enum(&self.values, self.closed, value)
//! }
//! }
//!
//! let schema = Schema::new(vec![
//! FieldRule::new(PathPat::each_item_of("audience"))
//! .ty(FieldType::Str)
//! .constraint(Vocabulary {
//! values: vec![Term::value("public"), Term::value("family")],
//! closed: true,
//! })
//! .present(Presentation::default().title("Audience"))
//! .on_change(
//! Consequence::when("public", "Anyone with the link will be able to read this.")
//! .severity(Severity::Confirm),
//! ),
//! ]);
//!
//! // Find the rule governing `audience[0]`, then check a candidate against it.
//! let path = [Seg::Key("audience".into()), Seg::Index(0)];
//! let rule = schema.rule_for(&path).expect("a rule governs this path");
//! assert!(rule.validate(&Value::Str("public".into())).is_ok());
//!
//! // Valid, but not free — ask before committing it.
//! assert_eq!(
//! rule.severity_of(&Value::Str("public".into())),
//! Some(Severity::Confirm),
//! );
//! assert_eq!(rule.severity_of(&Value::Str("family".into())), None);
//!
//! let rejected = rule.validate(&Value::Str("familly".into()));
//! assert!(rejected.is_reject());
//! assert_eq!(
//! rejected.issue().unwrap().suggestion.as_deref(),
//! Some("family"),
//! );
//! ```
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;