Split the glossary into one file per term, built in CI #37

Merged

olli merged 1 commit from feat/glossary-split into dev

2026-10-16 13:48:03 +03:00

olli-agent commented

2026-10-16 13:46:36 +03:00

Collaborator

Closes the editing part of #34: every glossary branch edited the same sorted lists in graph.json, so branches adding terms at the same time would conflict.

What changes

Source: glossary/terms/<kind>/<id>.json, one file per term with the edges that start from it. The file name is the id and the folder the kind, so neither is written inside. A symmetric edge may sit at either end, not both. edge-types.json, tags.json and abbreviations.json sit beside terms/.
Build: scripts/build-glossary.mjs (was check-glossary.mjs) runs every old check, and also rejects unknown or path-derived fields, stray files, unknown kinds and duplicate ids. It writes public/glossary/graph.json only when all checks pass, and names the file to fix in each error.
Output: the same data, order and fields as the hand-kept file (byte-identical before minifying), now minified and no longer committed. The page, the quiz and the Go server are unchanged.
CI: lint builds and checks; the image and server jobs build it in their own workspaces, as go test and both images read it.
Local dev: a one-shot glossary service in compose.dev.yml (pinned Node 24, no network, read-only, writes only public/glossary/). web and server wait for it, so a broken glossary stops up.
Docs: README and AGENTS.md describe the layout, the editing rules and the build step.

Tested

Broken input (bad JSON, misspelt field, id in a file, wrong folder, duplicate id, symmetric edge at both ends, missing Finnish) fails and writes nothing.
html-validate; the dev stack through the new service: page serves graph.json, the quiz deals a round.
gofmt, go vet, go test in the dev server container against its PostgreSQL.

Not decided here, per #34: loading in parts (revisit at ~1,000 terms), and a Business domain folder level, which would come with the business terms (#29, #36).

Closes the editing part of #34: every glossary branch edited the same sorted lists in `graph.json`, so branches adding terms at the same time would conflict. ## What changes - **Source:** `glossary/terms/<kind>/<id>.json`, one file per term with the edges that start from it. The file name is the id and the folder the kind, so neither is written inside. A symmetric edge may sit at either end, not both. `edge-types.json`, `tags.json` and `abbreviations.json` sit beside `terms/`. - **Build:** `scripts/build-glossary.mjs` (was `check-glossary.mjs`) runs every old check, and also rejects unknown or path-derived fields, stray files, unknown kinds and duplicate ids. It writes `public/glossary/graph.json` only when all checks pass, and names the file to fix in each error. - **Output:** the same data, order and fields as the hand-kept file (byte-identical before minifying), now minified and no longer committed. The page, the quiz and the Go server are unchanged. - **CI:** lint builds and checks; the image and server jobs build it in their own workspaces, as `go test` and both images read it. - **Local dev:** a one-shot `glossary` service in `compose.dev.yml` (pinned Node 24, no network, read-only, writes only `public/glossary/`). `web` and `server` wait for it, so a broken glossary stops `up`. - **Docs:** README and AGENTS.md describe the layout, the editing rules and the build step. ## Tested - Broken input (bad JSON, misspelt field, `id` in a file, wrong folder, duplicate id, symmetric edge at both ends, missing Finnish) fails and writes nothing. - `html-validate`; the dev stack through the new service: page serves `graph.json`, the quiz deals a round. - `gofmt`, `go vet`, `go test` in the dev server container against its PostgreSQL. Not decided here, per #34: loading in parts (revisit at ~1,000 terms), and a Business domain folder level, which would come with the business terms (#29, #36).

olli-agent added 1 commit

2026-10-16 13:46:36 +03:00

Split the glossary into one file per term, built in CI

CI / lint (push) Successful in 3s

Details

CI / server (push) Successful in 23s

Details

CI / image (push) Successful in 4s

Details

CI / verify-staging (push) Successful in 11s

Details

e8bf1c3025

Every glossary branch edited the same sorted node and edge lists in
public/glossary/graph.json, so two branches adding terms at once would
conflict (#34). Each term is now its own file,
glossary/terms/<kind>/<id>.json, holding the edges that start from it.
The file name is the id and the folder the kind, so neither is written
twice; a symmetric edge may sit at either end but not both.

scripts/build-glossary.mjs, formerly check-glossary.mjs, runs every
check it ran before, rejects unknown or path-derived fields and stray
files, and writes graph.json only when all of them pass. Its output has
the same data, order and fields as the hand-kept file, minified, so the
page, the quiz and the backend are unchanged. graph.json is no longer
committed: CI builds it in each job, and compose.dev.yml gets a one-shot
service that builds it before the web server and backend start.

olli merged commit e8bf1c3025 into dev

2026-10-16 13:48:03 +03:00

olli deleted branch feat/glossary-split

2026-10-16 13:48:03 +03:00

olli-agent referenced this pull request

2026-10-16 13:49:40 +03:00

Bring the docs up to date with the glossary split #38