@sdboyer/thema-ui 0.0.0-bootstrap.0 → 0.1.0

package/errors/E0251.md

@@ -0,0 +1,83 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0251: a published version's lens was changed
+
+A version's lenses are part of it: an instance translated through the
+published lens would translate differently through a changed one. Here the
+candidate's 1.0 keeps its schema, but its ForwardLens writes a different
+placeholder. The schema's identity is unchanged and its lenses' is not.
+
+## Example
+
+`candidate/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+`candidate/ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	name: string
+	size: int
+}
+
+ForwardLens: {
+	v0_0: _
+	v1_0: {
+		size: 0
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "0 is a placeholder"
+		}]
+	}
+}
+```
+
+`published/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+`published/ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	name: string
+	size: int
+}
+
+ForwardLens: {
+	v0_0: _
+	v1_0: {
+		size: -1
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "-1 is a placeholder"
+		}]
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0251]: the ForwardLens in history/1.0.thema is not as published
+ --> candidate/ship/history/1.0.thema:6:1
+  |
+6 | ForwardLens: {
+  | ^^^^^^^^^^^
+  |
+  = note: a version's lenses are part of it: instances already translated through the published lens would translate differently
+  = help: restore the ForwardLens in history/1.0.thema as it was published
+```

package/errors/E0252.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0252: a published version was removed
+
+A published version may have instances, so it is never removed. Here the
+candidate's history/ stops at 0.0, and 0.1, which was published, is gone.
+
+## Example
+
+`candidate/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+`published/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+`published/ship/history/0.1.thema`:
+
+```cue
+Schema: {
+	name:  string
+	size?: int
+}
+```
+
+thema reports:
+
+```
+error[E0252]: the lineage removes published version 0.1
+  |
+  = note: the schema in history/0.1.thema was published, so instances of it may exist
+  = help: restore the schema in history/0.1.thema as it was published; a published version is never removed
+```

package/errors/E0253.md

@@ -0,0 +1,142 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0253: a new version comes before the newest published version
+
+Versions are only appended: a new version comes after the newest published
+one. Here 0.0 and 1.0 were published, and the candidate adds 0.1 between them,
+so the published 1.0 would no longer follow the version it was published
+after. 1.0 itself is as published: its lenses map the same from 0.1 as from
+0.0, and its backward lens derives the same drop of crew, though the drop's
+message now names 0.1.
+
+## Example
+
+`candidate/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	size: int & <10
+}
+```
+
+`candidate/ship/history/0.1.thema`:
+
+```cue
+Schema: {
+	size: int & <20
+}
+
+BackwardLens: {
+	v0_1: _
+	v0_0: {
+		size: 0
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "0 is a placeholder"
+		}]
+	}
+}
+```
+
+`candidate/ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	size: string
+	crew: int
+}
+
+ForwardLens: {
+	v0_1: _
+	v1_0: {
+		size: "unknown"
+		crew: 0
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "unknown is a placeholder"
+		}]
+		crew: [{
+			type:    Placeholder
+			message: "0 is a placeholder"
+		}]
+	}
+}
+
+BackwardLens: {
+	v1_0: _
+	v0_1: {
+		size: 0
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "0 is a placeholder"
+		}]
+	}
+}
+```
+
+`published/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	size: int & <10
+}
+```
+
+`published/ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	size: string
+	crew: int
+}
+
+ForwardLens: {
+	v0_0: _
+	v1_0: {
+		size: "unknown"
+		crew: 0
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "unknown is a placeholder"
+		}]
+		crew: [{
+			type:    Placeholder
+			message: "0 is a placeholder"
+		}]
+	}
+}
+
+BackwardLens: {
+	v1_0: _
+	v0_0: {
+		size: 0
+	}
+	lacunas: {
+		size: [{
+			type:    Placeholder
+			message: "0 is a placeholder"
+		}]
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0253]: new version 0.1 comes before published version 1.0
+ --> candidate/ship/history/0.1.thema:1:1
+  |
+1 | Schema: {
+  | ^^^^^^
+  |
+  = note: versions are only appended: a new version comes after the newest published one, 1.0, so that every published version keeps its predecessor
+  = help: remove the schema in history/0.1.thema, and make the change in a version after 1.0
+```

package/errors/E0254.md

