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
fix(renderer): classify and format authoring failures at their source
tt-a1ibfb7603ec362
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.zipindex 20cff800..b7f887d6 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 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 oroutside the current working directory; authored `meta.output` remains confineddiff --git a/archify/renderers/shared/cli.mjs b/archify/renderers/shared/cli.mjsindex 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 = pinputPaths: [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.mjsindex 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/constfunction 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.mjsnew file mode 100644index 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');+});