Skip to content

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

13.3 KB
Raw Blame
import assert from 'node:assert/strict';
import { spawn } from 'node:child_process';
import { createHash } from 'node:crypto';
import fs from 'node:fs';
import http from 'node:http';
import os from 'node:os';
import path from 'node:path';
import test from 'node:test';
import { fileURLToPath } from 'node:url';

const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'archify');
const cli = path.join(skillRoot, 'bin/archify.mjs');
// Valid blue and red PNGs: a wrong candidate must not fall through after a 404.
const icon = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYPj/HwADAgH/5ncLrgAAAABJRU5ErkJggg==', 'base64');
const inactiveIcon = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg==', 'base64');
const digest = createHash('sha256').update(icon).digest('hex');
const inactiveDigest = createHash('sha256').update(inactiveIcon).digest('hex');
const activeLink = '<link rel="icon" href="/active.png">';
const inactiveLink = '<link rel="icon" href="/inactive.png">';
const noscriptLink = '<noscript><link rel="apple-touch-icon" href="/inactive.png" sizes="512x512" /></noscript>';

function run(args) {
  return new Promise((resolve, reject) => {
    const child = spawn(process.execPath, [cli, ...args], {
      cwd: skillRoot,
      env: { ...process.env, ARCHIFY_BRAND_ALLOW_PRIVATE: '1' },
      stdio: ['ignore', 'pipe', 'pipe'],
      timeout: 15000,
    });
    let stdout = '';
    let stderr = '';
    child.stdout.setEncoding('utf8').on('data', (chunk) => { stdout += chunk; });
    child.stderr.setEncoding('utf8').on('data', (chunk) => { stderr += chunk; });
    child.once('error', reject);
    child.once('close', (status) => resolve({ status, stdout, stderr }));
  });
}

async function fixture(t, markup, { byteChunks = false, contentType = 'text/html; charset=utf-8', fallbackIcon = icon } = {}) {
  const data = { markup, requests: [] };
  const server = http.createServer(async (request, response) => {
    data.requests.push(request.url);
    if (request.url === '/studio') {
      response.writeHead(200, { 'content-type': contentType });
      const html = `<head>${data.markup}</head>`;
      if (byteChunks) {
        for (const byte of Buffer.from(html)) {
          if (response.destroyed) return;
          response.write(Buffer.from([byte]));
          await new Promise((resolve) => setTimeout(resolve, 2));
        }
      } else {
        response.write(html);
      }
      response.end();
    } else if (['/active.png', '/active.png?a=1&b=2'].includes(request.url)) {
      response.writeHead(200, { 'content-type': 'image/png' });
      response.end(icon);
    } else if (request.url === '/favicon.ico' && fallbackIcon) {
      response.writeHead(200, { 'content-type': 'image/png' });
      response.end(fallbackIcon);
    } else if (request.url === '/inactive.png') {
      response.writeHead(200, { 'content-type': 'image/png' });
      response.end(inactiveIcon);
    } else {
      response.writeHead(404);
      response.end('no icon');
    }
  });
  await new Promise((resolve, reject) => {
    server.once('error', reject);
    server.listen(0, '127.0.0.1', resolve);
  });
  t.after(() => new Promise((resolve) => {
    server.closeAllConnections?.();
    server.close(resolve);
  }));
  data.url = `http://127.0.0.1:${server.address().port}/studio`;
  return data;
}

async function capture(data, paths = ['/active.png'], expectedDigest = digest) {
  const result = await run(['brands', 'capture', data.url, '--json']);
  assert.equal(result.status, 0, result.stderr || result.stdout);
  const receipt = JSON.parse(result.stdout);
  assert.deepEqual(data.requests, ['/studio', ...paths]);
  assert.equal(receipt.ok, true);
  assert.deepEqual(receipt.brand, { url: data.url, sha256: expectedDigest });
  assert.equal(receipt.evidence.status, 'captured');
  return receipt.brand;
}

