scripts/generate-content-types.ts writes the gitignored src/types/content-ids.ts (id unions + project category values) from the four structure documents; wired as generate:ids / predev / prebuild / prepare. src/types/index.ts re-exports them type-only and keeps only the code-owned unions. Edit mode now writes JSON only: the v4 union leg is deleted (saveIdUnions, diffIdsWithUnions, applyUnionChanges, readUnionBlock, the EditBar union card, edit.union.* labels). Validator rule 7 requires a label for every category a project uses, in both ui/projects.json documents. Tests: smoke-draft.ts 11/11 (rename re-sluging + category-label rule replace checks 9-12); new scripts/smoke-generated-ids.ts 7/7. Verified: pnpm build (chunk names unchanged, no runtime reference to the generated module), lint with no new warnings, validate:content, resume HTML byte-identical before/after with identical documents. Docs: spec-v5-generated-content-ids.md added; spec-v4-live-edit.md §3.1 marked superseded + §12 row 23; AGENTS.md and README.md updated.
25 KiB
Specification — v5: Generated Content Ids
Parent:
specs/v4/spec-v4-live-edit.md§3.1 (supersedes its id-union legs),spec-v4-data-organization.md§3,spec-v4-inline-editing.mdE3. Status: rev.3 — approved 2026-10-24. OQ1 = generated file stays gitignored (D2 stands); OQ2 = dedicatedscripts/smoke-generated-ids.ts, same shape assmoke-draft.ts; OQ3 = out of scope for v5. Implementation follows §10.
Overview
Content ids live in two places today: the record in src/data/*.json, and the id type in src/types/index.ts. v4 answered that by teaching the editor to patch the TypeScript file. This spec removes the second declaration instead: the id unions are generated from the JSON at build time, so a content change is a content change, and every guarantee tsc provides today stays in place.
The type contract does not change. Only where the union comes from changes.
1. Problem — measured
| # | Evidence |
|---|---|
| 1 | A record deleted in edit mode broke pnpm build: TS2741: Property '"logistics-technology"' is missing in type … but required in type 'Record<SkillGroupId, SkillGroupText>' at src/i18n/index.ts:69. The editor had done its own part correctly — src/data/skills.json and both text documents no longer carried the id; src/types/index.ts still did. |
| 2 | The repair is machinery in the browser save path: UNION_SPECS, readUnionBlock (line-ending aware, never-aware, order-preserving), renderUnion, applyUnionChanges, diffIdsWithUnions, saveIdUnions in src/i18n/draft.ts, plus TYPES_FILE / fetchTextFile / putTextFile, typesRef and the fetch in EditModeShell.tsx:51,139-144,286-296, an EditBar note (EditBar.tsx:27,59,251-253) and two UI strings in ui/edit.json. ~150 lines whose only job is keeping a TS file in step with JSON. |
| 3 | That machinery works — commit 1a1fc14 content: update id union members (-facility-management, -local-llm-experiments) is a real production run — but every content add/delete therefore writes a code file into the content history, and the patch has to reason about line endings, member order, never, and blob-sha conflicts. |
| 4 | The same coupling is already stale where nothing patches it: ProjectCategory (src/types/index.ts:7-13) lists six categories; src/data/projects.json uses two (logistics, computer-vision). It is harmless today only because no Record<ProjectCategory, _> exists — and s.projects.categories[project.category] (Projects.tsx:66) is an implicit-any lookup, because tsconfig.app.json sets no strict / noImplicitAny. |
Root cause: one fact declared twice. Everything in row 2–4 is the cost of keeping the two copies in step.
2. What the unions guarantee today — and must keep guaranteeing
| Guarantee | Where it comes from | Survives this change? |
|---|---|---|
Every structure id has Vietnamese text: ContentVi.skills: Record<SkillGroupId, SkillGroupText> (dict-types.ts:121) — an object literal missing a key is an error regardless of strict |
closed id union | Yes. Same Record<…>, union generated instead of hand-written |
A structure value outside its union is rejected: projectsJson as ProjectStructure[] (src/data/projects.ts:10) is non-comparable when a category/id literal is wrong (TS2352) |
closed id union + as assertion |
Partly — see D4. The assertion cannot fail any more, because the union is defined by the data. The guard that matters (a category with no label) moves to the validator |
| A malformed document fails the build, CI, and the browser load — never a silent half-render | tsc + src/i18n/validate.ts at load + scripts/validate-content.ts in CI |
Yes, unchanged |
| Nothing at runtime | the unions are erased at emit; edit mode casts draft data (draft.ts:465-472, 545-553) |
Yes — the generated file is type-only, so no runtime import, no bundle change |
3. Decisions
D1 — ids and category values are data, generated from the structure documents
ProjectId, ExperienceId, SkillGroupId, PhilosophyId, ProjectCategory are derived from src/data/*.json.
Rejected:
- Keep hand-edited unions. Two sources of truth; the owner must edit code to change content.
- Keep the v4 browser patch. It works, but it is permanent machinery in the save path plus a code commit for every content change — the thing this spec exists to remove.
- Make ids
string. Deletes the machinery, and also deletes the exhaustiveness guarantee in row 1 of §2, which is the load-bearing part of §3.1. Enforcement would fall to the validator alone.
D2 — the generator runs at build/dev time; its output is gitignored
Rejected: committing the generated file (a content edit would still dirty a code file in the working tree and in review — D1's point); generating only inside CI (the IDE and local tsc need the file present).
D3 — renderer kinds stay code-owned
ProjectSectionStructure.type: 'text' | 'diagram' | 'metrics' | 'code', ExperienceStructure.variant, logo, PageId, ManifestId, ContentEntityId, Language, Palette, SocialId stay hand-written in src/types/index.ts. They enumerate what the code can render, not what the owner writes — the settings popover's section-type picker offers exactly these values. This is D5 of spec-v4-live-edit.md (content editable, design is code), applied to types.
D4 — ProjectCategory is generated, and its guard moves to the validator
New rule 7 in src/i18n/validate.ts: every category value used in projects.json must have a non-empty label at ui.<lang>.projects.categories[<value>] in both languages; the issue names the file and the key. Rationale: D1 removes the as-assertion typo guard, and the failure that actually matters is not "an unknown category" but "a category that renders an empty badge" (Projects.tsx:66). Rule 7 checks exactly that.
D5 — the type contract itself does not change
dict-types.ts, Record<…> text coverage, the loaders, the page manifests, validator rules 1–6, the 12-document draft registry, the save pipeline: unchanged.
D6 — edit mode never writes a TypeScript file again
saveIdUnions and everything it needs is deleted, not deprecated. src/types/index.ts is not in the writable-document set, and the EditBar loses its union note.
4. Target architecture
graph LR
A[src/data/*.json] --> B[scripts/generate-content-types.ts]
B --> C[src/types/content-ids.ts]
C --> D[src/types/index.ts type-only re-export]
D --> E[tsc -b]
E --> F[vite build → CI gate]
A --> G[validate-content / load-time validator]
G --> F
4.1 The generated file
src/types/content-ids.ts (gitignored):
// Generated by scripts/generate-content-types.ts — do not edit.
// Sources: src/data/projects.json, src/data/experience.json,
// src/data/skills.json, src/data/profile.json
export type ProjectId = 'iot-dws-integration' | 'awb-detection';
export type ExperienceId = 'open-to-work' | 'relax-gap' | 'lazada-senior-swe' | 'nexts-founder' | 'sap-senior-swe';
export type SkillGroupId = 'software-engineering' | 'system-architecture' | 'ai-ml' | 'infrastructure' | 'engineering-practices';
export type PhilosophyId = 'build-for-the-real-problem' | 'think-in-systems' | 'measure-impact' | 'keep-learning' | 'business-domain-knowledge-is-a-key-of-success';
export type ProjectCategory = 'logistics' | 'computer-vision';
Rules: document order (stable, reviewable output); literals quoted with JSON.stringify so any slug is expressible; an empty document emits never (Record<never, T> accepts {}, X[] accepts []); LF output; byte-identical output for identical input; if the existing bytes match, the file is not rewritten (no mtime churn for watchers).
4.2 src/types/index.ts after
Lines 1–5 (Language, Palette, SocialId) and 45–79 (PageId, ManifestId, ContentEntityId, manifest types) stay exactly as they are. Lines 7–13 and 15–43 are replaced by:
// Content ids and category values are generated from the structure documents
// (spec-v5). Type-only re-export: erased at emit, no runtime import.
export type { ProjectCategory, ExperienceId, PhilosophyId, ProjectId, SkillGroupId } from './content-ids';
5. Implementation Details
5.1 New scripts/generate-content-types.ts
- Read the four structure documents with
readFileSync+JSON.parsefrom paths resolved againstimport.meta.url(the same approachscripts/smoke-draft.tsuses for its inputs). No imports fromsrc/— this script writes the modulesrc/depends on. - Collect:
projects[].id,experience[].id,skills[].id,profile.philosophy[].id; and uniqueprojects[].categoryin first-use order. - Reject, with the file path in the message and exit 1: a document that is not an array; a missing
philosophyarray; a row without a stringid; a duplicate id in one document (a duplicate would makeRecord<…>narrower than the document, silently). - Write
src/types/content-ids.ts(§4.1). Print a one-line summary in the style ofgenerate-sitemap.ts:content ids generated (2 project, 5 experience, 5 skill group, 5 philosophy, 2 category). scripts/*.tsare outside both tsconfigs (tsconfig.node.jsonincludes onlyvite.config.ts), so the generator is not type-checked bytsc -b— it runs throughtsx, likevalidate-content.tsandsmoke-draft.ts. Keep it dependency-free. Optional (decide at implementation): add it totsconfig.node.jsonincludeso its own types are checked..oxlintrc.jsonsets noignorePatterns, sopnpm lintwill lint the generated file. It is plain type aliases and should pass; if it does not, add"ignorePatterns": ["src/types/content-ids.ts"]rather than changing the generator's output.
5.2 Wiring
package.json:"generate:ids": "pnpm tsx scripts/generate-content-types.ts", pluspredevandprebuildhooks, and"prepare": "pnpm generate:ids"so a fresh install produces the file before the IDE type-checks.buildkeeps its current body;validate:contentunchanged. Hook behaviour verified on pnpm 12.4.1 with a probe package:pnpm run proberanpreprobefirst. CI pins^12.0.0(.gitea/workflows/deploy.yml:27), same major..gitea/workflows/deploy.ymlneeds no change — verified: thebuildjob runspnpm tsx scripts/validate-content.ts(line 28) thenpnpm build(line 29), soprebuildgenerates the file beforetsc -b, and validation runs first but reads only JSON, never the generated module. Thegenerate-resumejob runspnpm install(line 59) — thepreparehook generates there too; even without it the resume script is safe, because the re-export in §4.2 is type-only and erased bytsx..gitignore:src/types/content-ids.ts.
5.3 Deletions (clean cutover, no shims)
| File | Remove |
|---|---|
src/i18n/draft.ts |
TYPES_FILE (101), fetchTextFile (231-236), putTextFile (290-298), the whole id-unions section (UNION_SPECS, UnionBlock, MEMBER_LINE, CLOSING_LINE, nextLine, readUnionBlock, renderUnion, applyUnionChanges, diffIdsWithUnions — 320-427 at writing), saveIdUnions (1156-1189), committedStructures() (558-566 — verified single caller, diffIdsWithUnions), and baseDataOf() (552-554 — dead code today: a repo-wide search finds no caller). Drop the now-unused ContentStructures type import. fetchDoc (218-229) stays — it is the JSON fetcher for the 12 draft documents and for the read-only UI fetch in §5.4 |
src/components/layout/EditModeShell.tsx |
imports TYPES_FILE (16), fetchTextFile (19), saveIdUnions (21); typesRef (51); the types-file fetch (139-144); unionNote state (63) and its reset (274); the union leg (284-296); the unionNote prop (397) |
src/components/layout/EditBar.tsx |
unionNote in the props type (27) and destructuring (59); the note block (251-253) |
src/i18n/locales/{vi,en}/ui/edit.json |
unionNote, unionFailed (69-70) |
scripts/smoke-draft.ts |
checks 9–12 (they test the deleted helpers). Checks 1–8 stay |
fetchTextFile / putTextFile have no other caller (verified across src/): they existed only to read and patch src/types/index.ts.
5.4 Validator rule 7
In collectContentIssues (src/i18n/validate.ts:69-168), after rule 6: for each unique category in structures.projects, require ui[lang].projects.categories[value] to be a non-empty string for vi and en; issue path src/i18n/locales/<lang>/ui/projects.json: categories.<value>.
Plumbing — corrected by the self-review. The draft store does not hold UI documents: DRAFT_DOCS (draft.ts:48-61) is exactly the 12 writable content documents, and DraftStore.validate() (draft.ts:585-588) calls collectContentIssues with structures and content texts only. The rule therefore needs a UI source at each call site, and collectContentIssues / validateContent gain a ui argument:
src/i18n/index.ts(load-time): both UI trees are already built there — pass them.scripts/validate-content.ts: already importsUIfromsrc/i18n(line 17) — pass it.DraftStore.validate()(the save gate):EditModeShellfetches the twoui/projects.jsondocuments read-only at session start withfetchDocand hands them tostore.validate(ui). Two extra GETs per edit session; no new transport helper.
Rejected alternative, recorded as the fallback: put the check in the generator (§5.1) instead — no plumbing at all, but a label-less category is then caught at prebuild/CI rather than before save, against §5.6 of spec-v4-live-edit.md ("an invalid draft never reaches the repository").
Edge case: if the two read-only GETs fail (proxy unreachable — the offline state EditModeShell already handles), rule 7 is skipped with a note in the EditBar, not treated as a failure: the offline state already disables save, and the CI gate runs the same rule against the committed documents.
5.5 Tests
- Remove
smoke-draft.tschecks 9–12. - New
scripts/smoke-generated-ids.ts: build the generator's collector over (a) the real documents — output contains exactly the ids the documents carry and nothing else; (b) a synthetic document with an empty array —neveremitted; (c) a duplicate id — error naming the file; (d) idempotence — running twice yields identical bytes. Open question OQ2 asks whether this file or a case insidevalidate-content.tsis the right home.
5.6 Docs
spec-v4-live-edit.md§3.1: add a "Superseded 2026-10-24 byspec-v5-generated-content-ids.md" note in the style already used for §5.4, keeping the text as the implementation record; add §12 row 23.AGENTS.md: Data Layer — ids and category values are generated,src/types/index.tsholds code-owned unions only; Live Edit — edit mode writes JSON only; Scripts —generate:idsand thepredev/prebuild/preparehooks; Commands table updated.README.mdif it documentspnpm devsteps (check during implementation).
6. Affected Files
| File | Action |
|---|---|
scripts/generate-content-types.ts |
new — generator |
src/types/content-ids.ts |
new, generated, gitignored |
src/types/index.ts |
edit 7-13 + 15-43 → type-only re-export |
src/i18n/draft.ts |
delete 101, 231-247, 290-298, 320-414, 545-553, ≈1148-1189 |
src/components/layout/EditModeShell.tsx |
delete 16, 19, 21, 51, 63, 139-144, 274, 284-296, 397 |
src/components/layout/EditBar.tsx |
delete 27, 59, 251-253 |
src/i18n/locales/vi/ui/edit.json, src/i18n/locales/en/ui/edit.json |
delete 69-70 |
src/i18n/validate.ts |
new rule 7 in collectContentIssues (69-168) + signature growth; validateContent (170-180) |
src/i18n/index.ts |
pass the UI dictionaries to the load-time validation |
src/i18n/draft.ts DraftStore.validate() |
pass UI documents (572-575) |
scripts/validate-content.ts |
pass UI documents |
scripts/smoke-draft.ts |
delete checks 9–12 |
scripts/smoke-generated-ids.ts |
new — generator regression smoke (OQ2) |
package.json |
generate:ids, predev, prebuild, prepare |
.gitignore |
src/types/content-ids.ts |
docs/design/specs/v4/spec-v4-live-edit.md |
§3.1 superseded note, §12 row 23 |
AGENTS.md |
Data Layer / Live Edit / Scripts / Commands |
Unchanged on purpose: src/i18n/dict-types.ts, src/data/*.ts loaders, src/data/pages/*.json, nginx.conf, compose.yaml, .gitea/workflows/* (verified in §5.2), scripts/generate-resume.ts, scripts/generate-sitemap.ts.
7. Acceptance Criteria
- On a fresh clone,
pnpm installorpnpm devproducessrc/types/content-ids.tsandpnpm buildpasses. —pre<script>hook execution verified on pnpm 12.4.1 (§9), and everypnpm build/pnpm tsxrun in this session regenerated the file through those hooks or throughgenerate:ids. ⬜ Not verified: an actual fresh-clone checkout. - A content add or delete touches JSON only:
git statusafter such an edit shows nosrc/types/*entry. —git status --porcelain --ignored src/types/lists the generated file as!! src/types/content-ids.ts(ignored, never a status entry), and after the add/delete experiments below,git status --porcelain src/data src/i18n/localescarried nosrc/typespath. - Deleting a record while its text is still present is an error the build catches; a stale union can no longer cause it. Verified with a throwaway skill group, both directions:
- structure record without text (
tmp-ghost-groupadded tosrc/data/skills.jsononly) →src/i18n/index.ts(69,3): error TS2741: Property '"tmp-ghost-group"' is missing in type … but required in type 'Record<SkillGroupId, SkillGroupText>'— the same class of failure the owner reported, now produced by the regenerated union rather than a hand-maintained one; - text without a record (
tmp-ghost-textadded tolocales/vi/content/skills.jsononly) →pnpm validate:content:src/i18n/locales/vi/content/skills.json: tmp-ghost-text: orphan text key — no such skill group in structure.tscalone does not catch this direction — extra keys in an imported JSON are assignable toRecord<Id, …>— so the validator is the gate here, exactly as before the change. - Staleness is impossible by construction: after the structure document was restored and regenerated,
grep -c "tmp-ghost" src/types/content-ids.ts→0.
- structure record without text (
- A category used in
projects.jsonwithout a label in bothui/projects.jsonfiles failspnpm validate:contentwith the exact file and key. Verified:projects[0].category = "tmp-ghost-cat"producedsrc/i18n/locales/vi/ui/projects.json: categories.tmp-ghost-cat: category used by a project has no label in this languageand the same line foren; with the union regenerated,tscalso reportedTS7053atsrc/components/sections/Projects.tsx:66,src/pages/ProjectDetailPage.tsx:73,src/pages/ProjectsListPage.tsx:55— the label-indexing sites §4.3 names. - Edit-mode save writes only the 12 JSON documents; no
content: update id union memberscommit can ever appear.grep -rn "saveIdUnions|diffIdsWithUnions|applyUnionChanges|UnionLogEntry|onUnionsSaved|unionNote|unionError" src scripts→ no match; neitherui/edit.jsoncarries aunion*key. pnpm build,pnpm lint(no new warnings — the four warnings it prints are the pre-existinguseTheme.tsx,provider.tsx,Footer.tsx,Typewriter.tsxones),pnpm validate:content,pnpm tsx scripts/smoke-draft.ts(11/11),pnpm tsx scripts/smoke-generated-ids.ts(7/7) all pass.- Resume output unchanged.
pnpm build:resume-allrenders both PDFs in both states, and the HTML handed to Playwright is byte-identical with identical content documents: sha256f4abe88c29f8fbe4…(en) and2a3ed5e23c8f8e1a…(vi) from a run with the refactor stashed and from a run with it applied (a temporaryRESUME_DUMP_DIRwrite ingenerate-resume.ts, removed after the check).pdftotextis not installed on this machine, so the comparison is on the rendered HTML — the input to the PDF; PDF bytes legitimately differ by Playwright metadata. - Bundle shape unchanged: 10 chunks with names identical to a build of the same documents before the refactor, and no runtime reference to the generated module (
grep -rl "content-ids" dist/→ nothing; the re-export is type-only and erased).
8. Open questions — decided 2026-10-24
- OQ1 — generated file: gitignored (owner's call).
src/types/content-ids.tsis generated output, not authored code: no content commit ever carries a code file, and no content review shows asrc/types/*diff. The id list is still reviewable — it is the id array in the structure documents, which is where it was always written. - OQ2 — generator regression test: dedicated
scripts/smoke-generated-ids.ts. Same shape as the existingscripts/smoke-draft.ts;validate-content.tsstays a validator, not a test harness. - OQ3 —
noImplicitAny: out of scope for v5.tsconfig.app.jsonsets nostrict, sos.projects.categories[category]is implicitanytoday and rule 7 is the guard. Enabling it is its own task with unmeasured fallout.
9. Risks & Mitigations
| Risk | Mitigation |
|---|---|
| Fresh clone / IDE errors before the first generation | prepare on install + predev; the generator names the file and the reason in its error |
pre<script> hooks not running |
verified on pnpm 12.4.1 (a probe script ran preprobe before probe); CI pins ^12.0.0. Note the CI build job never runs pnpm install, so prebuild — not prepare — is what guarantees generation there |
Losing the as-assertion typo guard for category |
validator rule 7 checks the real failure (no label); the category list is reviewed as a JSON diff in Gitea |
| Generated file committed by accident | .gitignore entry + an acceptance check that a content edit dirties JSON only |
| Draft data in the browser is not type-checked | unchanged from v4 — edit mode casts draft data; the CI build is the gate, as in D4 of spec-v4-live-edit.md |
| A deleted project id that is already a published URL | unchanged behaviour from v4; pnpm build regenerates sitemap.xml |
| Removing the EditBar union note leaves an orphan UI string | both keys deleted with the feature; edit group keeps every other key |
10. Progress Tracking
| # | Task | Status |
|---|---|---|
| 1 | This spec (rev.1) reviewed & approved by owner — OQ1–OQ3 decided | ✅ Decided 2026-10-24 — OQ1 gitignored, OQ2 dedicated generator smoke, OQ3 out of scope (§8) |
| 2 | scripts/generate-content-types.ts + generated file + package.json hooks + .gitignore (deploy.yml confirmed unchanged) |
✅ Done 2026-10-24 — generator writes the 777-byte module (2 project, 5 experience, 5 skill group, 5 philosophy, 2 category ids) and is byte-stable on a second run; generate:ids + predev / prebuild / prepare in package.json; .gitignore carries src/types/content-ids.ts; .gitea/workflows/deploy.yml untouched |
| 3 | src/types/index.ts re-export; delete the v4 union machinery in draft.ts, EditModeShell.tsx, EditBar.tsx, ui/edit.json |
✅ Done 2026-10-24 — index.ts re-exports the generated unions type-only and keeps Language, Palette, SocialId, PageId, PageManifestClaim, PageManifest, Theme; saveIdUnions / diffIdsWithUnions / applyUnionChanges / readUnionBlock / unionNote / unionError / UnionLogEntry / onUnionsSaved / the EditBar union card / edit.union.* deleted — grep over src + scripts finds no match |
| 4 | Validator rule 7 + ui argument at all three call sites (index.ts, validate-content.ts, store.validate(ui) fed by a read-only fetchDoc pair in EditModeShell) |
✅ Done 2026-10-24 — verified end-to-end: a project with category: "tmp-ghost-cat" fails pnpm validate:content naming both ui/projects.json files and categories.tmp-ghost-cat; the draft store skips the rule when the labels cannot be read and the EditBar says so |
| 5 | Tests: remove smoke-draft.ts 9–12; add the generator smoke (OQ2) |
✅ Done 2026-10-24 — smoke-draft.ts 11/11 (checks 9–12 replaced by the rename re-sluging check and the category-label rule check); scripts/smoke-generated-ids.ts 7/7: the unions equal the documents, the file on disk equals what these documents generate now, output byte-stable, never for an emptied document, a duplicate id refused naming the file, a record with no usable id or category refused naming the file, every slug quoted so it round-trips in document order |
| 6 | Verification run: pnpm build, pnpm lint, pnpm validate:content, both smokes, resume PDF text diff, dist/ chunk list comparison against a build of the same documents |
✅ Done 2026-10-24 — all commands pass; resume HTML byte-identical before/after with identical documents (sha256 in §7); dist/ chunk names identical, 10 chunks, no runtime reference to the generated module; pnpm build:resume-all produces both PDFs in both states. ⬜ Not run: a fresh-clone checkout |
| 7 | Docs: spec-v4-live-edit.md §3.1 superseded note + §12 row 23, AGENTS.md, README.md if needed |
✅ Done 2026-10-24 — §3.1 banner, §12 row 22 marked superseded + row 23 added here; AGENTS.md Commands row, Data Layer bullet, Live Edit bullet rewritten, component tree, Scripts list, Gotcha 8, Design Specs v5 row; README.md generate:ids row + the generated-ids note |