Docs and guard rails: GitHub Pages only, where code goes, updated skills

- docs/adr/0001: GitHub Pages is the only host, not open for renegotiation
- docs/adr/0002: source in many files, shipped as one page assembled at build
- tests/pages.test.js: builds stay static files Pages can serve, all local
  references resolve, only release.yml deploys and only via the Pages actions
- tests/build.test.js: partial naming and layout rules
- new skills: github-pages, edit-the-game; add-strings, performance, release
  and write-tests updated for src/, sorted dictionaries and --base-ref
- CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md (incl. porting older branches),
  README.md and the PR template describe the new layout
This commit is contained in:
Frederic Jung 2026-10-27 10:15:12 +01:00
parent 052fdd713f
commit 05ff4ea7ad
No known key found for this signature in database
15 changed files with 530 additions and 101 deletions

View file

@ -40,3 +40,16 @@ test('a release build refuses to ship without release notes', () => {
assert.throws(() => execFileSync(process.execPath, ['scripts/build.js'], { cwd: root, stdio: 'pipe', env: { ...process.env, OUT, VERSION: '9.9.9', REQUIRE_NOTES: '1' } }));
assert.throws(() => execFileSync(process.execPath, ['scripts/build.js'], { cwd: root, stdio: 'pipe', env: { ...process.env, OUT, VERSION: '1.0; rm -rf /' } }), 'junk versions are rejected');
});
test('src: partials follow the layout rules (docs/adr/0002-one-page-assembled-at-build.md)', () => {
const { listFiles, assemble } = require('../scripts/lib/page');
const src = path.join(root, 'src');
for (const f of listFiles(src)) {
if (f === 'index.html') continue;
assert.match(f, /^(styles\/(\d\d-[a-z0-9-]+\/)*\d\d-[a-z0-9-]+\.css|game\/(\d\d-[a-z0-9-]+\/)*\d\d-[a-z0-9-]+\.js)$/, `${f}: name it NN-lower-case under styles/ or game/`);
}
const { html, map } = assemble();
assert.equal((html.match(/^const ACT=\{$/gm) || []).length, 1, 'ACT is declared once; other action files use Object.assign(ACT,{…})');
assert.equal((html.match(/<script>/g) || []).length, 2, 'the language loader and the game: one inline game script');
assert.ok(map.length > 50 && map.every((m) => m.to >= m.from), 'the line map covers every partial');
});

72
tests/pages.test.js Normal file
View file

@ -0,0 +1,72 @@
// The game is hosted on GitHub Pages and only there (docs/adr/0001-github-pages-only.md). These tests make
// sure every build stays something Pages serves as it is: plain static files, all from one origin.
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { execFileSync } = require('node:child_process');
const root = path.join(__dirname, '..');
const OUT = fs.mkdtempSync(path.join(os.tmpdir(), 'tubes-pages-'));
execFileSync(process.execPath, ['scripts/build.js'], { cwd: root, stdio: 'pipe', env: { ...process.env, OUT, VERSION: '1.2.3', BUILD_DATE: '2026-10-27' } });
const files = (dir, rel = '') => fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).flatMap((e) => {
const r = path.posix.join(rel, e.name);
return e.isDirectory() ? files(dir, r) : [{ r, e }];
});
const built = files(OUT);
const read = (f) => fs.readFileSync(path.join(OUT, f), 'utf8');
// Files that only mean something to other hosts or to a server. On Pages they would be served as plain
// files (or ignored), so their presence means someone is designing for a different host.
const FOREIGN = /(^|\/)(_redirects|_headers|\.htaccess|netlify\.toml|vercel\.json|wrangler\.toml|firebase\.json|staticwebapp\.config\.json|now\.json|app\.yaml|Procfile|Dockerfile|nginx\.conf|server\.js|package\.json)$|\.(php|py|rb|cgi)$/;
test('pages: the build is plain static files within GitHub Pages limits', () => {
let total = 0;
for (const { r, e } of built) {
assert.ok(e.isFile(), `${r} is a regular file (no symlinks)`);
assert.doesNotMatch(r, FOREIGN, `${r} is server or other-host configuration`);
const size = fs.statSync(path.join(OUT, r)).size;
assert.ok(size < 100e6, `${r} is under the 100 MB file limit`);
total += size;
}
assert.ok(total < 1e9, 'the site is under the 1 GB limit');
for (const f of ['index.html', '404.html', 'CNAME', 'version.json', 'sw.js']) assert.ok(fs.existsSync(path.join(OUT, f)), `${f} is shipped`);
assert.equal(read('CNAME').trim(), 'seriesoftub.es');
});
test('pages: the repository has no hosting configuration for anywhere else', () => {
for (const f of fs.readdirSync(root)) assert.doesNotMatch(f, /^(netlify\.toml|vercel\.json|wrangler\.toml|firebase\.json|staticwebapp\.config\.json|now\.json|app\.yaml|Procfile|Dockerfile|_redirects|_headers)$/, `${f} configures another host`);
});
test('pages: every local file the site refers to is in the build', () => {
const html = read('index.html');
const refs = new Set();
for (const m of html.matchAll(/\b(?:src|href)="([^"]+)"/g)) refs.add(m[1]);
for (const m of read('sw.js').matchAll(/'(\/[^']*)'/g)) refs.add(m[1]);
for (const i of JSON.parse(read('site.webmanifest')).icons || []) refs.add(i.src);
const local = [...refs].filter((u) => !/^(https?:|data:|mailto:|#|\$\{|javascript:)/.test(u) && !u.includes('${') && !u.includes("'+"));
assert.ok(local.length >= 5, 'found the local references');
for (const u of local) {
const p = u.split(/[?#]/)[0].replace(/^\//, '') || 'index.html';
assert.ok(fs.existsSync(path.join(OUT, p)), `${u} resolves inside the build`);
}
// Same origin for code: the only scripts from elsewhere are the analytics counter, and no stylesheets
// but the web fonts (see the ADR).
for (const m of html.matchAll(/<script[^>]*\bsrc="(https?:[^"]+)"/g)) assert.fail(`page loads a script from ${m[1]}`);
for (const m of html.matchAll(/<link[^>]*rel="stylesheet"[^>]*href="(https?:[^"]+)"/g)) assert.match(m[1], /^https:\/\/fonts\.googleapis\.com\//);
});
test('pages: only the release workflow deploys, and only with the GitHub Pages actions', () => {
const dir = path.join(root, '.github', 'workflows');
for (const f of fs.readdirSync(dir)) {
const y = fs.readFileSync(path.join(dir, f), 'utf8');
assert.doesNotMatch(y, /netlify|vercel|wrangler|cloudflare\/pages-action|firebase deploy|surge\.sh|peaceiris\/actions-gh-pages|aws s3 sync|rsync /i, `${f} deploys somewhere other than GitHub Pages`);
if (f !== 'release.yml') assert.doesNotMatch(y, /pages:\s*write|deploy-pages/, `${f} must not deploy`);
}
const rel = fs.readFileSync(path.join(dir, 'release.yml'), 'utf8');
assert.match(rel, /actions\/upload-pages-artifact@/);
assert.match(rel, /actions\/deploy-pages@/);
assert.match(rel, /path: \.\/_site/);
});