Skip to content

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

21.9 KB
Raw Blame
import assert from 'node:assert/strict';
import { execFileSync, spawnSync } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import test, { after } from 'node:test';
import { fileURLToPath } from 'node:url';
import { startPreview } from '../archify/bin/preview.mjs';
import { validateSchema } from '../archify/renderers/shared/validator.mjs';

const here = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(here, '..', 'archify');
const cli = path.join(skillRoot, 'bin', 'archify.mjs');

// One table for the whole file: every diagram type names its node array
// differently, and repository evidence must behave identically across all of
// them. `first` is the first authored node id, which is where the fixtures
// attach sources and where the verified payload must key them.
const TYPES = [
  { type: 'architecture', collection: 'components', example: 'web-app.architecture.json', first: 'users' },
  { type: 'workflow', collection: 'nodes', example: 'agent-tool-call.workflow.json', first: 'user' },
  { type: 'sequence', collection: 'participants', example: 'cache-miss-request.sequence.json', first: 'user' },
  { type: 'dataflow', collection: 'nodes', example: 'product-analytics.dataflow.json', first: 'web' },
  { type: 'lifecycle', collection: 'states', example: 'agent-run.lifecycle.json', first: 'queued' },
  { type: 'erd', collection: 'entities', example: 'orders.erd.json', first: 'customer' },
  { type: 'tree', collection: 'nodes', example: 'payment-platform.tree.json', first: 'platform' },
  { type: 'class', collection: 'types', example: 'payments.class.json', first: 'order_service' },
  { type: 'timeline', collection: 'events', example: 'payment-incident.timeline.json', first: 'deploy' },
  { type: 'waterfall', collection: 'spans', example: 'checkout-request.waterfall.json', first: 'request' },
];

function git(repo, ...args) {
  return execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
}

function run(args) {
  return spawnSync(process.execPath, [cli, ...args], { cwd: skillRoot, encoding: 'utf8' });
}

function evidencePayload(html) {
  const match = html.match(/<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/);
  assert.ok(match, 'verified evidence payload missing');
  return JSON.parse(match[1]);
}

function temporaryDirectory(t, prefix) {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
  return root;
}

// Initialize identical source history once. Each test copies the whole checkout,
// including .git, so changing its origin or index cannot affect another test.
let sourceSeed;
let seedRoot;
after(() => {
  if (seedRoot) fs.rmSync(seedRoot, { recursive: true, force: true });
});
function repositorySeed() {
  if (sourceSeed) return sourceSeed;
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-evidence-seed-'));
  seedRoot = root;
  fs.mkdirSync(path.join(root, 'src', 'nested'), { recursive: true });
  fs.writeFileSync(path.join(root, 'src', 'router.js'), 'export function route(input) {\n  return input.kind;\n}\n');
  fs.writeFileSync(path.join(root, 'src', 'store.js'), 'export const store = new Map();\n');
  git(root, 'init');
  git(root, 'config', 'user.name', 'Archify Tests');
  git(root, 'config', 'user.email', '[email protected]');
  git(root, 'remote', 'add', 'origin', '[email protected]:example/evidence-repo.git');
  git(root, 'add', '.');
  git(root, 'commit', '-m', 'fixture');
  const revision = git(root, 'rev-parse', 'HEAD');
  sourceSeed = { root, revision };
  return sourceSeed;
}

// A throwaway origin-matched checkout plus the typed diagram that points at it.
function fixture(t, { type, collection, example, first }) {
  const seed = repositorySeed();
  const root = temporaryDirectory(t, 'archify-evidence-types-');
  // cpSync copies files rather than hardlinking them or sharing a Git common dir.
  fs.cpSync(seed.root, root, { recursive: true });
  const { revision } = seed;

  const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));
  diagram.meta.repository = { url: 'https://github.com/example/evidence-repo', revision };
  const node = diagram[collection].find((candidate) => candidate.id === first);
  assert.ok(node, `${type} example is missing node ${JSON.stringify(first)}`);
  node.sources = [
    { path: 'src/router.js', line: 1, end_line: 3, label: 'Request router' },
    { path: 'src/store.js', line: 1 },
  ];
  const input = path.join(root, `diagram.${type}.json`);
  const write = () => fs.writeFileSync(input, JSON.stringify(diagram, null, 2));
  write();
  return { root, revision, diagram, node, input, write };
}

