Skip to content

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

feat: dedicated unknown-endpoint diagnostics for non-workflow types

momoyeyufdc02b41cf74
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index 01333504..9a97cffc 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -618,9 +618,27 @@ function validateArchitecture() {
}
}
- for (const conn of asArray(arch.connections)) {
- if (!components.has(conn.from)) problems.push(`Connection "${conn.label || conn.from}" references unknown source "${conn.from}".`);
- if (!components.has(conn.to)) problems.push(`Connection "${conn.label || conn.to}" references unknown target "${conn.to}".`);
+ const connectionList = asArray(arch.connections);
+ const knownComponentIds = [...components.keys()].sort();
+ for (const conn of connectionList) {
+ const connIndex = connectionList.indexOf(conn);
+ for (const [field, endpoint] of [['from', 'source'], ['to', 'target']]) {
+ if (components.has(conn[field])) continue;
+ const message = `Connection "${conn.label || conn[field]}" references unknown ${endpoint} "${conn[field]}".`;
+ diagnostics.push({
+ code: 'architecture/unknown-endpoint', severity: 'error', message,
+ subject: {
+ diagramType: 'architecture',
+ connection: conn.id ?? null,
+ path: `/connections/${connIndex}/${field}`,
+ from: conn.from,
+ to: conn.to,
+ },
+ evidence: { endpoint, unknownNodeId: conn[field], availableNodeIds: knownComponentIds },
+ supportedFixes: knownComponentIds.map((id) => `set /connections/${connIndex}/${field} to verified node id "${id}"`),
+ });
+ problems.push(message);
+ }
if (components.has(conn.from) && components.has(conn.to)) {
const routed = pathFor(conn);
const outsidePoints = routed.points.filter(([x, y]) => x < 0 || y < 0 || x > viewBox[0] || y > viewBox[1]);
diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjs
index 8907988e..203aa636 100644
--- a/archify/renderers/dataflow/render-dataflow.mjs
+++ b/archify/renderers/dataflow/render-dataflow.mjs
@@ -119,6 +119,7 @@ for (const [index, node] of asArray(dataflow.nodes).entries()) {
function validateDataflow() {
const problems = [];
+ const diagnostics = [];
if (nodes.size !== asArray(dataflow.nodes).length) problems.push('Node ids must be unique.');
const stageCount = asArray(dataflow.stages).length;
@@ -171,9 +172,42 @@ function validateDataflow() {
}
}
- for (const flow of asArray(dataflow.flows)) {
- if (!nodes.has(flow.from)) problems.push(`Flow "${flow.label || flow.from}" references unknown source "${flow.from}".`);
- if (!nodes.has(flow.to)) problems.push(`Flow "${flow.label || flow.to}" references unknown target "${flow.to}".`);
+ const flowList = asArray(dataflow.flows);
+ const stageById = new Map(asArray(dataflow.nodes).map((node) => [node.id, node.stage]));
+ for (const flow of flowList) {
+ const flowIndex = flowList.indexOf(flow);
+ for (const [field, endpoint] of [['from', 'source'], ['to', 'target']]) {
+ if (nodes.has(flow[field])) continue;
+ const problem = `Flow "${flow.label || flow[field]}" references unknown ${endpoint} "${flow[field]}".`;
+ const anchorStage = stageById.get(flow[field === 'from' ? 'to' : 'from']);
+ const anchorId = flow[field === 'from' ? 'to' : 'from'];
+ const stageDelta = (id) => (anchorStage === undefined || stageById.get(id) === undefined
+ ? 0
+ : field === 'to'
+ ? stageById.get(id) - anchorStage
+ : anchorStage - stageById.get(id));
+ const candidates = [...stageById.keys()]
+ .filter((id) => id !== anchorId)
+ .sort((a, b) => {
+ const da = stageDelta(a);
+ const db = stageDelta(b);
+ const forwardDiff = (db > 0) - (da > 0);
+ return forwardDiff !== 0 ? forwardDiff : da - db;
+ });
+ diagnostics.push({
+ code: 'dataflow/unknown-endpoint', severity: 'error', message: problem,
+ subject: {
+ diagramType: 'dataflow',
+ flow: flow.id ?? null,
+ path: `/flows/${flowIndex}/${field}`,
+ from: flow.from,
+ to: flow.to,
+ },
+ evidence: { endpoint, unknownNodeId: flow[field], availableNodeIds: candidates },
+ supportedFixes: candidates.map((id) => `set /flows/${flowIndex}/${field} to verified node id "${id}"`),
+ });
+ problems.push(problem);
+ }
if (!flow.label) problems.push(`Flow "${flow.from}" -> "${flow.to}" must include a short data label.`);
if (nodes.has(flow.from) && nodes.has(flow.to)) {
const routed = pathFor(flow);
@@ -298,6 +332,7 @@ function validateDataflow() {
if (problems.length) {
throwDiagnosticProblems('Data-flow layout validation failed', problems, {
subject: { diagramType: 'dataflow' },
+ diagnostics,
});
}
}
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 91904ad3..3ad3f602 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -348,6 +348,7 @@ for (const [index, state] of asArray(lifecycle.states).entries()) {
function validateLifecycle() {
const problems = [];
+ const diagnostics = [];
if (states.size !== asArray(lifecycle.states).length) problems.push('State ids must be unique.');
// The three bands are fixed at y=112/264/436. Preserve the original
@@ -431,9 +432,27 @@ function validateLifecycle() {
}
}
- for (const transition of asArray(lifecycle.transitions)) {
- if (!states.has(transition.from)) problems.push(`Transition "${transition.label || transition.from}" references unknown source "${transition.from}".`);
- if (!states.has(transition.to)) problems.push(`Transition "${transition.label || transition.to}" references unknown target "${transition.to}".`);
+ const transitionList = asArray(lifecycle.transitions);
+ const knownStateIds = [...states.keys()].sort();
+ for (const transition of transitionList) {
+ const transitionIndex = transitionList.indexOf(transition);
+ for (const [field, endpoint] of [['from', 'source'], ['to', 'target']]) {
+ if (states.has(transition[field])) continue;
+ const problem = `Transition "${transition.label || transition[field]}" references unknown ${endpoint} "${transition[field]}".`;
+ diagnostics.push({
+ code: 'lifecycle/unknown-endpoint', severity: 'error', message: problem,
+ subject: {
+ diagramType: 'lifecycle',
+ transition: transition.id ?? null,
+ path: `/transitions/${transitionIndex}/${field}`,
+ from: transition.from,
+ to: transition.to,
+ },
+ evidence: { endpoint, unknownNodeId: transition[field], availableNodeIds: knownStateIds },
+ supportedFixes: knownStateIds.map((id) => `set /transitions/${transitionIndex}/${field} to verified node id "${id}"`),
+ });
+ problems.push(problem);
+ }
if (states.has(transition.from) && states.has(transition.to)) {
const routed = pathFor(transition);
const [start, end] = [routed.points[0], routed.points[routed.points.length - 1]];
@@ -558,6 +577,7 @@ function validateLifecycle() {
if (problems.length) {
throwDiagnosticProblems('Lifecycle layout validation failed', problems, {
subject: { diagramType: 'lifecycle' },
+ diagnostics,
});
}
}
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index 808db62f..fc381418 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -194,6 +194,7 @@ function messagePath(message) {
function validateSequence() {
const problems = [];
+ const diagnostics = [];
if (participants.size !== asArray(sequence.participants).length) problems.push('Participant ids must be unique.');
if (layout.lifelineBottom - layout.lifelineTop < 120) {
@@ -218,9 +219,33 @@ function validateSequence() {
}
}
- for (const message of asArray(sequence.messages)) {
- if (!participants.has(message.from)) problems.push(`Message "${message.label}" references unknown source "${message.from}".`);
- if (!participants.has(message.to)) problems.push(`Message "${message.label}" references unknown target "${message.to}".`);
+ const messageList = asArray(sequence.messages);
+ const participantList = asArray(sequence.participants);
+ const participantOrder = new Map(participantList.map((p, index) => [p.id, index]));
+ for (const message of messageList) {
+ const messageIndex = messageList.indexOf(message);
+ for (const [field, endpoint] of [['from', 'source'], ['to', 'target']]) {
+ if (participants.has(message[field])) continue;
+ const problem = `Message "${message.label}" references unknown ${endpoint} "${message[field]}".`;
+ const otherField = field === 'from' ? 'to' : 'from';
+ const anchorOrder = participantOrder.get(message[otherField]) ?? 0;
+ const candidates = [...participantOrder.keys()]
+ .filter((id) => id !== message[otherField])
+ .sort((a, b) => Math.abs(participantOrder.get(a) - anchorOrder) - Math.abs(participantOrder.get(b) - anchorOrder));
+ diagnostics.push({
+ code: 'sequence/unknown-endpoint', severity: 'error', message: problem,
+ subject: {
+ diagramType: 'sequence',
+ message: message.label ?? null,
+ path: `/messages/${messageIndex}/${field}`,
+ from: message.from,
+ to: message.to,
+ },
+ evidence: { endpoint, unknownNodeId: message[field], availableNodeIds: candidates },
+ supportedFixes: candidates.map((id) => `set /messages/${messageIndex}/${field} to verified node id "${id}"`),
+ });
+ problems.push(problem);
+ }
if (typeof message.y !== 'number') problems.push(`Message "${message.label}" must provide a numeric y.`);
if (message.y < layout.lifelineTop + 18 || message.y > layout.lifelineBottom - 18) {
problems.push(`Message "${message.label}" sits outside the readable timeline — keep y between ${layout.lifelineTop + 18} and ${layout.lifelineBottom - 18}.`);
@@ -368,6 +393,7 @@ function validateSequence() {
if (problems.length) {
throwDiagnosticProblems('Sequence layout validation failed', problems, {
subject: { diagramType: 'sequence' },
+ diagnostics,
});
}
}