diff --git a/AGENTS.md b/AGENTS.md index f6c7ca9..7bd10f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,6 +46,7 @@ In [docs/decisions.md](docs/decisions.md): - A change to what exists is a major; a minor only adds - Seeded output is promised within one version - An error is a contract by what it names, not its bytes +- A load reports every mistake at once - Formats are checked after all data is loaded, so their errors name the category - Raising the lowest supported Go is a major - The format check runs on the latest Go only diff --git a/README.md b/README.md index 0bb4537..80b7546 100644 --- a/README.md +++ b/README.md @@ -291,6 +291,11 @@ ok, err := fejkdata.IsTemplate(arg) // an inline template by its shape, el | `WithDataFS(fsys)` | layer an `fs.FS`, such as your own `embed.FS` | | `WithoutShippedData()` | load only what you give | +`New` refuses a mistake in the data and `NewTemplate` one in the template, so on a +loaded generator `Fake` fails only for a path that names nothing or could name two +things, `FakeStruct` only for a non-struct argument or a type its tags do not describe, +with the same error every call, and `Template.Fake` cannot fail at all. + A `*Record` carries its columns via `Columns()` — each a `Column` of `Name`, `DataType`, rendered `Value` and `Null` — and serializes them with `JSON()` (one object), `CSVHeader()`/`CSVLine()`, or `SQLInsert(table)` — the shapes the @@ -837,10 +842,7 @@ the Development section below, and who ships a register the five above then draw Where two writers could expect different outputs, the template is a load error naming a spelling for each. One spelling per result; the wrong one is a load error naming the right one. -5. **Every mistake is a load error** — `New` rejects the data and `NewTemplate` - the inline template; on a loaded generator `Fake` fails only for a path that - names nothing or could name two things, `FakeStruct` only for a non-struct argument or a type its tags do not - describe, with the same error every call, and `Template.Fake` cannot fail at all. +5. **Errors are up front and easy to understand.** 6. **Zero to a value in one command** — `go install`, then `fejkdata sv_SE.person`: no checkout, no flag. Flags are GNU-form (`--seed 42`, `-n 3`) in any position; the first custom template needs no escape and no option. diff --git a/docs/decisions.md b/docs/decisions.md index 7cdcb04..bc66c4d 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -148,8 +148,16 @@ this repo's own are. 2026-09-16, Lilleman auf Larv. -A script branches on the exit code and reads the named path or spelling, so those hold; -wording improves in a minor. +Goal 5. A script branches on the exit code and reads the named path or spelling, so +those hold; wording improves in a minor. + +## A load reports every mistake at once + +2026-09-30, Lilleman auf Larv. Goal 5. An author learns everything wrong with the data +in one load, not one mistake per run: `New` and `NewTemplate` report every mistake in one +error, ordered by the path each names. A mistake following only from another, such as a +reference into a category that did not compile, is left out, so each one names something +to fix. Valid while a load checks the whole set before its first render. ## Formats are checked after all data is loaded, so their errors name the category diff --git a/todo.md b/todo.md index f748ed9..d73406a 100644 --- a/todo.md +++ b/todo.md @@ -208,6 +208,9 @@ by a `data-import/` script, as README goal 12 asks. ### Library and CLI +- Report every mistake a load finds in one error, as the decision "A load reports every + mistake at once" states: `New` and `NewTemplate` stop at the first, so data holding + two mistakes takes two runs to fix. Split it into sub-items before starting. - Rename `newRand` to `newGeneratorState` and `Generator.rand` to `state`: both name half of a `generatorState`, hiding its `{seq()}` counters, and `New`'s local `rng` shadows the `rng` interface. @@ -297,10 +300,6 @@ by a `data-import/` script, as README goal 12 asks. together, where the fence counts them alternatives and compares neither. Have the error name the path spelling that holds, `{/geo.SE.locality.name}|{/geo.SE.municipality.name}`, as the README's rule on a rejected spelling asks. -- Decide, in "An error is a contract by what it names", which of several mistakes a - load names, and link the entry to goal 5, which it serves and does not name. The - fence names the lowest by route and path, so a data edit can move which one is named; - proposed: fixed within a version, as seeded output is, and free to change in any release. - Name the file a link error comes from beside its category path, `sub.x (/d/a/sub/x.json): …`: with several `--data-path` layers the author has to work out which directory won, while a parse error on the same file names it.