// All renderers enter the same repository verifier through loadDiagram. Keep
// the full rejection matrix once; the type loop below owns each mode's wiring.
test('shared repository evidence rejects invalid roots, revisions, paths and lines without replacing output', (t) => {
  const shape = TYPES.find(({ type }) => type === 'architecture');
  const { type } = shape;
  const data = fixture(t, shape);
  const output = path.join(data.root, `must-stay.${type}.html`);
  fs.writeFileSync(output, 'trusted previous artifact');
  const deliver = (...args) => {
    const result = run(['deliver', type, data.input, output, ...args, '--json']);
    assert.equal(fs.readFileSync(output, 'utf8'), 'trusted previous artifact');
    return result;
  };

  // No --repo-root at all.
  let result = deliver();
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /Pass --repo-root/);

  // Not the Git top-level directory.
  result = deliver('--repo-root', path.join(data.root, 'src'));
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /must be the Git top-level directory/);

  // Origin does not match the authored repository.
  git(data.root, 'remote', 'set-url', 'origin', 'https://github.com/example/other-repo.git');
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /does not match/);
  git(data.root, 'remote', 'set-url', 'origin', '[email protected]:example/evidence-repo.git');

  // Commit does not exist locally.
  const pinned = data.diagram.meta.repository.revision;
  data.diagram.meta.repository.revision = '0'.repeat(40);
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /is not available in the local repository/);
  data.diagram.meta.repository.revision = pinned;

  // Path escape.
  data.node.sources = [{ path: '../outside.js' }];
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /must stay inside the repository/);

  // Non-POSIX / control-character path.
  data.node.sources = [{ path: 'src/router.js\n' }];
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /repo-relative POSIX path/);

  // Blob does not exist at the pinned revision.
  data.node.sources = [{ path: 'src/missing.js' }];
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /does not identify a file/);

  // Line range beyond the pinned blob.
  data.node.sources = [{ path: 'src/router.js', line: 4 }];
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /has 3 lines/);

  // Inverted line range.
  data.node.sources = [{ path: 'src/router.js', line: 3, end_line: 2 }];
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /must be greater than or equal to line/);

  // end_line without line.
  data.node.sources = [{ path: 'src/router.js', end_line: 2 }];
  data.write();
  result = deliver('--repo-root', data.root);
  assert.equal(result.status, 1);
  assert.match(JSON.parse(result.stdout).error, /requires line/);

});

