From 05c06200e341837da96a2248d6ed7222104d4a6e Mon Sep 17 00:00:00 2001 From: Wynne Pirini Date: Fri, 6 Nov 2026 15:54:18 +1300 Subject: [PATCH] fix(admin): never render catalogue text as HTML, and guard the call sites Two gaps the catalogue tests cannot see, both from the #217 review. 1. `{@html $t('layout.reportDialog.descriptionHtml')}` in +layout.svelte rendered catalogue content as markup, while catalog.ts claims the opposite and the guard in catalog.test.ts only rejected `` in a future locale file would have passed every test and executed in an operator's admin session. Community locale PRs are a real input here, so that is a live surface, not a theoretical one. The HTML key was also redundant: `description` already existed, plain and unused, with the same sentence. The dialog now uses it and `descriptionHtml` is deleted from en and fr, so the contract in catalog.ts is true again without needing a rule to enforce it. 2. Nothing checked the call sites against the catalogue. A typo rendered the dotted key on screen and CI stayed green. frontend/scripts/check-i18n.mjs (pnpm check:i18n, run in CI) now enforces both: every literal key passed to $t/tr/trp/trp2 exists in en.json; plural group paths count as keys because trp appends `.one`/`.other` itself; dynamic template and ternary keys are counted and skipped rather than guessed at; and no call site renders catalogue text with {@html}. Verified: the guard passes on this tree (1503 call sites, 1323 keys, 299 plural groups, 11 dynamic skipped). A probe file containing a missing $t key, a missing tr key and one {@html} call makes it exit 1 and report all three, so the gate fails when it should. svelte-check is clean and the 27 visual tests pass. --- .github/workflows/ci.yml | 7 ++ frontend/package.json | 1 + frontend/scripts/check-i18n.mjs | 108 +++++++++++++++++++++++++++++ frontend/src/lib/i18n/en.json | 3 +- frontend/src/lib/i18n/fr.json | 3 +- frontend/src/routes/+layout.svelte | 2 +- 6 files changed, 119 insertions(+), 5 deletions(-) create mode 100644 frontend/scripts/check-i18n.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 57f1756d..4bff0bce 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,6 +88,13 @@ jobs: working-directory: frontend run: pnpm check + # Data-level catalogue tests cannot see the 1,500-odd call sites that use the keys, + # or how the strings are rendered. This checks both: every literal $t/tr/trp key + # exists in en.json, and no catalogue value is rendered with {@html}. + - name: i18n catalogue guard (call sites, no {@html}) + working-directory: frontend + run: pnpm check:i18n + - name: Build frontend (required by the Go embed) working-directory: frontend run: pnpm build diff --git a/frontend/package.json b/frontend/package.json index 32df993d..715e485a 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -15,6 +15,7 @@ "scripts": { "dev": "vite dev", "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json", + "check:i18n": "node scripts/check-i18n.mjs", "build": "vite build", "preview": "vite preview", "test:visual": "vitest run" diff --git a/frontend/scripts/check-i18n.mjs b/frontend/scripts/check-i18n.mjs new file mode 100644 index 00000000..5e3dec8d --- /dev/null +++ b/frontend/scripts/check-i18n.mjs @@ -0,0 +1,108 @@ +#!/usr/bin/env node +// Source-level guards for the admin catalogue. +// +// The catalogue tests (src/lib/i18n/i18n.test.ts) prove things about the data: keys line +// up, placeholders match, no baked plurals. They cannot see the 1,270-odd call sites that +// use that data, and they cannot see how it is rendered. That gap is what this checks: +// +// 1. Every literal key passed to $t/tr/trp/trp2 exists in en.json. A typo currently +// renders the dotted key on screen and every test stays green. +// 2. No catalogue string is rendered with {@html}. Catalogue text is plain text by +// contract (see catalog.ts); community locale PRs are a real input, so HTML in a +// catalogue is an injection surface, not a styling convenience. +// +// Runs from the frontend directory: `pnpm check:i18n`, and in CI. +// +// Dynamic keys (template literals, ternaries) are skipped rather than guessed at. They +// are listed at the end so a reviewer can see what is not covered. + +import { readFileSync, readdirSync, statSync } from 'node:fs'; +import { join, relative, extname } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const frontendDir = fileURLToPath(new URL('..', import.meta.url)); +const srcDir = join(frontendDir, 'src'); +const cataloguePath = join(srcDir, 'lib/i18n/en.json'); + +// The catalogue's own module and tests define the helpers; they are not call sites. +const SKIP_DIRS = [join(srcDir, 'lib/i18n')]; + +function flatten(value, prefix = '', leaves = new Map(), groups = new Set()) { + if (value && typeof value === 'object' && !Array.isArray(value)) { + // An object is a real key too: trp/trp2 append `.one`/`.other` themselves, so a + // plural call passes the group path, not a leaf. + if (prefix) groups.add(prefix); + for (const [k, v] of Object.entries(value)) flatten(v, prefix ? `${prefix}.${k}` : k, leaves, groups); + } else { + leaves.set(prefix, value); + } + return { leaves, groups }; +} + +function* walk(dir) { + for (const entry of readdirSync(dir)) { + const full = join(dir, entry); + if (SKIP_DIRS.some((skip) => full === skip || full.startsWith(skip + '/'))) continue; + const st = statSync(full); + if (st.isDirectory()) yield* walk(full); + else if (['.svelte', '.ts'].includes(extname(full))) yield full; + } +} + +const { leaves: keys, groups } = flatten(JSON.parse(readFileSync(cataloguePath, 'utf8'))); + +// `$t('key')`, `tr('key')`, `trp('key', n)`, `trp2('key', a, b)`. The key must be the +// first argument and a plain quoted string; anything else is dynamic and is counted, not +// checked. +const CALL = /(?:\$t\(|\b(?:tr|trp|trp2)\()\s*(['"])((?:(?!\1).)+)\1/g; +const ANY_CALL = /(?:\$t\(|\b(?:tr|trp|trp2)\()/g; +const RENDERED_AS_HTML = /\{@html[^}]*?(?:\$t\(|\b(?:tr|trp|trp2)\()/; + +const missing = []; +const asHtml = []; +let checked = 0; +let dynamic = 0; + +for (const file of walk(srcDir)) { + const rel = relative(frontendDir, file); + const source = readFileSync(file, 'utf8'); + source.split('\n').forEach((line, i) => { + if (RENDERED_AS_HTML.test(line)) asHtml.push(`${rel}:${i + 1}: ${line.trim()}`); + const literalKeys = new Set(); + for (const m of line.matchAll(CALL)) { + checked++; + literalKeys.add(m[2]); + if (!keys.has(m[2]) && !groups.has(m[2])) missing.push(`${rel}:${i + 1}: ${m[2]}`); + } + // Calls on this line with no literal key are dynamic. + const total = [...line.matchAll(ANY_CALL)].length; + dynamic += Math.max(0, total - literalKeys.size); + }); +} + +let failed = false; + +if (missing.length > 0) { + failed = true; + console.error(`\n${missing.length} call site(s) use a key that is not in en.json:\n`); + for (const m of missing) console.error(` ${m}`); + console.error('\nA missing key renders as the dotted key on screen. Check the spelling, or add it to en.json first.\n'); +} + +if (asHtml.length > 0) { + failed = true; + console.error(`\n${asHtml.length} call site(s) render catalogue text with {@html}:\n`); + for (const h of asHtml) console.error(` ${h}`); + console.error( + '\nCatalogue values are plain text and community locale PRs are a real input, so this is an injection surface.\n' + + 'Render the markup in the component and use a key per fragment, or use LinkedText for operator links.\n' + ); +} + +console.log( + `i18n guard: ${checked} literal call site(s) checked against ${keys.size} keys ` + + `(+${groups.size} plural groups), ` + + `${dynamic} dynamic call site(s) skipped (template/ternary keys).` +); + +if (failed) process.exit(1); diff --git a/frontend/src/lib/i18n/en.json b/frontend/src/lib/i18n/en.json index e64f36c9..6572f081 100644 --- a/frontend/src/lib/i18n/en.json +++ b/frontend/src/lib/i18n/en.json @@ -81,8 +81,7 @@ "title": "Report an issue", "description": "Please search the existing issues first — it may already be reported or being worked on. The tracker is for reproducible bugs in Calnode; for setup help or \"how do I…\" questions, please use Discussions instead.", "searchIssues": "Search existing issues", - "reportBug": "Report a bug", - "descriptionHtml": "Please search the existing issues first — it may already be reported or being worked on. The tracker is for reproducible bugs in Calnode; for setup help or “how do I…” questions, please use Discussions instead." + "reportBug": "Report a bug" }, "headTitleSuffix": "Calnode" }, diff --git a/frontend/src/lib/i18n/fr.json b/frontend/src/lib/i18n/fr.json index a9476340..34f34ae4 100644 --- a/frontend/src/lib/i18n/fr.json +++ b/frontend/src/lib/i18n/fr.json @@ -81,8 +81,7 @@ "title": "Signaler un problème", "description": "Veuillez d'abord rechercher parmi les tickets existants — le problème a peut-être déjà été signalé ou est en cours de traitement. Le suivi est réservé aux bugs reproductibles dans Calnode ; pour une aide à la configuration ou les questions du type « comment faire pour… », utilisez plutôt Discussions.", "searchIssues": "Rechercher parmi les tickets existants", - "reportBug": "Signaler un bug", - "descriptionHtml": "Veuillez d'abord rechercher parmi les tickets existants — le problème a peut-être déjà été signalé ou est en cours de traitement. Le suivi est réservé aux bugs reproductibles dans Calnode ; pour une aide à la configuration ou les questions du type « comment faire pour… », utilisez plutôt Discussions." + "reportBug": "Signaler un bug" }, "headTitleSuffix": "Calnode" }, diff --git a/frontend/src/routes/+layout.svelte b/frontend/src/routes/+layout.svelte index c74fc71d..8c48c731 100644 --- a/frontend/src/routes/+layout.svelte +++ b/frontend/src/routes/+layout.svelte @@ -387,7 +387,7 @@ {$t('layout.reportDialog.title')} - {@html $t('layout.reportDialog.descriptionHtml')} + {$t('layout.reportDialog.description')}