@sdboyer/thema-ui 0.0.0-stage → 0.1.0

package/errors/E0210.md

@@ -0,0 +1,44 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0210: a minor version requires a field its predecessor does not declare
+
+A minor version is backward compatible with its predecessor: every instance of
+the predecessor is an instance of it. A new field that data must supply breaks
+that, since no prior instance supplies it. Give the field a default, make it
+optional, or make this a major version.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+		"1": {
+			schema: {
+				a: string
+				b: int
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0210]: b in schema 0.1 is required in the new schema but not declared in the prior one
+  --> lineage.cue:12:5
+   |
+12 |                 b: int
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule field-added-required)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0211.md

@@ -0,0 +1,43 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0211: a minor version rejects a field its predecessor declares
+
+A minor version accepts every instance of its predecessor. Removing a field the
+predecessor declares rejects every instance that has it. The position is the
+predecessor's declaration, since the new schema has nothing to point at.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+				b: int
+			}
+		}
+		"1": {
+			schema: {
+				a: string
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0211]: b in schema 0.1 is declared in the prior schema and not accepted by the new one
+ --> lineage.cue:7:5
+  |
+7 |                 b: int
+  |                 ^
+  |
+  = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule field-removed)
+  = help: make the change compatible, or make this version 1.0
+```

package/errors/E0212.md

@@ -0,0 +1,41 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0212: a minor version requires a field its predecessor left optional
+
+A field the predecessor left optional may be absent from its instances; a minor
+version that requires it rejects those instances.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a?: int
+			}
+		}
+		"1": {
+			schema: {
+				a!: int
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0212]: a in schema 0.1 was optional and is now required
+  --> lineage.cue:11:5
+   |
+11 |                 a!: int
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule field-now-required)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0213.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0213: a minor version drops a default its predecessor filled
+
+A defaulted field is filled when absent, and a consumer of the predecessor sees
+that value. A minor version that makes the field optional leaves it absent
+instead, so the same data means something different.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: *1 | int
+			}
+		}
+		"1": {
+			schema: {
+				a?: int
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0213]: a in schema 0.1 was filled when absent and is now left absent
+  --> lineage.cue:11:5
+   |
+11 |                 a?: int
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule default-removed)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0214.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0214: a minor version changes a default
+
+A defaulted field fills with its default when absent. A minor version that
+changes the default makes the same absent field mean a different value, which
+is a breaking change for every instance that relied on the old one.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				u: *"foo" | "bar" | "baz"
+			}
+		}
+		"1": {
+			schema: {
+				u: "foo" | "bar" | *"baz"
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0214]: u in schema 0.1 fills with "baz" when absent, where the prior schema filled it with "foo"
+  --> lineage.cue:11:5
+   |
+11 |                 u: "foo" | "bar" | *"baz"
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule default-changed)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0215.md

@@ -0,0 +1,44 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0215: a minor version narrows the values a field accepts
+
+A minor version accepts every value its predecessor accepts at every path. A
+bound, a narrower kind or a smaller disjunction rejects values the predecessor
+accepted. A field the predecessor admitted only through `...` is the same case
+(see also issue #47): it may already hold any value, so declaring it with a type
+narrows it.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				n: int
+			}
+		}
+		"1": {
+			schema: {
+				n: int & >=0
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0215]: n in schema 0.1 is now uint, which does not accept every value of the prior int
+  --> lineage.cue:11:5
+   |
+11 |                 n: int & >=0
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule value-narrowed)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0216.md

@@ -0,0 +1,41 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0216: a minor version narrows a list's length
+
+A list's length is part of what a schema accepts. A minor version that fixes or
+shortens a list's length rejects the predecessor's longer and shorter lists.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				l: [...int]
+			}
+		}
+		"1": {
+			schema: {
+				l: [int, int]
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0216]: l in schema 0.1 had length uint and now has length 2
+  --> lineage.cue:11:5
+   |
+11 |                 l: [int, int]
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule length-narrowed)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0217.md

@@ -0,0 +1,43 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0217: a minor version narrows the field names a struct accepts
+
+A struct written with `...` accepts any field name; its instances may hold
+fields the schema never names. A minor version that closes the struct, or
+narrows it to a pattern, rejects those instances.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: int
+				...
+			}
+		}
+		"1": {
+			schema: {
+				a: int
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0217]: schema 0.1 accepts any field name in the prior schema and is closed in the new one
+  --> lineage.cue:11:4
+   |
+11 |             schema: {
+   |             ^^^^^^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule labels-narrowed)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0218.md

@@ -0,0 +1,44 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0218: a minor version adds or tightens a validator
+
+A validator such as strings.MinRunes rejects values that fail it. A minor
+version that adds one, or tightens one, rejects values the predecessor
+accepted.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+import "strings"
+
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				s: string
+			}
+		}
+		"1": {
+			schema: {
+				s: strings.MinRunes(1)
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0218]: s in schema 0.1 must now satisfy strings.MinRunes(1), which the prior schema did not require
+  --> lineage.cue:13:5
+   |
+13 |                 s: strings.MinRunes(1)
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule validator-added)
+   = help: make the change compatible, or make this version 1.0
+```

