Check the documentation against the kit it describes

REFERENCE.md was 751 lines long and said the kit had 27 models, 15,425
triangles and eleven material slots. It had 35, 31,404 and thirteen, and the
document named none of the last six models at all. A reference nobody can trust
the numbers in is worse than no reference, because a reader has no way to tell
which parts are still true.

This is the third time the same failure has happened here. It is why
`catalog-table.ts` exists — the reference once said "four items" when the kit
had twenty-three — but regenerating the TABLE never touched the prose around
it, and the prose kept its own copies of every number.

So the counts are now checked the way the geometry is: against the models
themselves, by a script that fails. `check-docs.ts` reads the built kit and
requires each of the three documents to state the right model count and
triangle total, to list every model that exists, to name none that does not,
and to get the slot count right where it is written as a word.

Mutation-tested, as everything else here is — a wrong total, a dropped model
row and a stale slot word each fail it. And that test cost me the very fix it
was testing: `git checkout REFERENCE.md` to undo a mutation threw away the
uncommitted repairs along with it. Mutation-test after committing, not before.

Two things it caught immediately:

  - The root README never stated a triangle total at all, so the number a
    reader most wants for judging whether a kit is affordable was in two of
    the three documents and absent from the front door.
  - My own first version of the slot check. It looked for any word before
    "slots", matched the ordinary phrase "material slots" several paragraphs
    earlier, found that "material" is not a number, and silently checked
    nothing — reporting nothing rather than failing. A check that passes by
    not running is worse than no check, because it reads as evidence.

`bun run check:docs`, and it is in the README's verify list with the others.
This commit is contained in:
CRTkafa 2026-08-27 01:37:18 +07:00
parent 9de2721422
commit 6ee7a9dcf0
4 changed files with 154 additions and 25 deletions

View file

