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 { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { createRouter } from '../archify/renderers/architecture/routing.mjs';
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
function box(id, x, y, width = 230, height = 80) {
return [id, { id, x, y, width, height, cx: x + width / 2, cy: y + height / 2 }];
}
// The hive runtime case: a bottom-to-left relationship shares the runtime's
// bottom side with an upward security link. Both a three-bend stub route and
// a one-bend corner pass every check at the same length.
function scene(labelRectFor) {
const boxes = new Map([box('runtime', 440, 230), box('tasks', 870, 450), box('tunnel', 440, 650)]);
const connections = [
{ id: 'tasks', from: 'runtime', to: 'tasks', label: 'watch', fromSide: 'bottom', toSide: 'left' },
{ id: 'tunnel', from: 'tunnel', to: 'runtime', fromSide: 'top', toSide: 'bottom' },
];
const router = createRouter(boxes, connections, { distinctAutomaticPorts: true, preferReadableRoutes: true, labelRectFor });
return router.pathFor(connections[0]).points;
}
test('architecture takes the fewest-bend route among equally long side-aware candidates', () => {
const points = scene();
assert.equal(points.length, 3, JSON.stringify(points));
assert.deepEqual(points.at(-1), [870, 490]);
assert.equal(points[1][1], 490);
});
test('architecture keeps a feasible route with label room over a fewer-bend route without it', () => {
const points = scene((conn, route) => (route.length > 3 ? { x: 0, y: 0, width: 1, height: 1 } : null));
assert.equal(points.length, 5, JSON.stringify(points));
});
test('showcase shortens a route when a neighboring automatic label can move safely', t => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-label-detour-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
fs.writeFileSync(input, JSON.stringify({
schema_version: 1,
diagram_type: 'architecture',
meta: { title: 'Content build', output: 'diagram.html', quality_profile: 'showcase' },
components: [
{ id: 'source', type: 'backend', label: 'Source', sublabel: 'Load and validate', pos: [400, 40], size: [235, 76] },
{ id: 'published', type: 'security', label: 'Published content', sublabel: 'Exclude drafts', pos: [760, 40], size: [235, 76] },
{ id: 'build', type: 'backend', label: 'Build', sublabel: 'Render pages', pos: [400, 210], size: [235, 76] },
{ id: 'feed', type: 'backend', label: 'Feed', sublabel: 'Requires SITE_URL', pos: [760, 210], size: [235, 76] },
],
connections: [
{ id: 'publish', from: 'source', to: 'published', label: '筛选' },
{ id: 'build-input', from: 'published', to: 'build', label: '公开内容' },
{ id: 'feed-output', from: 'build', to: 'feed', label: 'SITE_URL 有值' },
],
}));
const original = fs.readFileSync(input, 'utf8');
const result = spawnSync(process.execPath, [cli, 'render', 'architecture', input, output, '--quality', 'showcase'], {
cwd: directory, encoding: 'utf8',
});
assert.equal(result.status, 0, result.stderr);
const html = fs.readFileSync(output, 'utf8');
const points = html.match(/data-edge-id="build-input"[^>]*data-composition-points="([^"]+)"/)[1].split(';');
assert.ok(points.length <= 4, `a movable label must not force three bends: ${points}`);
for (const label of ['筛选', '公开内容', 'SITE_URL 有值']) assert.ok(html.includes(`>${label}</text>`), label);
assert.equal(fs.readFileSync(input, 'utf8'), original);
});
function validate(t, profile, replySides) {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-pinned-reply-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'diagram.json');
fs.writeFileSync(input, JSON.stringify({
schema_version: 1,
diagram_type: 'architecture',
meta: { title: 'Reply', output: 'diagram.html', quality_profile: profile },
components: [
{ id: 'runtime', type: 'backend', label: 'Runtime', pos: [40, 120], size: [200, 80] },
{ id: 'agents', type: 'backend', label: 'Agents', pos: [440, 120], size: [200, 80] },
],
connections: [
{ id: 'spawn', from: 'runtime', to: 'agents', label: 'spawn' },
{ id: 'report', from: 'agents', to: 'runtime', label: 'report', ...replySides },
],
}));
const result = spawnSync(process.execPath, [cli, 'validate', 'architecture', input, '--quality', profile, '--json'], {
cwd: directory, encoding: 'utf8',
});
return { status: result.status, receipt: JSON.parse(result.stdout) };
}
test('showcase preserves a valid authored reply side even when automatic lanes are straighter', t => {
const { status, receipt } = validate(t, 'showcase', { fromSide: 'top', toSide: 'top' });
assert.equal(status, 0, JSON.stringify(receipt));
assert.ok(receipt.composition.metrics.maxBends > 0);
const automatic = validate(t, 'showcase', {});
assert.equal(automatic.status, 0, JSON.stringify(automatic.receipt));
assert.equal(automatic.receipt.composition.metrics.maxBends, 0);
assert.equal(validate(t, 'standard', { fromSide: 'top', toSide: 'top' }).status, 0);
});
test('architecture straightens a dogleg between facing nodes that overlap across the route', () => {
const boxes = new Map([box('api', 40, 100, 200, 80), box('worker', 440, 130, 200, 80), box('store', 440, 330, 200, 80)]);
const connections = [
{ id: 'run', from: 'api', to: 'worker' },
{ id: 'save', from: 'worker', to: 'store' },
];
const router = createRouter(boxes, connections, { distinctAutomaticPorts: true, preferReadableRoutes: true });
const points = router.pathFor(connections[0]).points;
assert.equal(points.length, 2, JSON.stringify(points));
assert.equal(points[0][1], points[1][1]);
assert.ok(points[0][1] >= 146 && points[0][1] <= 164, JSON.stringify(points));
});
test('showcase slides a boundary title off a route that crosses its rail', t => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-title-route-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
fs.writeFileSync(input, JSON.stringify({
schema_version: 1,
diagram_type: 'architecture',
meta: { title: 'Title', output: 'diagram.html', quality_profile: 'showcase' },
components: [
{ id: 'cache', type: 'database', label: 'Cache', pos: [40, 40], size: [100, 64] },
{ id: 'api', type: 'backend', label: 'API', pos: [60, 220], size: [260, 80] },
],
connections: [{ id: 'read', from: 'api', to: 'cache' }],
boundaries: [{ kind: 'region', label: 'Backend services', wraps: ['api'] }],
}));
const result = spawnSync(process.execPath, [cli, 'render', 'architecture', input, output, '--quality', 'showcase'], { cwd: directory, encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
const html = fs.readFileSync(output, 'utf8');
const [, x, width] = html.match(/structural-frame-label-mask" x="([\d.]+)" y="[\d.]+" width="([\d.]+)"/).map(Number);
const routeX = Number(html.match(/data-edge-id="read"[^>]*data-composition-points="([\d.]+),/)[1]);
assert.ok(routeX < x - 2 || routeX > x + width + 2, JSON.stringify({ x, width, routeX }));
});
test('showcase moves a boundary title around an authored connection label', t => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-title-authored-label-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
fs.writeFileSync(input, JSON.stringify({
schema_version: 1,
diagram_type: 'architecture',
meta: { title: 'Title', output: 'diagram.html', quality_profile: 'showcase' },
components: [
{ id: 'cache', type: 'database', label: 'Cache', pos: [40, 40], size: [100, 64] },
{ id: 'api', type: 'backend', label: 'API', pos: [60, 220], size: [260, 80] },
{ id: 'a', type: 'backend', label: 'A', pos: [400, 300], size: [200, 80] },
{ id: 'b', type: 'backend', label: 'B', pos: [800, 300], size: [200, 80] },
],
connections: [
{ id: 'read', from: 'api', to: 'cache' },
{ id: 'other', from: 'a', to: 'b', label: 'read', labelAt: [165, 208] },
],
boundaries: [{ kind: 'region', label: 'Backend services', wraps: ['api'] }],
}));
const result = spawnSync(process.execPath, [cli, 'render', 'architecture', input, output, '--quality', 'showcase'], { cwd: directory, encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
const html = fs.readFileSync(output, 'utf8');
const [, x, width] = html.match(/structural-frame-label-mask" x="([\d.]+)" y="[\d.]+" width="([\d.]+)"/).map(Number);
// The authored label occupies x=150..180; the title must move past it,
// rather than asking the author to repair an overlap introduced by layout.
assert.ok(x > 180 || x + width < 150, JSON.stringify({ x, width }));
assert.match(html, /x="165" y="208"/);
});
test('showcase uses a clear off-centre corner when central ports force a detour', t => {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-corner-port-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const diagram = {
schema_version: 1, diagram_type: 'architecture',
meta: { title: 'Shared client', output: 'diagram.html', quality_profile: 'showcase' },
components: [
{ id: 'entry', type: 'backend', label: 'Entry', pos: [350, 200], size: [240, 80] },
{ id: 'service', type: 'backend', label: 'Service', pos: [760, 200], size: [290, 90] },
{ id: 'catalog', type: 'backend', label: 'Catalog', pos: [350, 390], size: [290, 90] },
{ id: 'client', type: 'backend', label: 'Client', pos: [760, 390], size: [290, 90] },
],
connections: [
{ id: 'dispatch', from: 'entry', to: 'service', label: '解析空间后调用' },
{ id: 'reply', from: 'service', to: 'entry', label: '受理 / 状态 / 失败' },
{ id: 'register', from: 'service', to: 'catalog', label: '检查通过后选空间' },
{ id: 'metadata', from: 'catalog', to: 'client', label: '目录 / 元数据 API' },
{ id: 'write', from: 'service', to: 'client', label: '消息写入 / 状态查询' },
],
};
const original = JSON.stringify(diagram);
fs.writeFileSync(input, original);
const result = spawnSync(process.execPath, [cli, 'render', 'architecture', input, output, '--quality', 'showcase'], {
cwd: directory, encoding: 'utf8',
});
assert.equal(result.status, 0, result.stderr);
const html = fs.readFileSync(output, 'utf8');
const route = id => html.match(new RegExp(`data-edge-id="${id}"[^>]*data-composition-points="([^"]+)"`))[1].split(';').map(point => point.split(',').map(Number));
const points = route('register');
assert.equal(points.length, 3, `a legal corner needs one bend: ${JSON.stringify(points)}`);
for (const id of ['dispatch', 'reply', 'metadata', 'write']) {
assert.equal(route(id).length, 2, `${id} retains its straight route`);
}
assert.ok(points[0][1] <= 274, 'source port retains the 16px corner inset');
assert.ok(points.at(-1)[0] <= 624, 'target port retains the 16px corner inset');
for (const { label } of diagram.connections) assert.ok(html.includes(`>${label}</text>`), label);
assert.equal(fs.readFileSync(input, 'utf8'), original);
});
test('a two-bend automatic branch can use a clear corner without disturbing the main route', () => {
const boxes = new Map([
box('build', 400, 305, 235, 76), box('data', 40, 305, 235, 76),
box('output', 40, 445, 235, 76), box('main', 400, 520, 235, 76),
]);
for (const pinned of [false, true]) {
const connections = [
{ id: 'input', from: 'data', to: 'build' },
{ id: 'branch', from: 'build', to: 'output', ...(pinned ? { fromSide: 'left', toSide: 'right' } : {}) },
{ id: 'main', from: 'build', to: 'main' },
];
const original = structuredClone(connections);
const router = createRouter(boxes, connections, { distinctAutomaticPorts: true, preferReadableRoutes: true });
const points = router.pathFor(connections[1]).points;
assert.equal(points.length, pinned ? 4 : 3, `authored sides remain authoritative: ${JSON.stringify({ pinned, points })}`);
for (const edge of [connections[0], connections[2]]) {
assert.equal(router.pathFor(edge).points.length, 2, `${edge.id} stays straight`);
}
assert.deepEqual(connections, original);
}
});