package/errors/E0230.md

@@ -0,0 +1,46 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0230: a minor version constrains a field by another field's value, which the checker cannot compare
+
+The compatibility checker compares each field's constraint between the two
+schemas. A field constrained by another field's value has no constraint of its
+own to compare, so the checker cannot decide, and a minor version it cannot
+decide about does not bind: change the schema so the checker can decide, or
+make it a major version.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: int
+				b?: a
+			}
+		}
+		"1": {
+			schema: {
+				a: int
+				b?: >a
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0230]: b in schema 0.1 is constrained by a in both schemas, differently; the checker cannot compare constraints between fields
+  --> lineage.cue:13:5
+   |
+13 |                 b?: >a
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule unknown-crossfield)
+   = help: change the schema so the checker can decide, or make this version 1.0
+```

package/errors/E0232.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0232: a minor version changes a validator the checker has no rule for
+
+The compatibility checker knows a fixed set of validators and how each narrows a
+value. A minor version that adds or changes one it has no rule for cannot be
+shown compatible.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				n: int
+			}
+		}
+		"1": {
+			schema: {
+				n: int & matchN(1, [>0, <0])
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0232]: n in schema 0.1 must now satisfy matchN(1, [>0, <0]), for which the checker has no rule
+  --> lineage.cue:11:5
+   |
+11 |                 n: int & matchN(1, [>0, <0])
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule unknown-validator)
+   = help: change the schema so the checker can decide, or make this version 1.0
+```

package/errors/E0233.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0233: a minor version's disjunction cannot be shown to cover its predecessor's
+
+The checker shows a disjunction compatible by finding, for each alternative of
+the predecessor, one alternative of the new schema that covers it. Alternatives
+that cover it only together are not combined, so the checker cannot decide.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				n: int
+			}
+		}
+		"1": {
+			schema: {
+				n: >=0 | <0
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0233]: n in schema 0.1 is now >=0 | <0, no single alternative of which covers the prior alternative int; the checker does not combine alternatives
+  --> lineage.cue:11:5
+   |
+11 |                 n: >=0 | <0
+   |                 ^
+   |
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule unknown-disjunction)
+   = help: change the schema so the checker can decide, or make this version 1.0
+```

package/errors/E0234.md

@@ -0,0 +1,43 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0234: a minor version's pattern constraints cannot be shown to cover its predecessor's
+
+Pattern constraints decide what a struct accepts for field names it does not
+declare. The checker compares one pattern per side; several on each side are
+compared only for identity, so a change among them cannot be decided.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				m: {[=~"^a"]: int, [=~"^b"]: string}
+			}
+		}
+		"1": {
+			schema: {
+				m: {[=~"^a"]: int, [=~"^b"]: number}
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0234]: m in schema 0.1 is not backward compatible with 0.0
+  --> lineage.cue:11:5
+   |
+11 |                 m: {[=~"^a"]: int, [=~"^b"]: number}
+   |                 ^
+   |
+   = note: m in schema 0.1 has several pattern constraints, [=~"^a"], [=~"^b"] in the prior schema and [=~"^a"], [=~"^b"] in the new one, which the checker compares only for identity
+   = note: schema 0.1 is declared as a minor version of 0.0, so every instance of schema 0.0 must be an instance of it (compatibility rule unknown-patterns)
+   = help: change the schema so the checker can decide, or make this version 1.0
+```

package/errors/E0240.md

@@ -0,0 +1,31 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0240: the lineage has no schema with that version
+
+A schema was asked for by a version the lineage does not have. The help lists
+the versions it does.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0240]: lineage ship has no schema 9.9
+  |
+  = help: its versions are 0.0
+```

package/errors/E0242.md

@@ -0,0 +1,5 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0242: a published schema was deleted
+
+**Retired.** thema.IsAppendOnly, which reported it, was replaced by thema.CheckAppendOnly (#56), which reports a removed version as E0252.

package/errors/E0243.md

@@ -0,0 +1,5 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0243: a published schema was changed
+
+**Retired.** thema.IsAppendOnly, which reported it, was replaced by thema.CheckAppendOnly (#56), which compares versions by their identity, and reports a changed schema as E0250 and a changed lens as E0251.

package/errors/E0250.md

@@ -0,0 +1,39 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0250: a published version's schema was changed
+
+Once a version is published, instances are validated against it as it was
+published, so its schema never changes. Here the candidate's 0.0 narrows
+name, which the published 0.0 left as any string. A change, compatible or not,
+is a new version: here, the tip, cut as 0.1 or 1.0.
+
+## Example
+
+`candidate/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string & !=""
+}
+```
+
+`published/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+thema reports:
+
+```
+error[E0250]: the schema in history/0.0.thema is not as published
+ --> candidate/ship/history/0.0.thema:1:1
+  |
+1 | Schema: {
+  | ^^^^^^
+  |
+  = note: a published version never changes: instances were validated against it as it was published
+  = help: restore the schema in history/0.0.thema as it was published, and make the change in a new version
+```