Skip to content

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

12.8 KB
Raw Blame
import test from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { parse } from 'parse5';

const skillRoot = fileURLToPath(new URL('../archify/', import.meta.url));
const cli = path.join(skillRoot, 'bin/archify.mjs');
const examples = [
  ['architecture', 'web-app.architecture.json', 'components'],
  ['workflow', 'agent-tool-call.workflow.json', 'nodes'],
  ['sequence', 'cache-miss-request.sequence.json', 'participants'],
  ['dataflow', 'product-analytics.dataflow.json', 'nodes'],
  ['lifecycle', 'agent-run.lifecycle.json', 'states'],
  ['erd', 'orders.erd.json', 'entities'],
  ['tree', 'payment-platform.tree.json', 'nodes'],
  ['class', 'payments.class.json', 'types'],
  ['timeline', 'payment-incident.timeline.json', 'events'],
  ['waterfall', 'checkout-request.waterfall.json', 'spans'],
  ['explainer', 'delivery.explainer.json', 'panels'],
];

function identity(file) {
  const bytes = fs.readFileSync(file);
  return { sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length };
}

function descendants(node) {
  return [node, ...(node.childNodes || []).flatMap(descendants)];
}

function attribute(node, name) {
  return node.attrs?.find((entry) => entry.name === name)?.value;
}

function assertDiagram(output, document, collection) {
  const elements = descendants(parse(fs.readFileSync(output, 'utf8')));
  if (document.diagram_type === 'explainer') {
    const answer = elements.find((node) => attribute(node, 'id') === 'answer');
    assert.ok(answer, 'the explainer must contain its initial answer without JavaScript');
    const text = descendants(answer).filter((node) => node.nodeName === '#text').map((node) => node.value).join('');
    assert.ok(text.includes(document.answer.summary.replaceAll('**', '')), 'the authored answer must remain readable in the HTML');
    for (const panel of document.panels) {
      assert.ok(elements.some((node) => attribute(node, 'id') === panel.id), `missing authored explainer panel ${panel.id}`);
    }
    const payload = elements.find((node) => attribute(node, 'id') === 'archify-explainer-prepared');
    assert.ok(payload, 'the explainer must retain its original draft for patching');
    const bundle = JSON.parse(payload.childNodes.map((node) => node.value || '').join(''));
    assert.equal(JSON.parse(bundle.sourceText).meta.id, document.meta.id);
    assert.equal(bundle.source.sha256, createHash('sha256').update(bundle.sourceText).digest('hex'));
    return;
  }
  const svg = elements.find((node) => node.tagName === 'svg' && attribute(node, 'role') === 'img');
  assert.ok(svg, 'the HTML must contain an accessible diagram SVG');
  const viewBox = attribute(svg, 'viewBox')?.trim().split(/\s+/).map(Number);
  assert.equal(viewBox?.length, 4, 'SVG must have a usable viewBox');
  assert.ok(viewBox.every(Number.isFinite) && viewBox[2] > 0 && viewBox[3] > 0);
  const contents = descendants(svg);
  for (const item of document[collection]) {
    const node = contents.find((entry) => attribute(entry, 'data-node-id') === item.id);
    assert.ok(node, `SVG is missing authored ${document.diagram_type} node ${item.id}`);
    const parts = descendants(node);
    assert.ok(parts.some((part) => ['rect', 'path', 'circle', 'polygon'].includes(part.tagName)),
      `authored node ${item.id} must contain actual SVG geometry`);
    const text = parts.filter((part) => part.tagName === 'text')
      .map((part) => descendants(part).filter((child) => child.nodeName === '#text')
        .map((child) => child.value).join('')).join(' ');
    assert.ok(text.trim(), `authored node ${item.id} must contain SVG text`);
    // Ignore line wrapping and whitespace while retaining the authored words.
    const label = item.label ?? item.name ?? item.title;
    assert.ok(text.replace(/\s+/g, '').includes(label.replace(/\s+/g, '')),
      `authored node ${item.id} must retain its label in SVG text`);
  }
  for (const edge of document.connections || document.edges || document.messages || document.flows || document.transitions || document.relationships || []) {
    assert.ok(contents.some((node) => attribute(node, 'data-edge-from') === edge.from
      && attribute(node, 'data-edge-to') === edge.to),
    `SVG is missing authored connection ${edge.from} → ${edge.to}`);
  }
}