@ -14,6 +14,10 @@ on an opaque package. This repository holds one such registry.
![The whole kit](media/kit.png) ![The whole kit](media/kit.png)
35 models and one shared library, **31,404 triangles** for the whole kit — less
than a single medium-detail character. Every one is procedural source you own
and edit, not an asset you load.
## Run the viewer ## Run the viewer
Requires [Bun](https://bun.sh) and a browser with WebGPU (the `@scifi-kit` model Requires [Bun](https://bun.sh) and a browser with WebGPU (the `@scifi-kit` model
@ -57,6 +61,7 @@ textures at all.
bun run typecheck bun run typecheck
bun run verify # geometry, protocol, metadata, actions bun run verify # geometry, protocol, metadata, actions
bun run verify:glb # export every model, read it back, compare bun run verify:glb # export every model, read it back, compare
bun run check:docs # the three READMEs against the kit they describe
bun run render # renders/_sheet.png — actually look at the models bun run render # renders/_sheet.png — actually look at the models
``` ```
@ -159,6 +164,7 @@ scripts/
support.ts voxel connectivity — nothing may float support.ts voxel connectivity — nothing may float
audit.ts runs the support check across every configuration audit.ts runs the support check across every configuration
render.ts offline software rasteriser → PNG contact sheet render.ts offline software rasteriser → PNG contact sheet
check-docs.ts documented counts against the models themselves
reference-shots.ts one photographic reference per model, for comparison reference-shots.ts one photographic reference per model, for comparison
probe-tree.ts measures the oak against its reference photographs probe-tree.ts measures the oak against its reference photographs
catalog-table.ts regenerates the model table in the registry README catalog-table.ts regenerates the model table in the registry README

View file

@ -79,7 +79,7 @@ src/viewer.ts · src/viewer.css the model viewer (WebGPU, sky, shadow)
src/catalog.ts the viewer's catalog — DERIVED from meta.ts src/catalog.ts the viewer's catalog — DERIVED from meta.ts
src/glb.ts GLB export (shared by viewer and CLI) src/glb.ts GLB export (shared by viewer and CLI)
src/models/scifi-kit/pressure-gauge/ the installed sci-fi model src/models/scifi-kit/pressure-gauge/ the installed sci-fi model
src/models/medieval-kit/… your OWN installed models (27 models) src/models/medieval-kit/… your OWN installed models (35 models)
my-registry/ my-registry/
meta.ts the SINGLE source of catalog metadata meta.ts the SINGLE source of catalog metadata
build.ts the registry.json generator build.ts the registry.json generator
@ -338,41 +338,49 @@ the same, the physical package changes.
## 5. Lowpoly medieval — yes, no problem ## 5. Lowpoly medieval — yes, no problem
This is not an assumption: `@medieval-kit` works, is validated and currently This is not an assumption: `@medieval-kit` works, is validated and currently
contains **27 models + 1 lib**. The table is generated from the models contains **35 models + 1 lib**. The table is generated from the models
themselves with `bun scripts/catalog-table.ts` — a hand-written list goes stale themselves with `bun scripts/catalog-table.ts` — a hand-written list goes stale
on the first model you add, and in fact it had gone stale once. on the first model you add, and in fact it had gone stale once.
| Model | Category | Triangles | Parts | Size (m) | Material slots | Animated | | Model | Category | Triangles | Parts | Size (m) | Material slots | Animated |
| --- | --- | ---: | ---: | --- | --- | :-: | | --- | --- | ---: | ---: | --- | --- | :-: |
| `wooden-chest` | Furniture | 552 | 4 | 0.86×0.51×0.48 | oak, iron | ✔ | | `wooden-chest` | Furniture | 552 | 4 | 0.86×0.51×0.48 | oak, iron | ✔ |
| `wooden-barrel` | Props | 806 | 3 | 0.82×1.05×0.81 | oak, iron | | | `wooden-barrel` | Props | 1690 | 3 | 0.83×1.05×0.83 | oak, iron | |
| `wooden-crate` | Props | 1320 | 3 | 0.69×0.52×0.55 | oak, iron | | | `wooden-crate` | Props | 1320 | 3 | 0.69×0.52×0.55 | oak, iron | |
| `wooden-bucket` | Props | 439 | 4 | 0.31×0.46×0.30 | oak, iron | | | `wooden-bucket` | Props | 439 | 4 | 0.31×0.46×0.30 | oak, iron | |
| `trestle-table` | Furniture | 660 | 3 | 1.91×0.74×0.79 | oak | | | `trestle-table` | Furniture | 660 | 3 | 1.91×0.74×0.78 | oak | |
| `wooden-bench` | Furniture | 168 | 3 | 1.62×0.48×0.30 | oak | | | `wooden-bench` | Furniture | 216 | 3 | 1.62×0.45×0.30 | oak | |
| `wooden-stool` | Furniture | 180 | 2 | 0.38×0.43×0.36 | oak | | | `wooden-stool` | Furniture | 180 | 2 | 0.38×0.43×0.36 | oak | |
| `pitch-torch` | Lighting | 239 | 3 | 0.10×0.77×0.11 | oak, char, ember | ✔ | | `pitch-torch` | Lighting | 239 | 3 | 0.13×0.70×0.13 | oak, char, ember | ✔ |
| `iron-lantern` | Lighting | 440 | 4 | 0.15×0.29×0.17 | iron, glass, char, ember | ✔ | | `iron-lantern` | Lighting | 480 | 4 | 0.15×0.30×0.17 | iron, glass, char, ember | ✔ |
| `iron-anvil` | Smithy | 220 | 5 | 0.48×0.36×0.21 | iron, steel | | | `iron-anvil` | Smithy | 256 | 6 | 0.54×0.75×0.41 | iron, steel, oak | |
| `cart-wheel` | Structure | 1056 | 4 | 0.99×1.04×0.19 | oak, iron | | | `cart-wheel` | Structure | 1136 | 4 | 1.04×1.06×0.19 | oak, iron | |
| `log-pile` | Props | 504 | 2 | 1.25×0.43×0.18 | oak | | | `log-pile` | Props | 924 | 2 | 0.99×0.58×0.70 | oak | |
| `hay-bale` | Props | 674 | 3 | 1.09×0.46×0.46 | straw, cloth | | | `hay-bale` | Props | 910 | 3 | 1.04×0.42×0.43 | straw, cloth | |
| `linen-sack` | Props | 300 | 3 | 0.32×0.53×0.32 | cloth | | | `linen-sack` | Props | 342 | 3 | 0.34×0.53×0.33 | cloth | |
| `oak-tankard` | Props | 366 | 4 | 0.09×0.17×0.10 | oak, iron | | | `oak-tankard` | Props | 390 | 4 | 0.11×0.16×0.14 | oak, iron | |
| `straw-broom` | Tools | 880 | 3 | 0.20×1.22×0.19 | oak, straw, cloth | | | `straw-broom` | Tools | 1048 | 3 | 0.30×1.22×0.30 | oak, straw, cloth | |
| `bronze-bell` | Props | 696 | 3 | 0.48×0.53×0.36 | brass, iron, oak | ✔ | | `bronze-bell` | Props | 1048 | 4 | 0.51×0.68×0.36 | brass, iron, oak | ✔ |
| `tavern-sign` | Props | 516 | 2 | 0.54×0.75×0.63 | oak, iron | ✔ | | `tavern-sign` | Props | 876 | 3 | 0.38×2.29×0.93 | oak, iron | ✔ |
| `wicker-basket` | Props | 1906 | 3 | 0.35×0.24×0.35 | straw, produce | | | `wicker-basket` | Props | 2326 | 3 | 0.34×0.16×0.35 | oak, produce | |
| `leather-book` | Props | 248 | 3 | 0.20×0.07×0.28 | leather, cloth, brass | | | `leather-book` | Props | 440 | 3 | 0.20×0.08×0.27 | leather, cloth, brass | |
| `glass-phial` | Props | 321 | 3 | 0.06×0.14×0.06 | glass, ember, oak, char | | | `glass-phial` | Props | 339 | 3 | 0.06×0.14×0.06 | glass, ember, oak, char | |
| `coin-pouch` | Props | 546 | 3 | 0.18×0.11×0.19 | leather, cloth, brass | | | `coin-pouch` | Props | 602 | 3 | 0.18×0.11×0.16 | leather, cloth, brass | |
| `wooden-ladder` | Structure | 440 | 2 | 0.49×2.20×0.06 | oak | | | `wooden-ladder` | Structure | 440 | 2 | 0.49×2.20×0.06 | oak | |
| `wooden-fence` | Structure | 860 | 2 | 5.18×1.31×0.31 | oak | | | `wooden-fence` | Structure | 860 | 2 | 5.18×1.31×0.31 | oak | |
| `wooden-hoe` | Tools | 282 | 3 | 0.20×1.23×0.30 | oak, iron, steel | | | `wooden-hoe` | Tools | 394 | 3 | 0.23×1.23×0.33 | oak, iron, steel | |
| `wooden-shovel` | Tools | 468 | 3 | 0.27×1.20×0.08 | oak, iron, steel | | | `wooden-shovel` | Tools | 496 | 3 | 0.27×1.20×0.08 | oak, iron | |
| `wooden-pitchfork` | Tools | 338 | 3 | 0.25×1.56×0.11 | oak, iron, steel | | | `wooden-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | |
| `iron-cauldron` | Lighting | 1134 | 3 | 1.09×1.37×1.10 | stone, iron, char, ember | |
| `hand-cart` | Structure | 2044 | 4 | 0.88×1.03×2.60 | oak, iron | |
| `vegetables` | Props | 1718 | 2 | 0.60×0.12×0.59 | produce | |
| `round-shield` | Arms | 729 | 3 | 0.73×0.73×0.17 | oak, leather, iron | |
| `forge-hearth` | Smithy | 1426 | 4 | 2.06×1.78×0.87 | stone, char, ember, oak, leather, iron | |
| `stone-well` | Structure | 1376 | 4 | 1.88×2.00×1.28 | stone, oak, iron, cloth | |
| `post-mill` | Structure | 1672 | 4 | 6.60×7.23×6.98 | oak, iron | |
| `oak-tree` | Nature | 2310 | 3 | 8.57×6.96×9.05 | oak, leaf | |
**15,425 triangles** in total. The whole kit in one scene has a budget smaller **31,404 triangles** in total. The whole kit in one scene has a budget smaller
than a single medium-complexity character model. than a single medium-complexity character model.
### 5.1 One source: `my-registry/meta.ts` ### 5.1 One source: `my-registry/meta.ts`
@ -396,7 +404,7 @@ declaration means a hidden material the consumer cannot reach with
this check was added it caught a real drift in four models (a `steel` slot had this check was added it caught a real drift in four models (a `steel` slot had
been added but not declared). been added but not declared).
### 5.2 The material vocabulary — eleven slots ### 5.2 The material vocabulary — thirteen slots
| Slot | What | Why separate | | Slot | What | Why separate |
| --- | --- | --- | | --- | --- | --- |
@ -411,6 +419,8 @@ been added but not declared).
| `produce` | fruit and vegetable skin | if I had given it the same roughness as straw an apple would look like dry hay | | `produce` | fruit and vegetable skin | if I had given it the same roughness as straw an apple would look like dry hay |
| `ember` | flame | `MeshBasicMaterial` — it does not receive light, it emits | | `ember` | flame | `MeshBasicMaterial` — it does not receive light, it emits |
| `char` | charcoal, pitch | — | | `char` | charcoal, pitch | — |
| `stone` | dressed and rubble masonry | its color is close to weathered oak; what tells them apart at a glance is that stone scatters light completely flat, and roughness is not something vertex color can carry |
| `leaf` | living foliage | the most matte thing here after stone: any sheen at all and a crown reads as plastic shrubbery, which is the usual failure of a lowpoly tree and is a material setting rather than a modelling one |
`ember` also works as a rule in two places: bodies in this slot are skipped `ember` also works as a rule in two places: bodies in this slot are skipped
entirely while occlusion and mottle are baked. The reason is simple — on an entirely while occlusion and mottle are baked. The reason is simple — on an

View file

@ -8,6 +8,7 @@
"preview": "vite preview", "preview": "vite preview",
"typecheck": "tsc --noEmit", "typecheck": "tsc --noEmit",
"verify": "bun scripts/verify-model.ts", "verify": "bun scripts/verify-model.ts",
"check:docs": "bun scripts/check-docs.ts",
"registry:build": "bun my-registry/build.ts", "registry:build": "bun my-registry/build.ts",
"registry:validate": "vibe3d registry validate my-registry/dist/registry.json", "registry:validate": "vibe3d registry validate my-registry/dist/registry.json",
"viewer:build": "vite build --config vite.viewer.config.ts && bun scripts/build-artifact.ts", "viewer:build": "vite build --config vite.viewer.config.ts && bun scripts/build-artifact.ts",

112
scripts/check-docs.ts Normal file
View file

@ -0,0 +1,112 @@
/**
* Checks that the documentation still describes the kit that actually exists.
*
* This is here because the same thing went wrong three times. `REFERENCE.md`
* said "four items" when there were twenty-three, which is what `catalog-table`
* was written to fix — but that only regenerates the TABLE, and the prose
* around it kept its own copies of the numbers. On the day the oak was added
* the reference still claimed 27 models, 15,425 triangles and eleven material
* slots, all three of them wrong, in a document 751 lines long whose whole
* value is that a reader can trust it.
*
* A document with confident wrong numbers in it is worse than no document, so
* the numbers are checked the way the geometry is: against the models
* themselves, in CI, where being wrong fails rather than waits to be noticed.
*
* bun scripts/check-docs.ts
*/
import { readFileSync } from 'node:fs'
import { Mesh } from 'three/webgpu'
import { MODEL_META } from '../my-registry/meta.ts'
import { CATALOG } from '@/catalog.ts'
const failures: string[] = []
function expect(label: string, ok: boolean, detail = ''): void {
if (ok) {
console.log(` PASS ${label}`)
} else {
console.log(` FAIL ${label}${detail ? ` — ${detail}` : ''}`)
failures.push(label)
}
}
// --- what the kit actually is ------------------------------------------------
const ids = Object.keys(CATALOG).filter((id) => MODEL_META[id] !== undefined && id !== 'pressure-gauge')
const slots = new Set<string>()
let triangles = 0
for (const id of ids) {
const built = CATALOG[id]!.build()
built.root.traverse((object) => {
if (!(object instanceof Mesh)) return
const index = object.geometry.getIndex()
triangles += (index ? index.count : object.geometry.getAttribute('position').count) / 3
})
built.dispose()
for (const slot of MODEL_META[id]!.materialSlots) slots.add(slot)
}
const models = ids.length
console.log(`kit: ${models} models · ${triangles} triangles · ${slots.size} material slots\n`)
/** Digits, however the document happens to group them: 31404, 31,404, 31 404. */
function hasNumber(text: string, value: number): boolean {
const digits = String(value)
const spaced = digits.replace(/\B(?=(\d{3})+(?!\d))/g, '[ , ]?')
return new RegExp(spaced).test(text)
}
const WORDS = [
'zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine',
'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen',
'seventeen', 'eighteen', 'nineteen', 'twenty',
]
for (const file of ['README.md', 'REFERENCE.md', 'my-registry/README.md']) {
const text = readFileSync(file, 'utf8')
console.log(file)
expect(`${file}: model count`, hasNumber(text, models), `expected ${models}`)
expect(`${file}: triangle total`, hasNumber(text, triangles), `expected ${triangles}`)
// Every model has to appear by id, or the document is describing a smaller
// kit than the one it ships with. The registry README and the reference each
// carry a generated table; the root README does not, so it is exempt.
if (file !== 'README.md') {
const missing = ids.filter((id) => !text.includes(`\`${id}\``))
expect(`${file}: every model listed`, missing.length === 0, missing.join(', '))
}
// A slot count written as a word ("thirteen slots") is the one number in
// these documents that cannot be grepped as a digit, and it was wrong.
//
// Looked up as a NUMBER WORD rather than as any word. The first version took
// whatever word preceded "slots", matched the ordinary phrase "material
// slots" several paragraphs earlier, found that "material" is not a number,
// and quietly checked nothing at all — a check that passes by not running is
// worse than no check, because it reads as evidence.
const written = text.match(new RegExp(`\\b(${WORDS.join('|')}) (?:material )?slots\\b`, 'i'))
expect(
`${file}: slot count in words`,
written === null || WORDS.indexOf(written[1]!.toLowerCase()) === slots.size,
written ? `says "${written[1]}", kit has ${slots.size}` : '',
)
// Any model named in prose but not in the kit at all: a rename that got
// half-applied leaves exactly this trace.
const named = [...text.matchAll(/`([a-z]+-[a-z-]+)`/g)].map((m) => m[1]!)
const ghosts = [...new Set(named)].filter(
(name) => /^(wooden|iron|oak|straw|hay|linen|log|pitch|leather|glass|coin|cart|bronze|tavern|trestle|wicker|round|forge|stone|post|hand)-/.test(name)
&& !ids.includes(name),
)
expect(`${file}: no models that do not exist`, ghosts.length === 0, ghosts.join(', '))
console.log('')
}
if (failures.length > 0) {
console.log(`${failures.length} documentation check(s) FAILED.`)
process.exit(1)
}
console.log('Documentation matches the kit.')