for (const [name, prefix] of [
  ['comment', `<!-- ${inactiveLink} -->`],
  ['script string', `<script>const example = '${inactiveLink}';</script>`],
  ['style string', `<style>p::after { content: '${inactiveLink}'; }</style>`],
  ['title text', `<title>Example ${inactiveLink}</title>`],
  ['quoted attribute', `<meta name="example" content='${inactiveLink}'>`],
  ['template', `<template>${inactiveLink}</template>`],
  ['nested template', `<template><template>${inactiveLink}</template>${inactiveLink}</template>`],
  ['template with literal closing tags', `<template><script>const end = '</template></head>';</script>${inactiveLink}</template>`],
  ['raw closing-tag prefix', `<script>"</scripture>${inactiveLink}";</script>`],
  ['noscript closing-tag prefix', `<noscript></noscripture>${inactiveLink}</noscript>`],
  ['self-closing script flag', `<script/>"${inactiveLink}";</script>`],
  ['lookalike tag name', '<link-preview rel="icon" href="/inactive.png"></link-preview>'],
  ['lookalike rel attribute', '<link data-rel="icon" href="/inactive.png">'],
]) {
  test(`capture ignores icon declarations in ${name}`, async (t) => {
    await capture(await fixture(t, prefix + activeLink));
  });
}

for (const contentType of ['text/html', 'Text/Html; charset=utf-8']) {
  test(`capture ignores a higher-ranked noscript icon for ${contentType}`, async (t) => {
    const markup = noscriptLink + '<link rel="icon" href="/active.png" />';
    await capture(await fixture(t, markup, { contentType }));
  });
}

for (const contentType of ['application/xhtml+xml', 'Application/XHTML+XML; charset=utf-8; profile="text/html"']) {
  test(`capture preserves noscript icon discovery for ${contentType}`, async (t) => {
    const markup = noscriptLink + '<link rel="icon" href="/active.png" />';
    await capture(await fixture(t, markup, { contentType }), ['/inactive.png'], inactiveDigest);
  });
}

for (const [name, prefix] of [
  ['script', '<script src="/app.js" />'],
  ['template', '<template />'],
]) {
  for (const [fallback, fallbackIcon] of [['different', inactiveIcon], ['missing', null]]) {
    test(`capture reads icons after an empty XHTML ${name} with a ${fallback} favicon`, async (t) => {
      const markup = prefix + '<link rel="icon" href="/active.png" />';
      await capture(await fixture(t, markup, { contentType: 'application/xhtml+xml', fallbackIcon }));
    });
  }

  test(`empty-element syntax does not close an HTML ${name}`, async (t) => {
    const markup = prefix + activeLink;
    await capture(await fixture(t, markup, { fallbackIcon: inactiveIcon }), ['/favicon.ico'], inactiveDigest);
  });

  test(`an empty XHTML ${name} survives one-byte response chunks`, { timeout: 20000 }, async (t) => {
    const markup = prefix + '<link rel="icon" href="/active.png" />';
    await capture(await fixture(t, markup, {
      byteChunks: true,
      contentType: 'Application/XHTML+XML; charset=utf-8; profile="text/html"',
      fallbackIcon: inactiveIcon,
    }));
  });
}

test('an empty XHTML template does not change the enclosing template depth', async (t) => {
  const markup = '<template><template /><link rel="icon" href="/inactive.png" /></template>'
    + '<link rel="icon" href="/active.png" />';
  await capture(await fixture(t, markup, { contentType: 'application/xhtml+xml', fallbackIcon: inactiveIcon }));
});

for (const [name, markup] of [
  ['ordinary icon', activeLink],
  ['quoted greater-than', '<link title="size > zero" rel="icon" href="/active.png">'],
  ['lookalike href attribute', '<link data-href="/inactive.png" HREF="/active.png" REL="icon">'],
  ['attribute value containing declarations', '<link data-example=\'rel="icon" href="/inactive.png"\' rel="icon" href="/active.png">'],
  ['unquoted attributes', '<link data-note=example rel=icon href=/active.png>'],
  ['first duplicate attribute', '<link rel="icon" href="/active.png" HREF="/inactive.png">'],
  ['empty first duplicate attribute', '<link rel="icon" href href="/inactive.png">' + activeLink],
  ['existing size ranking', '<link rel="icon" sizes="16x16" href="/inactive.png"><link rel="icon" sizes="32x32" href="/active.png">'],
]) {
  test(`capture reads complete link attributes: ${name}`, async (t) => {
    await capture(await fixture(t, markup));
  });
}

