@sdboyer/thema-ui 0.0.0-stage → 0.1.0

package/errors/E0145.md

@@ -0,0 +1,48 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0145: a lens refers to another lens of the lineage
+
+A lens reads a hidden field of another lens through the lineage (reference
+rule ref-lens-to-lens). Each lens declares what it needs.
+
+## 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: _
+			_fallback: "x"
+			v0_0: {a: v1_0.b}
+		}
+		"0.0->1.0": {
+			v0_0: _
+			v1_0: {b: lin.lenses["1.0->0.0"]._fallback}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0145]: v1_0.b in lens 0.0->1.0 refers to lenses["1.0->0.0"]._fallback, another lens
+  --> lineage.cue:19:14
+   |
+19 |             v1_0: {b: lin.lenses["1.0->0.0"]._fallback}
+   |                       ^^^
+   |
+   = note: reference rule ref-lens-to-lens
+   = help: a lens may refer only to v0_0, the instance it takes, its own body and CUE's builtin packages
+```

package/errors/E0146.md

@@ -0,0 +1,38 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0146: a reference cannot be resolved statically
+
+A schema selects a field of the lineage by a label only an instance decides.
+CUE leaves the selection pending, and thema cannot tell from the schema what
+the reference denotes (reference rule ref-unresolved). Written with constant
+labels it would be a reference thema can judge (a label the evaluator can
+fold, such as lin["na"+"me"], already is: it resolves to lin.name); either
+way, the schema writes the literal it wants.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+lin: {
+	name: "ship"
+	schemas: {
+		"0": "0": {
+			schema: {a: string, n: lin[a]}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0146]: n in schema 0.0 refers to the lineage[...], which thema cannot resolve statically
+ --> lineage.cue:5:27
+  |
+5 |             schema: {a: string, n: lin[a]}
+  |                                    ^^^
+  |
+  = note: reference rule ref-unresolved
+  = help: write the reference with constant labels, or declare what it needs inside the schema
+```

package/errors/E0147.md

