From 709d3ab5b5127bf171bf744c1266425f3042d375 Mon Sep 17 00:00:00 2001 From: Gerome Grignon Date: Wed, 28 Oct 2026 10:36:34 +0000 Subject: [PATCH 1/2] fix(build): make Bazel output writable before post-processing Bazel writes its outputs read-only (files 0444, directories 0555), and parts of the output tree (assets/content/**) are symlinks into other read-only Bazel outputs. postProcess rewrites index.html, JS bundles, the rendered docs, robots.txt and sitemap.xml in place, so `pnpm build` failed on CI with EACCES (seen in angular-devs-france/angular-docs-fr, first on browser/ai/agent-skills/index.html, then on assets/content/ai/agent-skills.md.html). makeWritable() now runs before the rewrite: each symlink in the output is replaced with a copy of its target (directories recursively, dereferenced) so Bazel's own outputs are never edited, dangling symlinks are left alone, and every file and directory gets owner write permission. Tests cover read-only files and directories, and directory, file and dangling symlinks (the target behind a symlink stays untouched). They fail without the fix when run as a non-root user, like CI. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012VyCYYm1hGSzUjxiYyX3iW --- tools/lib/build-steps.mjs | 41 +++++++++++++++++++++++++++++++- tools/test/build-steps.test.mjs | 42 +++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 1 deletion(-) diff --git a/tools/lib/build-steps.mjs b/tools/lib/build-steps.mjs index 261ad95..c6923d9 100644 --- a/tools/lib/build-steps.mjs +++ b/tools/lib/build-steps.mjs @@ -2,7 +2,7 @@ * Steps shared by `pnpm build` and `pnpm start`: worktree, patches, overlay, dictionaries, * status report, pnpm in the build directory, post-processing of the output. */ -import {appendFile, readFile} from 'node:fs/promises'; +import {appendFile, chmod, copyFile as fsCopyFile, cp, lstat, readFile, readdir, realpath, stat, unlink} from 'node:fs/promises'; import path from 'node:path'; import {applyIndexHtmlPairs, applyNavLabels, applyPipelinePairs, applyTemplateStrings} from './adev.mjs'; import {git, run} from './exec.mjs'; @@ -253,12 +253,51 @@ export async function checkNodeVersion(dir) { export const OUTPUT_REL = path.join('dist', 'bin', 'adev', 'dist', 'browser'); +/** + * Bazel writes its outputs read-only (files 0444, directories 0555), and parts of the output tree + * (assets/content, for example) are symlinks into other read-only Bazel outputs. Post-processing + * edits the tree in place, so: replace every symlink with a real copy of its target (Bazel's own + * outputs stay untouched), then give the owner write access to every file and directory. + * Dangling symlinks are left as they are. + */ +export async function makeWritable(dir) { + let count = 0; + const walk = async (p) => { + let st = await lstat(p); + if (st.isSymbolicLink()) { + let target; + try { + target = await realpath(p); + } catch { + return; + } + const tst = await stat(target); + await unlink(p); + if (tst.isDirectory()) await cp(target, p, {recursive: true, dereference: true}); + else await fsCopyFile(target, p); + count++; + st = await lstat(p); + } + const mode = st.mode & 0o7777; + const want = st.isDirectory() ? mode | 0o700 : mode | 0o200; + if (want !== mode) { + await chmod(p, want); + count++; + } + if (st.isDirectory()) for (const name of await readdir(p)) await walk(path.join(p, name)); + }; + await walk(dir); + return count; +} + /** Rewrite edit links, add canonical + hreflang per page, write sitemap.xml and robots.txt. */ export async function postProcess(lang, dir) { const site = await loadSite(lang); const out = path.join(dir, OUTPUT_REL); if (!(await exists(out))) throw new Error(`build output not found at ${out}`); log.step('post-process output'); + const unlocked = await makeWritable(out); + if (unlocked) log.info(`made ${unlocked} read-only Bazel output entr${unlocked === 1 ? 'y' : 'ies'} writable`); const editFrom = ['https://github.com/angular/angular/edit/main/adev/src/content/', 'https://github.com/angular/angular/blob/main/adev/src/content/']; const editTo = `${site.repoUrl}/edit/${site.repo.branch}/i18n/${lang}/src/content/`; diff --git a/tools/test/build-steps.test.mjs b/tools/test/build-steps.test.mjs index bce4bf6..1cab1f7 100644 --- a/tools/test/build-steps.test.mjs +++ b/tools/test/build-steps.test.mjs @@ -4,6 +4,7 @@ * upstream as origin/ (a real git repository), so ROSETTA_ORIGIN stays unset like in a real build. */ import assert from 'node:assert/strict'; +import {chmod, lstat, mkdir, stat, symlink} from 'node:fs/promises'; import path from 'node:path'; import {after, before, describe, test} from 'node:test'; import {execa} from 'execa'; @@ -278,6 +279,47 @@ describe('postProcess', () => { await postProcess(lang, dir); assert.equal((await read(path.join(out, 'robots.txt'))).match(/Sitemap:/g).length, 1, 'idempotent'); }); + test('edits Bazel output even when files and directories are read-only', async () => { + const out = path.join(dir, OUTPUT_REL); + const page = path.join(out, 'ai/agent-skills/index.html'); + await write(page, 'Apage'); + await write(path.join(out, 'robots.txt'), 'User-agent: *\nAllow: /\n'); + await chmod(page, 0o444); + await chmod(path.join(out, 'robots.txt'), 0o444); + await chmod(path.join(out, 'ai/agent-skills'), 0o555); + await chmod(out, 0o555); + await postProcess(lang, dir); + assert.ok((await read(page)).includes('')); + assert.ok((await read(path.join(out, 'robots.txt'))).includes('Sitemap: https://angular.fr/sitemap.xml')); + // Root ignores permission bits, so also assert the modes themselves (CI runs as a normal user). + assert.equal((await stat(page)).mode & 0o200, 0o200, 'file made writable'); + assert.equal((await stat(path.join(out, 'ai/agent-skills'))).mode & 0o700, 0o700, 'directory made writable'); + }); + test('replaces symlinks into other Bazel outputs with writable copies, leaving the targets untouched', async () => { + const out = path.join(dir, OUTPUT_REL); + const elsewhere = path.join(dir, 'bazel-out-elsewhere'); + const target = path.join(elsewhere, 'content/ai/agent-skills.md.html'); + const blob = 'https://github.com/angular/angular/blob/main/adev/src/content/ai/agent-skills.md'; + await write(target, `

edit

`); + await write(path.join(elsewhere, 'single.js'), `const e = "${blob}";`); + await write(path.join(out, 'index.html'), 'home'); + await mkdir(path.join(out, 'assets'), {recursive: true}); + await symlink(path.join(elsewhere, 'content'), path.join(out, 'assets/content')); + await symlink(path.join(elsewhere, 'single.js'), path.join(out, 'single.js')); + await symlink(path.join(elsewhere, 'missing'), path.join(out, 'dangling')); + await chmod(target, 0o444); + await chmod(path.join(elsewhere, 'content/ai'), 0o555); + await postProcess(lang, dir); + const copied = path.join(out, 'assets/content/ai/agent-skills.md.html'); + assert.ok(!(await lstat(path.join(out, 'assets/content'))).isSymbolicLink(), 'directory symlink replaced by a copy'); + assert.ok(!(await lstat(path.join(out, 'single.js'))).isSymbolicLink(), 'file symlink replaced by a copy'); + assert.ok((await lstat(path.join(out, 'dangling'))).isSymbolicLink(), 'dangling symlink left alone'); + assert.equal((await stat(copied)).mode & 0o200, 0o200, 'copied file writable'); + assert.ok((await read(copied)).includes('https://github.com/org/docs-fr/edit/main/i18n/fr/src/content/ai/agent-skills.md')); + assert.ok((await read(target)).includes(blob), 'the Bazel output behind the symlink is not edited'); + assert.equal((await stat(target)).mode & 0o777, 0o444, 'and keeps its mode'); + await chmod(path.join(elsewhere, 'content/ai'), 0o755); // let the suite's cleanup remove it as a normal user + }); test('fails when there is no build output', async () => { await removeDir(path.join(dir, 'dist')); await assert.rejects(postProcess(lang, dir), /build output not found/); From d746fc60d4f46a403ce55d445d53dd0f930b2c57 Mon Sep 17 00:00:00 2001 From: Gerome Grignon Date: Wed, 28 Oct 2026 12:56:23 +0100 Subject: [PATCH 2/2] fix(example): remove related tests on first create-language --- CONTRIBUTING.md | 2 +- tools/test/fixtures/example/LANGUAGE.md | 60 +++++++++++++++++++++++ tools/test/fixtures/example/README.md | 24 +++++++++ tools/test/fixtures/example/glossary.json | 32 ++++++++++++ tools/test/fixtures/example/site.json | 36 ++++++++++++++ tools/test/helpers.mjs | 4 +- tools/test/scripts.test.mjs | 11 +++++ 7 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 tools/test/fixtures/example/LANGUAGE.md create mode 100644 tools/test/fixtures/example/README.md create mode 100644 tools/test/fixtures/example/glossary.json create mode 100644 tools/test/fixtures/example/site.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 522e298..4ef2323 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,7 @@ If you use an AI assistant, point it at `AGENTS.md`; the `adev-translation` skil - `tools/` is plain Node (ESM, no build step): one [citty](https://github.com/unjs/citty) CLI (`tools/cli.mjs`) whose subcommands live in `tools/commands/`, shared code in `tools/lib/`. Prefer a maintained library over custom code (see [docs/architecture.md](docs/architecture.md#tooling)). Every subcommand has a `pnpm ` alias of the same name in `package.json`; a name that pnpm itself owns (`setup`, `deploy`, `init`, `docs`, `search`…) is unusable, because `pnpm ` runs pnpm's command instead of the script: `tools/test/scripts.test.mjs` rejects those. - Diagrams in `docs/` and the README are Mermaid blocks (GitHub renders them); keep them small, keep the commands in them identical to the real flags, and preview a change in GitHub's Markdown preview or at mermaid.live before opening the PR. -- `pnpm test` runs the suite in `tools/test/` (about a minute): one unit file per `tools/lib/` module, `scripts.test.mjs` for the `package.json` aliases, `cli.test.mjs` which drives the real CLI end to end in a temporary repository (scaffold, translate, check, sync, mechanical apply, dictionaries, glossary, report, Firebase config, `build --prepare-only`), and `parity.test.mjs` which runs upstream's own `heading.mts` against our anchor port. Tests never touch this checkout: they build throwaway repositories from `tools/test/fixtures/upstream` (a pocket `angular/angular`) and point the tooling at them with `ROSETTA_ROOT` / `ROSETTA_ORIGIN`. A change to a command needs a case in `cli.test.mjs`; a change to upstream's file layout needs the fixture updated. +- `pnpm test` runs the suite in `tools/test/` (about a minute): one unit file per `tools/lib/` module, `scripts.test.mjs` for the `package.json` aliases, `cli.test.mjs` which drives the real CLI end to end in a temporary repository (scaffold, translate, check, sync, mechanical apply, dictionaries, glossary, report, Firebase config, `build --prepare-only`), and `parity.test.mjs` which runs upstream's own `heading.mts` against our anchor port. Tests never touch this checkout, and never read its `i18n/` (repositories created from the template delete `i18n/_example`): they build throwaway repositories from `tools/test/fixtures/upstream` (a pocket `angular/angular`) and `tools/test/fixtures/example` (a frozen copy of the example's configuration) and point the tooling at them with `ROSETTA_ROOT` / `ROSETTA_ORIGIN`. A change to a command needs a case in `cli.test.mjs`; a change to upstream's file layout needs the fixture updated. - Never change files under `origin/`. Code-level changes to the site live in `tools/adev-patches/*.patch` and must pass `git apply --check` against the pinned upstream in CI. - Workflows pin actions by commit SHA. Keep permissions minimal. - Changes to skills or docs follow the same review as code. diff --git a/tools/test/fixtures/example/LANGUAGE.md b/tools/test/fixtures/example/LANGUAGE.md new file mode 100644 index 0000000..c28f26a --- /dev/null +++ b/tools/test/fixtures/example/LANGUAGE.md @@ -0,0 +1,60 @@ +--- +lang: fr +name: Français +direction: ltr +formality: formal +lineParity: strict +quotes: ["«", "»"] +spaceBeforePunctuation: + chars: [":", ";", "?", "!"] + space: " " +headingCase: sentence +numberFormat: "1 234,56" +dateFormat: "27 octobre 2026" +fonts: [] +--- + +# Règles de traduction : français + +Ces règles s'appliquent à toute page sous `i18n/fr/src/`. Le glossaire (`glossary.json`) fait foi pour la terminologie. En cas de doute, cherchez une page déjà traduite qui traite du même sujet et alignez-vous. + +## Registre et ton + +- Vouvoiement, toujours : « vous pouvez », jamais « tu peux ». +- Phrases directes, voix active quand l'anglais l'emploie. Ne rien ajouter : pas d'explication supplémentaire, pas d'avis, pas de promotion. +- Les instructions utilisent l'impératif à la deuxième personne du pluriel (« Créez un composant »), pas l'infinitif, sauf dans les listes de tâches courtes où l'anglais utilise des fragments. + +## Typographie + +- Espace fine insécable (U+202F) avant `:` `;` `?` `!`. Le vérificateur signale une espace ordinaire ou une absence d'espace. +- Guillemets français « » avec espaces insécables à l'intérieur. Les guillemets droits restent dans le code, les sorties de commande et les citations en anglais. +- Titres en casse de phrase : « Composants et modèles », pas « Composants Et Modèles ». +- Noms de produits et d'API tels quels : Angular, Angular CLI, TypeScript, `signal`, `computed`, `inject`. +- Nombres : espace insécable pour les milliers, virgule décimale (1 234,56). Dates en toutes lettres dans la prose (27 octobre 2026). + +## Ce qui reste en anglais + +- Les noms d'API, de fichiers, de commandes et d'options : `@Component`, `ng generate`, `--standalone`. +- Les termes marqués `keep` dans le glossaire : *signal*, *template*, *pipe*, *standalone*, *zoneless*, *hydration* est traduit (hydratation) mais *SSR* reste. +- Le code, y compris ses commentaires (règle v1), les exemples de sortie, les URL, les ancres. + +## Pièges + +- *Component* → composant (masculin). *Directive* → directive (féminin). *Signal* reste signal, masculin : un signal, des signals (pas « signaux », qui désigne le concept général). +- *Template* reste template (masculin : le template). Jamais « gabarit » ni « modèle ». +- *Dependency injection* → injection de dépendances (pluriel). *Change detection* → détection de changements. +- *Library* → bibliothèque, jamais « librairie ». +- *Form* → formulaire ; *reactive forms* → formulaires réactifs ; *signal forms* → formulaires à base de signals. +- *You* dans une instruction → « vous » ; *your application* → « votre application ». +- Ne traduisez pas les faux amis à l'identique : *actually* → en réalité ; *eventually* → au final ; *consistent* → cohérent. + +## Chaînes d'interface + +- Libellés de navigation et de boutons courts : nom ou infinitif, sans point final (« Guide », « Commencer », « Référence »). +- Respectez la longueur : un libellé de menu dépassant deux mots de plus que l'anglais déborde sur mobile. + +## Échantillon + +> **EN** Signals are Angular's primitive for reactive state. A signal holds a value and notifies interested consumers when that value changes. +> +> **FR** Les signals sont la primitive d'Angular pour l'état réactif. Un signal contient une valeur et notifie les consommateurs intéressés quand cette valeur change. diff --git a/tools/test/fixtures/example/README.md b/tools/test/fixtures/example/README.md new file mode 100644 index 0000000..58b12b1 --- /dev/null +++ b/tools/test/fixtures/example/README.md @@ -0,0 +1,24 @@ +# Français (exemple) — `i18n/_example` + +Reference language of the template. It carries a complete French `LANGUAGE.md`, a seeded glossary and generated dictionaries so the template's own CI can build a localized site. It is removed from repositories created from the template (`pnpm create-language` offers to delete it). + +Use it as a model for your own `i18n//README.md`: + +## Maintainers + +- `@handle` (lead), `@handle` + +## Where we talk + +- Chat: _link_ +- Issues: label `lang:fr` + +## How we review + +- New page: one translator, one reviewer who did not write the text. +- Outdated page (classes a, b, c): one reviewer. +- Terminology changes go through the glossary (`glossary.json`), not through line comments only. + +## Status + +- Coverage and freshness: `/assets/others/translation-status.json` on the site, or `pnpm report fr`. diff --git a/tools/test/fixtures/example/glossary.json b/tools/test/fixtures/example/glossary.json new file mode 100644 index 0000000..7cb2913 --- /dev/null +++ b/tools/test/fixtures/example/glossary.json @@ -0,0 +1,32 @@ +[ + {"term": "signal", "keep": true, "note": "API name; masculine in French: un signal, des signals", "forbidden": ["signaux"]}, + {"term": "template", "keep": true, "note": "masculine: le template", "forbidden": ["gabarit"]}, + {"term": "pipe", "keep": true, "note": "masculine: un pipe"}, + {"term": "standalone", "keep": true}, + {"term": "zoneless", "keep": true}, + {"term": "component", "translation": "composant", "note": "masculine"}, + {"term": "directive", "translation": "directive", "note": "feminine"}, + {"term": "service", "translation": "service"}, + {"term": "dependency injection", "translation": "injection de dépendances", "forbidden": ["injection de dépendance"]}, + {"term": "change detection", "translation": "détection de changements", "forbidden": ["détection des changements", "détection de changement"]}, + {"term": "hydration", "translation": "hydratation"}, + {"term": "server-side rendering", "translation": "rendu côté serveur (SSR)", "note": "keep the SSR acronym"}, + {"term": "library", "translation": "bibliothèque", "forbidden": ["librairie"]}, + {"term": "form", "translation": "formulaire"}, + {"term": "reactive forms", "translation": "formulaires réactifs"}, + {"term": "signal forms", "translation": "formulaires à base de signals"}, + {"term": "binding", "translation": "liaison", "note": "property binding: liaison de propriété"}, + {"term": "event listener", "translation": "écouteur d'événements"}, + {"term": "lifecycle hook", "translation": "hook de cycle de vie"}, + {"term": "deferrable views", "translation": "vues différables"}, + {"term": "control flow", "translation": "flux de contrôle"}, + {"term": "route", "translation": "route", "note": "feminine: une route"}, + {"term": "router", "translation": "routeur"}, + {"term": "guard", "translation": "garde", "note": "feminine in this context: une garde de route"}, + {"term": "resolver", "translation": "résolveur"}, + {"term": "input", "translation": "input", "note": "the API (input(), @Input) stays in English; 'entrée' for user input in prose, so not a keep term"}, + {"term": "output", "translation": "output", "note": "the API (output(), @Output) stays in English; 'sortie' in prose when not the API"}, + {"term": "build", "translation": "build", "note": "masculine: le build; 'compiler' or 'construire' as a verb in prose"}, + {"term": "deploy", "translation": "déployer"}, + {"term": "bundle", "translation": "bundle", "note": "masculine: un bundle; 'paquet' is acceptable in prose"} +] diff --git a/tools/test/fixtures/example/site.json b/tools/test/fixtures/example/site.json new file mode 100644 index 0000000..be5849b --- /dev/null +++ b/tools/test/fixtures/example/site.json @@ -0,0 +1,36 @@ +{ + "$schema": "../../../site.schema.json", + "lang": "fr", + "name": "Français (exemple)", + "englishName": "French (template example)", + "direction": "ltr", + "domain": "example.invalid", + "upstreamSite": "https://angular.dev", + "repo": { + "owner": "openng-org", + "name": "angular-docs-rosetta", + "branch": "main" + }, + "firebase": { + "projectId": "rosetta-example", + "target": "docs-example" + }, + "search": { + "provider": "none" + }, + "analytics": { + "provider": "none" + }, + "community": { + "chat": "", + "maintainers": [] + }, + "notice": "Traduction communautaire de angular.dev, non affiliée à Google.", + "strings": { + "readInEnglish": "Lire cette page en anglais", + "otherLanguages": "Autres langues", + "outdatedBanner": "Cette traduction est en retard sur la page anglaise ; certains passages peuvent être obsolètes.", + "untranslatedBanner": "Cette page n'est pas encore traduite ; elle est affichée en anglais.", + "reportIssue": "Signaler un problème de traduction" + } +} diff --git a/tools/test/helpers.mjs b/tools/test/helpers.mjs index 0b45b6d..0ff6606 100644 --- a/tools/test/helpers.mjs +++ b/tools/test/helpers.mjs @@ -66,7 +66,9 @@ export async function makeRepo({example = true, git = false, origin = false} = { await mkdir(path.join(root, '.github', 'workflows'), {recursive: true}); await writeFile(path.join(root, '.github', 'workflows', 'template-canary.yml'), 'name: canary\n'); if (example) { - const from = path.join(packageRoot, 'i18n', '_example'); + // A frozen copy of the template's example language: the suite must pass in repositories where + // `create-language --remove-example` deleted i18n/_example. + const from = path.join(fixturesDir, 'example'); const to = path.join(root, 'i18n', '_example'); await mkdir(path.join(to, 'src'), {recursive: true}); for (const f of ['site.json', 'LANGUAGE.md', 'glossary.json', 'README.md']) await cp(path.join(from, f), path.join(to, f)); diff --git a/tools/test/scripts.test.mjs b/tools/test/scripts.test.mjs index ad853e4..e288495 100644 --- a/tools/test/scripts.test.mjs +++ b/tools/test/scripts.test.mjs @@ -44,3 +44,14 @@ describe('package.json scripts', () => { assert.deepEqual(aliases.sort(), subcommands.map(([, name]) => name).sort()); }); }); + +describe('test independence', () => { + test("no test reads the repository's own i18n/ (instances delete i18n/_example)", async () => { + const {readdir} = await import('node:fs/promises'); + const dir = path.join(packageRoot, 'tools', 'test'); + for (const f of (await readdir(dir)).filter((n) => n.endsWith('.mjs'))) { + const src = await read(path.join(dir, f)); + assert.ok(!/packageRoot,\s*'i18n'/.test(src), `${f} reads packageRoot/i18n: use tools/test/fixtures instead`); + } + }); +});