Skip to content

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

13.7 KB
Raw Blame
// Golden-file harness for the archify renderers. No test framework needed:
// renderers are deterministic, so fresh renders must match both checked-in
// development and packaged example HTML aside from platform checkout line endings. Also covers schema enforcement (negative cases),
// template freshness of the architecture-mode example, and version sync.
//
// Run from the repository root: 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, '..', 'archify');
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'] });
}

function normalizeNewlines(text) {
  return text.replace(/\r\n?/g, '\n');
}

function shieldsBadgeMessages(source, label) {
  const marker = `/badge/${label}-`;
  const messages = [];
  let searchFrom = 0;
  while (searchFrom < source.length) {
    const start = source.indexOf(marker, searchFrom);
    if (start === -1) break;
    let cursor = start + marker.length;
    let message = '';
    while (cursor < source.length) {
      const character = source[cursor];
      const next = source[cursor + 1];
      if (character === '-' && next === '-') {
        message += '-';
        cursor += 2;
      } else if (character === '_' && next === '_') {
        message += '_';
        cursor += 2;
      } else if (character === '-') {
        break;
      } else {
        message += character;
        cursor += 1;
      }
    }
    try { messages.push(decodeURIComponent(message)); } catch { messages.push(message); }
    searchFrom = cursor + 1;
  }
  return messages;
}

// ---------------------------------------------------------------------------
console.log('golden renders (renderer output must 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'],
  ['erd', 'orders.erd.json', 'erd-orders-rendered.html'],
  ['erd', 'subscription-billing.erd.json', 'subscription-billing-rendered.html'],
  ['tree', 'payment-platform.tree.json', 'tree-payment-platform-rendered.html'],
  ['tree', 'archify-repository.tree.json', 'tree-archify-repository-rendered.html'],
  ['class', 'payments.class.json', 'class-payments-rendered.html'],
  ['class', 'payment-processors.class.json', 'class-payment-processors-rendered.html'],
  ['timeline', 'payment-incident.timeline.json', 'timeline-payment-incident-rendered.html'],
  ['timeline', 'archify-dev-activity.timeline.json', 'timeline-archify-dev-activity-rendered.html'],
  ['waterfall', 'checkout-request.waterfall.json', 'waterfall-checkout-request-rendered.html'],
  ['waterfall', 'example-rebuild.waterfall.json', 'waterfall-example-rebuild-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');
    const packaged = fs.readFileSync(path.join(skillRoot, 'examples', golden), 'utf8');
    check(`${mode}: ${golden}`, normalizeNewlines(fresh) === normalizeNewlines(checked),
      `fresh render differs from examples/${golden}; if the change is intentional, re-render the examples and commit them`);
    check(`${mode}: packaged ${golden}`, normalizeNewlines(fresh) === normalizeNewlines(packaged),
      `fresh render differs from archify/examples/${golden}; re-render the packaged examples and rebuild archify.zip`);
  } 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');
{
  // Schema 1/2 files may still carry retired guided views: accept, ignore.
  const d = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', GOLDEN.find(([m]) => m === 'workflow')[1]), 'utf8'));
  d.meta.views = [{ id: 'v', label: 'Legacy view', focus: [d.nodes[0].id] }];
  const input = path.join(tmp, 'legacy-views.json');
  const out = path.join(tmp, 'legacy-views.html');
  fs.writeFileSync(input, JSON.stringify(d));
  let html = '';
  try { render('workflow', input, out); html = fs.readFileSync(out, 'utf8'); } catch (_) {}
  check('legacy meta.views accepted and ignored', html && !html.includes('Legacy view'),
    'a file with meta.views must still render, without guided-view UI');
}
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('main-path step without a transition', 'lifecycle',
  (d) => { d.transitions = d.transitions.filter((t) => !(t.from === 'queued' && t.to === 'planning')); },
  'mainPath step "queued" -> "planning" has no transition');
expectFailure('zero component width rejected by schema', 'architecture',
  (d) => { d.components[0].size = [0, 60]; }, '/components/0/size/0');
expectFailure('zero component height rejected by schema', 'architecture',
  (d) => { d.components[0].size = [120, 0]; }, '/components/0/size/1');
expectFailure('negative component width rejected by schema', 'architecture',
  (d) => { d.components[0].size = [-1, 60]; }, '/components/0/size/0');
expectFailure('unknown attribute key rejected by schema', 'erd',
  (d) => { d.entities[0].attributes[0].key = 'super'; }, '/entities/0/attributes/0/key');
expectFailure('key role outside the list enum rejected by schema', 'erd',
  (d) => { d.entities[0].attributes[0].key = ['pk', 'super']; }, '/entities/0/attributes/0/key');