for (const [typeIndex, shape] of TYPES.entries()) {
  const { type, collection, first } = shape;

  test(`${type} repository evidence is revision-verified, receipt-backed, and keyed by node id`, (t) => {
    const data = fixture(t, shape);
    const output = path.join(data.root, `verified.${type}.html`);
    const result = run(['deliver', type, data.input, output, '--repo-root', data.root, '--json']);
    assert.equal(result.status, 0, result.stderr || result.stdout);

    assert.deepEqual(JSON.parse(result.stdout).evidence, {
      verified: true,
      repository: 'https://github.com/example/evidence-repo',
      revision: data.revision,
      references: 2,
    });

    const html = fs.readFileSync(output, 'utf8');
    const evidence = evidencePayload(html);
    assert.equal(evidence.verified, true);
    assert.equal(evidence.referenceCount, 2);
    assert.equal(evidence.repository.shortRevision, data.revision.slice(0, 7));
    assert.deepEqual(Object.keys(evidence.nodes), [first]);
    assert.equal(evidence.nodes[first].length, 2);
    assert.equal(
      evidence.nodes[first][0].href,
      `https://github.com/example/evidence-repo/blob/${data.revision}/src/router.js#L1-L3`,
    );
    assert.equal(evidence.nodes[first][0].label, 'Request router');

    // Evidence stays keyed to the rendered subject for Focus/Finder lookup.
    assert.match(html, new RegExp(`data-node-id="${first}"`));
    assert.doesNotMatch(html, /Archify\.sourceEvidence\.installBeacons\(\)|classList\.add\('source-evidence-beacon'\)/);

    const svg = html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
    assert.doesNotMatch(svg, /src\/router\.js|github\.com\/example\/evidence-repo|source-evidence/);
  });

  test(`${type} duplicate evidence node IDs cannot replace a trusted artifact`, (t) => {
    const data = fixture(t, shape);
    const duplicate = structuredClone(data.node);
    duplicate.sources = [{ path: 'src/store.js', line: 1 }];
    data.diagram[collection].push(duplicate);
    data.write();
    const output = path.join(data.root, 'duplicate.html');
    fs.writeFileSync(output, 'trusted previous artifact');
    for (const args of [
      ['validate', type, data.input, '--repo-root', data.root, '--json'],
      ['deliver', type, data.input, output, '--repo-root', data.root, '--json'],
    ]) {
      const result = run(args);
      assert.equal(result.status, 1, type);
      const receipt = JSON.parse(result.stdout);
      assert.equal(receipt.ok, false, type);
      if (['tree', 'timeline', 'waterfall'].includes(type)) {
        const duplicateDiagnostic = receipt.diagnostics.find((entry) => entry.code === `${type}/duplicate-id`);
        assert.ok(duplicateDiagnostic, `${type}: duplicate ID diagnostic missing`);
        assert.equal(duplicateDiagnostic.severity, 'error');
        assert.deepEqual(duplicateDiagnostic.evidence, { id: first });
        assert.deepEqual(duplicateDiagnostic.subject, {
          diagramType: type,
          path: `/${collection}/${data.diagram[collection].length - 1}/id`,
        });
      } else {
        assert.ok(
          /ids must be unique/.test(receipt.error) ||
          receipt.diagnostics.some((entry) => entry.code === 'workflow/duplicate-node-id'),
          `${type}: duplicate ID rejection missing`,
        );
      }
      assert.equal(fs.readFileSync(output, 'utf8'), 'trusted previous artifact', `${type}/${args[0]}`);
    }
    assert.equal(fs.readFileSync(output, 'utf8'), 'trusted previous artifact');
  });

  // GitHub integration is checked above for every type. The full provider,
  // origin and rejection matrix lives in repository-evidence.test.mjs, using
  // the same verifier. Each type also proves one alternate configuration is
  // threaded through its schema, delivery receipt and embedded payload.
  test(`${type} repository evidence preserves alternate provider settings`, (t) => {
    const data = fixture(t, shape);
    const output = path.join(data.root, `provider.${type}.html`);
    const providers = [
      {
        repository: { url: 'https://gitee.com/example/evidence-repo', provider: 'gitee' },
        origin: '[email protected]:example/evidence-repo.git',
        tree: `https://gitee.com/example/evidence-repo/tree/${data.revision}`,
        source: `https://gitee.com/example/evidence-repo/blob/${data.revision}/src/router.js#L1-3`,
      },
      {
        repository: { url: 'https://gitlab.com/example/platform/evidence-repo' },
        origin: '[email protected]:example/platform/evidence-repo.git',
        tree: `https://gitlab.com/example/platform/evidence-repo/-/tree/${data.revision}`,
        source: `https://gitlab.com/example/platform/evidence-repo/-/blob/${data.revision}/src/router.js#L1-3`,
      },
      {
        repository: { url: 'http://git.internal:3000/Platform/evidence-repo', link_mode: 'local-only' },
        origin: 'http://git.internal:3000/Platform/evidence-repo',
      },
    ];
    const provider = providers[typeIndex % providers.length];
    data.diagram.meta.repository = { ...provider.repository, revision: data.revision };
    data.write();
    git(data.root, 'remote', 'set-url', 'origin', provider.origin);
    const result = run(['deliver', type, data.input, output, '--repo-root', data.root, '--json']);
    assert.equal(result.status, 0, result.stderr || result.stdout);
    const receipt = JSON.parse(result.stdout);
    assert.equal(receipt.evidence.verified, true);
    assert.equal(receipt.evidence.references, 2);
    const evidence = evidencePayload(fs.readFileSync(output, 'utf8'));
    assert.equal(evidence.verified, true);
    assert.deepEqual(Object.keys(evidence.nodes), [first]);
    assert.equal(evidence.nodes[first].length, 2);
    assert.equal(evidence.repository.href, provider.tree);
    assert.equal(evidence.nodes[first][0].href, provider.source);
    if (provider.repository.link_mode === 'local-only') {
      assert.equal(receipt.evidence.linkMode, 'local-only');
      assert.equal(evidence.repository.linkMode, 'local-only');
      assert.ok(evidence.nodes[first].every((source) => !Object.hasOwn(source, 'href')));
    }
  });

  test(`${type} failed evidence delivery identifies its node collection and preserves output`, (t) => {
    const data = fixture(t, shape);
    data.node.sources = [{ path: 'src/missing.js' }];
    data.write();
    const output = path.join(data.root, 'trusted.html');
    fs.writeFileSync(output, 'trusted previous artifact');
    const result = run(['deliver', type, data.input, output, '--repo-root', data.root, '--json']);
    assert.equal(result.status, 1);
    const receipt = JSON.parse(result.stdout);
    const diagnostic = receipt.diagnostics.find((entry) => entry.code === 'repository-evidence/file-missing');
    assert.ok(diagnostic, JSON.stringify(receipt.diagnostics));
    assert.match(diagnostic.subject.path, new RegExp(`^/${collection}/\\d+/sources/0/path$`));
    assert.equal(diagnostic.subject.nodeId, first);
    assert.equal(diagnostic.evidence.sourcePath, 'src/missing.js');
    assert.ok(diagnostic.supportedFixes.length);
    assert.equal(fs.readFileSync(output, 'utf8'), 'trusted previous artifact');
  });

  test(`${type} sources stay bounded by the shared schema shape`, (t) => {
    // These failures occur before Git verification. Exercise each generated
    // type validator directly; one CLI witness retains exit/diagnostic wiring.
    const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', shape.example), 'utf8'));
    const nodeIndex = diagram[collection].findIndex(node => node.id === first);
    const node = diagram[collection][nodeIndex];
    diagram.meta.repository = { url: 'https://github.com/example/evidence-repo', revision: 'a'.repeat(40) };
    node.sources = [{ path: 'src/router.js' }];
    assert.doesNotThrow(() => validateSchema(type, diagram));
    const cliData = type === 'architecture' ? fixture(t, shape) : null;
    for (const [sources, pattern, code, sourceSuffix] of [
      [Array.from({ length: 4 }, () => ({ path: 'src/router.js' })), /must NOT have more than 3 items/, 'schema/maxItems', ''],
      [[{ path: 'src/router.js', branch: 'main' }], /must NOT have additional properties/, 'schema/additionalProperties', '/0'],
    ]) {
      node.sources = sources;
      assert.throws(() => validateSchema(type, diagram), (error) => {
        assert.match(error.message, pattern);
        const diagnostic = error.archifyDiagnostics.find(entry => entry.code === code);
        assert.ok(diagnostic, `${type}: missing ${code}`);
        assert.equal(diagnostic.subject.diagramType, type);
        assert.equal(diagnostic.subject.path, `/${collection}/${nodeIndex}/sources${sourceSuffix}`);
        return true;
      });
      if (cliData) {
        cliData.node.sources = sources;
        cliData.write();
        const result = run(['validate', type, cliData.input, '--repo-root', cliData.root]);
        assert.equal(result.status, 1);
        assert.match(result.stderr, pattern);
      }
    }
  });

  test(`${type} node sources require pinned repository metadata`, (t) => {
    const data = fixture(t, shape);
    delete data.diagram.meta.repository;
    data.write();
    const result = run(['validate', type, data.input, '--repo-root', data.root, '--json']);
    assert.equal(result.status, 1);
    assert.ok(JSON.parse(result.stdout).diagnostics.some(
      (entry) => entry.code === 'repository-evidence/repository-required',
    ));
  });

  test(`${type} repository metadata requires at least one verified source`, (t) => {
    const data = fixture(t, shape);
    delete data.node.sources;
    data.write();
    const result = run(['validate', type, data.input, '--repo-root', data.root, '--json']);
    assert.equal(result.status, 1);
    assert.ok(JSON.parse(result.stdout).diagnostics.some(
      (entry) => entry.code === 'repository-evidence/source-required',
    ));
  });
}