@@ -0,0 +1,57 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0147: a version file imports a package its Schema does not use
+
+A version file's imports serve its Schema. A lens calls the strings functions
+without an import, so an import the Schema does not use has no purpose.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	name: string
+}
+```
+
+`ship/history/1.0.thema`:
+
+```cue
+import "strings"
+
+Schema: {
+	name:  string
+	label: string
+}
+
+ForwardLens: {
+	v0_0: _
+	v1_0: {
+		label: strings.ToUpper(v0_0.name)
+	}
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+import "strings"
+
+Schema: {
+	name:  string
+	label: string
+}
+```
+
+thema reports:
+
+```
+error[E0147]: history/1.0.thema imports strings, which its Schema does not use
+ --> history/1.0.thema:1:8
+  |
+1 | import "strings"
+  |        ^^^^^^^^^
+  |
+  = help: remove the import: a lens calls the strings functions without one
+```

package/errors/E0148.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0148: a numbered version file is at the top of the lineage's directory, not under history/
+
+A numbered version file sits at the top of the lineage's directory. The top
+holds only the tip, `tip.thema`, whose version is derived rather than written;
+numbered versions are frozen, and live under `history/`.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/1.0.thema`:
+
+```cue
+Schema: {
+	b: string
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	b: string
+}
+```
+
+thema reports:
+
+```
+error[E0148]: 1.0.thema is a numbered version at the top of the lineage's directory
+  |
+  = note: the top of the lineage's directory holds only the tip, tip.thema; numbered versions are frozen, and live under history/
+  = help: move it to history/1.0.thema
+```

package/errors/E0149.md

@@ -0,0 +1,27 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0149: the lineage's directory has no tip.thema
+
+The lineage has no `tip.thema`. The tip is the version being worked on, and is
+always present: after a cut it equals the newest version under `history/`. The
+development path, which binds the tip, and the clean check, which compares it
+with the history, need it; binding the history alone does not read it.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+thema reports:
+
+```
+error[E0149]: the lineage has no tip.thema
+  |
+  = note: the tip is the version being worked on, and is always present: after a cut it equals the newest version in history/
+  = help: add tip.thema, starting from a copy of the newest version's Schema
+```

package/errors/E0150.md

@@ -0,0 +1,77 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0150: a lens of the tip names a version other than the tip's parent, the newest version under history/
+
+A lens of the tip connects it to its parent, the newest version under
+`history/`, and names the parent's instance after that version. Here the
+`ForwardLens` was written when the newest version was 1.0, and then 1.1 was
+cut beneath it, as happens when the tip's branch is rebased onto one that cut
+a version. The lens still names `v1_0`, so it no longer connects the tip to its
+parent. Renaming the parameter is not enough on its own: the mappings were
+written against 1.0's schema, and need review against 1.1's.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	a: string
+	b: int
+}
+
+ForwardLens: {
+	v0_0: _
+	v1_0: {
+		b: 0
+	}
+}
+```
+
+`ship/history/1.1.thema`:
+
+```cue
+Schema: {
+	a:  string
+	b:  int
+	c?: string
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	a: string
+	b: int
+	d: bool
+}
+
+ForwardLens: {
+	v1_0: _
+	tip: {
+		d: false
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0150]: ForwardLens in tip.thema names v1_0, but the tip's parent is 1.1
+ --> tip.thema:8:2
+  |
+8 |     v1_0: _
+  |     ^^^^
+  |
+  = note: the lens was written against an older parent, 1.0; the newest version under history/ is now 1.1, history/1.1.thema
+  = help: declare v1_1: _ in place of v1_0, and review the mappings against 1.1's schema
+```

package/errors/E0151.md

@@ -0,0 +1,47 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0151: a schema or lens declares a hidden field or a hidden definition
+
+A version's ID is computed over its schema and lenses, and must be the same
+however the lineage is loaded. CUE scopes a hidden field (_x) or a hidden
+definition (_#X) to the package it is declared in, and writes its name
+qualified by that package wherever the value is used outside it: the same
+schema would hash one way compiled from its version files, another loaded as
+a package, and another imported (#250). So a schema, the joinSchema, and the
+input, result and lacunas of a lens declare neither. A helper in a schema is a
+definition (#X) or a let; a lens in the normal form keeps its scratch in hidden
+fields beside its input and result: its ID covers the values its result reads
+from them, but not their names.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	_limit: 10
+	count:  int & <=_limit
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	_limit: 10
+	count:  int & <=_limit
+}
+```
+
+thema reports:
+
+```
+error[E0151]: the schema in history/0.0.thema declares _limit, a hidden field
+ --> history/0.0.thema:2:2
+  |
+2 |     _limit: 10
+  |     ^^^^^^
+  |
+  = note: a version's ID must not depend on how its lineage is loaded, and how CUE writes a hidden name depends on the package the lineage was loaded through (#250)
+  = help: write a helper as a definition or a let instead; to declare a data field whose name starts with _, quote it: "_limit"
+```

package/errors/E0152.md

@@ -0,0 +1,35 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0152: the value a lineage is bound from is not the root of a value CUE built from source
+
+A lineage compiled on its own is filled into a larger value with `FillPath`
+and bound from there. The result is a value built in Go: CUE keeps no build
+instance for it, so bind cannot tell the lineage's own declarations from the
+value around it, and refuses it. `thema.Compose` writes the lineage into the
+larger value's package as a file instead, and the package loaded from those
+files binds. A field of a loaded package, passed instead of the package's
+root and the path to the field, is refused the same way.
+
+## Example
+
+`holder.cue`:
+
+```cue
+lineages: ship: _
+```
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: "0": "0": schema: {a?: string}
+```
+
+thema reports:
+
+```
+error[E0152]: a lineage is bound from the root of a value CUE built from source, and this root was built in Go
+  |
+  = note: bind tells the lineage's own declarations from the CUE around it by the build instance of the root it is bound from, and a value made by FillPath or Unify has none
+  = help: compose separately built lineages into one package with thema.Compose, load it, and bind each lineage from that package's root
+```

package/errors/E0201.md

@@ -0,0 +1,35 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0201: the first schema is not version 0.0
+
+Every lineage starts at version 0.0. Versions are contiguous from there, so a
+lineage whose first schema is any other version has a gap before it.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"1": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0201]: the first schema is version 1.0, not 0.0
+ --> lineage.cue:4:3
+  |
+4 |         "0": {
+  |         ^^^
+  |
+  = help: every lineage starts at version 0.0
+```

package/errors/E0202.md

@@ -0,0 +1,42 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0202: a schema's version does not follow its predecessor's
+
+Versions are contiguous: each schema is the next minor version of its
+predecessor, or the first version of the next major. A skipped version would be
+a version with no schema.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+		"2": {
+			schema: {
+				a: string
+				b?: int
+			}
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0202]: schema version 0.2 does not follow 0.0
+ --> lineage.cue:9:3
+  |
+9 |         "2": {
+  |         ^^^
+  |
+  = help: the next schema after 0.0 is version 0.1 or 1.0
+```

package/errors/E0203.md

@@ -0,0 +1,37 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0203: a major version declares no schemas
+
+A major version is a group of minor versions, keyed by minor version; its first
+schema is version N.0. A major version key with nothing under it declares no
+schema at all.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+	}
+	"1": {}
+}
+```
+
+thema reports:
+
+```
+error[E0203]: major version 1 declares no schemas
+  --> lineage.cue:10:2
+   |
+10 |     "1": {}
+   |     ^^^
+   |
+   = help: declare its first schema as version 1.0
+```

package/errors/E0204.md

@@ -0,0 +1,46 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0204: two version files declare the same version
+
+A version has one file. Two files at the same path, `history/0.0.thema`, can
+only reach the compiler through its API, as in a playground request, and
+would be two schemas for one version.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+thema reports:
+
+```
+error[E0204]: history/0.0.thema and history/0.0.thema both declare version 0.0
+ --> history/0.0.thema:1:1
+  |
+1 | Schema: {
+  | ^^^^^^
+  | ------ the other is here
+  |
+  = help: a version has one file, under history/
+```

package/errors/E0205.md

@@ -0,0 +1,47 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0205: the version files skip a version
+
+Versions are contiguous: each file is the next minor version of its
+predecessor, or the first version of the next major. A gap would be a version
+with no file.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/history/0.2.thema`:
+
+```cue
+Schema: {
+	a:  string
+	b?: int
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	a:  string
+	b?: int
+}
+```
+
+thema reports:
+
+```
+error[E0205]: history/0.2.thema skips a version: after 0.0 comes 0.1
+ --> history/0.2.thema:1:1
+  |
+1 | Schema: {
+  | ^^^^^^
+  |
+  = help: rename the file history/0.1.thema, or add the versions between
+```

package/errors/E0206.md

@@ -0,0 +1,47 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0206: a version file named as a major version is backward compatible with its predecessor
+
+Whether a version is major or minor is derived from the compatibility check,
+and the file's name must agree. This file is named as a major version, but its
+schema is backward compatible with its predecessor's, so it is a minor version.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/history/1.0.thema`:
+
+```cue
+Schema: {
+	a:  string
+	b?: int
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	a:  string
+	b?: int
+}
+```
+
+thema reports:
+
+```
+error[E0206]: history/1.0.thema is backward compatible with 0.0, so it is minor version 0.1, not a major version
+ --> history/1.0.thema:1:1
+  |
+1 | Schema: {
+  | ^^^^^^
+  |
+  = help: rename the file history/0.1.thema, or make a breaking change
+```

package/errors/E0208.md

@@ -0,0 +1,59 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0208: a major version is backward compatible with its predecessor
+
+A new major version is a breaking change: some instance of the predecessor is
+not an instance of it. A schema declared as N.0 that is backward compatible
+with its predecessor belongs under the previous major version, as its next
+minor version.
+
+## Example
+
+`lineage.cue`:
+
+```cue
+name: "ship"
+schemas: {
+	"0": {
+		"0": {
+			schema: {
+				a: string
+			}
+		}
+	}
+	"1": {
+		"0": {
+			schema: {
+				a: string
+				b?: int
+			}
+		}
+	}
+}
+lenses: {
+	"0.0->1.0": {
+		v0_0: _
+		v1_0: {
+			a: v0_0.a
+		}
+	}
+	"1.0->0.0": {
+		v1_0: _
+		v0_0: {
+			a: v1_0.a
+		}
+	}
+}
+```
+
+thema reports:
+
+```
+error[E0208]: schema 1.0 is backward compatible with 0.0, so it is not a major version
+  --> lineage.cue:12:4
+   |
+12 |             schema: {
+   |             ^^^^^^
+   |
+   = help: declare it as version 0.1, or make a breaking change
+```