test('old noscript pins fail closed until explicitly recaptured', { timeout: 45000 }, async (t) => {
  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-brand-recapture-'));
  t.after(() => fs.rmSync(temporary, { recursive: true, force: true }));
  const data = await fixture(t, noscriptLink + activeLink);
  const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/web-app.architecture.json'), 'utf8'));
  diagram.components[0].brand = { url: data.url, sha256: inactiveDigest };
  const input = path.join(temporary, 'diagram.json');
  const original = JSON.stringify(diagram);
  fs.writeFileSync(input, original);

  const outdated = await run(['validate', 'architecture', input, '--json']);
  assert.notEqual(outdated.status, 0, outdated.stderr || outdated.stdout);
  assert.ok(JSON.parse(outdated.stdout).diagnostics.some((entry) => entry.code === 'brand/digest-mismatch'));
  assert.deepEqual(data.requests, ['/studio', '/active.png']);
  assert.equal(fs.readFileSync(input, 'utf8'), original, 'validation must not rewrite an existing pin');

  data.requests.length = 0;
  const recaptured = await capture(data);
  assert.equal(fs.readFileSync(input, 'utf8'), original, 'capture must not rewrite authored diagrams');
  diagram.components[0].brand = recaptured;
  fs.writeFileSync(input, JSON.stringify(diagram));
  data.requests.length = 0;
  const updated = await run(['validate', 'architecture', input, '--json']);
  assert.equal(updated.status, 0, updated.stderr || updated.stdout);
  assert.equal(JSON.parse(updated.stdout).ok, true);
  assert.deepEqual(data.requests, ['/studio', '/active.png']);
});

test('inactive declarations do not consume the five icon candidate slots', async (t) => {
  const removed = Array.from({ length: 5 }, (_, index) => `<link rel="icon" href="/missing-${index}.png">`).join('');
  await capture(await fixture(t, `<!-- ${removed} -->${activeLink}`));
});

test('active declarations retain the five-candidate limit and favicon fallback', async (t) => {
  const paths = Array.from({ length: 5 }, (_, index) => `/missing-${index}.png`);
  const markup = paths.map((href) => `<link rel="icon" href="${href}">`).join('') + activeLink;
  await capture(await fixture(t, markup), [...paths, '/favicon.ico']);
});

for (const [name, markup] of [
  ['unclosed comment', `<!-- ${inactiveLink}`],
  ['unclosed script', `<script>const example = '${inactiveLink}';`],
  ['unclosed noscript', `<noscript>${inactiveLink}`],
  ['unclosed template', `<template>${inactiveLink}`],
]) {
  test(`capture uses the favicon fallback for an ${name}`, async (t) => {
    await capture(await fixture(t, markup), ['/favicon.ico']);
  });
}

for (const [name, prefix] of [
  ['comment', `<!-- ${inactiveLink} </head> -->`],
  ['script', `<ScRiPt data-note=">">'${inactiveLink}'</sCrIpT \n>`],
  ['noscript', `<NoScRiPt>${inactiveLink}</head></nOsCrIpT>`],
  ['template', `<template>${inactiveLink}</template>`],
]) {
  test(`link attributes and ${name} context survive one-byte response chunks`, { timeout: 20000 }, async (t) => {
    // Keep each response short enough for the real request deadline, including
    // hosts with coarse timer resolution. Do not relax the capture timeout.
    const markup = prefix + '<LiNk title="图 > icon" REL=icon HREF="/active.png?a=1&amp;b=2">';
    await capture(await fixture(t, markup, { byteChunks: true }), ['/active.png?a=1&b=2']);
  });
}

for (const [type, example, collection] of [
  ['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'],
]) {
  test(`inactive HTML changes preserve pinned ${type} validation and rendered bytes`, { timeout: 45000 }, async (t) => {
    const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-brand-context-'));
    t.after(() => fs.rmSync(temporary, { recursive: true, force: true }));
    const data = await fixture(t, activeLink);
    const brand = await capture(data);
    const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));
    diagram[collection][0].brand = brand;
    const input = path.join(temporary, 'diagram.json');
    const output = path.join(temporary, 'diagram.html');
    fs.writeFileSync(input, JSON.stringify(diagram));
    let original;
    for (const prefix of ['', `<!-- ${inactiveLink} --><script>const sample = '${inactiveLink}';</script>${noscriptLink}`]) {
      data.markup = prefix + activeLink;
      for (const command of ['validate', 'render']) {
        data.requests.length = 0;
        const args = [command, type, input, ...(command === 'render' ? [output] : ['--json'])];
        const result = await run(args);
        assert.equal(result.status, 0, result.stderr || result.stdout);
        assert.deepEqual(data.requests, ['/studio', '/active.png']);
      }
      const html = fs.readFileSync(output, 'utf8');
      assert.ok(html.includes(`data-brand-sha256="${digest}"`));
      assert.ok(html.includes(`data:image/png;base64,${icon.toString('base64')}`));
      assert.ok(!html.includes(inactiveIcon.toString('base64')));
      if (original) assert.equal(html, original, 'inactive source markup must not change the final artifact');
      original = html;
    }
  });
}