// The issue's own reproduction: --repo-root must be accepted by every typed
// command, including for a diagram that carries no evidence at all.
test('--repo-root is accepted for every diagram type', () => {
  for (const { type, example } of TYPES) {
    const result = run(['validate', type, path.join(skillRoot, 'examples', example), '--repo-root', '.']);
    assert.equal(result.status, 0, `${type}: ${result.stderr || result.stdout}`);
  }
});

test('ordinary typed artifacts still carry no repository evidence', (t) => {
  for (const { type, example } of TYPES) {
    const output = path.join(temporaryDirectory(t, 'archify-no-evidence-types-'), `${type}.html`);
    const result = run(['render', type, path.join(skillRoot, 'examples', example), output]);
    assert.equal(result.status, 0, result.stderr);
    const html = fs.readFileSync(output, 'utf8');
    assert.doesNotMatch(html, /id="archify-source-evidence-data"/);
  }
});

async function waitForState(url, predicate, timeoutMs = 12000) {
  const started = Date.now();
  let latest;
  while (Date.now() - started < timeoutMs) {
    latest = await (await fetch(new URL('/state', url))).json();
    if (predicate(latest)) return latest;
    await new Promise((resolve) => setTimeout(resolve, 40));
  }
  assert.fail(`preview did not settle; latest state: ${JSON.stringify(latest)}`);
}

