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
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);
});