Skip to content

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

fix(renderer): classify and format authoring failures at their source

tt-a1ibfb7603ec362
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd03a391..3ada7edd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
> Development identity: `v2.17.0-dev.1`. Not a stable release.
### Fixed
+- **Readable renderer failures.** `render` and direct renderer entry points format classified input, schema, layout, and output failures without Node stacks. Filesystem failures identify the failing operation instead of labelling output errors as unreadable input; successful artifact bytes and existing validation/delivery receipt formats remain unchanged.
- **DSH plugin refresh.** Adapter 0.2.0 pins the current Archify development snapshot, includes the newer runtime and CLI fixes, and targets DSH 0.1.2-rc.1. Release metadata replaces the frozen 0.1.0 packaging source; the tarball uses the canonical clean-Skill stager and documents independent plugin upgrades.
- **Machine-readable CLI argument failures (#330).** `validate --json` and `deliver --json` now keep invalid or missing option values, unknown options and diagram types, unsupported option combinations, and usage errors inside one versioned failure receipt on stdout. These failures use the `arguments` stage, stable diagnostic codes, and exit status 2, while human-mode stderr behavior remains unchanged.
- **Complete artifact-check receipts (#311).** The checker now lets stdout drain before exiting, so large JSON receipts remain complete through pipes. Validation, delivery, and architecture comparison retain their original success/failure status without truncated-JSON errors.
diff --git a/archify.zip b/archify.zip
index 20cff800..b7f887d6 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 301d7df7..ce215f5c 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -2,6 +2,15 @@
## Validate and deliver
+`render` and direct renderer entry points print classified authoring failures
+to stderr as readable diagnostics and exit 1. Input read/JSON parse failures
+use `input/read` or `input/json-parse`; output filesystem failures use
+`output/write` and identify the output path. Schema and layout failures keep
+their existing rule codes. Use the advertised `validate --json` or
+`deliver --json` interface for a machine receipt; `render` has no `--json` flag.
+Unexpected implementation failures retain debugging information in human
+mode and remain `internal/unclassified` in machine receipts.
+
Use `validate` after every candidate edit. CLI HTML output paths must end in `.html`, including after symbolic-link resolution.
Compare receipt paths must end in `.json`. Explicit CLI paths may be absolute or
outside the current working directory; authored `meta.output` remains confined
diff --git a/archify/renderers/shared/cli.mjs b/archify/renderers/shared/cli.mjs
index 32f66726..62032dc0 100644
--- a/archify/renderers/shared/cli.mjs
+++ b/archify/renderers/shared/cli.mjs
@@ -3,7 +3,7 @@ import path from 'node:path';
import { applyTemplate, renderCards, esc } from './utils.mjs';
import { validateSchema } from './validator.mjs';
import { verifyRepositoryEvidence } from './repository-evidence.mjs';
-import { installRendererDiagnosticBoundary, throwDiagnosticProblems } from './diagnostics.mjs';
+import { installRendererDiagnosticBoundary, throwDiagnosticError, throwDiagnosticProblems } from './diagnostics.mjs';
import { validateEngineeringProfile } from './engineering-profiles.mjs';
import { resolveOutputPath } from './output-path.mjs';
import { prepareDiagramBrandMarks } from './brand-marks.mjs';
@@ -19,7 +19,32 @@ const outputPathGuards = new Map();
export function loadDiagram({ rendererDir, diagramType, defaultExample, argv = process.argv }) {
const skillRoot = path.resolve(rendererDir, '../..');
const inputPath = path.resolve(argv[2] || path.join(skillRoot, 'examples', defaultExample));
- const diagram = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+ let input;
+ try {
+ input = fs.readFileSync(inputPath, 'utf8');
+ } catch (error) {
+ if (typeof error?.code !== 'string') throw error;
+ const message = `Input could not be read: ${error.message}`;
+ throwDiagnosticError(message, [{
+ code: 'input/read', message,
+ subject: { input: inputPath },
+ evidence: { systemCode: error.code, reason: error.message },
+ supportedFixes: ['provide one readable JSON input file'],
+ }]);
+ }
+ let diagram;
+ try {
+ diagram = JSON.parse(input);
+ } catch (error) {
+ if (!(error instanceof SyntaxError)) throw error;
+ const message = `Input JSON could not be parsed: ${error.message}`;
+ throwDiagnosticError(message, [{
+ code: 'input/json-parse', message,
+ subject: { input: inputPath },
+ evidence: { reason: error.message },
+ supportedFixes: ['repair the JSON syntax and run validation again'],
+ }]);
+ }
validateSchema(diagramType, diagram);
validateGuidedViews(diagramType, diagram);
validateRelationshipIds(diagramType, diagram);
@@ -33,7 +58,12 @@ export function loadDiagram({ rendererDir, diagramType, defaultExample, argv = p
inputPaths: [inputPath],
cwd: process.cwd(),
};
- const { outputPath: outPath } = resolveOutputPath(outputRequest);
+ let outPath;
+ try {
+ ({ outputPath: outPath } = resolveOutputPath(outputRequest));
+ } catch (error) {
+ throwOutputError(error, path.resolve(outputRequest.requestedOutput || outputRequest.authoredOutput || outputRequest.defaultOutput));
+ }
outputPathGuards.set(outPath, outputRequest);
return { diagram, template, outPath, sourceEvidence };
}
@@ -49,13 +79,22 @@ export async function loadDiagramWithBrandMarks(options) {
const START_TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
+function throwOutputError(error, output) {
+ if (error?.archifyDiagnostics || typeof error?.code !== 'string') throw error;
+ const message = `Output could not be written: ${error.message}`;
+ throwDiagnosticError(message, [{
+ code: 'output/write', message,
+ subject: { output },
+ evidence: { systemCode: error.code, reason: error.message },
+ supportedFixes: ['choose a writable HTML file path and ensure its parent directories can be created'],
+ }]);
+}
+
// Common CLI tail: fill the template and write the standalone HTML file.
export function writeDiagram({ outPath, template, diagramType, meta, svg, cards, sourceEvidence = null }) {
if (!START_TYPES.has(diagramType)) throw new Error(`writeDiagram: unknown diagram type ${JSON.stringify(diagramType)}`);
const outputGuard = outputPathGuards.get(outPath);
- if (outputGuard) resolveOutputPath(outputGuard);
- fs.mkdirSync(path.dirname(outPath), { recursive: true });
- fs.writeFileSync(outPath, applyTemplate(template, {
+ const html = applyTemplate(template, {
title: meta.title,
subtitle: meta.subtitle,
svg,
@@ -64,7 +103,14 @@ export function writeDiagram({ outPath, template, diagramType, meta, svg, cards,
visualPreset: meta.visual_preset || 'classic',
guidedViews: meta.views || [],
sourceEvidence,
- }));
+ });
+ try {
+ if (outputGuard) resolveOutputPath(outputGuard);
+ fs.mkdirSync(path.dirname(outPath), { recursive: true });
+ fs.writeFileSync(outPath, html);
+ } catch (error) {
+ throwOutputError(error, outPath);
+ }
outputPathGuards.delete(outPath);
console.log(outPath);
}
diff --git a/archify/renderers/shared/diagnostics.mjs b/archify/renderers/shared/diagnostics.mjs
index 03cf6aa3..5f3dda95 100644
--- a/archify/renderers/shared/diagnostics.mjs
+++ b/archify/renderers/shared/diagnostics.mjs
@@ -68,26 +68,6 @@ export function throwDiagnosticProblems(prefix, problems, { code = 'layout/const
function fallbackDiagnostic(error) {
const input = process.argv[2] ? path.resolve(process.argv[2]) : undefined;
- if (error instanceof SyntaxError) {
- return normalizedDiagnostic({
- code: 'input/json-parse',
- severity: 'error',
- message: `Input JSON could not be parsed: ${error.message}`,
- subject: { input },
- evidence: { reason: error.message },
- supportedFixes: ['repair the JSON syntax and run validation again'],
- });
- }
- if (error?.code === 'ENOENT' || error?.code === 'EACCES' || error?.code === 'EISDIR') {
- return normalizedDiagnostic({
- code: 'input/read',
- severity: 'error',
- message: `Input could not be read: ${error.message}`,
- subject: { input },
- evidence: { systemCode: error.code, reason: error.message },
- supportedFixes: ['provide one readable JSON input file'],
- });
- }
return normalizedDiagnostic({
code: 'internal/unclassified',
severity: 'error',
@@ -111,9 +91,38 @@ function rendererFailure(error) {
};
}
+// Match the public CLI's text format without making its standalone doctor
+// bootstrap depend on this renderer runtime being present.
+function formatDiagnostics(error, diagnostics = []) {
+ if (!diagnostics.length) return error;
+ return [
+ error,
+ ...diagnostics.map((entry) => {
+ const fix = entry.supportedFixes?.length ? ` Fix: ${entry.supportedFixes.join('; ')}.` : '';
+ return `[${entry.code}] ${entry.message}${fix}`;
+ }),
+ ].join('\n');
+}
+
export function installRendererDiagnosticBoundary() {
- if (!DIAGNOSTIC_MODE || globalThis[boundaryKey]) return;
+ if (globalThis[boundaryKey]) return;
globalThis[boundaryKey] = true;
+ if (!DIAGNOSTIC_MODE) {
+ process.once('uncaughtException', (error) => {
+ // Only errors classified at their operation boundary are author-facing.
+ // Preserve Node's debugging information for unexpected implementation errors.
+ if (!error?.archifyDiagnostics?.length) {
+ // The once-listener is already removed. Rethrow outside the exception
+ // handler so Node retains its normal stack and exit code (not code 7).
+ process.nextTick(() => { throw error; });
+ return;
+ }
+ const payload = `${formatDiagnostics(error.message, error.archifyDiagnostics)}\n`;
+ process.stderr.once('error', () => process.exit(1));
+ process.stderr.write(payload, () => process.exit(1));
+ });
+ return;
+ }
process.on('uncaughtException', (error) => {
const payload = `${JSON.stringify(rendererFailure(error))}\n`;
try {
diff --git a/archify/test/render-failure-diagnostics.test.mjs b/archify/test/render-failure-diagnostics.test.mjs
new file mode 100644
index 00000000..d9ee4838
--- /dev/null
+++ b/archify/test/render-failure-diagnostics.test.mjs
@@ -0,0 +1,129 @@
+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 skillRoot = fileURLToPath(new URL('../', import.meta.url));
+const cli = path.join(skillRoot, 'bin/archify.mjs');
+const examples = {
+ architecture: 'web-app.architecture.json',
+ workflow: 'agent-tool-call.workflow.json',
+ sequence: 'cache-miss-request.sequence.json',
+ dataflow: 'product-analytics.dataflow.json',
+ lifecycle: 'agent-run.lifecycle.json',
+};
+
+function workspace(t) {
+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-render-diagnostics-'));
+ t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+ return directory;
+}
+
+function run(args, cwd, json = false) {
+ return spawnSync(process.execPath, args, {
+ cwd,
+ encoding: 'utf8',
+ env: { ...process.env, ARCHIFY_DIAGNOSTIC_FORMAT: json ? 'json' : '' },
+ });
+}
+
+function assertHumanFailure(result, code) {
+ assert.equal(result.status, 1, result.stdout || result.stderr);
+ assert.equal(result.stdout, '');
+ assert.ok(result.stderr.includes(`[${code}]`), result.stderr);
+ assert.doesNotMatch(result.stderr, /\n\s+at\s|file:\/\/|Node\.js v/);
+}
+
+for (const [type, example] of Object.entries(examples)) {
+ test(`render ${type}: input read/parse and output failures name the failing operation`, t => {
+ const cwd = workspace(t);
+ const input = path.join(skillRoot, 'examples', example);
+ const output = path.join(cwd, 'diagram.html');
+ const missing = run([cli, 'render', type, path.join(cwd, 'missing.json'), output], cwd);
+ assertHumanFailure(missing, 'input/read');
+ assert.match(missing.stderr, /Fix: provide one readable JSON input file/);
+
+ const malformed = path.join(cwd, 'malformed.json');
+ fs.writeFileSync(malformed, '{"broken":');
+ assertHumanFailure(run([cli, 'render', type, malformed, output], cwd), 'input/json-parse');
+ assert.equal(fs.existsSync(output), false);
+
+ // Directory targets fail on both POSIX and Windows without relying on
+ // permission bits (which a privileged test process may bypass).
+ fs.mkdirSync(output);
+ assertHumanFailure(run([cli, 'render', type, input, output], cwd), 'output/write');
+ const renderer = path.join(skillRoot, 'renderers', type, `render-${type}.mjs`);
+ const machine = run([renderer, input, output], cwd, true);
+ assert.equal(machine.status, 1);
+ assert.equal(machine.stdout, '');
+ const failure = JSON.parse(machine.stderr);
+ assert.equal(failure.diagnostics[0].code, 'output/write');
+ assert.deepEqual(failure.diagnostics[0].subject, { output });
+ assert.ok(failure.diagnostics[0].evidence.systemCode);
+ assert.ok(failure.diagnostics[0].supportedFixes.length);
+ assert.deepEqual(fs.readdirSync(output), []);
+
+ const blockedParent = path.join(cwd, 'parent');
+ fs.writeFileSync(blockedParent, 'preserved');
+ assertHumanFailure(run([renderer, input, path.join(blockedParent, 'diagram.html')], cwd), 'output/write');
+ assert.equal(fs.readFileSync(blockedParent, 'utf8'), 'preserved');
+ });
+
+ test(`render ${type}: successful direct and public rendering retain the output contract`, t => {
+ const cwd = workspace(t);
+ const input = path.join(skillRoot, 'examples', example);
+ const output = path.join(cwd, 'diagram.html');
+ const publicResult = run([cli, 'render', type, input, output], cwd);
+ assert.equal(publicResult.status, 0, publicResult.stderr);
+ assert.equal(publicResult.stdout, `${output}\n`);
+ assert.equal(publicResult.stderr, '');
+ const bytes = fs.readFileSync(output);
+ const directResult = run([path.join(skillRoot, 'renderers', type, `render-${type}.mjs`), input, output], cwd);
+ assert.equal(directResult.status, 0, directResult.stderr);
+ assert.equal(directResult.stdout, `${output}\n`);
+ assert.equal(directResult.stderr, '');
+ assert.deepEqual(fs.readFileSync(output), bytes);
+ });
+}
+
+test('render layout rejection exposes the existing diagnostic and preserves an existing artifact', t => {
+ const cwd = workspace(t);
+ const input = path.join(cwd, 'layout.json');
+ const output = path.join(cwd, 'diagram.html');
+ fs.writeFileSync(input, JSON.stringify({
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Wide label', quality_profile: 'standard', viewBox: [975, 395] },
+ components: [{ id: 'node', type: 'security', label: '字'.repeat(40), pos: [40, 40], size: [88, 71] }],
+ }));
+ fs.writeFileSync(output, 'trusted artifact');
+ const result = run([cli, 'render', 'architecture', input, output], cwd);
+ assertHumanFailure(result, 'layout/constraint');
+ assert.match(result.stderr, /shorten the label or widen size/);
+ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted artifact');
+ for (const command of ['validate', 'deliver']) {
+ const machine = run([cli, command, 'architecture', input, ...(command === 'deliver' ? [output] : []), '--json'], cwd);
+ assert.equal(machine.status, 1);
+ assert.equal(machine.stderr, '');
+ const failure = JSON.parse(machine.stdout);
+ assert.equal(failure.diagnostics[0].code, 'layout/constraint');
+ assert.deepEqual(failure.diagnostics[0].subject, { diagramType: 'architecture' });
+ }
+ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted artifact');
+});
+
+test('unexpected renderer exceptions keep native debugging information and are not relabelled as input errors', t => {
+ const cwd = workspace(t);
+ const helper = new URL('../renderers/shared/cli.mjs', import.meta.url).href;
+ const script = `import ${JSON.stringify(helper)}; throw Object.assign(new SyntaxError('implementation defect'), { code: 'EACCES' });`;
+ const human = run(['--input-type=module', '-e', script], cwd);
+ assert.equal(human.status, 1);
+ assert.match(human.stderr, /SyntaxError: implementation defect/);
+ assert.match(human.stderr, /\n\s+at\s/);
+ const machine = run(['--input-type=module', '-e', script], cwd, true);
+ assert.equal(machine.status, 1);
+ assert.equal(JSON.parse(machine.stderr).diagnostics[0].code, 'internal/unclassified');
+});