test('live preview publishes verified evidence for a non-architecture type', { timeout: 20000 }, async (t) => {
  const shape = TYPES.find(({ type }) => type === 'lifecycle');
  const data = fixture(t, shape);
  const output = path.join(data.root, 'preview.lifecycle.html');
  const preview = await startPreview({
    type: shape.type,
    input: data.input,
    output,
    repoRoot: data.root,
    open: false,
    debounceMs: 30,
    pollMs: 60,
  });
  try {
    const state = await waitForState(preview.url, (candidate) => candidate.status === 'verified');
    assert.equal(state.revision, 1);
    const html = await (await fetch(new URL('/artifact.html', preview.url))).text();
    const evidence = evidencePayload(html);
    assert.equal(evidence.repository.revision, data.revision);
    assert.equal(evidence.nodes[shape.first].length, 2);
  } finally {
    await preview.stop();
  }
});

test('workflow migration verifies and preserves pinned source evidence before replacement', (t) => {
  const data = fixture(t, TYPES.find(shape => shape.type === 'workflow'));
  const repository = data.diagram.meta.repository;
  const legacy = JSON.parse(fs.readFileSync(path.join(skillRoot, '..', 'test', 'fixtures/v1-workflow-explicit-coordinates.workflow.json'), 'utf8'));
  legacy.meta.repository = repository;
  legacy.nodes[0].sources = [{ path: 'src/router.js', line: 1, end_line: 3 }];
  const sourceBytes = JSON.stringify(legacy);
  fs.writeFileSync(data.input, sourceBytes);
  const output = path.join(data.root, 'migrated.json');
  fs.writeFileSync(output, 'trusted prior migration');
  const args = ['migrate', 'workflow', data.input, output, '--to-schema', '2', '--json'];
  const missing = run(args);
  assert.equal(missing.status, 1);
  assert.match(missing.stdout, /repository-evidence\/root-required/);
  assert.equal(fs.readFileSync(output, 'utf8'), 'trusted prior migration');
  const migrated = run([...args, '--repo-root', data.root]);
  assert.equal(migrated.status, 0, migrated.stdout || migrated.stderr);
  const doc = JSON.parse(fs.readFileSync(output, 'utf8'));
  assert.equal(doc.schema_version, 2);
  assert.deepEqual(doc.meta.repository, repository);
  assert.deepEqual(doc.nodes.find(n => n.id === legacy.nodes[0].id).sources, legacy.nodes[0].sources);
  assert.equal(fs.readFileSync(data.input, 'utf8'), sourceBytes);
  assert.equal(run(['validate', 'workflow', output, '--repo-root', data.root, '--json']).status, 0);
  const trusted = fs.readFileSync(output);
  legacy.nodes[0].sources[0].line = 999;
  delete legacy.nodes[0].sources[0].end_line;
  fs.writeFileSync(data.input, JSON.stringify(legacy));
  const invalid = run([...args, '--repo-root', data.root]);
  assert.equal(invalid.status, 1);
  assert.match(invalid.stdout, /repository-evidence\/line-out-of-range/);
  assert.deepEqual(fs.readFileSync(output), trusted);
});