From 831f36e6185393d3e53c8e31b7cc09376524b011 Mon Sep 17 00:00:00 2001 From: "bert.hausmans" Date: Mon, 4 May 2026 21:53:38 +0200 Subject: [PATCH] docs(backlog): add TECH-TYPED-ROUTER-DRIFT Triggered by the typed-router.d.ts regeneration in 3198698. Documents three approaches (lefthook pre-commit, gitignore+postinstall, CI-check) with their trade-offs. Defers selection to implementation time; recommends bundling with the next pages-tree refactor (likely WS-3 PR-B). Co-Authored-By: Claude --- dev-docs/BACKLOG.md | 61 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/dev-docs/BACKLOG.md b/dev-docs/BACKLOG.md index f1e309cf..4db9073d 100644 --- a/dev-docs/BACKLOG.md +++ b/dev-docs/BACKLOG.md @@ -642,6 +642,67 @@ of `plugins/` raakt, of een dedicated 2-3 uur sessie na WS-6 sluiting. --- +### TECH-TYPED-ROUTER-DRIFT — apps/app/typed-router.d.ts drifts when pages/ changes are merged without rebuild + +**Aanleiding:** Op 2026-05-04 bleek `apps/app/typed-router.d.ts` +achter te lopen op de pages-tree: vier `form-failures` routes +(organisation + platform, list + detail) waren al maanden geleden +gelandt in main, maar de gegenereerde route-types waren nooit +mee-gecommit. Pas een lokale `pnpm build` triggerde +`unplugin-vue-router` om het bestand te regenereren, waarna een +losse commit (`3198698`) de drift dichtmaakte. Zonder die toevallige +build-run had de drift onbeperkt door kunnen lopen — TypeScript +flagde de stale routes niet, en niemand routeert via de typed names +hard genoeg dat het brak. + +Het bestand is tracked, niet gitignored. Dat betekent: elke PR die +een file in `apps/app/src/pages/` toevoegt of hernoemt, moet +óók de regeneratie van `typed-router.d.ts` meecommitten. In de +praktijk gebeurt dat nu inconsistent. + +**Wat:** Drie reële paden, kies bij implementatie: + +- **Approach 1 (preferred): pre-commit hook in lefthook.** + Voeg een lefthook pre-commit hook toe die — wanneer een + `apps/app/src/pages/**` file in de staging-set zit — + `unplugin-vue-router` triggert en `apps/app/typed-router.d.ts` + re-stage't als hij is veranderd. Hook is silent op de happy + path; faalt loud bij regeneratie-error. Voordeel: types altijd + in sync in git, fresh clones werken zonder eerst te builden. + Nadeel: extra commit-tijd voor pages-changes (~2-5s per commit + in de plugin), en `unplugin-vue-router` heeft geen standalone + CLI-mode dus de hook wordt een Node-script dat de plugin laadt + en handmatig aanstuurt — fragiel bij plugin-versie-upgrades. + +- **Approach 2 (alternative): gitignore + regenereer in postinstall.** + Voeg `apps/app/typed-router.d.ts` toe aan `.gitignore`. Voeg een + `postinstall` script in `apps/app/package.json` dat `vue-tsc` of + een vergelijkbare prebuild-stap triggert die `unplugin-vue-router` + zijn type-emit laat doen. Voordeel: drift is structureel + onmogelijk — er is niets meer in git om uit sync te raken. Nadeel: + fresh clones zijn een paar seconden trager (`pnpm install` doet + meer werk), en als `postinstall` faalt heb je IDE-rode-squiggles + totdat je het oplost. + +- **Approach 3 (status quo + alarm): CI-check.** + Houd het bestand tracked, maar voeg een CI-stap toe die + `unplugin-vue-router` regenereert en faalt als de output + verschilt van wat in git staat. Voordeel: minimale lokale + workflow-impact. Nadeel: CI-only — drift wordt pas gevonden + bij PR-build. Werkt alleen als er CI is (op het moment van + schrijven: er is nog geen GitHub-Actions / Drone / Gitea-Actions + pipeline geconfigureerd in deze repo). + +**Prioriteit:** Laag — geen functionele impact, alleen DX en +type-safety-betrouwbaarheid. Geen blocker voor andere +workstreams. Aanbevolen moment: meelift met de eerste +substantiële pages-tree refactor (bijvoorbeeld WS-3 PR-B die +de portal pages naar `apps/app/src/pages/portal/` verhuist — +dán is de drift-kans het grootst en de pijn van onbeschermd +laten ook). + +--- + ### TECH-WS3-BOUNDARIES-SUBZONES — Sub-zone import-boundaries inside components/ and pages/ **Aanleiding:** WS-3 sessie 1c heeft top-level zone-boundaries in