diff --git a/README.md b/README.md index 4e0b47e..ae79666 100644 --- a/README.md +++ b/README.md @@ -1117,10 +1117,7 @@ Where the project is heading; the sections before Audience document what ships t 1. In the library, the caller supplies everything that can change the output: data, seed and date. 11. **No unnecessary runtime dependencies** — use standard library by default. -12. **The docs are a map of the template language.** - 1. Every feature has its own heading. - 2. Every example runs as a test and shows its output. - 3. Each rule is stated in one place. +12. **Great documentation.** 13. **It is fast enough that you never notice it with the shipped data.** 1. A render's cost grows only with the data it reaches. 14. **Strongly prioritize data sourced from good online sources** @@ -1313,6 +1310,21 @@ replaces what it uploaded before. For a tag older than the latest release it lea tap, the bucket, the image's `latest` tags and the repositories alone, since each holds one version. +### Documentation + +How the README serves goal 12: + +- The top shows the CLI and the library side by side, each a short quickstart rendering + the same value. +- A table of the shipped data follows: every path, an example value, and what makes it + valid or where it comes from. +- Recipes show common tasks end to end. +- Every feature has its own heading, and the docs are a map of the template language. +- Every example runs as a test and shows its output. +- Each rule is stated in one place. +- Edge cases and a category's caveats sit in the reference sections, below what a first + reader needs. + ## License MIT — see [LICENSE](LICENSE). Forked from [github.com/Timewave-AB/fakes](https://github.com/Timewave-AB/fakes). diff --git a/todo.md b/todo.md index b38ca2a..35ef2a1 100644 --- a/todo.md +++ b/todo.md @@ -6,7 +6,7 @@ `Bar = 9` -`Next ID = 258` +`Next ID = 262` | Goal | W | |---|---| @@ -52,9 +52,6 @@ | 10.1 | 0.55 | | 11 | 0.50 | | 12 | 0.45 | -| 12.1 | 0.45 | -| 12.2 | 0.45 | -| 12.3 | 0.45 | | 13 | 0.40 | | 13.1 | 0.40 | | 14 | 0.35 | @@ -102,6 +99,7 @@ | 177 | 0.2.0 | decision | **Run the nine-seat comprehension panel and the scoring run again once item 107 has moved the engine, and file what the panel names.** | 1 | 3 | 2 | 3 | 9 | 3 | 20.4 | | 244 | 0.2.0 | | **Draw `en_US.company`'s suffixes and name patterns from SEC company names, and add `en_US.naics`, a table of NAICS 2022 codes.** | 2 | 4 | 3 | 6 | 6 | 2.1 | 20.4 | | 247 | 0.2.0 | | **Add `en_US.licenseplate`, drawn per state from that state's pattern.** | 2 | 4 | 3 | 6 | 6 | 2, 4 | 20.4 | +| 259 | 0.2.0 | | **Follow the quickstarts with a table of every shipped path, its example value and what makes it valid or where it comes from, generated from the data and checked by a test.** | 2 | 4 | 4 | 8 | 8 | 12, 15 | 20.2 | | 196 | 0.2.0 | decision | **Name, in the error for a reference nothing loaded provides, the module the reader's manifest reads by default that would provide it, or say none does.** | 3 | 4 | 6 | 6 | 8 | 6.2, 9.2 | 20.0 | | 91 | 0.2.0 | | **Accept a path through a name as a `calc` operand, so `{/misc.coordinate as c}{c}: {calc(c.lat * 60)}` computes from the coordinate `{c}` prints.** | 3 | 4 | 7 | 6 | 7 | 4.1, 5.3 | 19.9 | | 223 | 0.2.0 | | **Let a column draw a key from another record's rows, so an order's `user_id` names a user the same run wrote.** | 4 | 6 | 9 | 7 | 6 | 2, 4.1 | 19.9 | @@ -111,12 +109,14 @@ | 220 | 0.2.0 | | **Suggest the nearest name where a path segment names nothing: `no entry "adress"; did you mean "address"?`.** | 1 | 3 | 3 | 6 | 6 | 6 | 19.2 | | 222 | 0.2.0 | | **Write `--format sql` and `SQLInsert` rows as multi-row INSERTs, so a bulk fixture loads fast.** | 2 | 3 | 3 | 6 | 5 | 1 | 19.2 | | 41 | 0.2.0 | decision | **Key every table by one key column, as the decision "A table selects by one key column, a code, never a free-form name" states.** | 6 | 7 | 5 | 7 | 8 | 5.5 | 19.1 | +| 258 | 0.2.0 | | **Open the README with a CLI quickstart and a Go quickstart side by side, rendering the same value.** | 1 | 1 | 2 | 7 | 7 | 12 | 19.1 | | 52 | 0.2.0 | | **Name the file a link error comes from beside its category path, `sub.x (/d/a/sub/x.json): …`.** | 1 | 2 | 2 | 5 | 7 | 6 | 19.0 | | 117 | 0.2.0 | | **List the fields of what a path has reached when its next segment names one that is not there: `{/word as a}{a.zz}` reports `no field "zz"; word has w`.** | 1 | 2 | 3 | 5 | 7 | 6 | 19.0 | | 28 | 0.2.0 | decision | **Accept a middle name, and draw a `personnummer` whose sex matches a sex selected through a named pick.** | 4 | 4 | 6 | 6 | 7 | 4.1 | 18.9 | | 24 | 0.2.0 | defect | **Stop `misc.territory[EH].tld` rendering `.eh`, the one shipped TLD `misc.tld` does not hold.** | 1 | 1 | 1 | 4 | 7 | 4 | 18.6 | | 239 | 0.2.0 | | **Add `sv_SE.month` and `sv_SE.weekday` names from CLDR, and `sv_SE.holiday` from lag 1989:253.** | 2 | 3 | 2 | 5 | 6 | 2.1 | 18.6 | | 250 | 0.2.0 | | **Add `en_US.month` and `en_US.weekday` names from CLDR, and `en_US.holiday`, the federal holidays.** | 2 | 3 | 2 | 5 | 6 | 2.1 | 18.6 | +| 260 | 0.2.0 | | **Add a Recipes section: seed a PostgreSQL table, fill a struct in a Go test, make a column unique, and build parent and child records in Go.** | 1 | 3 | 3 | 7 | 7 | 12 | 18.6 | | 178 | 0.2.0 | | **Plan with the systems architect which `internal/` packages the engine splits into, by area, and how each type stops being written by more than one stage, then file the moves as items.** | 1 | 3 | 9 | 2 | 9 | 3, 3.2 | 18.4 | | 246 | 0.2.0 | | **Add `en_US.bankaccount`, an account number of at most 17 characters, the width of a Nacha ACH entry's account field.** | 1 | 2 | 2 | 5 | 5 | 2.1 | 18.0 | | 193 | 0.2.0 | decision | **Move the largest shipped packages into nested Go modules that keep their import paths, once `TestShippedDataStaysUnder100MiB` fails.** | 6 | 6 | 6 | 6 | 7 | 2.2, 2 | 17.8 | @@ -159,7 +159,7 @@ | 46 | 0.2.0 | | **Report the same error every load for a table with two bad options.** | 2 | 2 | 2 | 3 | 7 | 6, 10 | 14.0 | | 110 | 0.2.0 | | **Refuse an empty segment in a path `Fake` and `FakeRecord` take, as a reference does: `sv_SE.person.` reports `path has an empty segment`.** | 1 | 1 | 2 | 3 | 6 | 6 | 13.8 | | 158 | 0.2.0 | | **Drop a UTF-8 byte order mark that starts stdin, and say in the README how to stop PowerShell 5.1 sending `Göteborg` as `G?teborg`.** | 2 | 2 | 2 | 4 | 5 | 7.2, 5.1 | 13.5 | -| 226 | 0.2.0 | | **Show in the README how to make a column unique, such as an email's local part carrying `{seq()}`.** | 1 | 2 | 1 | 4 | 4 | 4 | 13.3 | +| 261 | 0.2.0 | | **Move the README's edge cases and each category's caveats into the reference sections, below what a first reader needs.** | 2 | 4 | 4 | 5 | 7 | 12 | 13.3 | | 166 | 0.2.0 | | **Let a key or name cell hold a bracket, a brace, a double quote or a pipe, so the table loads, its row draws at random, and only a selector cannot reach it.** | 2 | 2 | 4 | 3 | 6 | 5.7 | 13.1 | | 171 | 0.2.0 | | **Handle a template that only reads one record column in one place, so `checkColumns`, `itemDatatype`, `proveColumnItem` and `renderLeaf` no longer each special-case `readsColumn`.** | 3 | 3 | 7 | 2 | 7 | 3, 3.2 | 12.8 | | 252 | 0.2.0 | | **Publish `fejkdata-bin` to the AUR from the Packages workflow, so Arch installs with `yay -S fejkdata-bin`.** | 1 | 1 | 1 | 3 | 4 | 1.1 | 12.8 | @@ -194,10 +194,9 @@ | 11 | 0.3.0 | | **Test that every `geo` tree holds the five table names and the `address` columns that port across countries.** | 1 | 2 | 2 | 3 | 5 | 4 | 13.0 | | 35 | 0.3.0 | | **Add `{base64url(n)}` for JWT shapes.** | 1 | 2 | 3 | 4 | 5 | 8 | 13.0 | | 40 | 0.3.0 | | **Parse `defaultTable`'s path with the library's grammar.** | 2 | 2 | 3 | 3 | 5 | 3.2 | 12.5 | -| 21 | 0.3.0 | | **List `title` in both locales, and `sv_SE`'s `birth-number`, in the README's Data list of what each locale carries.** | 1 | 1 | 1 | 4 | 6 | 12 | 12.2 | | 86 | 0.3.0 | | **Read both `en_US.phone` formats' area codes from one category, as their exchange reads `en_US.phone-exchange`.** | 1 | 2 | 2 | 2 | 5 | 3.2 | 11.5 | | 23 | 0.3.0 | | **Give every other shipped category that could reach something real a path that never does.** | 3 | 6 | 4 | 6 | 7 | 16 | 11.0 | -| 75 | 0.3.0 | | **Run every README `sh`, `go` and `text` example as a test, and compare each "Renders" line to a seeded render.** | 2 | 6 | 5 | 4 | 7 | 12.2 | 10.8 | +| 75 | 0.3.0 | | **Run every README `sh`, `go` and `text` example as a test, and compare each "Renders" line to a seeded render.** | 2 | 6 | 5 | 4 | 7 | 12 | 10.8 | | 33 | 0.3.0 | | **Group `data/misc` into folders where a group name makes a path easier to guess.** | 4 | 5 | 4 | 4 | 5 | 5 | 10.8 | | 72 | 0.3.0 | principle | **Fail the merge gate when test coverage falls below the last recorded figure.** | 2 | 3 | 3 | 2 | 5 | 3 | 10.2 | | 30 | 0.3.0 | | **Draw `email.local` from `username`, so the two share one handle list.** | 2 | 2 | 2 | 3 | 5 | 8 | 10.0 | @@ -408,6 +407,10 @@ NAICS 2022 is public domain; SEC's `company_tickers.json` is free to reuse. [Sou No open list of state patterns exists: write each state's pattern by hand and check it against that state's DMV. Wikipedia's list (CC BY-SA) and openalpr's (AGPL) may be read, never copied. [Source research](docs/research/research-sources-world.md). +### 259. Follow the quickstarts with a table of every shipped path, its example value and what makes it valid or where it comes from, generated from the data and checked by a test. + +"What can I get?" is a reader's first question, and today the answer is one sentence in the Data section, about 440 lines down. Group the rows by `sv_SE`, `en_US`, `misc` and `geo`. Generate them from `List` and one seeded render per path, and have `readme_test.go` fail when the table drifts. The Data section keeps the sources and the linked-table detail. Replaces item 21, so `title` and `birth-number` are listed with the rest. + ### 196. Name, in the error for a reference nothing loaded provides, the module the reader's manifest reads by default that would provide it, or say none does. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0", and ends the locale-address decision's conflict with goal 6.2. Carved out of item 182 on 2026-10-11, after six rounds of the comprehension panel ruled each attempt worse. Tried and ruled worse: a module list carried per category from each source's manifest (two routes, `walked` and `indexed`); the union of every manifest's list on the `Generator`, noted at four entry points; and the same noted inside `loadReached`, its list threaded through `loadInline` and `structCompile`. Each named every module read, even loaded ones, until the list held namespaces and the note named only those nothing in the tree provides, which the product-owner and goals reviewers accepted. A shipped locale's `Modules()` already carries its places, so this serves a bare `FS` beside a stand-in, a `--data-path` folder and anyone else's module; the error names the module and points to `Modules()`, as the 2026-10-11 bench asked. Bench the manifest key and the note's wording with the data author, since entries changed from import paths to namespaces after the 2026-10-11 bench. @@ -441,6 +444,10 @@ The maintainer ruled so on 2026-10-09: a name is a lexical closure, as the decis - Drop `key` from `last-name` and `sv_SE.title`, and re-pin `testdata/shipped_shape.txt`. - Leave no selection by name in README.md, CHANGELOG.md, docs/ or `--help`. +### 258. Open the README with a CLI quickstart and a Go quickstart side by side, rendering the same value. + +The opening line says "a Go library and a CLI", but its example is CLI-only, and the Library section starts after about 150 lines of CLI detail. A Go reader learns late that the library composes with code: a loop per parent, a random count, a shuffle for exact counts. README → Development → Documentation states the layout. + ### 52. 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. @@ -465,6 +472,10 @@ CLDR is under the Unicode licence; the law is facts. [Source research](docs/rese CLDR is under the Unicode licence. [Source research](docs/research/research-sources-world.md). The federal holidays are listed in 5 U.S.C. 6103, which no research file covers yet. +### 260. Add a Recipes section: seed a PostgreSQL table, fill a struct in a Go test, make a column unique, and build parent and child records in Go. + +Each recipe runs as a test. The unique column carries `{seq()}`, as in an email's local part (it replaces item 226). The parent and child recipe compiles one template per parent with `NewTemplate`, draws the child count in Go, and marshals with `encoding/json`, as the 2026-10-14 Jira seeding experiment needed. + ### 178. Plan with the systems architect which `internal/` packages the engine splits into, by area, and how each type stops being written by more than one stage, then file the moves as items. The maintainer chose on 2026-10-09 to regroup the engine into packages in 0.2.0, untangled first, over naming the root files by area. What the panels of 2026-10-09 on b9d1af6 found: @@ -612,6 +623,10 @@ Today `Fake("sv_SE.person.")` reports `no field ""`, while `{/sv_SE.person.}` re A file a Windows editor saves with a BOM prints an invisible U+FEFF first, and a JSON template with one is read as a format string. PowerShell 5.1 encodes what it pipes to a program by `$OutputEncoding`, ASCII by default. The maintainer chose 0.2.0 on 2026-10-07. +### 261. Move the README's edge cases and each category's caveats into the reference sections, below what a first reader needs. + +Examples: the bytes stdin renders, MySQL's `ANSI_QUOTES`, CSV rows spanning lines, `misc.timezone`'s standard offset against DST, and a Swedish street that may sit under a neighbouring postort. A category's caveat may instead be a note in item 259's table. Each rule still sits in one place. + ### 166. Let a key or name cell hold a bracket, a brace, a double quote or a pipe, so the table loads, its row draws at random, and only a selector cannot reach it. The maintainer ruled so on 2026-10-09. Today `checkSelectorCells` in `internal/rows` refuses the whole table. Afterwards a path naming such a key fails with an error naming the character a selector cannot spell, and the README says a row whose name holds such a character is still selected by its key.