function assertDiagnostic(receipt, code) {
  assert.equal(receipt.ok, false);
  const diagnostic = receipt.diagnostics.find((entry) => entry.code === code);
  assert.ok(diagnostic, `missing ${code}: ${JSON.stringify(receipt.diagnostics)}`);
  assert.equal(diagnostic.severity, 'error');
  assert.ok(diagnostic.subject && typeof diagnostic.subject === 'object');
  assert.ok(diagnostic.evidence && typeof diagnostic.evidence === 'object');
  assert.ok(diagnostic.supportedFixes.length > 0, 'failure must give a repair action');
  return diagnostic;
}

test('core smoke: public CLI diagrams, compatibility and delivery safety', async (t) => {
  // Resolve Windows 8.3 temp aliases using the same native path semantics as delivery.
  const workspace = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'archify-core-')));
  t.after(() => fs.rmSync(workspace, { recursive: true, force: true }));
  const runtimeTmp = path.join(workspace, 'runtime-temp');
  fs.mkdirSync(runtimeTmp);
  const env = {
    ...process.env,
    ARCHIFY_UPDATE_CHECK_DISABLED: '1',
    TMPDIR: runtimeTmp,
    TMP: runtimeTmp,
    TEMP: runtimeTmp,
  };
  function run(args, cwd = workspace, status = 0) {
    const result = spawnSync(process.execPath, [cli, ...args], {
      cwd, env, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout: 60_000,
    });
    assert.ifError(result.error);
    assert.equal(result.status, status, `${args.join(' ')}\n${result.stderr}\n${result.stdout}`);
    assert.deepEqual(fs.readdirSync(runtimeTmp), [], 'CLI must clean its private temporary outputs');
    return result;
  }
  function receipt(args, cwd, status) {
    return JSON.parse(run(args, cwd, status).stdout);
  }
  function assertNoStaging(directory) {
    assert.deepEqual(fs.readdirSync(directory).filter((name) => name.startsWith('.archify-')
      || name.endsWith('.delivery-lock.json')), [], 'completed attempt must release locks and staging');
  }
  let workflow;

  for (const [type, filename, collection] of examples) {
    await t.test(`${type}: validate, render and deliver the official example`, () => {
      const directory = path.join(workspace, `${type} 空间 Ω`);
      fs.mkdirSync(directory);
      const input = path.join(directory, `输入 ${filename}`);
      fs.copyFileSync(path.join(skillRoot, 'examples', filename), input);
      const document = JSON.parse(fs.readFileSync(input, 'utf8'));
      assert.equal(document.diagram_type, type);

      const validation = receipt(['validate', type, input, '--json'], directory);
      assert.equal(validation.ok, true);
      assert.equal(validation.command, 'validate');
      assert.equal(validation.type, type);
      assert.equal(validation.candidateFrozen, true);
      assert.equal(validation.candidate.path, input);
      assert.deepEqual({ sha256: validation.candidate.sha256, bytes: validation.candidate.bytes }, identity(input));
      assert.ok(validation.checks.length > 0 && validation.checks.every((check) => check.ok));

      const rendered = path.join(directory, 'rendered.html');
      run(['render', type, input, rendered], directory);
      assertDiagram(rendered, document, collection);

      const output = path.join(directory, '交付 diagram.html');
      const delivered = receipt(['deliver', type, input, output, '--json'], directory);
      assert.equal(delivered.ok, true);
      assert.equal(delivered.command, 'deliver');
      assert.equal(delivered.type, type);
      assert.equal(delivered.input, input);
      assert.equal(delivered.output, output);
      assert.deepEqual(delivered.specification, identity(input));
      assert.deepEqual(delivered.artifact, identity(output));
      assert.equal(delivered.validation.checksPassed, delivered.validation.checkCount);
      assert.ok(delivered.validation.checkCount > 0);
      assert.equal(delivered.validation.errors, 0);
      assertDiagram(output, document, collection);

      const sidecar = output.replace(/\.html$/, '.delivery.json');
      const provenance = JSON.parse(fs.readFileSync(sidecar, 'utf8'));
      assert.equal(provenance.schemaVersion, 1);
      assert.equal(provenance.status, 'current');
      assert.equal(provenance.command, 'deliver');
      assert.equal(provenance.type, type);
      assert.ok(provenance.receiptId && provenance.receiptId === delivered.receiptId);
      assert.equal(provenance.input, input);
      assert.equal(provenance.output, output);
      assert.deepEqual(provenance.specification, identity(input));
      assert.deepEqual(provenance.artifact, identity(output));
      assert.deepEqual(fs.readdirSync(directory).sort(), [path.basename(input), path.basename(rendered), path.basename(output), path.basename(sidecar)].sort());
      if (type === 'workflow') workflow = { directory, input, output, sidecar, document };
    });
  }

  for (const [type, filename, collection] of examples.slice(0, 4)) {
    await t.test(`${type}: frozen schema-v1 input remains valid and renderable`, () => {
      const input = fileURLToPath(new URL(`./fixtures/v1-baseline/${filename}`, import.meta.url));
      const document = JSON.parse(fs.readFileSync(input, 'utf8'));
      assert.equal(document.schema_version, 1);
      const validated = receipt(['validate', type, input, '--json']);
      assert.equal(validated.ok, true);
      assert.equal(validated.type, type);
      assert.ok(validated.checks.every((check) => check.ok));
      const output = path.join(workspace, `v1-${type}.html`);
      run(['render', type, input, output]);
      assertDiagram(output, document, collection);
    });
  }

  await t.test('unknown diagram types return a structured diagnostic', () => {
    const failed = receipt(['validate', 'unknown', 'ignored.json', '--json'], workspace, 2);
    const diagnostic = assertDiagnostic(failed, 'cli/unknown-diagram-type');
    assert.equal(diagnostic.subject.type, 'unknown');
    assert.deepEqual(new Set(diagnostic.evidence.supportedTypes), new Set(examples.map(([type]) => type)));
  });

  await t.test('strict provenance binds the delivered artifact bytes', (t) => {
    if (!workflow) return t.skip('requires a successful official workflow delivery');
    const checked = receipt(['check', workflow.output, '--require-provenance']);
    assert.equal(checked.ok, true);
    assert.equal(checked.provenance, 'current');
    const original = fs.readFileSync(workflow.output);
    try {
      fs.appendFileSync(workflow.output, '\n<!-- changed after delivery -->\n');
      const failed = receipt(['check', workflow.output, '--require-provenance'], workspace, 1);
      const diagnostic = assertDiagnostic(failed, 'delivery/provenance-mismatch');
      assert.equal(diagnostic.evidence.expectedSha256, createHash('sha256').update(original).digest('hex'));
      assert.equal(diagnostic.evidence.actualSha256, identity(workflow.output).sha256);
      assert.notEqual(diagnostic.evidence.actualSha256, diagnostic.evidence.expectedSha256);
    } finally {
      fs.writeFileSync(workflow.output, original);
    }
  });

  await t.test('invalid schema preserves the last artifact and marks its delivery as failed', (t) => {
    if (!workflow) return t.skip('requires a successful official workflow delivery');
    const invalid = structuredClone(workflow.document);
    invalid.nodes[0].unexpected = true;
    const input = path.join(workflow.directory, 'invalid.workflow.json');
    fs.writeFileSync(input, JSON.stringify(invalid));
    const prior = fs.readFileSync(workflow.output);
    const validated = receipt(['validate', 'workflow', input, '--json'], workspace, 1);
    const diagnostic = assertDiagnostic(validated, 'schema/additionalProperties');
    assert.equal(diagnostic.subject.identity, invalid.nodes[0].id);
    assert.equal(diagnostic.evidence.additionalProperty, 'unexpected');
    const failed = receipt(['deliver', 'workflow', input, workflow.output, '--json'], workspace, 1);
    assertDiagnostic(failed, 'schema/additionalProperties');
    assert.deepEqual(fs.readFileSync(workflow.output), prior);
    const provenance = JSON.parse(fs.readFileSync(workflow.sidecar, 'utf8'));
    assert.equal(provenance.status, 'failed');
    assert.equal(provenance.receiptId, failed.receiptId);
    assert.deepEqual(provenance.artifact, identity(workflow.output));
    const checked = receipt(['check', workflow.output, '--require-provenance'], workspace, 1);
    assertDiagnostic(checked, 'delivery/provenance-failed');
    // The failure record/journal is intentional recovery evidence; temporary
    // publication directories and completed-attempt locks must be gone.
    assertNoStaging(workflow.directory);
  });
});