Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
ci: add conservative README-only fast path (#490)
tt-a1i1aa1db9f9c32
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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-lateststrategy: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: npmcache-dependency-path: archify/package-lock.json- name: Install renderer dependencies+ if: needs.scope.outputs.scope == 'full'run: npm ciworking-directory: archify- name: Golden-file + schema tests+ if: needs.scope.outputs.scope == 'full'run: npm testworking-directory: archifywebm-artifact:+ needs: scope+ if: always() && !cancelled()runs-on: ubuntu-lateststeps:+ # 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-chromeuses: browser-actions/setup-chrome@v2with:chrome-version: stableinstall-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:webmworking-directory: archifyenv: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.mjsworking-directory: archifyenv: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.mjsworking-directory: archifyenv: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-fundworking-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.mjsworking-directory: archifyenv: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.mjsworking-directory: archifyenv: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.mjsworking-directory: archifyenv: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.mjsworking-directory: archifyenv:@@ -86,13 +150,27 @@ jobs:ARCHIFY_CHROME_NO_SANDBOX: '1'zip-freshness:+ needs: scope+ if: always() && !cancelled()runs-on: ubuntu-lateststeps:+ # 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.zipif ! cmp -s /tmp/fresh.zip archify.zip; then@@ -101,13 +179,27 @@ jobs:fipublished-update-manifest:+ needs: scope+ if: always() && !cancelled()runs-on: ubuntu-lateststeps:+ # 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:fipackage-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 pipefailpackage_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: pwshrun: |$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.mjsdeploy-pages:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 84585f71..d26cfbdc 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -39,6 +39,12 @@ Skill instructions, authored examples, build inputs, and generated-site sourcesStart 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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`);+}