Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33

Open
lilleman wants to merge 966 commits from worktree-todo-relative-dates-exact-counts into main
4 changed files with 20 additions and 24 deletions
Showing only changes of commit 00f31e6f59 - Show all commits
+2 -7
View File
@@ -125,15 +125,10 @@ func literal(c Column, quote func(string) string, nullText string) string {
func (f *Generator) FakeRecord(path string) (*Record, error) {
f.mu.Lock()
defer f.mu.Unlock()
path, err := grammar.CallerPath(path)
path, segments, err := f.callerPath(path)
if err != nil {
return nil, fmt.Errorf("fejkdata: %w", err)
return nil, err
}
segments, err := grammar.SplitPath(path)
if err != nil {
return nil, fmt.Errorf("fejkdata: %w", err)
}
f.loadShippedAt(segments)
_, n, tail, err := resolveCategory(f.root.children, segments)
if err != nil {
return nil, f.noDataNote(fmt.Errorf("fejkdata: %s: %w", path, err))
+2 -7
View File
@@ -16,15 +16,10 @@ import (
func (f *Generator) Fake(path string) (string, error) {
f.mu.Lock()
defer f.mu.Unlock()
path, err := grammar.CallerPath(path)
path, segments, err := f.callerPath(path)
if err != nil {
return "", fmt.Errorf("fejkdata: %w", err)
return "", err
}
segments, err := grammar.SplitPath(path)
if err != nil {
return "", fmt.Errorf("fejkdata: %w", err)
}
f.loadShippedAt(segments)
n, pins, err := drawCallerPath(f.drawState, &f.root, segments)
if err != nil {
return "", f.noDataNote(fmt.Errorf("fejkdata: %s: %w", path, err))
+14 -3
View File
@@ -2,9 +2,11 @@ package fejkdata
import (
"embed"
"fmt"
"strings"
"github.com/larvit/fejkdata/internal/datafiles"
"github.com/larvit/fejkdata/internal/grammar"
"github.com/larvit/fejkdata/internal/invariant"
)
@@ -56,12 +58,21 @@ func unloadedAt(root *folder, segs []string) (unloadedCategory, bool) {
return unloadedCategory{dir: segs[:i:i], in: g, name: segs[i]}, true
}
// loadShippedAt loads the shipped category a caller's path names or descends into. An entry
// point calls it before walking root: a walk is a query and loads nothing.
func (f *Generator) loadShippedAt(segs []string) {
// callerPath is a caller's path without its leading /, and split, with the shipped category
// it names or descends into loaded: a walk is a query and loads nothing.
func (f *Generator) callerPath(path string) (string, []string, error) {
path, err := grammar.CallerPath(path)
if err != nil {
return "", nil, fmt.Errorf("fejkdata: %w", err)
}
segs, err := grammar.SplitPath(path)
if err != nil {
return "", nil, fmt.Errorf("fejkdata: %w", err)
}
if u, unloaded := unloadedAt(&f.root, segs); unloaded {
loadShipped(&f.root, []unloadedCategory{u})
}
return path, segs, nil
}
// unloadedReads is every unloaded shipped category the templates of nodes reference, each
+2 -7
View File
@@ -73,7 +73,7 @@
| 129 | 0.1.0 | decision | **Take a template wherever the library renders, so `fake:"{/sv_SE.person.first}"` and `Fake("{/sv_SE.person}")` render, and text with no `{…}` prints as written, as the CLI already does.** | 5 | 8 | 8 | 10 | 5.9, 7 | 25.0 |
| 163 | 0.1.0 | | **Lift the CLI's `--repeat` cap, since the CLI streams each render, and give the builtins' count and decimal caps a technical reason in the README.** | 2 | 2 | 7 | 7 | 2, 5.7 | 24.8 |
| 57 | 0.1.0 | | **Rewrite `CHANGELOG.md`'s `[Unreleased]` as what v0.1.0 holds.** | 1 | 2 | 6 | 6 | 1.1 | 22.5 |
| 153 | 0.1.0 | decision | **Run the nine-seat comprehension panel and the scoring run again once items 148 and 151 have merged, and file what the panel names.** | 1 | 3 | 3 | 9 | 3 | 20.4 |
| 153 | 0.1.0 | decision | **Run the nine-seat comprehension panel and the scoring run again, and file what the panel names.** | 1 | 3 | 3 | 9 | 3 | 20.4 |
| 164 | 0.1.0 | | **Let a table's format or a cell bind a name, which lives in that format or cell and keeps one pick through the draw.** | 2 | 2 | 5 | 7 | 4.1, 5.3 | 19.4 |
| 157 | 0.1.0 | | **Show in the README's CLI section how PowerShell and cmd.exe pipe a template, one line per shell family.** | 1 | 1 | 5 | 6 | 7.2 | 17.1 |
| 167 | 0.1.0 | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 1 | 3 | 2 | 8 | 3, 3.4 | 16.6 |
@@ -82,7 +82,6 @@
| 127 | 0.1.0 | | **Give a Swedish street only postal codes whose delivery digit means street or rural delivery, dropping codes whose delivery digit is 9, or record why they stay.** | 3 | 3 | 4 | 6 | 4 | 14.4 |
| 110 | 0.1.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 | 3 | 6 | 6 | 13.8 |
| 166 | 0.1.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 | 3 | 6 | 5.7 | 13.1 |
| 151 | 0.1.0 | | **Load a caller's path and walk it in one `Generator` method, so no entry point walks the root before the shipped category the path names has loaded.** | 2 | 2 | 1 | 6 | 3.2 | 10.3 |
| 58 | 0.2.0 | | **Ship prebuilt binaries, a container image, and packages for Homebrew, Scoop and the biggest Linux package managers, so the CLI needs no Go.** | 3 | 7 | 8 | 9 | 1.1, 7 | 29.2 |
| 113 | 0.2.0 | defect | **Draw `{iban(CC)}` with its country's national check digits, and SE's with a real bank's id, so a validator checking more than mod 97 accepts it.** | 3 | 5 | 7 | 9 | 4 | 25.0 |
| 154 | 0.2.0 | | **Add `en_US.routing`, an ABA routing number over the Fed's prefix ranges with its check digit drawn by `{aba()}`.** | 2 | 2 | 6 | 7 | 2.2, 15 | 22.8 |
@@ -265,7 +264,7 @@ The README's Audience names a bulk fixture author writing millions of rows, and
Nothing has shipped, so "no longer paths", "where it used to fail" and "where it used to be an empty string" describe versions no reader can have installed.
### 153. Run the nine-seat comprehension panel and the scoring run again once items 148 and 151 have merged, and file what the panel names.
### 153. Run the nine-seat comprehension panel and the scoring run again, and file what the panel names.
The decision "comprehension floor: every dimension and the overall at 7.0 or above" holds the scores this run is measured against.
@@ -301,10 +300,6 @@ Today `Fake("sv_SE.person.")` reports `no field ""`, while `{/sv_SE.person.}` re
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.
### 151. Load a caller's path and walk it in one `Generator` method, so no entry point walks the root before the shipped category the path names has loaded.
`Fake` and `FakeRecord` each call `loadShippedAt` before they walk, and its doc asks the next entry point to do the same. The greenfield architect of the 2026-10-07 panel on ad59967 named it the one corner a new senior would break without warning. A test passing `WithDataPath` would not catch it, because then `New` loads every category.
### 58. Ship prebuilt binaries, a container image, and packages for Homebrew, Scoop and the biggest Linux package managers, so the CLI needs no Go.
GoReleaser attaches the binaries to the release the tag workflow publishes, and builds deb and rpm packages, an Alpine APK and an AUR package beside Homebrew and Scoop. A checkout build prints `devel` for `--version`; the binaries carry the stamped tag. v0.1.0 ships first, so it can be tested before it is packaged.