expectFailure('fk role inside a key list without a target rejected by schema', 'erd',
  (d) => { d.entities[0].attributes[0].key = ['fk', 'pk']; }, "must have required property 'references'");
expectFailure('identifying false with a contradicting variant rejected by schema', 'erd',
  (d) => {
    d.relationships[0].identifying = false;
    d.relationships[0].variant = 'emphasis';
  }, '/relationships/0/variant');
expectFailure('entity without a label rejected by schema', 'erd',
  (d) => { delete d.entities[0].label; }, '/entities/0');
expectFailure('unknown relationship cardinality rejected by schema', 'erd',
  (d) => { d.relationships[0].toCardinality = 'several'; }, '/relationships/0/toCardinality');
expectFailure('unstated relationship cardinality rejected by schema', 'erd',
  (d) => { delete d.relationships[0].fromCardinality; }, '/relationships/0');
expectFailure('fk attribute without a target rejected by schema', 'erd',
  (d) => {
    const fk = d.entities.flatMap((entity) => entity.attributes).find((attribute) => attribute.key === 'fk');
    delete fk.references;
  }, "must have required property 'references'");
expectFailure('tree node without a label rejected by schema', 'tree',
  (d) => { delete d.nodes[1].label; }, '/nodes/1');
expectFailure('unknown tree direction rejected by schema', 'tree',
  (d) => { d.layout = { direction: 'up' }; }, '/layout/direction');
expectFailure('type without a kind rejected by schema', 'class',
  (d) => { delete d.types[0].kind; }, '/types/0');
expectFailure('unknown relationship kind rejected by schema', 'class',
  (d) => { d.relationships[0].kind = 'uses'; }, '/relationships/0/kind');
expectFailure('unknown member visibility rejected by schema', 'class',
  (d) => { d.types[0].methods[0].visibility = 'internal'; }, '/types/0/methods/0/visibility');
expectFailure('timeline timestamp without an offset rejected by schema', 'timeline',
  (d) => { d.events[0].at = '2026-10-01T10:00:00'; }, '/events/0/at');
expectFailure('timeline without evidence status rejected by schema', 'timeline',
  (d) => { delete d.meta.evidence; }, "must have required property 'evidence'");
expectFailure('negative span start rejected by schema', 'waterfall',
  (d) => { d.spans[0].start = -1; }, '/spans/0/start');
expectFailure('waterfall without evidence status rejected by schema', 'waterfall',
  (d) => { delete d.meta.evidence; }, "must have required property 'evidence'");
expectFailure('references outside entity.attribute rejected by schema', 'erd',
  (d) => {
    const fk = d.entities.flatMap((entity) => entity.attributes).find((attribute) => attribute.key === 'fk');
    fk.references = 'product';
  }, 'pattern');

// ---------------------------------------------------------------------------
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');
// Viewer styles in the document head and executable scripts pass through
// applyTemplate untouched. Renderer-owned SVG styles are covered by golden renders.
for (const tag of ['style', 'script']) {
  // The guided-view JSON script is generated from meta.views; compare only
  // template-owned executable scripts, not per-diagram data payloads.
  const isTemplateOwned = (block) => !block.includes('type="application/json"');
  const t = blocks(template, tag).filter((b) => !b.includes('[PROJECT NAME]') && isTemplateOwned(b));
  const viewerHtml = tag === 'style' ? webApp.slice(0, webApp.indexOf('</head>')) : webApp;
  const w = blocks(viewerHtml, tag).filter((b) => !b.includes('Sample Web App') && isTemplateOwned(b));
  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];
const packageMajorMinor = pkg.version.match(/^(\d+\.\d+)\./)?.[1];
check('SKILL.md metadata version matches package.json major.minor',
  !!packageMajorMinor && skillVersion === packageMajorMinor,
  `SKILL.md says ${skillVersion}, package.json says ${pkg.version}`);

for (const readmeName of ['README.md', 'README_EN.md', 'README_ZH.md', 'README_JA.md']) {
  const readme = fs.readFileSync(path.join(repoRoot, readmeName), 'utf8');
  const badgeVersions = shieldsBadgeMessages(readme, 'version');
  check(`${readmeName} badge matches package.json version`,
    badgeVersions.length > 0 && badgeVersions.every((version) => version === pkg.version),
    `${readmeName} badge says ${[...new Set(badgeVersions)].join(', ') || '(missing)'} instead of ${pkg.version}`);
}

const landingPage = fs.readFileSync(path.join(repoRoot, 'docs/index.html'), 'utf8');
const landingVersions = [...landingPage.matchAll(/\bv\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\b/g)]
  .map((match) => match[0]);
check('GitHub Pages version labels match package.json',
  landingVersions.length > 0 && landingVersions.every((v) => v === `v${pkg.version}`),
  `landing page says ${[...new Set(landingVersions)].join(', ') || '(no 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');