Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

ci: add conservative README-only fast path (#490)

tt-a1i1aa1db9f9c32
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 368c2888..9668c79f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -5,80 +5,144 @@ on:
branches: [main]
pull_request:
+# Cancel obsolete PR runs, but never interrupt main verification/deployment.
+concurrency:
+ group: ci-${{ github.event.pull_request.number || github.run_id }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
jobs:
+ scope:
+ runs-on: ubuntu-latest
+ outputs:
+ scope: ${{ steps.classify.outputs.scope }}
+ steps:
+ - uses: actions/checkout@v5
+ with:
+ fetch-depth: 0
+ - uses: actions/setup-node@v5
+ with:
+ node-version: 22
+ - name: Classify changed paths
+ id: classify
+ run: node scripts/ci-scope.mjs
+ env:
+ CI_EVENT_NAME: ${{ github.event_name }}
+ CI_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ - name: Check README content for documentation-only changes
+ if: steps.classify.outputs.scope == 'docs'
+ run: node --test archify/test/readme-showcase.test.mjs
+
test:
+ needs: scope
+ if: always() && !cancelled()
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22, 24]
steps:
+ # Keep every required matrix check present; fail closed if classification/checks fail.
+ - name: Require successful scope checks
+ env:
+ SCOPE_RESULT: ${{ needs.scope.result }}
+ CI_SCOPE: ${{ needs.scope.outputs.scope }}
+ shell: bash
+ run: |
+ test "$SCOPE_RESULT" = success
+ case "$CI_SCOPE" in docs|full) ;; *) exit 1 ;; esac
- uses: actions/checkout@v5
+ if: needs.scope.outputs.scope == 'full'
- uses: actions/setup-node@v5
+ if: needs.scope.outputs.scope == 'full'
with:
node-version: ${{ matrix.node-version }}
cache: npm
cache-dependency-path: archify/package-lock.json
- name: Install renderer dependencies
+ if: needs.scope.outputs.scope == 'full'
run: npm ci
working-directory: archify
- name: Golden-file + schema tests
+ if: needs.scope.outputs.scope == 'full'
run: npm test
working-directory: archify
webm-artifact:
+ needs: scope
+ if: always() && !cancelled()
runs-on: ubuntu-latest
steps:
+ # Keep every required matrix check present; fail closed if classification/checks fail.
+ - name: Require successful scope checks
+ env:
+ SCOPE_RESULT: ${{ needs.scope.result }}
+ CI_SCOPE: ${{ needs.scope.outputs.scope }}
+ shell: bash
+ run: |
+ test "$SCOPE_RESULT" = success
+ case "$CI_SCOPE" in docs|full) ;; *) exit 1 ;; esac
- uses: actions/checkout@v5
+ if: needs.scope.outputs.scope == 'full'
- uses: actions/setup-node@v5
+ if: needs.scope.outputs.scope == 'full'
with:
node-version: 22
- name: Provision a known Chrome runtime
+ if: needs.scope.outputs.scope == 'full'
id: setup-chrome
uses: browser-actions/setup-chrome@v2
with:
chrome-version: stable
install-dependencies: true
- name: Install the WebM decoder
+ if: needs.scope.outputs.scope == 'full'
run: sudo apt-get update && sudo apt-get install --no-install-recommends -y ffmpeg
- name: Decode a real motion export and reject static frames
+ if: needs.scope.outputs.scope == 'full'
run: npm run test:webm
working-directory: archify
env:
ARCHIFY_CHROME: ${{ steps.setup-chrome.outputs.chrome-path }}
- name: Verify packaged examples and Reader Layout boundaries in a real browser
+ if: needs.scope.outputs.scope == 'full'
run: node --test test/desktop-reader-browser.test.mjs test/reader-layout-browser.test.mjs
working-directory: archify
env:
ARCHIFY_CHROME: ${{ steps.setup-chrome.outputs.chrome-path }}
ARCHIFY_CHROME_NO_SANDBOX: '1'
- name: Verify SVG export cleanup and live state isolation
+ if: needs.scope.outputs.scope == 'full'
run: node --test test/export-cleanup-browser.test.mjs
working-directory: archify
env:
ARCHIFY_CHROME: ${{ steps.setup-chrome.outputs.chrome-path }}
ARCHIFY_CHROME_NO_SANDBOX: '1'
- name: Install offline font test parser
+ if: needs.scope.outputs.scope == 'full'
run: npm ci --ignore-scripts --no-audit --no-fund
working-directory: archify
- name: Verify offline fonts and independent SVG/raster exports
+ if: needs.scope.outputs.scope == 'full'
run: node --test test/offline-font-browser.test.mjs
working-directory: archify
env:
ARCHIFY_CHROME: ${{ steps.setup-chrome.outputs.chrome-path }}
ARCHIFY_CHROME_NO_SANDBOX: '1'
- name: Verify all five diagram modes localize Viewer interactions
+ if: needs.scope.outputs.scope == 'full'
run: node --test test/i18n.test.mjs
working-directory: archify
env:
ARCHIFY_CHROME: ${{ steps.setup-chrome.outputs.chrome-path }}
ARCHIFY_CHROME_NO_SANDBOX: '1'
- name: Verify Semantic Radar collision and drag behavior
+ if: needs.scope.outputs.scope == 'full'
run: node --test test/semantic-radar.test.mjs
working-directory: archify
env:
ARCHIFY_CHROME: ${{ steps.setup-chrome.outputs.chrome-path }}
ARCHIFY_CHROME_NO_SANDBOX: '1'
- name: Verify Viewer chrome, camera, motion and input interactions
+ if: needs.scope.outputs.scope == 'full'
run: node --test --test-concurrency=2 test/viewer-chrome-layout.test.mjs test/viewer-camera-browser.test.mjs test/motion-governor-browser.test.mjs test/finder-browser.test.mjs test/intent-trace-browser.test.mjs test/semantic-lens-browser.test.mjs test/route-probe-browser.test.mjs test/guided-views-browser.test.mjs test/focus-browser.test.mjs test/export-browser.test.mjs test/viewer-identifiers-browser.test.mjs
working-directory: archify
env:
@@ -86,13 +150,27 @@ jobs:
ARCHIFY_CHROME_NO_SANDBOX: '1'
zip-freshness:
+ needs: scope
+ if: always() && !cancelled()
runs-on: ubuntu-latest
steps:
+ # Keep every required matrix check present; fail closed if classification/checks fail.
+ - name: Require successful scope checks
+ env:
+ SCOPE_RESULT: ${{ needs.scope.result }}
+ CI_SCOPE: ${{ needs.scope.outputs.scope }}
+ shell: bash
+ run: |
+ test "$SCOPE_RESULT" = success
+ case "$CI_SCOPE" in docs|full) ;; *) exit 1 ;; esac
- uses: actions/checkout@v5
+ if: needs.scope.outputs.scope == 'full'
- uses: actions/setup-node@v5
+ if: needs.scope.outputs.scope == 'full'
with:
node-version: 22
- name: Rebuild archify.zip and compare exact bytes
+ if: needs.scope.outputs.scope == 'full'
run: |
scripts/build-zip.sh /tmp/fresh.zip
if ! cmp -s /tmp/fresh.zip archify.zip; then
@@ -101,13 +179,27 @@ jobs:
fi
published-update-manifest:
+ needs: scope
+ if: always() && !cancelled()
runs-on: ubuntu-latest
steps:
+ # Keep every required matrix check present; fail closed if classification/checks fail.
+ - name: Require successful scope checks
+ env:
+ SCOPE_RESULT: ${{ needs.scope.result }}
+ CI_SCOPE: ${{ needs.scope.outputs.scope }}
+ shell: bash
+ run: |
+ test "$SCOPE_RESULT" = success
+ case "$CI_SCOPE" in docs|full) ;; *) exit 1 ;; esac
- uses: actions/checkout@v5
+ if: needs.scope.outputs.scope == 'full'
- uses: actions/setup-node@v5
+ if: needs.scope.outputs.scope == 'full'
with:
node-version: 22
- name: Public notifier manifest must reference an existing stable Release
+ if: needs.scope.outputs.scope == 'full'
env:
GH_TOKEN: ${{ github.token }}
run: |
@@ -156,6 +248,8 @@ jobs:
fi
package-smoke:
+ needs: scope
+ if: always() && !cancelled()
name: package smoke (${{ matrix.os }})
strategy:
fail-fast: false
@@ -163,12 +257,23 @@ jobs:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
+ # Keep every required matrix check present; fail closed if classification/checks fail.
+ - name: Require successful scope checks
+ env:
+ SCOPE_RESULT: ${{ needs.scope.result }}
+ CI_SCOPE: ${{ needs.scope.outputs.scope }}
+ shell: bash
+ run: |
+ test "$SCOPE_RESULT" = success
+ case "$CI_SCOPE" in docs|full) ;; *) exit 1 ;; esac
- uses: actions/checkout@v5
+ if: needs.scope.outputs.scope == 'full'
- uses: actions/setup-node@v5
+ if: needs.scope.outputs.scope == 'full'
with:
node-version: 22
- name: Extract packaged skill
- if: runner.os != 'Windows'
+ if: needs.scope.outputs.scope == 'full' && (runner.os != 'Windows')
run: |
set -euo pipefail
package_root="$RUNNER_TEMP/archify-package"
@@ -176,13 +281,14 @@ jobs:
mkdir -p "$package_root"
unzip -q archify.zip -d "$package_root"
- name: Extract packaged skill
- if: runner.os == 'Windows'
+ if: needs.scope.outputs.scope == 'full' && (runner.os == 'Windows')
shell: pwsh
run: |
$packageRoot = Join-Path $env:RUNNER_TEMP 'archify-package'
if (Test-Path $packageRoot) { Remove-Item -Recurse -Force $packageRoot }
Expand-Archive -Path archify.zip -DestinationPath $packageRoot
- name: Validate packaged skill without installing dependencies
+ if: needs.scope.outputs.scope == 'full'
run: node scripts/package-smoke.mjs
deploy-pages:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 84585f71..d26cfbdc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,6 +39,12 @@ Skill instructions, authored examples, build inputs, and generated-site sources
Start with focused checks for the affected behavior. Use the full `npm test` suite from `archify/` when shared behavior, broad changes, or findings require wider coverage. Final review needs sufficient evidence for the impact above; relevant CI results can supply that coverage without repeating the same run locally. Identify the revision and coverage of reused results, and explain material gaps. Required remote CI and branch protection still apply.
+### Documentation-only CI
+
+Pull requests changing only `README.md`, `README_EN.md`, `README_ZH.md`, or PNG/SVG files directly under `docs/assets/community/` run the existing README checks once on Node 22. Required CI job names remain present, but their unrelated runtime, browser, and package steps do not run. A failed scope classification or README check fails those required jobs.
+
+Any other changed path (including tests, Skill instructions, templates, generated diagrams, dependencies, and workflow configuration) keeps full CI. Empty change sets also use full CI. Pushes to `main` always run the complete suite. New pushes cancel obsolete CI runs for the same PR; main runs are not cancelled.
+
## Product and compatibility contracts
- Existing schema-v1 typed JSON remains valid unless a reviewed change explicitly introduces a breaking rule and migration path.
diff --git a/archify/test/ci-scope.test.mjs b/archify/test/ci-scope.test.mjs
new file mode 100644
index 00000000..363c6606
--- /dev/null
+++ b/archify/test/ci-scope.test.mjs
@@ -0,0 +1,55 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyPaths } from '../../scripts/ci-scope.mjs';
+
+test('community documentation takes the fast path', () => {
+ assert.equal(classifyPaths(['README.md', 'README_EN.md', 'README_ZH.md', 'docs/assets/community/qq.svg', 'docs/assets/community/wechat-qr.png']), 'docs');
+});
+
+test('unknown, mixed, and behavior-bearing changes retain full CI', () => {
+ for (const path of ['archify/SKILL.md', 'archify/assets/template.html', 'archify/test/readme-showcase.test.mjs', '.github/workflows/ci.yml', 'scripts/ci-scope.mjs', 'docs/guide.html', 'docs/assets/community/script.js', 'README-other.md']) {
+ assert.equal(classifyPaths(['README.md', path]), 'full', path);
+ }
+ assert.equal(classifyPaths([]), 'full');
+ // --no-renames reports the old runtime path as well as the new documentation path.
+ assert.equal(classifyPaths(['archify/bin/archify.mjs', 'docs/assets/community/example.svg']), 'full');
+});
+
+// Exercise Git and output handling, not just the path allowlist.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const script = fileURLToPath(new URL('../../scripts/ci-scope.mjs', import.meta.url));
+
+test('scope CLI handles documentation, renames, main pushes, and invalid bases', () => {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-ci-scope-'));
+ try {
+ const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+ git('init', '-q');
+ git('config', 'user.name', 'CI Test');
+ git('config', 'user.email', '[email protected]');
+ fs.writeFileSync(path.join(root, 'README.md'), 'before');
+ fs.writeFileSync(path.join(root, 'runtime.js'), 'runtime');
+ git('add', '.'); git('commit', '-qm', 'base');
+ const base = git('rev-parse', 'HEAD');
+ fs.writeFileSync(path.join(root, 'README.md'), 'after');
+ git('add', '.'); git('commit', '-qm', 'docs');
+ const output = path.join(root, 'output');
+ const run = (event, sha = base) => {
+ fs.writeFileSync(output, '');
+ const result = spawnSync(process.execPath, [script], { cwd: root, env: { ...process.env, CI_EVENT_NAME: event, CI_BASE_SHA: sha, GITHUB_OUTPUT: output } });
+ return { status: result.status, output: fs.readFileSync(output, 'utf8') };
+ };
+ assert.deepEqual(run('pull_request'), { status: 0, output: 'scope=docs\n' });
+ assert.deepEqual(run('push'), { status: 0, output: 'scope=full\n' });
+ assert.notEqual(run('pull_request', 'bad').status, 0);
+ assert.equal(run('pull_request', 'f'.repeat(40)).output, '');
+ git('mv', 'runtime.js', 'README_EN.md');
+ git('commit', '-qm', 'rename runtime into docs');
+ assert.deepEqual(run('pull_request'), { status: 0, output: 'scope=full\n' });
+ } finally {
+ fs.rmSync(root, { recursive: true, force: true });
+ }
+});
diff --git a/scripts/ci-scope.mjs b/scripts/ci-scope.mjs
new file mode 100644
index 00000000..84d48cd6
--- /dev/null
+++ b/scripts/ci-scope.mjs
@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+// Deliberately narrow: unknown paths, test changes, and authoring inputs run full CI.
+export function classifyPaths(paths) {
+ return paths.length > 0 && paths.every(path =>
+ /^(README(?:_EN|_ZH)?\.md|docs\/assets\/community\/[^/]+\.(?:png|svg))$/.test(path)
+ ) ? 'docs' : 'full';
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ let scope = 'full';
+ if (process.env.CI_EVENT_NAME === 'pull_request') {
+ const base = process.env.CI_BASE_SHA;
+ if (!/^[0-9a-f]{40}$/.test(base || '')) throw new Error('Missing or invalid PR base SHA');
+ // Include both sides of renames so a runtime file moved into docs cannot bypass CI.
+ const diff = execFileSync('git', ['diff', '--no-renames', '--name-only', '-z', base, 'HEAD'], { encoding: 'utf8' });
+ scope = classifyPaths(diff.split('\0').filter(Boolean));
+ }
+ console.log(`CI scope: ${scope}`);
+ if (process.env.GITHUB_OUTPUT) fs.appendFileSync(process.env.GITHUB_OUTPUT, `scope=${scope}\n`);
+}