DX: curate & categorise the examples/ crowd (42 flat files, chronorift dir+file dup) #28

New issue

Closed

opened 2026-08-30 12:50:17 +02:00 by orkun · 1 comment

orkun commented

2026-08-30 12:50:17 +02:00

Owner

Problem

examples/ is a flat crowd of 42 entries with no categorisation, and it reads
as noise rather than a curated showcase:

8 net_*.ludic, 6 world_*.ludic, 6 *events*.ludic, plus a long
tail of one-off micro-demos (toggle, promote, cancel, recurse,
reason, scoped, qdecl, strings, …).
chronorift exists as both a directory and a chronorift.ludic file, and
there is an examples/lib/ — the layout is ambiguous about what's a real,
runnable, showcase example vs. a scratch test.
Only 6 examples are actually referenced by bin/x test; the rest are
unverified and can silently rot.

Proposal

Curate and categorise:

Split into intent-revealing subfolders, e.g. examples/games/ (chronorift,
snake, menu), examples/networking/, examples/ecs-world/,
examples/events/, examples/language-tour/ (the tiny feature demos).
Collapse the many near-duplicate micro-demos into a small number of documented
"feature tour" files, or move the pure regression snippets under selfhost/tests/
where they belong.
Resolve the chronorift dir-vs-file duplication.
Each kept example gets a one-line purpose comment, and ideally is exercised by
bin/x test so examples can't rot.
Add a short examples/README.md indexing what's there and how to run it.

Acceptance criteria

Examples grouped into meaningful subdirectories.
Redundant/scratch demos removed or relocated to tests.
chronorift duplication resolved.
examples/README.md explains the set; kept examples are covered by tests.

Part of the repository-cleanup / DX pass.

## Problem `examples/` is a flat crowd of **42 entries** with no categorisation, and it reads as noise rather than a curated showcase: - **8** `net_*.ludic`, **6** `world_*.ludic`, **6** `*events*.ludic`, plus a long tail of one-off micro-demos (`toggle`, `promote`, `cancel`, `recurse`, `reason`, `scoped`, `qdecl`, `strings`, …). - **`chronorift` exists as both a directory *and* a `chronorift.ludic` file**, and there is an `examples/lib/` — the layout is ambiguous about what's a real, runnable, showcase example vs. a scratch test. - Only **6** examples are actually referenced by `bin/x test`; the rest are unverified and can silently rot. ## Proposal Curate and categorise: - Split into intent-revealing subfolders, e.g. `examples/games/` (chronorift, snake, menu), `examples/networking/`, `examples/ecs-world/`, `examples/events/`, `examples/language-tour/` (the tiny feature demos). - Collapse the many near-duplicate micro-demos into a small number of documented "feature tour" files, or move the pure regression snippets under `selfhost/tests/` where they belong. - Resolve the `chronorift` dir-vs-file duplication. - Each kept example gets a one-line purpose comment, and ideally is exercised by `bin/x test` so examples can't rot. - Add a short `examples/README.md` indexing what's there and how to run it. ## Acceptance criteria - [ ] Examples grouped into meaningful subdirectories. - [ ] Redundant/scratch demos removed or relocated to tests. - [ ] `chronorift` duplication resolved. - [ ] `examples/README.md` explains the set; kept examples are covered by tests. Part of the repository-cleanup / DX pass.

orkun added the

priority:medium

area:repo

cleanup

labels 2026-08-30 12:50:17 +02:00

orkun referenced this issue from a commit

2026-08-30 17:57:48 +02:00

chore(repo): DX cleanup — categorise examples, text-diffable golden, build/ output (#27 #28 #30)

orkun commented

2026-08-30 17:58:41 +02:00

Author

Owner

Done in fb728bb (verified: bin/x test 49/0, bin/x selfhost-test 29/0, bin/x test-tools 29/0).

Acceptance criteria

Examples grouped into meaningful subdirectories — the 42 flat entries are now games/, rendering/, ecs/, events/, networking/, lang/, and library/ (was lib/).
Redundant/scratch demos relocated / covered — every example is now exercised by the suite. The showcase demos that have no self-asserting entry (ecs/hello, events/events, networking/net_rt) get a new compile-only rot guard in bin/x test ("== showcase examples still compile =="), so nothing here can silently rot.
chronorift duplication resolved — it was never a true dup: chronorift.ludic is the entry that imports the modules beside it. They now live together under examples/games/chronorift.ludic + examples/games/chronorift/, which makes the entry-vs-modules relationship unambiguous.
examples/README.md — added; indexes every example by category with copy-paste run commands.

All path references were updated repo-wide in the same commit (the Ludic test runner, the LSP/grammar drivers, docs/site, and the root design docs), and the test helpers now take a category-qualified path (games/snake, lang/annotations, …).

Done in fb728bb (verified: `bin/x test` 49/0, `bin/x selfhost-test` 29/0, `bin/x test-tools` 29/0). **Acceptance criteria** - [x] **Examples grouped into meaningful subdirectories** — the 42 flat entries are now `games/`, `rendering/`, `ecs/`, `events/`, `networking/`, `lang/`, and `library/` (was `lib/`). - [x] **Redundant/scratch demos relocated / covered** — every example is now exercised by the suite. The showcase demos that have no self-asserting `entry` (`ecs/hello`, `events/events`, `networking/net_rt`) get a new compile-only rot guard in `bin/x test` ("== showcase examples still compile =="), so nothing here can silently rot. - [x] **`chronorift` duplication resolved** — it was never a true dup: `chronorift.ludic` is the entry that `import`s the modules beside it. They now live together under `examples/games/chronorift.ludic` + `examples/games/chronorift/`, which makes the entry-vs-modules relationship unambiguous. - [x] **`examples/README.md`** — added; indexes every example by category with copy-paste run commands. All path references were updated repo-wide in the same commit (the Ludic test runner, the LSP/grammar drivers, `docs/site`, and the root design docs), and the test helpers now take a category-qualified path (`games/snake`, `lang/annotations`, …).

orkun closed this issue

2026-08-30 17:58:41 +02:00

orkun referenced this issue

2026-08-30 18:10:48 +02:00

Docs: rewrite the outdated README (native+web backends, stdlib, links) #35