Skip to content

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

fix(delta): preserve baseline relationship arrowheads (#434)

逺坂凛3d972342c521
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f49b388f..1b841d01 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
+- **Architecture Delta baseline arrowheads (#433).** Removed and rerouted baseline relationships retain their marker definitions in the composed Delta SVG, preserving their authored direction alongside current relationships.
- **Compare rollback recovery (#438).** If restoring a previous output fails, compare preserves its recovery directory and reports backup-to-target paths instead of deleting the remaining backups during cleanup.
- **固定提交的来源校验 (#420)。** 校验忽略本地 Git replacement refs,始终读取指定提交的原始对象,避免替换后的文件或行范围造成误接受或误拒绝;保留原有来源链接、诊断与用户 Git 配置。
- **导出的独立 SVG 声明 UTF-8 编码。** 架构图「下载 SVG」和架构对比(compare)导出的 SVG 文档现在以 `<?xml version="1.0" encoding="UTF-8"?>` 声明开头;缺少声明时,部分消费方不按 XML 规范默认 UTF-8 而猜测编码,导致中文等非 ASCII 文本乱码。
diff --git a/archify.zip b/archify.zip
index eea25d54..ddd0ebba 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/delta/architecture-delta.mjs b/archify/delta/architecture-delta.mjs
index ccb02798..7ca38d62 100644
--- a/archify/delta/architecture-delta.mjs
+++ b/archify/delta/architecture-delta.mjs
@@ -555,6 +555,9 @@ function boundarySymbolMarkup(markup, state) {
export function buildDeltaSvg(baseSvg, headSvg, receipt) {
const [baseW, baseH] = viewBoxSize(baseSvg);
const [headW, headH] = viewBoxSize(headSvg);
+ // Baseline paths and their definitions must travel together in a namespace
+ // distinct from the current snapshot before the final Delta prefix is added.
+ const baseRelationshipsSvg = prefixSvgIds(baseSvg, 'base');
const nodes = changeMap(receipt.changes.components);
const edges = changeMap(receipt.changes.connections);
const boundaries = boundaryChangeMap(receipt.changes.boundaries);
@@ -571,11 +574,11 @@ export function buildDeltaSvg(baseSvg, headSvg, receipt) {
}
for (const change of edges.values()) {
if (change.status === 'removed' || change.classifications.includes('topology')) {
- const phantom = forceElementState(elementById(baseSvg, 'edge', change.id), 'removed', change.classifications);
+ const phantom = forceElementState(elementById(baseRelationshipsSvg, 'edge', change.id), 'removed', change.classifications);
baseEdgePhantoms.push(phantom);
edgeMarkers.push(edgeSymbolMarkup(phantom, 'removed'));
} else if (change.classifications.includes('geometry')) {
- const phantom = forceElementState(elementById(baseSvg, 'edge', change.id), 'moved-from', change.classifications);
+ const phantom = forceElementState(elementById(baseRelationshipsSvg, 'edge', change.id), 'moved-from', change.classifications);
baseEdgePhantoms.push(phantom);
edgeMarkers.push(edgeSymbolMarkup(phantom, 'moved-from'));
}
@@ -598,6 +601,10 @@ export function buildDeltaSvg(baseSvg, headSvg, receipt) {
}
let delta = annotateArchitectureSideSvg(headSvg, receipt, 'head');
+ if (baseEdgePhantoms.length) {
+ const baseDefinitions = baseRelationshipsSvg.match(/<defs>([\s\S]*?)<\/defs>/)?.[1] || '';
+ delta = delta.replace('</defs>', `${baseDefinitions}</defs>`);
+ }
delta = delta.replace(/^<svg[^>]+>/, (tag) => tag.replace(/viewBox="[^"]+"/, `viewBox="0 0 ${Math.max(baseW, headW) + 24} ${Math.max(baseH, headH) + 24}"`));
delta = delta.replace(' <!-- Boundaries (behind everything) -->', ` <!-- Baseline boundary frame phantoms -->\n${baseBoundaryFramePhantoms.filter(Boolean).join('\n')}\n\n <!-- Boundaries (behind everything) -->`);
delta = delta.replace(' <!-- Connection paths (before components for correct z-order) -->', ` <!-- Baseline relationship phantoms -->\n${baseEdgePhantoms.join('\n')}\n\n <!-- Connection paths (before components for correct z-order) -->`);
diff --git a/archify/test/architecture-delta-markers.test.mjs b/archify/test/architecture-delta-markers.test.mjs
new file mode 100644
index 00000000..4ff2dae8
--- /dev/null
+++ b/archify/test/architecture-delta-markers.test.mjs
@@ -0,0 +1,137 @@
+import test from 'node:test';
+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 { fileURLToPath } from 'node:url';
+import { parse, serializeOuter } from 'parse5';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const variants = ['default', 'emphasis', 'security', 'dashed'];
+const attr = (node, name) => node.attrs?.find((entry) => entry.name === name)?.value;
+function descendants(node) {
+ return [node, ...(node.childNodes || []).flatMap(descendants)];
+}
+function svgIn(document) {
+ const svg = descendants(document).find((node) => node.tagName === 'svg');
+ assert.ok(svg, 'expected an SVG');
+ return svg;
+}
+function edgePaths(svg) {
+ return descendants(svg).filter((node) => node.tagName === 'path' && attr(node, 'data-edge-id'));
+}
+function markerId(node) {
+ const value = attr(node, 'marker-end');
+ assert.match(value || '', /^url\(#[^)]+\)$/);
+ return value.slice(5, -1);
+}
+function markerMap(svg) {
+ return new Map(descendants(svg).filter((node) => node.tagName === 'marker').map((node) => [attr(node, 'id'), node]));
+}
+function assertResolved(svg) {
+ const nodes = descendants(svg);
+ const ids = nodes.map((node) => attr(node, 'id')).filter(Boolean);
+ assert.equal(new Set(ids).size, ids.length, 'SVG IDs must be unique');
+ const markers = markerMap(svg);
+ const missing = [];
+ for (const node of nodes) {
+ for (const name of ['marker-start', 'marker-mid', 'marker-end']) {
+ const value = attr(node, name);
+ if (!value) continue;
+ const match = value.match(/^url\(#([^)]+)\)$/);
+ assert.ok(match, `expected a local marker reference: ${value}`);
+ if (!markers.has(match[1])) missing.push(`${attr(node, 'data-edge-id') || node.tagName}: ${match[1]}`);
+ }
+ }
+ assert.deepEqual(missing, [], 'every arrowhead must resolve within its own SVG');
+}
+function markerShape(marker) {
+ // Compare geometry and paint semantics independently of namespaced IDs.
+ return serializeOuter(marker).replace(/\sid="[^"]+"/, '');
+}
+function compare(t, base, head) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-delta-markers-'));
+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+ const inputs = [base, head].map((value, index) => {
+ if (typeof value === 'string') return value;
+ const file = path.join(root, `${index}.json`);
+ fs.writeFileSync(file, JSON.stringify(value));
+ return file;
+ });
+ const output = path.join(root, 'delta.html');
+ const result = spawnSync(process.execPath, [
+ path.join(skillRoot, 'bin/archify.mjs'), 'compare', 'architecture', ...inputs,
+ output, '--quality', 'standard', '--json',
+ ], { cwd: skillRoot, encoding: 'utf8', timeout: 30000 });
+ assert.ifError(result.error);
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ const html = fs.readFileSync(output, 'utf8');
+ const document = parse(html);
+ const section = descendants(document).find((node) => node.tagName === 'section' && attr(node, 'data-view') === 'delta');
+ assert.ok(section);
+ const frames = descendants(document).filter((node) => node.tagName === 'iframe');
+ assert.equal(frames.length, 2);
+ const snapshots = frames.map((frame) => svgIn(parse(attr(frame, 'srcdoc'))));
+ snapshots.forEach(assertResolved);
+ return { html, delta: svgIn(section), base: snapshots[0], head: snapshots[1] };
+}
+function assertPreserved(artifact, expectedOld) {
+ const paths = edgePaths(artifact.delta);
+ const oldPaths = paths.filter((node) => ['removed', 'moved-from'].includes(attr(node, 'data-delta-state')));
+ assert.equal(oldPaths.length, expectedOld);
+ for (const side of ['base', 'head']) {
+ const sourcePaths = edgePaths(artifact[side]);
+ const sourceMarkers = markerMap(artifact[side]);
+ const candidates = side === 'base' ? oldPaths : paths.filter((node) => !oldPaths.includes(node));
+ for (const candidate of candidates) {
+ const original = sourcePaths.find((node) => attr(node, 'data-edge-id') === attr(candidate, 'data-edge-id'));
+ assert.ok(original, 'Delta path must correspond to its source snapshot');
+ assert.equal(attr(candidate, 'd'), attr(original, 'd'), 'authored path geometry must survive composition');
+ assert.equal(attr(candidate, 'data-composition-points'), attr(original, 'data-composition-points'));
+ const marker = markerMap(artifact.delta).get(markerId(candidate));
+ assert.ok(marker, `${side} edge ${attr(candidate, 'data-edge-id')} has no arrowhead definition`);
+ assert.equal(markerShape(marker), markerShape(sourceMarkers.get(markerId(original))), `${side} arrowhead variant changed`);
+ }
+ }
+}
+
+test('checkout compare resolves all three baseline arrowheads and keeps snapshot markers', { timeout: 40000 }, (t) => {
+ const artifact = compare(t,
+ path.join(skillRoot, 'examples/checkout-platform.base.architecture.json'),
+ path.join(skillRoot, 'examples/checkout-platform.head.architecture.json'));
+ assertResolved(artifact.delta);
+ assertPreserved(artifact, 3);
+});
+
+function variantFixture(operation) {
+ const base = { schema_version: 1, diagram_type: 'architecture', meta: { title: 'Marker variants' }, components: [], connections: [] };
+ for (const [index, variant] of variants.entries()) {
+ const y = 100 + index * 260;
+ for (const [column, suffix] of ['a', 'b', 'c'].entries()) {
+ base.components.push({ id: `${variant}-${suffix}`, type: 'backend', label: `${variant} ${suffix}`, pos: [100 + column * 300, y], size: [140, 60] });
+ }
+ base.connections.push({ id: variant, from: `${variant}-a`, to: `${variant}-b`, variant });
+ }
+ const head = structuredClone(base);
+ if (operation === 'removed') head.connections = [];
+ else head.connections.forEach((edge, index) => {
+ const y = 200 + index * 260;
+ if (operation === 'topology') edge.to = `${edge.id}-c`;
+ edge.fromSide = 'bottom';
+ edge.toSide = 'bottom';
+ edge.via = [[170, y], [operation === 'topology' ? 770 : 470, y]];
+ });
+ return [base, head];
+}
+
+for (const operation of ['removed', 'rerouted', 'topology']) {
+ test(`compare preserves all four marker variants for ${operation} relationships`, { timeout: 40000 }, (t) => {
+ const artifact = compare(t, ...variantFixture(operation));
+ assertResolved(artifact.delta);
+ assertPreserved(artifact, 4);
+ const old = edgePaths(artifact.delta).filter((node) => ['removed', 'moved-from'].includes(attr(node, 'data-delta-state')));
+ assert.deepEqual(old.map((node) => attr(node, 'data-edge-id')).sort(), [...variants].sort());
+ assert.ok(old.every((node) => attr(node, 'data-delta-state') === (operation === 'rerouted' ? 'moved-from' : 'removed')));
+ });
+}
diff --git a/archify/test/webm-artifact.smoke.mjs b/archify/test/webm-artifact.smoke.mjs
index c4f80c57..8b96b22a 100644
--- a/archify/test/webm-artifact.smoke.mjs
+++ b/archify/test/webm-artifact.smoke.mjs
@@ -840,12 +840,22 @@ try {
document.querySelector('.change-row').click();
var svgB = Archify.deltaExport.canonicalSvg();
var parsed = new DOMParser().parseFromString(svgB, 'image/svg+xml');
+ var baselineMarkers = Array.from(parsed.querySelectorAll('path[data-edge-id][data-delta-state="removed"], path[data-edge-id][data-delta-state="moved-from"]')).map(function (edge) {
+ var markerId = (edge.getAttribute('marker-end') || '').match(/^url\(#([^)]+)\)$/)?.[1];
+ var marker = markerId ? parsed.getElementById(markerId) : null;
+ return {
+ edge: edge.getAttribute('data-edge-id'),
+ resolved: marker?.localName === 'marker',
+ tone: marker?.querySelector('polygon')?.getAttribute('class') || null
+ };
+ }).sort(function (a, b) { return a.edge.localeCompare(b.edge); });
var exportStyle = parsed.querySelector('style')?.textContent || '';
var blob = await Archify.deltaExport.shareCard();
var bytes = new Uint8Array(await blob.arrayBuffer());
return {
explorers: explorers,
stable: svgA === svgB,
+ baselineMarkers: baselineMarkers,
reviewResidue: parsed.querySelectorAll('[data-delta-review-current]').length,
boundaryStyle: exportStyle.includes('text[data-delta-boundary-state="added"]{fill:#34d399!important}'),
markerStyle: exportStyle.includes('.delta-edge-marker[data-delta-state],.delta-boundary-marker[data-delta-state]{color:var(--delta)}'),
@@ -858,6 +868,11 @@ try {
})()`, true), 15_000, 'Architecture Delta export');
assert.deepEqual(exportProof.explorers, [true, true]);
assert.equal(exportProof.stable, true);
+ assert.deepEqual(exportProof.baselineMarkers, [
+ { edge: 'authorize-payment', resolved: true, tone: 'm-security' },
+ { edge: 'publish-order', resolved: true, tone: 'm-dashed' },
+ { edge: 'session-read', resolved: true, tone: 'm-default' },
+ ]);
assert.equal(exportProof.reviewResidue, 0);
assert.equal(exportProof.boundaryStyle, true);
assert.equal(exportProof.markerStyle, true);
diff --git a/examples/checkout-platform-delta.html b/examples/checkout-platform-delta.html
index f81f6e07..aecf2523 100644
--- a/examples/checkout-platform-delta.html
+++ b/examples/checkout-platform-delta.html
@@ -19789,6 +19789,22 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<pattern id="delta-head-grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
</pattern>
+
+ <marker id="delta-base-arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
+ </marker>
+ <marker id="delta-base-arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
+ </marker>
+ <marker id="delta-base-arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
+ </marker>
+ <marker id="delta-base-arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
+ </marker>
+ <pattern id="delta-base-grid" width="40" height="40" patternUnits="userSpaceOnUse">
+ <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
+ </pattern>
</defs>
<!-- Background Grid -->
@@ -19804,18 +19820,18 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<rect data-graph-role="structural-frame" data-composition-frame-kind="security-group" data-composition-frame-id="1" data-composition-frame-label="Checkout trust zone" x="400" y="70" width="400" height="260" rx="8" class="c-security-group" stroke-width="1" data-delta-state="changed" data-delta-classifications="scope" data-delta-boundary-key="security-group:Checkout trust zone"/>
<!-- Baseline relationship phantoms -->
-<path data-edge-from="orders" data-edge-to="payments" data-edge-label="authorize" data-edge-key="0" data-edge-id="authorize-payment" data-composition-points="770,280;850,280" d="M 770 280 L 850 280" class="a-security" stroke-width="1.5" marker-end="url(#arrowhead-security)" data-delta-state="removed" data-delta-classifications="geometry,topology"/>
+<path data-edge-from="orders" data-edge-to="payments" data-edge-label="authorize" data-edge-key="0" data-edge-id="authorize-payment" data-composition-points="770,280;850,280" d="M 770 280 L 850 280" class="a-security" stroke-width="1.5" marker-end="url(#delta-base-arrowhead-security)" data-delta-state="removed" data-delta-classifications="geometry,topology"/>
<g data-detail="context" data-edge-from="orders" data-edge-to="payments" data-edge-label="authorize" data-edge-key="0" data-edge-id="authorize-payment" data-delta-state="removed" data-delta-classifications="geometry,topology">
<rect x="783.4" y="260" width="53.199999999999996" height="14" rx="3" class="c-mask"/>
<text x="810" y="270" class="t-security" font-size="8" text-anchor="middle">authorize</text>
</g>
-<path data-edge-from="checkout" data-edge-to="queue" data-edge-label="accepted" data-edge-key="5" data-edge-id="publish-order" data-composition-points="495,310;495,400" d="M 495 310 L 495 400" class="a-dashed" stroke-width="1.5" marker-end="url(#arrowhead-dashed)" data-delta-state="moved-from" data-delta-classifications="geometry"/>
+<path data-edge-from="checkout" data-edge-to="queue" data-edge-label="accepted" data-edge-key="5" data-edge-id="publish-order" data-composition-points="495,310;495,400" d="M 495 310 L 495 400" class="a-dashed" stroke-width="1.5" marker-end="url(#delta-base-arrowhead-dashed)" data-delta-state="moved-from" data-delta-classifications="geometry"/>
<g data-detail="context" data-edge-from="checkout" data-edge-to="queue" data-edge-label="accepted" data-edge-key="5" data-edge-id="publish-order" data-delta-state="moved-from" data-delta-classifications="geometry">
<rect x="470.8" y="356" width="48.4" height="14" rx="3" class="c-mask"/>
<text x="495" y="366" class="t-messagebus" font-size="8" text-anchor="middle">accepted</text>
</g>
-<path data-edge-from="checkout" data-edge-to="cache" data-edge-label="session" data-edge-key="6" data-edge-id="session-read" data-composition-points="495,250;495,160" d="M 495 250 L 495 160" class="a-default" stroke-width="1.5" marker-end="url(#arrowhead)" data-delta-state="removed" data-delta-classifications="topology"/>
+<path data-edge-from="checkout" data-edge-to="cache" data-edge-label="session" data-edge-key="6" data-edge-id="session-read" data-composition-points="495,250;495,160" d="M 495 250 L 495 160" class="a-default" stroke-width="1.5" marker-end="url(#delta-base-arrowhead)" data-delta-state="removed" data-delta-classifications="topology"/>
<g data-detail="context" data-edge-from="checkout" data-edge-to="cache" data-edge-label="session" data-edge-key="6" data-edge-id="session-read" data-delta-state="removed" data-delta-classifications="topology">
<rect x="473.2" y="164" width="43.6" height="14" rx="3" class="c-mask"/>
<text x="495" y="174" class="t-muted" font-size="8" text-anchor="middle">session</text>
diff --git a/examples/checkout-platform-delta.receipt.json b/examples/checkout-platform-delta.receipt.json
index 7a3196dd..2ede6546 100644
--- a/examples/checkout-platform-delta.receipt.json
+++ b/examples/checkout-platform-delta.receipt.json
@@ -219,8 +219,8 @@
"Boundary identity is conservatively derived from kind + label."
],
"artifact": {
- "sha256": "581a09d56e822f86abd90101799c51613f16ef92b79b86a13d8d200035b0c9fc",
- "bytes": 2217437
+ "sha256": "718fa5f08befa088ae9ecbcc00e0c0a1109347305173cb1df5413b282247c834",
+ "bytes": 2218492
},
"validation": {
"checksPassed": 28,