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(sequence): diagnose unsupported self-messages
tt-a1ib18ea2ed0f72
diff --git a/archify.zip b/archify.zipindex dd53e282..33373304 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.mdindex 1a16877f..7ccd576f 100644--- a/archify/references/authoring-defaults.md+++ b/archify/references/authoring-defaults.md@@ -36,6 +36,6 @@ Use one primary authored language from the user's choice or the request/conversaOmit `meta.visual_preset` for classic, `meta.subtitle` for a title-only header, `meta.legend` for truthful auto, and `meta.engineering_profile` for an ordinary system overview. Explicit styles and a subtitle require a user request. Use legend or deployment ownership under the [legend](authoring-contract.md#legend-contract) or [engineering profile](authoring-contract.md#engineering-profile-default) contracts. Branding is optional and explicit when a node names a real product; [Brand marks](brand-marks.md) gives lookup and capture rules for that branch. Never let a badge replace semantic type, label, or relationship facts. Set required `meta.output` to a portable POSIX-relative `.html` path within the working directory; see [Output path contracts](delivery-contract.md#output-path-contracts) for native path exceptions.-For new Workflow use schema v2, preserving v1 for a fixed legacy source; use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For Sequence omit `meta.column_fit` for spread columns on both automatic and authored canvases; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Give an exit shared by several consecutive phases the same label so it draws once, and keep transition labels short; a recoverable failure needs a real transition back. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.+For new Workflow use schema v2, preserving v1 for a fixed legacy source; use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For Sequence omit `meta.column_fit` for spread columns on both automatic and authored canvases; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. Describe a participant's internal action in a note on its surrounding real cross-participant message, preserving its meaning and order; Sequence self-message loops are not supported. For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Give an exit shared by several consecutive phases the same label so it draws once, and keep transition labels short; a recoverable failure needs a real transition back. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.`finalize` performs the browser gate. Keep the complete drawing comfortably readable on desktop, with zero horizontal overflow. Use meaningful vertical rows and intrinsic-height page scroll when necessary. The 6px projected-text check is a failure floor; at 1440px, aim for ordinary context text around 7.5px or larger. See [Automated browser evidence](delivery-contract.md#automated-browser-evidence) when viewport evidence fails.diff --git a/archify/renderers/sequence/README.md b/archify/renderers/sequence/README.mdindex 188a43e8..dcd98f65 100644--- a/archify/renderers/sequence/README.md+++ b/archify/renderers/sequence/README.md@@ -103,6 +103,14 @@ for the bounded authoring repair and explicit-fixed preservation rules.## Design Rules+- Messages currently require distinct `from` and `to` participants. Although+ schema-v1 accepts matching IDs, this renderer does not draw self-call loops+ and rejects them with `sequence/self-message-unsupported`, naming the message+ path and participant. Increasing column distance cannot repair a self-message.+ Preserve an internal step's wording, ownership, and order in a note on an+ actual interaction or an explicitly ordered card. Do not invent another+ participant or change the target merely to pass validation. These authoring+ choices require semantic review and are not advertised as automatic fixes.- Put participants across the top, ordered by the story the reader shouldfollow.- Time moves downward.diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjsindex 805768cc..5468d7f1 100644--- a/archify/renderers/sequence/render-sequence.mjs+++ b/archify/renderers/sequence/render-sequence.mjs@@ -259,8 +259,35 @@ function validateSequence() {problems.push(`Message "${message.label}" sits outside the readable timeline — keep y between ${layout.lifelineTop + 18} and ${layout.lifelineBottom - 18}.`);}if (participants.has(message.from) && participants.has(message.to)) {- const distance = Math.abs(participants.get(message.to).cx - participants.get(message.from).cx);- if (distance < 60) problems.push(`Message "${message.label}" spans ${Math.round(distance)}px (minimum 60px) — give its participants more column distance.`);+ if (message.from === message.to) {+ const problem = `Message "${message.label}" is a self-message on participant "${message.from}"; this Sequence renderer supports only messages between distinct participants. Participant spacing cannot repair it. Preserve the internal step's meaning and order in a supported representation such as a note on a real message or a card; do not invent a participant.`;+ diagnostics.push({+ code: 'sequence/self-message-unsupported', severity: 'error', message: problem,+ subject: {+ diagramType: 'sequence',+ message: message.label,+ collection: 'messages',+ index: messageIndex,+ path: `/messages/${messageIndex}`,+ ...(message.id ? { id: message.id } : {}),+ from: message.from,+ to: message.to,+ fromPath: `/messages/${messageIndex}/from`,+ toPath: `/messages/${messageIndex}/to`,+ },+ evidence: {+ participant: message.from,+ participantPath: `/participants/${participantOrder.get(message.from)}`,+ y: message.y,+ supportedMessageGeometry: 'horizontal-between-distinct-participants',+ },+ supportedFixes: [],+ });+ problems.push(problem);+ } else {+ const distance = Math.abs(participants.get(message.to).cx - participants.get(message.from).cx);+ if (distance < 60) problems.push(`Message "${message.label}" spans ${Math.round(distance)}px (minimum 60px) — give its participants more column distance.`);+ }}}diff --git a/test/sequence-self-message.test.mjs b/test/sequence-self-message.test.mjsnew file mode 100644index 00000000..95cd4d86--- /dev/null+++ b/test/sequence-self-message.test.mjs@@ -0,0 +1,60 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { spawnSync } from 'node:child_process';+import { fileURLToPath } from 'node:url';+import { validateSchema } from '../archify/renderers/shared/validator.mjs';++const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));++for (const quality of ['standard', 'showcase']) {+ test(`sequence ${quality} names unsupported self-messages without advertising a spacing repair`, t => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-sequence-self-'));+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));+ const input = path.join(dir, 'input.json');+ const doc = {+ schema_version: 1, diagram_type: 'sequence',+ meta: { title: 'Internal operation', output: 'self.html', quality_profile: quality },+ participants: [+ { id: 'caller', type: 'frontend', label: 'Caller' },+ { id: 'worker', type: 'backend', label: 'Worker' },+ ],+ messages: [+ { id: 'request', from: 'caller', to: 'worker', y: 200, label: 'Request' },+ { id: 'internal', from: 'worker', to: 'worker', y: 260, label: 'Apply local policy' },+ ],+ };+ assert.doesNotThrow(() => validateSchema('sequence', doc), 'schema accepts the unsupported renderer capability');+ fs.writeFileSync(input, JSON.stringify(doc));+ const result = spawnSync(process.execPath, [cli, 'validate', 'sequence', input, '--quality', quality, '--json'], { encoding: 'utf8' });+ assert.notEqual(result.status, 0);+ const receipt = JSON.parse(result.stdout);+ const diagnostic = receipt.diagnostics.find(({ code }) => code === 'sequence/self-message-unsupported');+ assert.ok(diagnostic, result.stdout || result.stderr);+ assert.equal(diagnostic.subject.path, '/messages/1');+ assert.equal(diagnostic.subject.collection, 'messages');+ assert.equal(diagnostic.subject.index, 1);+ assert.equal(diagnostic.subject.id, 'internal');+ assert.equal(diagnostic.subject.from, 'worker');+ assert.equal(diagnostic.subject.to, 'worker');+ assert.equal(diagnostic.subject.fromPath, '/messages/1/from');+ assert.equal(diagnostic.subject.toPath, '/messages/1/to');+ assert.equal(diagnostic.evidence.participant, 'worker');+ assert.equal(diagnostic.evidence.participantPath, '/participants/1');+ assert.equal(diagnostic.evidence.y, 260);+ assert.equal(diagnostic.evidence.supportedMessageGeometry, 'horizontal-between-distinct-participants');+ assert.deepEqual(diagnostic.supportedFixes, []);+ assert.match(diagnostic.message, /meaning and order/);+ assert.doesNotMatch(result.stdout, /spans 0px|give its participants more column distance/);+ assert.deepEqual(JSON.parse(fs.readFileSync(input, 'utf8')), doc, 'rejection preserves authored semantics');+ assert.equal(fs.existsSync(path.join(dir, 'self.html')), false);+ const output = path.join(dir, 'rendered.html');+ const rendered = spawnSync(process.execPath, [cli, 'render', 'sequence', input, output, '--quality', quality], { encoding: 'utf8' });+ assert.notEqual(rendered.status, 0);+ assert.match(rendered.stderr, /self-message on participant "worker"/);+ assert.doesNotMatch(rendered.stderr, /spans 0px|give its participants more column distance/);+ assert.equal(fs.existsSync(output), false, 'render rejects before producing an artifact');+ });+}