Skip to content

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

6.4 KB
Raw Blame
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 test from 'node:test';
import { fileURLToPath } from 'node:url';

const root = fileURLToPath(new URL('../archify/', import.meta.url));
const cli = path.join(root, 'bin/archify.mjs');

function component(id, pos, size = [120, 60]) {
  return { id, type: 'backend', label: id, pos, size };
}

function validate(t, diagram, extra = []) {
  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-route-detour-'));
  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
  const input = path.join(directory, 'diagram.json');
  fs.writeFileSync(input, JSON.stringify(diagram));
  const result = spawnSync(process.execPath, [
    cli, 'validate', 'architecture', input, '--quality', diagram.meta.quality_profile,
    '--layout-json', '--json', ...extra,
  ], { cwd: directory, encoding: 'utf8' });
  assert.equal(result.stderr, '', result.stderr);
  return { result, receipt: JSON.parse(result.stdout) };
}

function longDetour(profile = 'showcase') {
  return {
    schema_version: 1,
    diagram_type: 'architecture',
    meta: { title: 'Long detour', output: 'diagram.html', quality_profile: profile },
    components: [
      component('sources', [60, 300], [150, 64]),
      component('worker', [410, 300], [150, 64]),
      component('cache', [290, 480], [150, 64]),
    ],
    connections: [{
      id: 'sources-to-worker', from: 'sources', to: 'worker', label: 'collect',
      fromSide: 'bottom', toSide: 'bottom', via: [[135, 1120], [485, 1120]],
    }],
  };
}

test('showcase rejects an authored route whose empty-space detour is far longer than a legal orthogonal route', t => {
  const { result, receipt } = validate(t, longDetour());
  assert.equal(result.status, 1);
  const diagnosis = receipt.diagnostics.find(({ code }) => code === 'composition/excessive-route-detour');
  assert.ok(diagnosis, JSON.stringify(receipt));
  assert.equal(diagnosis.subject.id, 'sources-to-worker');
  assert.equal(diagnosis.evidence.actualLengthPx, 1862);
  assert.equal(diagnosis.evidence.shortestLegalLengthPx, 358);
  assert.equal(diagnosis.evidence.detourRatio, 5.2);
  assert.equal(diagnosis.evidence.emptyExcursionPx.bottom, 576);
  assert.equal(diagnosis.evidence.emptyControlPointClearancePx.maximum, 731);
  assert.deepEqual(diagnosis.evidence.shortestLegalPoints, [
    [135, 364], [135, 368], [485, 368], [485, 364],
  ]);
  assert.match(diagnosis.supportedFixes.join(' '), /remove the distant via points/);
});

test('an unnecessary control corridor is diagnosed inside a large content envelope', t => {
  const diagram = {
    schema_version: 1,
    diagram_type: 'architecture',
    meta: { title: 'Internal empty corridor', output: 'diagram.html', quality_profile: 'showcase' },
    components: [
      component('source', [60, 100]),
      component('target', [410, 100]),
      component('lower-content', [60, 700]),
    ],
    connections: [{
      id: 'internal-detour', from: 'source', to: 'target',
      fromSide: 'bottom', toSide: 'bottom', via: [[120, 500], [470, 500]],
    }],
  };
  const { result, receipt } = validate(t, diagram);
  assert.equal(result.status, 1);
  const diagnosis = receipt.diagnostics.find(({ code }) => code === 'composition/excessive-route-detour');
  assert.ok(diagnosis, JSON.stringify(receipt));
  assert.equal(diagnosis.evidence.emptyExcursionPx.maximum, 0);
  assert.equal(diagnosis.evidence.emptyControlPointClearancePx.maximum, 340);
});

test('the same relationship passes after the unnecessary authored detour is removed', t => {
  const diagram = longDetour();
  diagram.connections[0] = { id: 'sources-to-worker', from: 'sources', to: 'worker', label: 'collect' };
  const { result, receipt } = validate(t, diagram);
  assert.equal(result.status, 0, result.stdout);
  assert.equal(receipt.ok, true);
});

test('standard keeps authored route freedom while showcase owns the compactness gate', t => {
  const { result, receipt } = validate(t, longDetour('standard'));
  assert.equal(result.status, 0, result.stdout);
  assert.equal(receipt.ok, true);
});

test('an explicit route around an opaque obstacle is not reported as an excessive detour', t => {
  const diagram = {
    schema_version: 1,
    diagram_type: 'architecture',
    meta: { title: 'Obstacle route', output: 'diagram.html', quality_profile: 'showcase' },
    components: [
      component('source', [60, 100]),
      component('blocker', [240, 80], [100, 100]),
      component('target', [410, 100]),
    ],
    connections: [{
      id: 'around-blocker', from: 'source', to: 'target',
      fromSide: 'right', toSide: 'left',
      via: [[200, 130], [200, 190], [390, 190], [390, 130]],
    }],
  };
  const { result, receipt } = validate(t, diagram);
  assert.equal(result.status, 0, result.stdout);
  assert.equal(receipt.ok, true);
});

test('a related shared outer corridor is treated as an intentional bus', t => {
  const diagram = {
    schema_version: 1,
    diagram_type: 'architecture',
    meta: { title: 'Shared bus', output: 'diagram.html', quality_profile: 'showcase' },
    components: [
      component('source', [60, 100]),
      component('first', [410, 100]),
      component('second', [410, 260]),
    ],
    connections: [
      {
        id: 'bus-first', from: 'source', to: 'first',
        fromSide: 'bottom', toSide: 'bottom', via: [[120, 700], [470, 700]],
      },
      {
        id: 'bus-second', from: 'source', to: 'second',
        fromSide: 'bottom', toSide: 'bottom', via: [[120, 700], [470, 700]],
      },
    ],
  };
  const { receipt } = validate(t, diagram);
  assert.equal(
    receipt.diagnostics?.some(({ code }) => code === 'composition/excessive-route-detour') || false,
    false,
    JSON.stringify(receipt),
  );
});

test('a direct relationship crossing a region boundary is not a detour', t => {
  const diagram = {
    schema_version: 1,
    diagram_type: 'architecture',
    meta: { title: 'Boundary crossing', output: 'diagram.html', quality_profile: 'showcase' },
    components: [component('outside', [40, 120]), component('inside', [340, 120])],
    boundaries: [{ kind: 'region', label: 'Runtime', wraps: ['inside'] }],
    connections: [{ id: 'enter', from: 'outside', to: 'inside' }],
  };
  const { result, receipt } = validate(t, diagram);
  assert.equal(result.status, 0, result.stdout);
  assert.equal(receipt.ok, true);
});