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 { createHash } from 'node:crypto';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
FINALIZE_STAGES,
compactFinalizeReceipt,
defaultFinalizeReceiptPath,
defaultFinalizeSummaryPath,
runFinalize,
} from '../archify/bin/finalize.mjs';
import { CAPTURE_VIEWPORTS, VISUAL_CHECK_VIEWPORTS } from '../archify/bin/visual-check.mjs';
import { bipartiteArchitectureSpec } from './helpers/dense-fixture.mjs';
function workspace(t) {
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-finalize-'));
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
return directory;
}
function result(receipt, status = 0, stderr = '') {
return { status, signal: null, stdout: `${JSON.stringify(receipt)}\n`, stderr };
}
function artifactIdentity(contents) {
const bytes = Buffer.isBuffer(contents) ? contents : Buffer.from(contents);
return {
sha256: createHash('sha256').update(bytes).digest('hex'),
bytes: bytes.byteLength,
};
}
function writeCurrentDelivery(output, receipt) {
fs.writeFileSync(output.replace(/\.html?$/i, '.delivery.json'), `${JSON.stringify({
schemaVersion: 1,
receiptId: receipt.receiptId,
status: 'current',
command: 'deliver',
type: receipt.type,
input: receipt.input,
output: receipt.output,
specification: receipt.specification,
artifact: receipt.artifact,
})}\n`);
}
function passingDelivery({ input, output, source, artifact = '<!doctype html><title>verified</title>', receiptId = '11111111-1111-4111-8111-111111111111', quality = 'showcase', type = 'architecture' }) {
fs.writeFileSync(output, artifact);
const receipt = {
schemaVersion: 1,
receiptId,
ok: true,
command: 'deliver',
type,
input,
output,
specification: artifactIdentity(source),
artifact: artifactIdentity(artifact),
validation: {
checksPassed: 9,
checkCount: 9,
compositionProfile: quality,
compositionStatus: 'pass',
errors: 0,
warnings: 0,
},
};
writeCurrentDelivery(output, receipt);
return receipt;
}
function passingCheck({ output, artifact, deliveryReceiptId, quality = 'showcase', checkCount = 9 }) {
return {
schemaVersion: 1,
ok: true,
file: output,
artifact,
checks: Array.from({ length: checkCount }, (_, index) => ({ name: `artifact-${index}`, ok: true })),
provenance: 'current',
deliveryReceiptId,
composition: {
schemaVersion: 1,
profile: quality,
status: 'pass',
summary: { errors: 0, warnings: 0 },
},
};
}
function passingBrowserCheck({ output, artifact, deliveryReceiptId, outDir }) {
return {
schemaVersion: 1,
ok: true,
command: 'browser-check',
evidenceKind: 'automated-browser',
status: 'pass',
visualReview: 'not-requested',
provenance: 'current',
deliveryReceiptId,
artifact: { path: output, ...artifact },
diagnostics: [],
containment: {
status: 'pass',
viewports: VISUAL_CHECK_VIEWPORTS.map(({ width, height }) => ({ width, height, theme: 'light', ok: true })),
},
themeStates: {
status: 'pass',
viewports: [
...VISUAL_CHECK_VIEWPORTS.map((viewport) => ({ ...viewport, requestedTheme: 'light', resolvedTheme: 'light', ok: true })),
...CAPTURE_VIEWPORTS.map((viewport) => ({ ...viewport, requestedTheme: 'dark', resolvedTheme: 'dark', ok: true })),
],
},
readability: {
status: 'pass',
viewports: VISUAL_CHECK_VIEWPORTS.map(({ width, height }) => ({ width, height, theme: 'light', ok: true, readabilityOk: true })),
},
viewerChrome: {
status: 'pass',
viewports: VISUAL_CHECK_VIEWPORTS.map(({ width, height }) => ({ width, height, theme: 'light', ok: true, viewerChromeOk: true })),
},
captures: { status: 'not-requested', screenshots: [], contactSheet: null, contactSheetImage: null },
sidecars: { directory: outDir, receipt: 'diagram.browser-check.json' },
};
}
test('finalize reuses delivery validation, runs one build, and keeps full stage receipts out of its compact summary', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const outDir = path.join(directory, 'evidence');
const source = '{"meta":{"quality_profile":"showcase"}}';
fs.writeFileSync(input, source);
const calls = [];
const runCommand = ({ stage, args }) => {
calls.push({ stage, args });
if (stage === 'deliver') {
return result(passingDelivery({ input, output, source }));
}
if (stage === 'check') {
const delivery = passingDelivery({ input, output, source });
return result(passingCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId }));
}
fs.mkdirSync(outDir, { recursive: true });
fs.writeFileSync(path.join(outDir, 'diagram.browser-check.json'), 'browser evidence');
const delivery = passingDelivery({ input, output, source });
const browser = passingBrowserCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir });
browser.containment.viewports[0].large = 'large-stage-array-is-kept-only-in-full-receipt';
return result(browser);
};
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
outDir,
runCommand,
});
assert.equal(finalized.exitCode, 0);
assert.equal(finalized.receipt.ok, true);
assert.deepEqual(calls.map(({ stage }) => stage), ['deliver', 'check', 'browser-check']);
assert.deepEqual(finalized.summary.gates, {
validate: 'pass', deliver: 'pass', check: 'pass', 'browser-check': 'pass',
});
assert.equal(finalized.summary.evidence.browserCheckReceipt, path.join(outDir, 'diagram.browser-check.json'));
assert.equal(finalized.summary.visualReview, 'not-requested');
assert.equal('stages' in finalized.summary, false);
assert.equal(JSON.stringify(finalized.summary).includes('large-stage-array'), false);
assert.equal(finalized.receipt.stages['browser-check'].receipt.containment.viewports.length, VISUAL_CHECK_VIEWPORTS.length);
const receiptPath = defaultFinalizeReceiptPath(output, { outDir });
assert.equal(finalized.summary.evidence.receipt, receiptPath);
const summaryPath = defaultFinalizeSummaryPath(receiptPath);
assert.equal(finalized.summary.evidence.summaryReceipt, summaryPath);
const persisted = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
assert.equal(persisted.ok, true);
assert.equal(persisted.stages.validate.execution, 'embedded-in-deliver');
assert.equal(persisted.stages.validate.receipt.validation.checkCount, 9);
const persistedSummary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
assert.equal(persistedSummary.ok, true);
assert.equal('stages' in persistedSummary, false);
});
test('finalize stops at the failed gate and persists actionable failure evidence', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
fs.writeFileSync(input, '{}');
const calls = [];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'workflow',
input,
output,
runCommand: ({ stage }) => {
calls.push(stage);
return result({
ok: false,
command: 'deliver',
stage: 'render',
diagnostics: [{
code: 'composition/route-crossing',
severity: 'error',
message: 'A route crosses an unrelated node.',
subject: { edge: 'a-b' },
evidence: { intersection: [12, 40] },
supportedFixes: ['move the diagnosed route'],
}],
}, 1);
},
});
assert.equal(finalized.exitCode, 1);
assert.deepEqual(calls, ['deliver']);
assert.equal(finalized.receipt.failedStage, 'validate');
assert.equal(finalized.summary.gates.deliver, 'not-run');
assert.equal(finalized.summary.gates.check, 'not-run');
assert.equal(finalized.summary.gates['browser-check'], 'not-run');
assert.deepEqual(finalized.summary.diagnostics, [{
code: 'composition/route-crossing',
severity: 'error',
message: 'A route crosses an unrelated node.',
subject: { edge: 'a-b' },
evidence: { intersection: [12, 40] },
supportedFixes: ['move the diagnosed route'],
}]);
assert.deepEqual(finalized.summary.diagnosticSummary, { total: 1, shown: 1, truncated: false });
assert.deepEqual(finalized.summary.nextAction, {
action: 'edit-in-place',
candidate: input,
constraint: 'Preserve unaffected semantics and geometry; apply each diagnostic\'s supportedFixes, or the fix its message names, and do not replace the whole candidate.',
then: 'finalize-once',
});
assert.equal(finalized.receipt.diagnostics[0].evidence.intersection[1], 40);
assert.equal(JSON.parse(fs.readFileSync(finalized.summary.evidence.receipt)).status, 'fail');
const persistedSummary = JSON.parse(fs.readFileSync(finalized.summary.evidence.summaryReceipt));
assert.deepEqual(persistedSummary, finalized.summary);
});
test('compact finalize receipts preserve the acceptance boundary', () => {
const compact = compactFinalizeReceipt({
ok: true,
status: 'pass',
type: 'sequence',
quality: 'showcase',
specification: { path: '/tmp/spec.json', sha256: 'spec' },
artifact: { path: '/tmp/artifact.html', sha256: 'artifact' },
stages: Object.fromEntries(['validate', 'deliver', 'check', 'browser-check'].map((stage) => [stage, { status: 'pass' }])),
diagnostics: [],
evidence: { receipt: '/tmp/artifact.finalize.json', browserCheckReceipt: '/tmp/artifact.browser-check.json' },
visualReview: 'not-requested',
durationMs: 4200,
});
assert.equal(compact.ok, true);
assert.equal(compact.visualReview, 'not-requested');
assert.equal(compact.gates['browser-check'], 'pass');
assert.equal(compact.evidence.browserCheckReceipt.endsWith('.json'), true);
assert.deepEqual(compact.diagnosticSummary, { total: 0, shown: 0, truncated: false });
assert.equal('nextAction' in compact, false);
});
test('compact success retains route-quality review signals without claiming perceptual approval', () => {
const compact = compactFinalizeReceipt({
ok: true, status: 'pass', diagnostics: [],
stages: { check: { status: 'pass', receipt: { composition: { metrics: {
resolvedCrossovers: 12, routesOverSuggestedBends: 11, routesOverSuggestedStretch: 0,
} } } } },
});
assert.equal(compact.ok, true);
assert.equal(compact.visualReview, 'not-requested');
assert.deepEqual(compact.visualReviewRecommendation.signals, { resolvedCrossovers: 12, routesOverSuggestedBends: 11 });
assert.equal(compact.visualReviewRecommendation.action, 'inspect-route-readability');
const uncomplicated = compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: { metrics: {
resolvedCrossovers: 0, routesOverSuggestedBends: 0, routesOverSuggestedStretch: 0,
} } } } } });
assert.equal('visualReviewRecommendation' in uncomplicated, false);
});
test('compact leading-space advice preserves successful gates and optional visual review', () => {
const leadingSpace = { occupiedTop: 181, emptyTopPx: 181, canvasHeight: 576,
emptyTopRatio: 181 / 576, reviewSuggested: true };
const receipt = { ok: true, status: 'pass', diagnostics: [], stages: {
check: { status: 'pass', receipt: { composition: { leadingSpace } } },
} };
const compact = compactFinalizeReceipt(receipt);
assert.equal(compact.status, 'pass');
assert.equal(compact.gates.check, 'pass');
assert.deepEqual(compact.diagnostics, []);
assert.equal(compact.visualReview, 'not-requested');
assert.equal(compact.layoutReviewRecommendation.action, 'inspect-leading-space');
assert.deepEqual(compact.layoutReviewRecommendation.evidence, leadingSpace);
assert.match(compact.layoutReviewRecommendation.repair, /user-fixed geometry/);
assert.match(compact.layoutReviewRecommendation.repair, /No screenshot is required/);
leadingSpace.reviewSuggested = false;
assert.equal('layoutReviewRecommendation' in compactFinalizeReceipt(receipt), false);
leadingSpace.reviewSuggested = true;
assert.equal('layoutReviewRecommendation' in compactFinalizeReceipt({ ...receipt, ok: false, status: 'fail' }), false);
});
test('compact success bounds review context and preserves relationship identity', () => {
const crossings = Array.from({ length: 10 }, (_, index) => ({ left: { id: `edge-${index}` }, right: { id: 'hub' }, point: [index, 50] }));
const detours = [{ relationship: { id: 'return', from: 'worker', to: 'api' }, bends: 4, stretch: 1.5,
directCorridorBlockers: [{ id: 'store', label: 'Shared store', box: [100, 40, 80, 50] }],
}];
const compact = compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: {
metrics: { resolvedCrossovers: 10, routesOverSuggestedBends: 1 }, routeReview: { crossings, detours },
} } } } });
assert.deepEqual(compact.visualReviewRecommendation.affectedRoutes, {
crossings: crossings.slice(0, 8), detours, truncated: true,
});
assert.equal(crossings.length, 10, 'compaction does not truncate the full evidence');
assert.equal(compact.visualReview, 'not-requested');
assert.match(compact.visualReviewRecommendation.repair, /architecture-layout-repair\.md/);
});
test('compact success turns route evidence into node-move hints that keep relationships', () => {
const routeReview = {
crossings: [
{ left: { from: 'desktop', to: 'http' }, right: { from: 'tunnel', to: 'http' }, sharedNode: 'http' },
{ left: { from: 'teamcli', to: 'http' }, right: { from: 'runtime', to: 'sqlite' } },
],
crowdedSides: [{ node: 'app', side: 'right', relationships: 4, sidePx: 70, neededPx: 74 }],
detours: [
{ relationship: { from: 'registry', to: 'shim' }, bends: 3 },
{ relationship: { from: 'worker', to: 'api' }, bends: 4, directCorridorBlockers: [{ id: 'store' }] },
],
};
const { hints } = compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: {
metrics: { resolvedCrossovers: 2, routesOverSuggestedBends: 2 }, routeReview,
} } } } }).visualReviewRecommendation;
assert.equal(hints.length, 4, 'a detour with named corridor blockers keeps its existing repair path');
assert.match(hints[0], /app has 4 relationships facing its right side, which fits 3 ports: make that side at least 74px/);
assert.match(hints[1], /move node desktop or tunnel so the two reach http from different sides/);
assert.match(hints[2], /teamcli → http crosses runtime → sqlite/);
assert.match(hints[3], /move node registry or shim/);
assert.ok(hints.every((hint) => !/endpoint/.test(hint)), 'hints move nodes, never re-attach relationships');
assert.equal('hints' in compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: {
metrics: { resolvedCrossovers: 1 }, routeReview: { crossings: [], detours: [] },
} } } } }).visualReviewRecommendation, false);
});
test('compact failure receipts retain diverse actionable subjects without embedding full stage evidence', () => {
const diagnostics = Array.from({ length: 20 }, (_, index) => ({
code: 'composition/proper-crossing',
severity: 'error',
message: `Connection edge-${index} crosses another route.`,
subject: { id: `edge-${index}`, collection: 'connections', index },
evidence: { crossing: { x: index * 10, y: index * 20 } },
supportedFixes: [`move edge-${index} without changing its endpoints`],
}));
const receipt = {
ok: false,
status: 'fail',
failedStage: 'validate',
type: 'architecture',
quality: 'showcase',
specification: { path: '/tmp/spec.json', sha256: 'spec' },
artifact: { path: '/tmp/artifact.html' },
stages: { validate: { status: 'fail', receipt: { diagnostics, renderedHtml: 'x'.repeat(100000) } } },
diagnostics,
evidence: {
receipt: '/tmp/artifact.finalize.json',
summaryReceipt: '/tmp/artifact.finalize-summary.json',
},
};
const compact = compactFinalizeReceipt(receipt);
assert.equal(compact.diagnostics.length, 8);
assert.equal(new Set(compact.diagnostics.map(({ subject }) => subject.id)).size, 8);
assert.deepEqual(compact.diagnosticSummary, { total: 20, shown: 8, truncated: true, omittedByCode: { 'composition/proper-crossing': 12 } });
assert.equal(compact.nextAction.action, 'edit-in-place');
assert.match(compact.nextAction.constraint, /Preserve all semantics and user-fixed geometry/);
assert.match(compact.nextAction.constraint, /local repair or connected-scene reflow/);
assert.equal('stages' in compact, false);
assert.ok(JSON.stringify(compact).length < JSON.stringify(receipt).length / 4);
});
test('compact failure summaries count omitted entries by code with repeated subjects', () => {
const codes = ['composition/proper-crossing', 'layout/constraint', '__proto__'];
const diagnostics = Array.from({ length: 14 }, (_, index) => ({
code: codes[index % codes.length],
message: `Failure ${index}`,
subject: { id: `edge-${Math.floor(index / 3)}` },
}));
const receipt = { ok: false, status: 'fail', diagnostics };
const originalDiagnostics = structuredClone(diagnostics);
const compact = compactFinalizeReceipt(receipt);
assert.deepEqual(compact.diagnostics.map(({ message }) => message),
[0, 1, 2, 3, 6, 9, 12, 4].map(index => `Failure ${index}`));
const omitted = diagnostics.filter(entry => !compact.diagnostics.some(shown => shown.message === entry.message));
assert.equal(omitted.length, compact.diagnosticSummary.total - compact.diagnosticSummary.shown);
assert.deepEqual(compact.diagnosticSummary.omittedByCode, { 'layout/constraint': 3, ['__proto__']: 3 });
assert.deepEqual(Object.entries(compact.diagnosticSummary.omittedByCode), [
['layout/constraint', omitted.filter(({ code }) => code === 'layout/constraint').length],
['__proto__', omitted.filter(({ code }) => code === '__proto__').length],
]);
assert.equal(Object.values(compact.diagnosticSummary.omittedByCode).reduce((sum, count) => sum + count, 0), omitted.length);
assert.deepEqual(receipt.diagnostics, originalDiagnostics);
for (const entries of [[], diagnostics.slice(0, 8)]) {
const summary = compactFinalizeReceipt({ ...receipt, diagnostics: entries }).diagnosticSummary;
assert.equal('omittedByCode' in summary, false);
}
});
test('merged viewport-overflow diagnostics preserve each subject, evidence, and detection source', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
fs.writeFileSync(input, '{}');
const diagnostics = [
{
code: 'viewer/viewport-overflow',
severity: 'error',
message: 'meta.title overflows the 2048px viewport by 193px.',
subject: { diagramType: 'architecture', path: '/meta/title', viewport: '2048x1200' },
evidence: { scrollWidth: 2241, scrollHeight: 1200, overflowX: true, overflowY: false, overflowDisposition: 'clipped' },
supportedFixes: ['shorten meta.title'],
},
{
code: 'viewer/viewport-overflow',
severity: 'error',
message: 'meta.subtitle overflows the 2048px viewport by 91px.',
subject: { diagramType: 'architecture', path: '/meta/subtitle', viewport: '2048x1200' },
evidence: { scrollWidth: 2139, scrollHeight: 1200, overflowX: true, overflowY: false, overflowDisposition: 'clipped' },
supportedFixes: ['shorten meta.subtitle'],
},
{
code: 'viewer/viewport-overflow',
severity: 'error',
message: 'meta.title (~4090px estimated) exceeds the widest 2048px viewport — it will overflow before render.',
subject: { diagramType: 'architecture', path: '/meta/title' },
evidence: { estimatedTextWidthPx: 4090, widestViewportPx: 2048, prediction: 'text-width estimate' },
supportedFixes: ['shorten meta.title'],
},
{
code: 'layout/constraint',
severity: 'error',
message: 'Two distinct subjects share this identical message.',
subject: { diagramType: 'architecture', path: '/nodes/0/label' },
evidence: { node: 0 },
supportedFixes: [],
},
{
code: 'layout/constraint',
severity: 'error',
message: 'Two distinct subjects share this identical message.',
subject: { diagramType: 'architecture', path: '/nodes/1/label' },
evidence: { node: 1 },
supportedFixes: [],
},
];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: () => result({ ok: false, command: 'deliver', diagnostics }, 1),
});
assert.equal(finalized.exitCode, 1);
const [merged, ...rest] = finalized.receipt.diagnostics;
assert.equal(merged.code, 'viewer/viewport-overflow');
assert.equal(merged.subject.path, undefined, 'the merged entry must not keep only the first subject');
assert.equal(merged.evidence.overflows.length, 3);
assert.deepEqual(
merged.evidence.overflows.map((entry) => [entry.subject.path, entry.detection]),
[
['/meta/title', 'browser-measurement'],
['/meta/subtitle', 'browser-measurement'],
['/meta/title', 'validate-prediction'],
],
);
assert.equal(merged.evidence.overflows[0].evidence.scrollWidth, 2241);
assert.equal(merged.evidence.overflows[1].evidence.scrollWidth, 2139);
assert.equal(merged.evidence.overflows[2].evidence.estimatedTextWidthPx, 4090);
// Identical messages with different subjects are not duplicates.
assert.deepEqual(rest.map((entry) => entry.subject.path), ['/nodes/0/label', '/nodes/1/label']);
});
test('finalize refuses a receipt path that aliases a gate sidecar', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const visualReceipt = path.join(directory, 'diagram.browser-check.json');
fs.writeFileSync(input, '{}');
fs.writeFileSync(visualReceipt, 'preserve me');
let invoked = false;
await assert.rejects(() => runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
receiptPath: visualReceipt,
runCommand: () => { invoked = true; return result({ ok: true }); },
}), /gate sidecars/);
assert.equal(invoked, false);
assert.equal(fs.readFileSync(visualReceipt, 'utf8'), 'preserve me');
});
test('finalize binds a passing validate receipt to the unchanged candidate', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"quality_profile":"showcase"}}';
fs.writeFileSync(input, source);
const candidateSha256 = createHash('sha256').update(source).digest('hex');
const calls = [];
const pass = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
candidateSha256,
runCommand: ({ stage }) => {
calls.push(stage);
const delivery = passingDelivery({ input, output, source, artifact: '<!doctype html>' });
if (stage === 'deliver') return result(delivery);
if (stage === 'check') return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId,
}));
return result(passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
}));
},
});
assert.equal(pass.exitCode, 0);
assert.deepEqual(calls, ['deliver', 'check', 'browser-check']);
fs.writeFileSync(input, `${source}\n`);
await assert.rejects(() => runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output: path.join(directory, 'changed.html'),
candidateSha256,
runCommand: () => { throw new Error('must not run'); },
}), error => {
assert.equal(error.finalizeCode, 'finalize/candidate-changed');
assert.equal(error.finalizeEvidence.expectedSha256, candidateSha256);
return true;
});
});
test('finalize fails closed when a stage exits zero without a valid passing receipt', async t => {
const invalidOutputs = [
'',
'not json',
'{}',
'"success"',
'{"ok":true,"status":"fail","command":"validate","checks":[]}',
];
for (const [index, stdout] of invalidOutputs.entries()) {
const directory = workspace(t);
const input = path.join(directory, `diagram-${index}.json`);
const output = path.join(directory, `diagram-${index}.html`);
fs.writeFileSync(input, '{}');
const calls = [];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
calls.push(stage);
return { status: 0, signal: null, stdout, stderr: '' };
},
});
assert.equal(finalized.exitCode, 1, `invalid receipt ${index} must fail`);
assert.deepEqual(calls, ['deliver']);
assert.equal(finalized.receipt.failedStage, 'deliver');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/invalid-stage-receipt');
}
});
test('showcase delivery warnings name the checker issue without advancing to later gates', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"quality_profile":"showcase"}}';
fs.writeFileSync(input, source);
const calls = [];
const issue = {
severity: 'warning', code: 'composition/viewport-height',
viewBoxHeight: 700, overflowPx: 193,
detail: '[composition/viewport-height] Preserve every node and compact vertical spacing to fit the Reader.',
};
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs', type: 'architecture', input, output,
runCommand: ({ stage }) => {
calls.push(stage);
const delivery = passingDelivery({ input, output, source });
delivery.validation.warnings = 1;
delivery.validation.compositionIssues = [issue];
return result(delivery);
},
});
assert.equal(finalized.exitCode, 1);
assert.deepEqual(calls, ['deliver']);
assert.equal(finalized.receipt.failedStage, 'deliver');
assert.equal(finalized.summary.gates.deliver, 'fail');
assert.equal(finalized.summary.gates.check, 'not-run');
assert.equal(finalized.summary.diagnostics[0].code, issue.code);
assert.equal(finalized.summary.diagnostics[0].evidence.overflowPx, 193);
assert.match(finalized.summary.diagnostics[0].supportedFixes[0], /compact vertical spacing/);
assert.equal(finalized.summary.diagnostics[0].evidence.reportedSeverity, 'warning');
assert.equal(JSON.parse(fs.readFileSync(finalized.summary.evidence.receipt)).diagnostics[0].code, issue.code);
});
test('showcase warning diagnostic never masks a mismatched delivery artifact', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{}';
fs.writeFileSync(input, source);
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs', type: 'architecture', input, output,
runCommand: () => {
const delivery = passingDelivery({ input, output, source });
delivery.validation.warnings = 1;
delivery.validation.compositionIssues = [{
severity: 'warning', code: 'composition/viewport-height', detail: 'Reduce height.',
}];
delivery.artifact = artifactIdentity('another artifact');
return result(delivery);
},
});
assert.equal(finalized.exitCode, 1);
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/artifact-binding-mismatch');
});
test('showcase warning count without matching issue details still fails with a quality diagnostic', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{}';
fs.writeFileSync(input, source);
const calls = [];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs', type: 'workflow', input, output,
runCommand: ({ stage }) => {
calls.push(stage);
const delivery = passingDelivery({ input, output, source, type: 'workflow' });
delivery.validation.warnings = 1;
delivery.validation.compositionIssues = [{ severity: 'warning', code: 'composition/viewport-height' }];
return result(delivery);
},
});
assert.equal(finalized.exitCode, 1);
assert.deepEqual(calls, ['deliver']);
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/showcase-warnings');
assert.equal(finalized.summary.diagnostics[0].evidence.warnings, 1);
});
test('public deliver and finalize CLI propagate a real workflow viewport warning', t => {
const directory = workspace(t);
const input = path.join(directory, 'warning.workflow.json');
const output = path.join(directory, 'warning.html');
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
fs.writeFileSync(input, `${JSON.stringify({
schema_version: 1,
diagram_type: 'workflow',
meta: {
title: 'Viewport warning fixture', output: 'warning.html',
quality_profile: 'showcase', viewBox: [1080, 780], legend: { mode: 'hidden' },
},
lanes: [{ id: 'work', label: 'Work' }],
nodes: [
{ id: 'start', lane: 'work', col: 0, type: 'frontend', label: 'Start' },
{ id: 'finish', lane: 'work', col: 2, type: 'backend', label: 'Finish' },
],
edges: [{ id: 'flow', from: 'start', to: 'finish' }],
}, null, 2)}\n`);
const run = (command) => spawnSync(process.execPath, [
cli, command, 'workflow', input, ...(command === 'validate' ? [] : [output]),
'--quality', 'showcase', '--json',
], { encoding: 'utf8', timeout: 30000 });
const validated = run('validate');
assert.equal(validated.status, 0, validated.stderr || validated.stdout);
const validation = JSON.parse(validated.stdout);
assert.equal(validation.checks.length, 9);
assert.equal(validation.checks.every((check) => check.ok), true);
assert.deepEqual(validation.composition.summary, { errors: 0, warnings: 1 });
const delivered = run('deliver');
assert.equal(delivered.status, 0, delivered.stderr || delivered.stdout);
const delivery = JSON.parse(delivered.stdout);
assert.equal(delivery.validation.checksPassed, 9);
assert.equal(delivery.validation.errors, 0);
assert.equal(delivery.validation.warnings, 1);
assert.equal(delivery.validation.compositionIssues.length, 1);
assert.equal(delivery.validation.compositionIssues[0].code, 'composition/viewport-height');
const finalized = run('finalize');
assert.equal(finalized.status, 1, finalized.stderr || finalized.stdout);
const summary = JSON.parse(finalized.stdout);
assert.equal(summary.failedStage, 'deliver');
assert.equal(summary.gates.check, 'not-run');
assert.equal(summary.diagnostics[0].code, 'composition/viewport-height');
assert.equal(summary.diagnostics[0].evidence.overflowPx, validation.composition.issues[0].overflowPx);
assert.match(summary.diagnostics[0].supportedFixes[0], /meta\.viewBox height/);
assert.equal(JSON.parse(fs.readFileSync(summary.evidence.receipt)).diagnostics[0].code, 'composition/viewport-height');
});
test('finalize rejects an interleaved delivery whose check proves another artifact and receipt', async t => {
const directory = workspace(t);
const input = path.join(directory, 'a.json');
const replacement = path.join(directory, 'b.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"A"}}';
const replacementSource = '{"meta":{"title":"B"}}';
fs.writeFileSync(input, source);
fs.writeFileSync(replacement, replacementSource);
const calls = [];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
calls.push(stage);
if (stage === 'deliver') return result(passingDelivery({
input, output, source, artifact: '<!doctype html><title>A</title>', receiptId: '11111111-1111-4111-8111-111111111111',
}));
const deliveredB = passingDelivery({
input: replacement,
output,
source: replacementSource,
artifact: '<!doctype html><title>B</title>',
receiptId: '22222222-2222-4222-8222-222222222222',
});
return result(passingCheck({
output,
artifact: deliveredB.artifact,
deliveryReceiptId: deliveredB.receiptId,
}));
},
});
assert.equal(finalized.exitCode, 1);
assert.deepEqual(calls, ['deliver', 'check']);
assert.equal(finalized.receipt.failedStage, 'check');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/artifact-binding-mismatch');
assert.equal(finalized.summary.diagnostics[0].evidence.expectedDeliveryReceiptId, '11111111-1111-4111-8111-111111111111');
assert.equal(finalized.summary.diagnostics[0].evidence.actualDeliveryReceiptId, '22222222-2222-4222-8222-222222222222');
});
test('finalize verifies the artifact and delivery sidecar after browser evidence completes', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"stable"}}';
fs.writeFileSync(input, source);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(delivery);
}
if (stage === 'check') return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId,
}));
const browser = passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
});
fs.unlinkSync(output);
return result(browser);
},
});
assert.equal(finalized.exitCode, 1);
assert.equal(finalized.receipt.failedStage, 'finalize');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/final-artifact-mismatch');
assert.deepEqual(finalized.receipt.artifact, { path: output });
});
test('a successful finalize receipt keeps the delivery identity after its final verification snapshot', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"stable"}}';
fs.writeFileSync(input, source);
let delivery;
let originalRead;
let mutated = false;
try {
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source, artifact: '<!doctype html><title>A</title>' });
return result(delivery);
}
if (stage === 'check') return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId,
}));
const browser = passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
});
originalRead = fs.readFileSync;
fs.readFileSync = function interceptedRead(file, ...args) {
const contents = originalRead.call(this, file, ...args);
if (!mutated && path.resolve(file) === output) {
mutated = true;
fs.writeFileSync(output, '<!doctype html><title>B</title>');
}
return contents;
};
return result(browser);
},
});
assert.equal(mutated, true);
assert.equal(finalized.exitCode, 0);
assert.equal(finalized.receipt.ok, true);
assert.deepEqual(finalized.receipt.artifact, { path: output, ...delivery.artifact });
assert.notDeepEqual(artifactIdentity(fs.readFileSync(output)), delivery.artifact);
} finally {
if (originalRead) fs.readFileSync = originalRead;
}
});
test('finalize rejects a delivery sidecar replaced after the browser receipt', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const replacement = path.join(directory, 'replacement.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"stable"}}';
const replacementSource = '{"meta":{"title":"replacement"}}';
fs.writeFileSync(input, source);
fs.writeFileSync(replacement, replacementSource);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(delivery);
}
if (stage === 'check') return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId,
}));
const browser = passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
});
const replacementDelivery = {
...delivery,
receiptId: '22222222-2222-4222-8222-222222222222',
input: replacement,
specification: artifactIdentity(replacementSource),
};
writeCurrentDelivery(output, replacementDelivery);
return result(browser);
},
});
assert.equal(finalized.exitCode, 1);
assert.equal(finalized.receipt.failedStage, 'finalize');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/final-artifact-mismatch');
assert.equal(finalized.summary.diagnostics[0].evidence.currentDeliveryReceiptId, '22222222-2222-4222-8222-222222222222');
});
test('finalize rejects a delivery type mismatch before checking a different diagram contract', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"type"}}';
fs.writeFileSync(input, source);
const calls = [];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
calls.push(stage);
return result(passingDelivery({ input, output, source, type: 'workflow' }));
},
});
assert.equal(finalized.exitCode, 1);
assert.deepEqual(calls, ['deliver']);
assert.equal(finalized.receipt.failedStage, 'deliver');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/delivery-type-mismatch');
assert.deepEqual(finalized.summary.diagnostics[0].evidence, {
expectedType: 'architecture', actualType: 'workflow',
});
});
test('finalize rejects a final delivery sidecar whose type no longer matches the requested diagram', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"type-sidecar"}}';
fs.writeFileSync(input, source);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(delivery);
}
if (stage === 'check') return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId,
}));
writeCurrentDelivery(output, { ...delivery, type: 'workflow' });
return result(passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
}));
},
});
assert.equal(finalized.exitCode, 1);
assert.equal(finalized.receipt.failedStage, 'finalize');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/final-artifact-mismatch');
assert.equal(finalized.summary.diagnostics[0].evidence.currentType, 'workflow');
});
test('finalize rejects a showcase delivery whose count does not match the complete artifact checker', async t => {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"incomplete"}}';
fs.writeFileSync(input, source);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
delivery.validation.checksPassed = 4;
delivery.validation.checkCount = 4;
return result(delivery);
}
return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, checkCount: 9,
}));
},
});
assert.equal(finalized.exitCode, 1);
assert.equal(finalized.receipt.failedStage, 'check');
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/delivery-validation-mismatch');
assert.deepEqual(finalized.summary.diagnostics[0].evidence, {
deliveryCheckCount: 4, checkerCheckCount: 9,
});
});
test('finalize requires the canonical check and browser artifact paths without inventing fallbacks', async t => {
const cases = [
{
stage: 'check',
receipt: ({ output, delivery }) => {
const receipt = passingCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId });
delete receipt.file;
return receipt;
},
},
{
stage: 'browser-check',
receipt: ({ output, delivery, directory }) => {
const receipt = passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
});
delete receipt.artifact.path;
return receipt;
},
},
];
for (const scenario of cases) {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"path"}}';
fs.writeFileSync(input, source);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(delivery);
}
if (stage === 'check') {
return result(scenario.stage === stage
? scenario.receipt({ output, delivery, directory })
: passingCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId }));
}
return result(scenario.receipt({ output, delivery, directory }));
},
});
assert.equal(finalized.exitCode, 1, scenario.stage);
assert.equal(finalized.receipt.failedStage, scenario.stage);
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/artifact-binding-mismatch');
}
});
test('finalize requires complete passing browser evidence coverage', async t => {
const cases = [
{
name: 'missing containment viewport',
mutate: (receipt) => { receipt.containment.viewports.pop(); },
},
{
name: 'null containment viewport before a valid matching entry',
mutate: (receipt) => { receipt.containment.viewports = [null, ...receipt.containment.viewports.slice(0, -1)]; },
},
{
name: 'failed readability child',
mutate: (receipt) => { receipt.readability.viewports[0].readabilityOk = false; },
},
{
name: 'non-light containment viewport',
mutate: (receipt) => { receipt.containment.viewports[1].theme = 'dark'; },
},
{
name: 'missing viewer chrome viewport',
mutate: (receipt) => { receipt.viewerChrome.viewports = []; },
},
{
name: 'incomplete theme coverage',
mutate: (receipt) => { receipt.themeStates.viewports.pop(); },
},
{
name: 'missing intermediate light-theme coverage',
mutate: (receipt) => {
receipt.themeStates.viewports = receipt.themeStates.viewports.filter(({ width }) => width !== 1600);
},
},
{
name: 'mismatched intermediate light theme despite passing parent status',
mutate: (receipt) => {
receipt.themeStates.viewports.find(({ width }) => width === 1920).resolvedTheme = 'dark';
},
},
];
for (const scenario of cases) {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"browser"}}';
fs.writeFileSync(input, source);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(delivery);
}
if (stage === 'check') return result(passingCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId,
}));
const browser = passingBrowserCheck({
output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory,
});
scenario.mutate(browser);
return result(browser);
},
});
assert.equal(finalized.exitCode, 1, scenario.name);
assert.equal(finalized.receipt.failedStage, 'browser-check', scenario.name);
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/invalid-stage-receipt', scenario.name);
}
});
test('finalize rejects incomplete or mismatched successful protocol receipts', async t => {
const cases = [
{
name: 'standard validation reported for a showcase delivery',
stage: 'deliver',
receipt: ({ input, output, source }) => {
const receipt = passingDelivery({ input, output, source, quality: 'standard' });
receipt.validation.checksPassed = 4;
receipt.validation.checkCount = 4;
return receipt;
},
},
{
name: 'empty artifact checker receipt',
stage: 'check',
receipt: () => ({ ok: true, artifact: {}, checks: [], provenance: 'current' }),
},
{
name: 'artifact checker child failure',
stage: 'check',
receipt: ({ output, delivery }) => ({
...passingCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId }),
checks: [{ name: 'artifact', ok: false }],
}),
},
{
name: 'minimal browser receipt',
stage: 'browser-check',
receipt: () => ({ ok: true, command: 'browser-check', status: 'pass' }),
},
];
for (const scenario of cases) {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{"meta":{"title":"protocol"}}';
fs.writeFileSync(input, source);
let delivery;
const calls = [];
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs',
type: 'architecture',
input,
output,
runCommand: ({ stage }) => {
calls.push(stage);
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(scenario.stage === stage ? scenario.receipt({ input, output, source, delivery }) : delivery);
}
if (stage === 'check') {
const receipt = scenario.stage === stage
? scenario.receipt({ input, output, source, delivery })
: passingCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId });
return result(receipt);
}
return result(scenario.receipt({ input, output, source, delivery }));
},
});
assert.equal(finalized.exitCode, 1, scenario.name);
assert.equal(finalized.receipt.failedStage, scenario.stage, scenario.name);
assert.deepEqual(calls, FINALIZE_STAGES.slice(1, FINALIZE_STAGES.indexOf(scenario.stage) + 1), scenario.name);
assert.equal(finalized.summary.diagnostics[0].code, 'finalize/invalid-stage-receipt', scenario.name);
}
});
test('finalize rechecks delivery barriers and the frozen candidate after the browser gate', async t => {
for (const scenario of ['pending-delivery', 'changed-candidate']) {
const directory = workspace(t);
const input = path.join(directory, 'diagram.json');
const output = path.join(directory, 'diagram.html');
const source = '{}';
fs.writeFileSync(input, source);
let delivery;
const finalized = await runFinalize({
cliPath: '/fake/archify.mjs', type: 'architecture', input, output,
...(scenario === 'pending-delivery' ? { inspectDelivery: () => ({
ok: false, status: 'pending', diagnostics: [{
code: 'delivery/provenance-pending', severity: 'error', message: 'A new delivery is pending.',
}],
}) } : {}),
runCommand: ({ stage }) => {
if (stage === 'deliver') {
delivery = passingDelivery({ input, output, source });
return result(delivery);
}
if (stage === 'check') return result(passingCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId }));
if (scenario === 'changed-candidate') fs.writeFileSync(input, '{"changed":true}');
return result(passingBrowserCheck({ output, artifact: delivery.artifact, deliveryReceiptId: delivery.receiptId, outDir: directory }));
},
});
assert.equal(finalized.exitCode, 1, scenario);
assert.equal(finalized.summary.failedStage, 'finalize');
assert.equal(finalized.summary.ok, false);
assert.equal(finalized.summary.diagnostics[0].code, scenario === 'pending-delivery' ? 'delivery/provenance-pending' : 'finalize/candidate-changed');
}
});
test('default finalize JSON preserves complete verified workflow repairs', t => {
const directory = workspace(t);
const input = path.join(directory, 'shared-endpoint.json');
const output = path.join(directory, 'shared-endpoint.html');
const receipt = path.join(directory, 'receipt.json');
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
const source = {
schema_version: 2,
diagram_type: 'workflow',
meta: { title: 'Shared missing endpoint', output: 'shared-endpoint.html', legend: { mode: 'hidden' } },
lanes: [{ id: 'main', label: 'M' }],
nodes: ['a', 'b', 'c'].map((id, col) => ({ id, lane: 'main', col, type: 'backend', label: id.toUpperCase() })),
edges: [{ id: 'ab', from: 'a', to: 'ghost' }, { id: 'bc', from: 'ghost', to: 'c' }],
mainPath: ['a', 'ghost', 'c'],
};
fs.writeFileSync(input, JSON.stringify(source));
const finalized = spawnSync(process.execPath, [
cli, 'finalize', 'workflow', input, output, '--quality', 'standard', '--json', '--receipt', receipt,
], { encoding: 'utf8', timeout: 30000 });
assert.equal(finalized.status, 1, finalized.stderr || finalized.stdout);
const summary = JSON.parse(finalized.stdout);
const full = JSON.parse(fs.readFileSync(receipt, 'utf8'));
const diagnostic = summary.diagnostics.find(entry => entry.code === 'workflow/unknown-edge-endpoint');
assert.ok(diagnostic);
assert.deepEqual(diagnostic.supportedFixes,
full.diagnostics.find(entry => entry.code === diagnostic.code).supportedFixes);
const candidates = new Map();
for (const fix of diagnostic.supportedFixes) {
const match = /^set (\/\S+) to verified node id "([^"]+)"$/.exec(fix);
assert.ok(match, `Expected an executable verified repoint: ${fix}`);
const [, pointer, candidate] = match;
if (!candidates.has(candidate)) candidates.set(candidate, []);
candidates.get(candidate).push(pointer);
}
assert.ok(candidates.size > 0);
for (const [candidate, pointers] of candidates) {
assert.deepEqual([...pointers].sort(), ['/edges/0/to', '/edges/1/from', '/mainPath/1']);
const repaired = structuredClone(source);
for (const pointer of pointers) {
const segments = pointer.slice(1).split('/');
const key = segments.pop();
const parent = segments.reduce((value, segment) => value[segment], repaired);
parent[key] = candidate;
}
fs.writeFileSync(input, JSON.stringify(repaired));
const validated = spawnSync(process.execPath, [
cli, 'validate', 'workflow', input, '--quality', 'standard', '--json',
], { encoding: 'utf8', timeout: 30000 });
assert.equal(validated.status, 0, validated.stderr || validated.stdout);
assert.equal(JSON.parse(validated.stdout).ok, true);
}
});
test('runFinalize reads the capture limit from the supplied env, not process.env', { timeout: 180000 }, async (t) => {
const here = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.join(here, '..', 'archify');
const cliPath = path.join(skillRoot, 'bin', 'archify.mjs');
const directory = workspace(t);
const input = path.join(directory, 'env-capture.architecture.json');
fs.writeFileSync(input, JSON.stringify(bipartiteArchitectureSpec(10)));
const output = path.join(directory, 'env-capture.html');
const missingChrome = path.join(directory, 'missing-chrome');
// The parent process sees a 5 MiB knob while the supplied env raises it
// to 10 MiB. The dense check echo sits between the two knobs (6.1 MiB on
// dev `9102a91`; it has drifted with dev-side warning volume before —
// 8.8 MiB on `7d3594e`, 10.5 MiB at 11+11 on `baffbdd3`), so a runner
// reading process.env overflows at the check gate while the child stages
// (which inherit the supplied env) pass. The overflow probe below pins
// the lower end of that window: if the echo ever drops under 5 MiB the
// test fails loudly instead of passing without exercising the regression.
// Restore, rather than clear, the variables this test overrides so a
// preconfigured environment cannot be damaged for later tests.
const previousCheckMaxBuffer = process.env.ARCHIFY_CHECK_MAX_BUFFER;
const previousChrome = process.env.ARCHIFY_CHROME;
process.env.ARCHIFY_CHECK_MAX_BUFFER = String(5 * 1024 * 1024);
process.env.ARCHIFY_CHROME = missingChrome;
t.after(() => {
if (previousCheckMaxBuffer === undefined) delete process.env.ARCHIFY_CHECK_MAX_BUFFER;
else process.env.ARCHIFY_CHECK_MAX_BUFFER = previousCheckMaxBuffer;
if (previousChrome === undefined) delete process.env.ARCHIFY_CHROME;
else process.env.ARCHIFY_CHROME = previousChrome;
});
const finalized = await runFinalize({
cliPath,
type: 'architecture',
input,
output,
quality: 'standard',
cwd: skillRoot,
env: {
...process.env,
ARCHIFY_CHECK_MAX_BUFFER: String(10 * 1024 * 1024),
ARCHIFY_CHROME: missingChrome,
},
});
assert.equal(finalized.exitCode, 2, JSON.stringify(finalized.summary?.gates || finalized.receipt?.failedStage));
assert.equal(finalized.receipt.stages.check.status, 'pass');
assert.equal(finalized.receipt.stages['browser-check'].status, 'skipped');
assert.equal(finalized.receipt.stages.check.receipt.provenance, 'current');
// Same fixture, supplied env pinned to the parent's 5 MiB: the check
// echo must overflow there, proving the window the first run relied on.
const overflowed = await runFinalize({
cliPath,
type: 'architecture',
input,
output,
quality: 'standard',
cwd: skillRoot,
env: {
...process.env,
ARCHIFY_CHECK_MAX_BUFFER: String(5 * 1024 * 1024),
ARCHIFY_CHROME: missingChrome,
},
});
assert.equal(overflowed.receipt.stages.validate.status, 'fail');
assert.equal(overflowed.receipt.stages.validate.receipt.diagnostics[0].code, 'artifact/check-output-limit');
});
test('compact review and repair guidance follow the mode and the failing diagnostics', () => {
const routeReview = { crossings: [{ left: { from: 'a', to: 'b' }, right: { from: 'c', to: 'd' } }], detours: [] };
const lifecycle = compactFinalizeReceipt({ ok: true, type: 'lifecycle', stages: { check: { receipt: { composition: {
metrics: { resolvedCrossovers: 1 }, routeReview,
} } } } }).visualReviewRecommendation;
assert.equal('hints' in lifecycle, false);
assert.doesNotMatch(lifecycle.repair, /architecture-layout-repair/);
const failure = (code) => compactFinalizeReceipt({
ok: false, status: 'fail', failedStage: 'validate', type: 'architecture',
diagnostics: [{ code, severity: 'error', message: code }],
}).nextAction.constraint;
assert.doesNotMatch(failure('composition/desktop-readability'), /architecture-layout-repair/);
assert.match(failure('composition/proper-crossing'), /architecture-layout-repair/);
});