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
Add test suite, CI, and release automation
tt-a1if2fb46209c39
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlnew file mode 100644index 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+ fidiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlnew file mode 100644index 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: truediff --git a/.gitignore b/.gitignoreindex 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/LICENSEnew file mode 100644index 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.jsonindex 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.jsonindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.shnew file mode 100755index 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"