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:
parent
9de2721422
commit
6ee7a9dcf0
4 changed files with 154 additions and 25 deletions
|
|
@ -14,6 +14,10 @@ on an opaque package. This repository holds one such registry.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
|
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
|
||||||
|
|
|
||||||
60
REFERENCE.md
60
REFERENCE.md
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
112
scripts/check-docs.ts
Normal 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.')
|
||||||
Loading…
Add table
Add a link
Reference in a new issue