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

[tt-a1i]

Problem and value

On main 6db72a9, node archify/bin/archify.mjs render architecture /no/such.json /tmp/diagram.html exits 1 with a raw Node stack. A valid-schema diagram with an overwide node label does the same, even though its renderer already attaches a layout diagnostic. A failed output write can also be reported as input/read by the JSON boundary because it guesses the operation from EISDIR/EACCES.

Classify read, JSON parse, and output filesystem failures where those operations occur. Human renderer failures now format attached diagnostics with their existing rule codes and supported repairs; an unexpected implementation exception retains its stack and exit 1. This is a narrow defect with a concrete reproduction, so it needs no separate planning issue.

Stability impact

• Shared behavior: the common load/write path and diagnostic boundary used by architecture, workflow, sequence, dataflow, and lifecycle renderers. Public render and direct renderer scripts are covered.
• Preserve schema/layout acceptance, successful artifact bytes, stdout output-path lines, non-zero failure exits, output alias guards, validate --json/deliver --json receipt structure, and standalone doctor startup. The public CLI source is unchanged. No new flag, schema, geometry, or Viewer change.
• Expected filesystem errors receive input/read or output/write at the actual operation, including parent-directory creation. JSON parse errors are classified only around JSON.parse. Existing classified output-path errors keep their own code. Unexpected implementation failures are not guessed to be malformed JSON or unreadable input.
• The JSON stderr transport block is unchanged. This is separate from the incomplete pipe-write problem in fix(renderer): flush complete failure diagnostics before exiting #351/fix(diagnostics): stop truncating large renderer receipts on a pipe #374; integrate one of those transport fixes independently.
• Rendering still writes directly to its requested target; this PR does not claim atomic render writes. deliver remains the interface that preserves the prior artifact until verification and commit succeed.

Tests run

Base 6db72a9aea3d0f67a6a034e41f8a5491476a11c1; candidate bfb7603ec3625a06b4587ecb4072711651594d98. Local macOS, official Node 22.23.2 unless noted.

• node --test archify/test/render-failure-diagnostics.test.mjs archify/test/repair-receipt.test.mjs archify/test/cli-output-types.test.mjs: 31 passed, 0 failed, 0 skipped on final source. The new 12-test regression suite gave 5 passed / 7 failed against the base. It covers all five renderers, missing/malformed inputs, directory output and blocked output parents, direct JSON output classification, successful output contracts, actual layout rejection, and unexpected implementation exceptions.
• Fixed-input base/candidate render comparison: all five bundled examples produce byte-identical HTML with identical successful stdout/stderr behavior.
• Independent review found and resolved a standalone doctor regression in an intermediate formatter refactor. The CLI source was restored, preserving its ability to diagnose an incomplete installation. Re-review passed the three doctor tests and both delivery/comparison alias-race tests, with no remaining finding.
• git diff --check: passed.
• A full suite was started during iteration before the doctor correction; it is not final-head evidence. Hosted CI subsequently passed on final head bfb7603 across Node 18/20/22/24, browser/WebM checks, ZIP freshness, published-manifest checks, and Ubuntu/macOS/Windows package smoke: CI run. The mid-edit local run is still not labelled final-head evidence.

Visual evidence

Not applicable. Only failure presentation/classification changes. The five-mode successful HTML comparison is byte-identical; no rendered appearance, interaction, or geometry is changed.

Generated artifacts

archify.zip rebuilt with official Node 22.23.2. All 79 archive entries are retained; changed entries are only references/delivery-contract.md, renderers/shared/cli.mjs, and renderers/shared/diagnostics.mjs. No gallery, examples, or other generated content changed because their rendered bytes remain identical.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}