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(delta): preserve baseline relationship arrowheads (#434)
逺坂凛3d972342c521
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.zipindex eea25d54..ddd0ebba 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/delta/architecture-delta.mjs b/archify/delta/architecture-delta.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.htmlindex 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.jsonindex 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,