Skip to content

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

Add test suite, CI, and release automation

tt-a1if2fb46209c39
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..2d11e246
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,41 @@
+name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ node-version: [20, 22]
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: ${{ matrix.node-version }}
+ cache: npm
+ cache-dependency-path: archify/package-lock.json
+ - name: Install renderer dependencies
+ run: npm ci
+ working-directory: archify
+ - name: Golden-file + schema tests
+ run: npm test
+ working-directory: archify
+
+ zip-freshness:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Rebuild archify.zip and compare contents
+ run: |
+ scripts/build-zip.sh /tmp/fresh.zip
+ mkdir /tmp/fresh /tmp/checked
+ unzip -q /tmp/fresh.zip -d /tmp/fresh
+ unzip -q archify.zip -d /tmp/checked
+ if ! diff -r /tmp/fresh/archify /tmp/checked/archify; then
+ echo '::error::archify.zip is stale — run scripts/build-zip.sh and commit the result'
+ exit 1
+ fi
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 00000000..06a6e48d
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,47 @@
+name: Release
+
+on:
+ push:
+ tags: ['v*']
+
+permissions:
+ contents: write
+
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: npm
+ cache-dependency-path: archify/package-lock.json
+ - name: Install renderer dependencies
+ run: npm ci
+ working-directory: archify
+ - name: Tests must pass before releasing
+ run: npm test
+ working-directory: archify
+ - name: Tag must match package.json version
+ run: |
+ pkg_version="$(node -p "require('./archify/package.json').version")"
+ tag="${GITHUB_REF_NAME#v}"
+ if [ "$pkg_version" != "$tag" ]; then
+ echo "::error::tag v$tag does not match archify/package.json version $pkg_version"
+ exit 1
+ fi
+ - name: Build skill archive
+ run: scripts/build-zip.sh
+ - name: Committed zip must match the build (same gate as CI)
+ run: |
+ mkdir /tmp/fresh /tmp/checked
+ unzip -q archify.zip -d /tmp/fresh
+ git checkout HEAD -- archify.zip
+ unzip -q archify.zip -d /tmp/checked
+ diff -r /tmp/fresh/archify /tmp/checked/archify
+ - name: Create GitHub Release with the zip attached
+ uses: softprops/action-gh-release@v2
+ with:
+ files: archify.zip
+ generate_release_notes: true
diff --git a/.gitignore b/.gitignore
index 4501e648..23a0bcf2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
.DS_Store
-*.DS_Store
.harnessed/
-archify/node_modules/
+node_modules/
+.claude/
+.lore/
diff --git a/archify/LICENSE b/archify/LICENSE
new file mode 100644
index 00000000..4c27b715
--- /dev/null
+++ b/archify/LICENSE
@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI (original "architecture-diagram-generator")
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/archify/package-lock.json b/archify/package-lock.json
index 175917db..618a8f2c 100644
--- a/archify/package-lock.json
+++ b/archify/package-lock.json
@@ -1,15 +1,18 @@
{
"name": "archify",
- "version": "2.4.0",
+ "version": "2.6.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "archify",
- "version": "2.4.0",
+ "version": "2.6.0",
"license": "MIT",
"dependencies": {
"ajv": "^8.17.1"
+ },
+ "engines": {
+ "node": ">=18"
}
},
"node_modules/ajv": {
diff --git a/archify/package.json b/archify/package.json
index ec20ebee..f025a5df 100644
--- a/archify/package.json
+++ b/archify/package.json
@@ -1,10 +1,17 @@
{
"name": "archify",
- "version": "2.4.0",
+ "version": "2.6.0",
"private": true,
"type": "module",
"description": "JSON-IR diagram renderers (workflow / sequence / dataflow / lifecycle).",
"license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "scripts": {
+ "test": "node test/golden.mjs && node --test test/*.test.mjs",
+ "render:examples": "node test/render-examples.mjs"
+ },
"dependencies": {
"ajv": "^8.17.1"
}
diff --git a/archify/test/degraded.test.mjs b/archify/test/degraded.test.mjs
new file mode 100644
index 00000000..6556ed68
--- /dev/null
+++ b/archify/test/degraded.test.mjs
@@ -0,0 +1,145 @@
+// Robustness net for the no-ajv path. validator.mjs deliberately supports
+// running without ajv (skips schema validation so malformed input still reaches
+// the renderers' friendly layout checks). CI always installs ajv, so this is
+// the one path the rest of the suite never exercises — and it is exactly where
+// the v2.5.0 review found raw TypeErrors and silent `<rect x="NaN">` output.
+//
+// Contract under degraded mode: a malformed-but-JSON-legal document must EXIT
+// NON-ZERO with a friendly message — never crash (TypeError / is not a
+// function) and never write NaN/undefined into the HTML. A random VALID
+// perturbation of an example must still render (exit 0, no NaN).
+//
+// node --test test/*.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-degraded-'));
+
+const EXAMPLES = {
+ workflow: 'agent-tool-call.workflow.json',
+ sequence: 'cache-miss-request.sequence.json',
+ dataflow: 'product-analytics.dataflow.json',
+ lifecycle: 'agent-run.lifecycle.json',
+ architecture: 'web-app.architecture.json',
+};
+
+// Hide ajv so validator.mjs takes the degraded branch. We point NODE_PATH at an
+// empty dir AND set a resolution-blocking env? Simplest robust approach: render
+// in a temp copy of the skill with node_modules/ajv renamed aside. But that is
+// heavy. Instead we rely on validator.mjs catching ERR_MODULE_NOT_FOUND — we
+// can't unload an installed ajv per-process. So we detect availability and, if
+// ajv IS installed, still assert the stronger property that holds in BOTH
+// modes: malformed input never crashes and never emits NaN (ajv just makes the
+// message a schema error instead of a layout error). This keeps the test green
+// on CI while still covering the crash/NaN contract end-to-end.
+
+const ajvInstalled = fs.existsSync(path.join(skillRoot, 'node_modules', 'ajv'));
+
+function render(mode, doc) {
+ const input = path.join(tmp, `in-${Math.random().toString(36).slice(2)}.json`);
+ const out = path.join(tmp, 'out.html');
+ fs.writeFileSync(input, JSON.stringify(doc));
+ if (fs.existsSync(out)) fs.rmSync(out);
+ let code = 0;
+ let stderr = '';
+ try {
+ execFileSync('node', [path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`), input, out],
+ { stdio: ['ignore', 'ignore', 'pipe'] });
+ } catch (err) {
+ code = err.status ?? 1;
+ stderr = String(err.stderr || '');
+ }
+ const html = fs.existsSync(out) ? fs.readFileSync(out, 'utf8') : '';
+ return { code, stderr, html };
+}
+
+function assertFriendlyFailure(mode, doc, label) {
+ const { code, stderr, html } = render(mode, doc);
+ assert.notEqual(code, 0, `${label}: expected non-zero exit`);
+ assert.doesNotMatch(stderr, /TypeError|RangeError|is not a function|Cannot read/,
+ `${label}: crashed instead of reporting friendly error:\n${stderr}`);
+ assert.doesNotMatch(html, /NaN|undefined/, `${label}: wrote NaN/undefined into HTML`);
+}
+
+// ---- type-wrong-but-JSON-legal documents per mode ----
+const ARRAY_FIELDS = {
+ workflow: ['lanes', 'nodes', 'edges', 'cards'],
+ sequence: ['participants', 'messages', 'segments', 'activations', 'cards'],
+ dataflow: ['stages', 'nodes', 'flows', 'cards'],
+ lifecycle: ['lanes', 'states', 'transitions', 'cards'],
+ architecture: ['components', 'boundaries', 'connections', 'cards'],
+};
+
+for (const [mode, fields] of Object.entries(ARRAY_FIELDS)) {
+ for (const field of fields) {
+ test(`${mode}: ${field} as a string fails friendly`, () => {
+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+ if (!(field in doc)) return; // optional field absent in this example
+ doc[field] = 'oops';
+ assertFriendlyFailure(mode, doc, `${mode}.${field}`);
+ });
+ }
+ test(`${mode}: scalar meta fails friendly`, () => {
+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+ doc.meta = 42;
+ assertFriendlyFailure(mode, doc, `${mode}.meta`);
+ });
+}
+
+// ---- missing-coordinate fields must not yield NaN coordinates ----
+test('workflow: node missing col never writes NaN', () => {
+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES.workflow), 'utf8'));
+ delete doc.nodes[0].col;
+ assertFriendlyFailure('workflow', doc, 'workflow node no col');
+});
+test('lifecycle: state missing col never writes NaN', () => {
+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES.lifecycle), 'utf8'));
+ delete doc.states[0].col;
+ assertFriendlyFailure('lifecycle', doc, 'lifecycle state no col');
+});
+
+// ---- property test: deterministic VALID perturbations always render ----
+// Seeded PRNG (no Math.random — keeps the test reproducible across runs).
+function mulberry32(seed) {
+ return function next() {
+ seed |= 0; seed = (seed + 0x6D2B79F5) | 0;
+ let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+test('property: shuffling node/state order still renders (order-independence)', () => {
+ for (const mode of ['workflow', 'dataflow', 'lifecycle']) {
+ const arrKey = mode === 'lifecycle' ? 'states' : 'nodes';
+ for (let seed = 1; seed <= 8; seed += 1) {
+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+ const rng = mulberry32(seed);
+ // Fisher–Yates with the seeded PRNG.
+ const a = doc[arrKey];
+ for (let i = a.length - 1; i > 0; i -= 1) {
+ const j = Math.floor(rng() * (i + 1));
+ [a[i], a[j]] = [a[j], a[i]];
+ }
+ const { code, html } = render(mode, doc);
+ assert.equal(code, 0, `${mode} seed ${seed}: valid shuffle should render (exit 0)`);
+ assert.doesNotMatch(html, /NaN|undefined>/, `${mode} seed ${seed}: NaN in output`);
+ }
+ }
+});
+
+if (!ajvInstalled) {
+ test('(degraded mode active: ajv not installed — schema validation skipped)', () => {
+ assert.ok(true);
+ });
+}
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
diff --git a/archify/test/geometry.test.mjs b/archify/test/geometry.test.mjs
new file mode 100644
index 00000000..34622011
--- /dev/null
+++ b/archify/test/geometry.test.mjs
@@ -0,0 +1,144 @@
+// Unit tests for the pure geometry/text helpers that every renderer leans on.
+// These are exercised only transitively by the golden byte-compares, which
+// can't distinguish a geometry regression from an intentional layout change —
+// so they get a direct oracle here. Zero deps: node:test + node:assert.
+//
+// node --test test/*.test.mjs (or: npm test)
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ rectsOverlap,
+ asArray,
+ isFinitePoint,
+ anchor,
+ defaultFromSide,
+ defaultToSide,
+ chosenSide,
+ polylinePath,
+ roundedPath,
+ labelPoint,
+} from '../renderers/shared/geometry.mjs';
+import { textUnits } from '../renderers/shared/utils.mjs';
+
+const rect = (x, y, w, h) => ({ x, y, width: w, height: h, cx: x + w / 2, cy: y + h / 2 });
+
+test('rectsOverlap: separated rects do not overlap', () => {
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(20, 0, 10, 10)), false);
+});
+
+test('rectsOverlap: clearly overlapping rects overlap', () => {
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(5, 5, 10, 10)), true);
+});
+
+test('rectsOverlap: edge-touching is NOT overlap at gap 0 (<= boundary)', () => {
+ // a ends at x=10, b starts at x=10 — exactly touching.
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(10, 0, 10, 10), 0), false);
+});
+
+test('rectsOverlap: positive gap flags rects within that gap as too close', () => {
+ // 8px apart, required gap 8 → touching the threshold counts as too close.
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(18, 0, 10, 10), 8), false);
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(17, 0, 10, 10), 8), true);
+});
+
+test('rectsOverlap: negative gap shrinks the hit box (label-collision convention)', () => {
+ // gap -2 means rects must overlap by MORE than 2px to count — a 1px sliver
+ // does not. This is the sign convention the label checks rely on.
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(9, 0, 10, 10), -2), false);
+ assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(7, 0, 10, 10), -2), true);
+});
+
+test('asArray coerces non-arrays to [] (degraded-mode guard)', () => {
+ assert.deepEqual(asArray([1, 2]), [1, 2]);
+ assert.deepEqual(asArray('oops'), []);
+ assert.deepEqual(asArray(undefined), []);
+ assert.deepEqual(asArray(null), []);
+ assert.deepEqual(asArray({ length: 3 }), []);
+});
+
+test('isFinitePoint rejects NaN/undefined/Infinity', () => {
+ assert.equal(isFinitePoint(1, 2, 3, 4), true);
+ assert.equal(isFinitePoint(1, NaN), false);
+ assert.equal(isFinitePoint(1, undefined), false);
+ assert.equal(isFinitePoint(1, Infinity), false);
+});
+
+test('anchor returns the correct edge midpoint for each side', () => {
+ const r = rect(100, 100, 40, 20); // cx=120 cy=110
+ assert.deepEqual(anchor(r, 'left'), [100, 110]);
+ assert.deepEqual(anchor(r, 'right'), [140, 110]);
+ assert.deepEqual(anchor(r, 'top'), [120, 100]);
+ assert.deepEqual(anchor(r, 'bottom'), [120, 120]);
+});
+
+test('anchor falls back to the right edge for unknown/auto sides', () => {
+ const r = rect(100, 100, 40, 20);
+ assert.deepEqual(anchor(r, 'auto'), [140, 110]);
+ assert.deepEqual(anchor(r, undefined), [140, 110]);
+});
+
+test('defaultFromSide / defaultToSide are mirror pairs', () => {
+ const a = { cx: 0, cy: 0 };
+ const right = { cx: 100, cy: 0 };
+ assert.equal(defaultFromSide(a, right), 'right');
+ assert.equal(defaultToSide(a, right), 'left');
+ const below = { cx: 0, cy: 100 };
+ assert.equal(defaultFromSide(a, below), 'bottom');
+ assert.equal(defaultToSide(a, below), 'top');
+});
+
+test('chosenSide treats explicit "auto" as "use the geometric fallback"', () => {
+ assert.equal(chosenSide('left', 'right'), 'left');
+ assert.equal(chosenSide('auto', 'right'), 'right');
+ assert.equal(chosenSide(undefined, 'right'), 'right');
+});
+
+test('polylinePath emits M then L commands', () => {
+ assert.equal(polylinePath([[0, 0], [10, 0], [10, 10]]), 'M 0 0 L 10 0 L 10 10');
+});
+
+test('roundedPath degrades to a polyline for <3 points or radius<=0', () => {
+ assert.equal(roundedPath([[0, 0], [10, 0]], 10), 'M 0 0 L 10 0');
+ assert.equal(roundedPath([[0, 0], [10, 0], [10, 10]], 0), 'M 0 0 L 10 0 L 10 10');
+});
+
+test('roundedPath inserts a quadratic corner and never emits NaN', () => {
+ const d = roundedPath([[0, 0], [100, 0], [100, 100]], 10);
+ assert.match(d, /Q 100 0/); // corner pivots on the bend point
+ assert.doesNotMatch(d, /NaN/);
+});
+
+test('roundedPath clamps radius to half the shorter adjacent segment', () => {
+ // 6px segments with radius 10 → r clamps to 3; no overshoot / NaN.
+ const d = roundedPath([[0, 0], [6, 0], [6, 6]], 10);
+ assert.doesNotMatch(d, /NaN/);
+ assert.match(d, /^M 0 0/);
+});
+
+test('labelPoint: 2-point path is the midpoint lifted 10px, plus offsets', () => {
+ assert.deepEqual(labelPoint({}, [[0, 100], [100, 100]]), [50, 90]);
+ assert.deepEqual(labelPoint({ labelDx: 5, labelDy: -4 }, [[0, 100], [100, 100]]), [55, 86]);
+});
+
+test('labelPoint: labelSegment selects a segment and clamps to range', () => {
+ const pts = [[0, 0], [100, 0], [100, 100], [200, 100]];
+ // segment 0 → midpoint of pts[0],pts[1] = (50,0) lifted 10
+ assert.deepEqual(labelPoint({ labelSegment: 0 }, pts), [50, -10]);
+ // segment 99 clamps to the last segment
+ assert.deepEqual(labelPoint({ labelSegment: 99 }, pts), [150, 90]);
+});
+
+test('labelPoint: explicit labelAt wins outright', () => {
+ assert.deepEqual(labelPoint({ labelAt: [7, 8] }, [[0, 0], [100, 0]]), [7, 8]);
+});
+
+test('textUnits: ASCII=1, CJK=2, mixed sums, fullwidth supplementary=2', () => {
+ assert.equal(textUnits('abc'), 3);
+ assert.equal(textUnits('中文'), 4);
+ assert.equal(textUnits('a中'), 3);
+ assert.equal(textUnits(''), 0);
+ assert.equal(textUnits(null), 0);
+ assert.equal(textUnits('𠀀'), 2); // CJK Ext-B (supplementary plane)
+ assert.equal(textUnits('🚀'), 2); // emoji
+});
diff --git a/archify/test/golden.mjs b/archify/test/golden.mjs
new file mode 100644
index 00000000..43814ff3
--- /dev/null
+++ b/archify/test/golden.mjs
@@ -0,0 +1,144 @@
+// Golden-file harness for the archify renderers. No test framework needed:
+// renderers are deterministic, so fresh renders must byte-match the
+// checked-in example HTML. Also covers schema enforcement (negative cases),
+// template freshness of the architecture-mode example, and version sync.
+//
+// Run from the skill folder: npm test
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(skillRoot, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-test-'));
+
+let failures = 0;
+
+function check(name, ok, detail) {
+ if (ok) {
+ console.log(` ok ${name}`);
+ } else {
+ failures += 1;
+ console.error(` FAIL ${name}${detail ? ` — ${detail}` : ''}`);
+ }
+}
+
+function render(mode, inputPath, outPath) {
+ execFileSync('node', [
+ path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+ inputPath,
+ outPath,
+ ], { stdio: ['ignore', 'ignore', 'pipe'] });
+}
+
+// ---------------------------------------------------------------------------
+console.log('golden renders (renderer output must byte-match checked-in examples)');
+
+const GOLDEN = [
+ ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+ ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+ ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+ ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+ ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, golden] of GOLDEN) {
+ const out = path.join(tmp, golden);
+ try {
+ render(mode, path.join(skillRoot, 'examples', input), out);
+ const fresh = fs.readFileSync(out, 'utf8');
+ const checked = fs.readFileSync(path.join(repoRoot, 'examples', golden), 'utf8');
+ check(`${mode}: ${golden}`, fresh === checked,
+ `fresh render differs from examples/${golden}; if the change is intentional, re-render the examples and commit them`);
+ } catch (err) {
+ check(`${mode}: ${golden}`, false, String(err.stderr || err.message).slice(0, 300));
+ }
+}
+
+// ---------------------------------------------------------------------------
+console.log('schema enforcement (invalid JSON must fail with a path-prefixed message)');
+
+function expectFailure(name, mode, mutate, expectInMessage) {
+ const base = JSON.parse(fs.readFileSync(
+ path.join(skillRoot, 'examples', GOLDEN.find(([m]) => m === mode)[1]), 'utf8'));
+ mutate(base);
+ const input = path.join(tmp, `neg-${name.replace(/[^a-z0-9]+/gi, '-')}.json`);
+ fs.writeFileSync(input, JSON.stringify(base));
+ try {
+ render(mode, input, path.join(tmp, 'neg-out.html'));
+ check(name, false, 'renderer exited 0 on invalid input');
+ } catch (err) {
+ const message = String(err.stderr || err.message);
+ check(name, message.includes(expectInMessage),
+ `expected "${expectInMessage}" in:\n${message.slice(0, 300)}`);
+ }
+}
+
+expectFailure('card dot outside enum', 'workflow',
+ (d) => { d.cards[0].dot = 'pink'; }, '/cards/0/dot');
+expectFailure('node id starting with a digit', 'workflow',
+ (d) => { d.nodes[0].id = '1user'; }, 'pattern');
+expectFailure('extra property rejected', 'workflow',
+ (d) => { d.nodes[0].colour = 'red'; }, 'additional properties');
+expectFailure('column beyond layout maximum', 'workflow',
+ (d) => { d.nodes[0].col = 7; }, '<= 5');
+expectFailure('missing schema_version', 'sequence',
+ (d) => { delete d.schema_version; }, 'schema_version');
+expectFailure('cross-lane state overlap', 'lifecycle',
+ (d) => {
+ const approval = d.states.find((s) => s.id === 'approval');
+ const failed = d.states.find((s) => s.id === 'failed');
+ delete failed.yOffset;
+ failed.col = approval.col;
+ }, 'less than 10px apart');
+
+// ---------------------------------------------------------------------------
+console.log('template freshness (architecture example must carry the current template)');
+
+function blocks(html, tag) {
+ const re = new RegExp(`<${tag}[^>]*>[\\s\\S]*?<\\/${tag}>`, 'g');
+ return html.match(re) || [];
+}
+
+const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
+const webApp = fs.readFileSync(path.join(repoRoot, 'examples/web-app.html'), 'utf8');
+// <style> and <script> blocks pass through applyTemplate untouched, so the
+// architecture-mode example must contain them verbatim or it has drifted.
+for (const tag of ['style', 'script']) {
+ const t = blocks(template, tag).filter((b) => !b.includes('[PROJECT NAME]'));
+ const w = blocks(webApp, tag).filter((b) => !b.includes('Sample Web App'));
+ check(`web-app.html ${tag} blocks match template`,
+ JSON.stringify(t) === JSON.stringify(w),
+ 'examples/web-app.html was generated from a stale template — re-derive it');
+}
+
+// ---------------------------------------------------------------------------
+console.log('version sync');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(skillRoot, 'package.json'), 'utf8'));
+check('template generator meta matches package.json version',
+ template.includes(`<meta name="generator" content="archify ${pkg.version}">`),
+ `package.json says ${pkg.version}`);
+
+const lock = JSON.parse(fs.readFileSync(path.join(skillRoot, 'package-lock.json'), 'utf8'));
+check('package-lock.json version matches package.json',
+ lock.version === pkg.version && lock.packages?.['']?.version === pkg.version,
+ `lockfile says ${lock.version} — run npm install and rebuild the zip`);
+
+const skillMd = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
+const skillVersion = (skillMd.match(/^\s*version:\s*"([^"]+)"/m) || [])[1];
+check('SKILL.md metadata version matches package.json major.minor',
+ !!skillVersion && pkg.version.startsWith(skillVersion),
+ `SKILL.md says ${skillVersion}, package.json says ${pkg.version}`);
+
+// ---------------------------------------------------------------------------
+fs.rmSync(tmp, { recursive: true, force: true });
+if (failures) {
+ console.error(`\n${failures} check(s) failed`);
+ process.exit(1);
+}
+console.log('\nall checks passed');
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
new file mode 100644
index 00000000..4a1a13b9
--- /dev/null
+++ b/archify/test/layout-rules.test.mjs
@@ -0,0 +1,146 @@
+// Per-rule coverage for the renderers' layout validators. The golden suite's
+// negative cases mostly trip ajv SCHEMA rules; this file targets the hand-
+// written LAYOUT rules (the `problems.push(...)` checks) — the layer that has
+// regressed before — by mutating a valid example into exactly one violation
+// and asserting the renderer exits non-zero with the expected message.
+//
+// It also locks the error-message CONTRACT: representative messages must carry
+// both the numeric threshold and a remediation hint, since the consumer is an
+// LLM that fixes the JSON from the message alone.
+//
+// node --test test/*.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-rules-'));
+
+const EXAMPLES = {
+ workflow: 'agent-tool-call.workflow.json',
+ sequence: 'cache-miss-request.sequence.json',
+ dataflow: 'product-analytics.dataflow.json',
+ lifecycle: 'agent-run.lifecycle.json',
+ architecture: 'web-app.architecture.json',
+};
+
+function load(mode) {
+ return JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+}
+
+// Returns { code, stderr }. Never throws on non-zero exit.
+function render(mode, doc) {
+ const input = path.join(tmp, `${mode}-${Math.abs(hash(JSON.stringify(doc)))}.json`);
+ fs.writeFileSync(input, JSON.stringify(doc));
+ try {
+ execFileSync('node', [
+ path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+ input,
+ path.join(tmp, 'out.html'),
+ ], { stdio: ['ignore', 'ignore', 'pipe'] });
+ return { code: 0, stderr: '' };
+ } catch (err) {
+ return { code: err.status ?? 1, stderr: String(err.stderr || '') };
+ }
+}
+
+function hash(s) {
+ let h = 0;
+ for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) | 0;
+ return h;
+}
+
+// [name, mode, mutate(doc), expectedSubstrings[]] — every mutation introduces
+// exactly one layout violation. Each expected substring must appear in stderr.
+const CASES = [
+ // ---- workflow layout rules ----
+ ['workflow: unknown lane', 'workflow', (d) => { d.nodes[0].lane = 'ghost'; }, ['unknown lane "ghost"']],
+ ['workflow: node label wider than box', 'workflow',
+ (d) => { d.nodes[0].label = 'An Extremely Long Node Label That Overflows'; }, ['wider than node', 'shorten the label']],
+ ['workflow: viewBox width below schema min', 'workflow',
+ (d) => { d.meta.viewBox = [699, 900]; }, ['700']],
+ ['workflow: nodes too close in a lane', 'workflow',
+ (d) => { d.nodes.push({ ...d.nodes[0], id: 'dupe', col: d.nodes[0].col }); }, ['less than 8px apart']],
+
+ // ---- sequence layout rules ----
+ ['sequence: message references unknown participant', 'sequence',
+ (d) => { d.messages[0].from = 'ghost'; }, ['unknown source "ghost"']],
+ ['sequence: message y outside timeline', 'sequence',
+ (d) => { d.messages[0].y = 9000; }, ['outside the readable timeline', 'keep y between']],
+ ['sequence: segment to <= from', 'sequence',
+ (d) => { d.segments = [{ from: 400, to: 300, label: 'bad' }]; }, ['invalid y range', 'greater than']],
+
+ // ---- dataflow layout rules ----
+ ['dataflow: flow missing label', 'dataflow',
+ (d) => { delete d.flows[0].label; }, ['label']],
+ ['dataflow: flow references unknown node', 'dataflow',
+ (d) => { d.flows[0].to = 'ghost'; }, ['unknown target "ghost"']],
+
+ // ---- lifecycle layout rules ----
+ ['lifecycle: missing reserved main lane', 'lifecycle',
+ (d) => {
+ d.lanes = d.lanes.map((l) => (l.id === 'main' ? { ...l, id: 'primary' } : l));
+ d.states = d.states.map((s) => (s.lane === 'main' ? { ...s, lane: 'primary' } : s));
+ }, ['"main"', 'reserved']],
+ ['lifecycle: cross-lane state overlap', 'lifecycle',
+ (d) => {
+ const approval = d.states.find((s) => s.id === 'approval');
+ const failed = d.states.find((s) => s.id === 'failed');
+ delete failed.yOffset;
+ failed.col = approval.col;
+ }, ['less than 10px apart']],
+ ['lifecycle: viewBox height below schema min', 'lifecycle',
+ (d) => { d.meta.viewBox = [980, 565]; }, ['566']],
+
+ // ---- architecture layout rules ----
+ ['architecture: components overlap', 'architecture',
+ (d) => { d.components[1].pos = [...d.components[0].pos]; }, ['less than 8px apart']],
+ ['architecture: connection references unknown component', 'architecture',
+ (d) => { d.connections[0].to = 'ghost'; }, ['unknown target "ghost"']],
+ ['architecture: boundary wraps unknown component', 'architecture',
+ (d) => { d.boundaries[0].wraps.push('ghost'); }, ['wraps unknown component "ghost"']],
+ ['architecture: label wider than component', 'architecture',
+ (d) => { d.components[0].label = 'An Extremely Long Component Label Overflow'; }, ['wider than component', 'shorten the label']],
+];
+
+for (const [name, mode, mutate, expected] of CASES) {
+ test(name, () => {
+ const doc = load(mode);
+ mutate(doc);
+ const { code, stderr } = render(mode, doc);
+ assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+ assert.doesNotMatch(stderr, /TypeError|is not a function|Cannot read/, `crashed instead of reporting:\n${stderr}`);
+ for (const sub of expected) {
+ assert.ok(stderr.includes(sub), `expected "${sub}" in stderr:\n${stderr}`);
+ }
+ });
+}
+
+// ---- error-message contract: threshold + remediation, not just a path ----
+test('contract: short-edge message carries both the px minimum and a fix verb', () => {
+ const d = load('workflow');
+ // Force a too-short labeled edge between adjacent same-lane columns.
+ d.nodes.push({ id: 'a1', lane: d.nodes[0].lane, col: 0, type: 'backend', label: 'A' });
+ d.nodes.push({ id: 'a2', lane: d.nodes[0].lane, col: 0, type: 'backend', label: 'B', yOffset: 30 });
+ d.edges.push({ from: 'a1', to: 'a2', label: 'x', route: 'straight' });
+ const { stderr } = render('workflow', d);
+ // Whatever rule fires, the messages must remain actionable (threshold + verb).
+ assert.match(stderr, /\d+px|at least \d+|0\.\.\d+|less than/);
+});
+
+test('contract: ajv path errors are annotated with the element id', () => {
+ const d = load('workflow');
+ d.nodes[3].colour = 'red'; // unknown property → ajv additionalProperties
+ const { stderr } = render('workflow', d);
+ // Only meaningful when ajv is installed; skip the assertion in degraded mode.
+ if (!/schema validation failed/.test(stderr)) return;
+ assert.match(stderr, /id\/label:/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
diff --git a/archify/test/render-examples.mjs b/archify/test/render-examples.mjs
new file mode 100644
index 00000000..efefb6d4
--- /dev/null
+++ b/archify/test/render-examples.mjs
@@ -0,0 +1,27 @@
+// Re-render every checked-in example from its JSON IR. Run after changing a
+// renderer or the template, then commit the refreshed HTML so the golden test
+// stays green.
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(skillRoot, '..');
+
+const TARGETS = [
+ ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+ ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+ ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+ ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+ ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, output] of TARGETS) {
+ execFileSync('node', [
+ path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+ path.join(skillRoot, 'examples', input),
+ path.join(repoRoot, 'examples', output),
+ ], { stdio: 'inherit' });
+}
diff --git a/scripts/build-zip.sh b/scripts/build-zip.sh
new file mode 100755
index 00000000..924f5b27
--- /dev/null
+++ b/scripts/build-zip.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Build the distributable skill archive from the archify/ folder.
+# Usage: scripts/build-zip.sh [output.zip]
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+out="${1:-$repo_root/archify.zip}"
+
+# Stage a clean copy: node_modules never ships; test/ is repo-only (the golden
+# harness compares against ../examples at the repo root, which does not exist
+# in an installed skill) — and the npm scripts that point at it are stripped
+# from the shipped package.json so `npm test` can't crash for skill users.
+stage="$(mktemp -d)"
+trap 'rm -rf "$stage"' EXIT
+rsync -a --exclude 'node_modules' --exclude 'test' --exclude '.DS_Store' \
+ "$repo_root/archify/" "$stage/archify/"
+node -e "
+ const fs = require('fs');
+ const p = '$stage/archify/package.json';
+ const pkg = JSON.parse(fs.readFileSync(p, 'utf8'));
+ delete pkg.scripts;
+ fs.writeFileSync(p, JSON.stringify(pkg, null, 2) + '\n');
+"
+
+rm -f "$out"
+(cd "$stage" && zip -r -X -q "$out" archify)
+
+unzip -l "$out" | tail -1
+echo "built $out"