From c63e011d2fc117d8a61d66c1fdfa5355ab1f9034 Mon Sep 17 00:00:00 2001 From: adamXbot <111877622+adamXbot@users.noreply.github.com> Date: Fri, 30 Oct 2026 16:32:52 +1100 Subject: [PATCH] Include new generated files in documentation refresh checks --- .github/workflows/refresh-docs.yml | 10 ++-- scripts/refresh-changes.mjs | 33 ++++++++++++ tests/refresh-changes.test.mjs | 85 ++++++++++++++++++++++++++++++ 3 files changed, 121 insertions(+), 7 deletions(-) create mode 100644 scripts/refresh-changes.mjs create mode 100644 tests/refresh-changes.test.mjs diff --git a/.github/workflows/refresh-docs.yml b/.github/workflows/refresh-docs.yml index 6f2e771..65019b3 100644 --- a/.github/workflows/refresh-docs.yml +++ b/.github/workflows/refresh-docs.yml @@ -73,12 +73,8 @@ jobs: version=$(cat content/source/version.txt) echo "version=$version" >> "$GITHUB_OUTPUT" echo "main=$(git -C main-checkout rev-parse --short HEAD)" >> "$GITHUB_OUTPUT" - outside=$(git diff --name-only -- . ':!content' ':!public/assets/icon.png' ':!public/search') - if [ -n "$outside" ]; then - echo "::error::npm run content changed files it should not: $outside" - exit 1 - fi - if git diff --quiet -- content public/assets/icon.png public/search; then + changes=$(node scripts/refresh-changes.mjs) + if [ "$changes" = unchanged ]; then echo "::notice title=Documentation already current::It matches main's README and fxcss $version." echo "publish=no" >> "$GITHUB_OUTPUT" exit 0 @@ -89,7 +85,7 @@ jobs: echo "publish=no" >> "$GITHUB_OUTPUT" exit 0 fi - if git diff --quiet -- content/source/version.txt; then + if [ "$changes" = content ]; then echo "message=Refresh the documentation from main" >> "$GITHUB_OUTPUT" else echo "message=Update the documentation to fxcss $version" >> "$GITHUB_OUTPUT" diff --git a/scripts/refresh-changes.mjs b/scripts/refresh-changes.mjs new file mode 100644 index 0000000..f1ef58c --- /dev/null +++ b/scripts/refresh-changes.mjs @@ -0,0 +1,33 @@ +import { execFileSync } from 'node:child_process'; +import { pathToFileURL } from 'node:url'; + +// Include staged, unstaged and untracked output. NUL delimiters preserve paths +// with whitespace and Git's --no-renames exposes both sides of a move. +export function refreshChangeKind(cwd = process.cwd()) { + const paths = new Set([ + ...gitPaths(['diff', '--name-only', '--no-renames', '-z', 'HEAD', '--'], cwd), + ...gitPaths(['ls-files', '--others', '--exclude-standard', '-z'], cwd), + ].filter((file) => !file.startsWith('main-checkout/'))); + const outside = [...paths].filter((file) => !( + file.startsWith('content/') || file === 'public/assets/icon.png' || + file.startsWith('public/search/') + )); + if (outside.length) { + throw new Error(`Documentation generation changed unexpected files: ${JSON.stringify(outside)}`); + } + if (paths.size === 0) return 'unchanged'; + return paths.has('content/source/version.txt') ? 'version' : 'content'; +} + +function gitPaths(args, cwd) { + return execFileSync('git', args, { cwd, encoding: 'utf8' }).split('\0').filter(Boolean); +} + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + try { + console.log(refreshChangeKind()); + } catch (error) { + console.error(error.message); + process.exitCode = 1; + } +} diff --git a/tests/refresh-changes.test.mjs b/tests/refresh-changes.test.mjs new file mode 100644 index 0000000..a3e5008 --- /dev/null +++ b/tests/refresh-changes.test.mjs @@ -0,0 +1,85 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { execFileSync, spawnSync } from 'node:child_process'; +import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { refreshChangeKind } from '../scripts/refresh-changes.mjs'; + +function repo(t) { + const root = mkdtempSync(path.join(tmpdir(), 'fxcss-refresh-')); + t.after(() => rmSync(root, { recursive: true, force: true })); + const git = (...args) => execFileSync('git', args, { cwd: root, stdio: 'pipe' }); + const write = (name, value = 'new') => { + mkdirSync(path.dirname(path.join(root, name)), { recursive: true }); + writeFileSync(path.join(root, name), value); + }; + git('init'); + write('content/source/version.txt', '0.25.0'); + write('public/search/old.json', '{}'); + write('.gitignore', '/node_modules/\n'); + git('add', '.'); + git('-c', 'user.name=Test', '-c', 'user.email=test@example.invalid', 'commit', '-m', 'fixture'); + return { root, git, write }; +} + +test('new search output alone requires publication', (t) => { + const { root, git, write } = repo(t); + write('public/search/new-hash.json'); + git('diff', '--quiet'); // The old tracked-only gate misses this change. + assert.equal(refreshChangeKind(root), 'content'); +}); + +test('new source/version output and staged edits are recognized', (t) => { + const { root, git, write } = repo(t); + write('content/source/version.txt', '0.26.0'); + git('add', 'content/source/version.txt'); + assert.equal(refreshChangeKind(root), 'version'); +}); + +test('tracked edits and deletions require publication', (t) => { + const { root, write } = repo(t); + write('public/search/old.json', '{"new":true}'); + assert.equal(refreshChangeKind(root), 'content'); + rmSync(path.join(root, 'public/search/old.json')); + assert.equal(refreshChangeKind(root), 'content'); +}); + +test('unexpected untracked paths fail, including paths with line breaks', (t) => { + const { root, write } = repo(t); + write('unexpected\nfile.txt'); + assert.throws(() => refreshChangeKind(root), /unexpected\\nfile\.txt/); + const script = fileURLToPath(new URL('../scripts/refresh-changes.mjs', import.meta.url)); + const result = spawnSync(process.execPath, [script], { cwd: root, encoding: 'utf8' }); + assert.equal(result.status, 1); + assert.equal(result.stdout, ''); +}); + +test('a staged move outside permitted output is rejected', (t) => { + const { root, git } = repo(t); + git('mv', 'public/search/old.json', 'unexpected.json'); + assert.throws(() => refreshChangeKind(root), /unexpected\.json/); +}); + +test('auxiliary checkout and ignored dependencies do not trigger publication', (t) => { + const { root, write } = repo(t); + write('main-checkout/README.md'); + write('node_modules/example/index.js'); + assert.equal(refreshChangeKind(root), 'unchanged'); +}); + +test('similar-looking directories do not bypass the output boundary', (t) => { + const { root, write } = repo(t); + write('main-checkout-elsewhere/file'); + write('public/search-unexpected/file'); + assert.throws(() => refreshChangeKind(root), /unexpected/); +}); + +test('refresh workflow uses the shared classifier for both publication decisions', () => { + const workflow = readFileSync(new URL('../.github/workflows/refresh-docs.yml', import.meta.url), 'utf8'); + assert.ok(workflow.includes('changes=$(node scripts/refresh-changes.mjs)')); + assert.ok(workflow.includes('if [ "$changes" = unchanged ]; then')); + assert.ok(workflow.includes('if [ "$changes" = content ]; then')); + assert.ok(!workflow.includes('git diff --quiet -- content')); +});