@@ -0,0 +1,38 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0254: the lineage's name differs from the name it was published with
+
+A lineage is named for its directory, and its name is part of what was
+published: what refers to the lineage names it. Here ship's history is
+published again as boat. A lineage with a new name is a new lineage.
+
+## Example
+
+`candidate/boat/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+`published/ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+thema reports:
+
+```
+error[E0254]: the lineage is named boat, but was published as ship
+ --> candidate/boat/history/0.0.thema:1:1
+  |
+1 | Schema: {
+  | ^^^^^^
+  |
+  = note: a lineage's name is part of what was published: what refers to it names it
+  = help: name it ship, or publish it as a new lineage
+```

package/errors/E0301.md

@@ -0,0 +1,43 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0301: the lineage lacks a lens its versions require
+
+A lineage declares a lens from every schema back to its predecessor, and one
+forward across every major version, so that an instance of any version can be
+translated to any other. This lineage adds version 0.1 without the lens back to
+0.0.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+		"1": {
+			schema: {
+				a: string
+				b?: int
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0301]: the lineage has no lens 0.1->0.0
+ --> lineage.cue:1:1
+  |
+1 | name: "ship"
+  | ^^^^
+  |
+  = note: every schema needs a lens back to its predecessor, so that instances of 0.1 can be translated to 0.0
+```

package/errors/E0302.md

@@ -0,0 +1,58 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0302: the lineage declares a lens its versions do not require
+
+A lineage declares exactly the lenses its versions call for. A forward lens
+across a minor version is one they do not: a minor version is backward
+compatible, so translating forward is implicit. The note says why the lens is
+not called for.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+		"1": {
+			schema: {
+				a: string
+				b?: int
+			}
+		}
+	}
+}
+lenses: {
+	"0.1->0.0": {
+		v0_1: _
+		v0_0: {
+			a: v0_1.a
+		}
+	}
+	"0.0->0.1": {
+		v0_0: _
+		v0_1: {
+			a: v0_0.a
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0302]: the lineage's versions do not call for lens 0.0->0.1
+  --> lineage.cue:24:2
+   |
+24 |     "0.0->0.1": {
+   |     ^^^^^^^^^^
+   |
+   = note: 0.1 is backward compatible with 0.0, so translating forward is implicit
+   = help: a lineage declares a lens from each schema back to its predecessor, and one forward across each major version
+```

package/errors/E0303.md

@@ -0,0 +1,57 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0303: a lens does not accept every instance of its source schema
+
+A lens takes any instance of its source schema, in the field named after the
+source version (v0_1 for a lens from 0.1), so it must accept every one of
+them. A lens that constrains that field rejects some instances. Leave it as
+`_`.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: int
+			}
+		}
+		"1": {
+			schema: {
+				a: int
+				b?: int
+			}
+		}
+	}
+}
+lenses: {
+	"0.1->0.0": {
+		v0_1: {
+			a: string
+		}
+		v0_0: {
+			a: v0_1.a
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0303]: the input of lens 0.1->0.0 does not accept every instance of schema 0.1
+   --> lineage.cue:19:3
+    |
+ 19 |         v0_1: {
+    |         ^^^^
+    |
+    = note: in thema's own CUE
+     --> thema/lineage.cue:183:11
+    = detail: field a not present in {a:int,b?:int}
+              missing field "a"
+    = help: v0_1 stands for any instance of its source schema; leave it as _
+```

package/errors/E0304.md

@@ -0,0 +1,9 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0304: what a lens produces is not an instance of its target schema
+
+This condition cannot arise when thema's checker is sound: every lens is proven total at bind, and the proof names the mapping at fault (E0360 to E0372) before this check runs.
+
+If thema reports it, the bug is in thema, not in the lineage or the data.
+Please report it at https://github.com/sdboyer/thema/issues with the lineage
+and, for a translation, the instance.

package/errors/E0305.md

@@ -0,0 +1,55 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0305: a lens writes a field its target schema does not declare
+
+A lens writes only fields its target schema declares, however open the author
+wrote the schema: a lens is bound to the schema as declared. A field written
+under a condition counts; it exists once data makes the condition true. Hidden
+fields the target does not declare are the lens's own scratch space and are
+not checked.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+		"1": {
+			schema: {
+				a:  string
+				b?: int
+			}
+		}
+	}
+}
+lenses: {
+	"0.1->0.0": {
+		v0_1: _
+		v0_0: {
+			a: v0_1.a
+			if v0_1.a == "boom" {
+				extra: 1
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0305]: the result of lens 0.1->0.0 writes extra, which schema 0.0 does not declare
+  --> lineage.cue:20:3
+   |
+20 |         v0_0: {
+   |         ^^^^
+   |
+   = help: a lens writes only fields its target schema declares, however open the schema is written
+```

package/errors/E0307.md

@@ -0,0 +1,9 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0307: translating an instance, a lens produced something that is not concrete
+
+This condition cannot arise when thema's checker is sound: every lens is proven total at bind, which rules out a result field left as a constraint for any instance (E0365).
+
+If thema reports it, the bug is in thema, not in the lineage or the data.
+Please report it at https://github.com/sdboyer/thema/issues with the lineage
+and, for a translation, the instance.

package/errors/E0308.md

@@ -0,0 +1,9 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0308: translating an instance, a lens failed
+
+This condition cannot arise when thema's checker is sound: every lens is proven total at bind, which rules out a result the target schema rejects for any instance (E0360, E0366, E0367).
+
+If thema reports it, the bug is in thema, not in the lineage or the data.
+Please report it at https://github.com/sdboyer/thema/issues with the lineage
+and, for a translation, the instance.

package/errors/E0310.md

@@ -0,0 +1,46 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0310: a lens does not declare the instance it takes
+
+A lens binds the instance it takes to a field named after the version it
+maps from: v1_0 for a lens from 1.0. This lens does not declare it, so it has
+nothing to map from.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+lin: {
+	name: "ship"
+	schemas: {
+		"0": "0": {
+			schema: {a: string}
+		}
+		"1": "0": {
+			schema: {b: string}
+		}
+	}
+	lenses: {
+		"1.0->0.0": {
+			v0_0: {a: "x"}
+		}
+		"0.0->1.0": {
+			v0_0: _
+			v1_0: {b: v0_0.a}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0310]: lens 1.0->0.0 does not declare v1_0, the instance of 1.0 it takes
+  --> lineage.cue:12:3
+   |
+12 |         "1.0->0.0": {
+   |         ^^^^^^^^^^
+   |
+   = help: write v1_0: _
+```

package/errors/E0311.md

@@ -0,0 +1,46 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0311: a lens does not declare the instance it returns
+
+A lens returns the instance it builds in a field named after the version it
+maps to: v0_0 for a lens to 0.0. This lens does not declare it, so it returns
+nothing.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+lin: {
+	name: "ship"
+	schemas: {
+		"0": "0": {
+			schema: {a: string}
+		}
+		"1": "0": {
+			schema: {b: string}
+		}
+	}
+	lenses: {
+		"1.0->0.0": {
+			v1_0: _
+		}
+		"0.0->1.0": {
+			v0_0: _
+			v1_0: {b: v0_0.a}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0311]: lens 1.0->0.0 does not declare v0_0, the instance of 0.0 it returns
+  --> lineage.cue:12:3
+   |
+12 |         "1.0->0.0": {
+   |         ^^^^^^^^^^
+   |
+   = help: write v0_0: {...}, mapping each field of 0.0
+```

package/errors/E0330.md

@@ -0,0 +1,67 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0330: a lens body holds something that is not a mapping
+
+A lens body holds only mappings: a target field and where it comes from.
+Embeddings, comprehensions and let declarations are not mappings. A reference
+to an optional field is guarded for you, and coalesce decides what to use when it
+is absent.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	b: string
+}
+
+ForwardLens: {
+	v0_0: _
+	v1_0: {
+		let x = v0_0.a
+		b: x
+	}
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	b: string
+}
+```
+
+thema reports:
+
+```
+error[E0330]: let is not allowed in a lens body
+ --> history/1.0.thema:8:3
+  |
+8 |         let x = v0_0.a
+  |         ^^^
+  |
+
+error[E0418]: x is not defined in a lens; an expression refers to v0_0, to len, quo, rem, div, mod and to the strings functions
+ --> history/1.0.thema:9:6
+  |
+9 |         b: x
+  |            ^
+  |
+
+error[E0347]: 0.0 declares a and 1.0 does not, and nothing maps it: write <field>: v0_0.a to move it, or a: _drop
+ --> history/1.0.thema:5:1
+  |
+5 | ForwardLens: {
+  | ^^^^^^^^^^^
+  |
+```