Skip to content

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

fix(diagnostics): identify nodes in desktop readability failures

yearthmain39b0b428acb1
diff --git a/archify.zip b/archify.zip
index 1b21ad02..0ca64f68 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index cb6c40f5..f56c36e0 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -237,12 +237,12 @@ function checkerDiagnostics(checker) {
const diagnostics = [];
for (const issue of checker?.composition?.issues || []) {
if (issue.severity !== 'error') continue;
- const { severity, code, relationship, ...evidence } = issue;
+ const { severity, code, relationship, nodeId, ...evidence } = issue;
diagnostics.push(diagnostic({
code,
severity,
message: `Final artifact failed ${code}.`,
- subject: relationship ? { relationship } : { check: 'composition' },
+ subject: relationship ? { relationship } : { check: 'composition', ...(nodeId ? { nodeId } : {}) },
evidence,
supportedFixes: COMPOSITION_FIXES[code] || [],
}));
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index d24ce7f6..b46a60e5 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -208,6 +208,7 @@ if (svgMatches.length === 1) {
...(desktopReadabilityIssue ? [{
severity: desktopReadabilityIsError ? 'error' : 'warning',
code: 'composition/desktop-readability',
+ ...(desktopReadabilityIssue.nodeId ? { nodeId: desktopReadabilityIssue.nodeId } : {}),
viewportWidth: DESKTOP_READABILITY_VIEWPORT.width,
viewportHeight: DESKTOP_READABILITY_VIEWPORT.height,
availableDiagramWidth: DESKTOP_READER_DIAGRAM_WIDTH,
@@ -625,7 +626,18 @@ function collectDesktopReadability(svgAttrs, fragment) {
if (!Number.isFinite(viewBoxWidth) || viewBoxWidth <= 0) return null;
const scale = Math.min(1, DESKTOP_READER_DIAGRAM_WIDTH / viewBoxWidth);
let worst = null;
- for (const match of fragment.matchAll(/<text\b([^>]*)>([\s\S]*?)<\/text>/gi)) {
+ const nodeOwners = [];
+ // Walk groups alongside text so nested decoration retains the owning node,
+ // without leaking that identity into a following boundary or loose label.
+ for (const match of fragment.matchAll(/<text\b([^>]*)>([\s\S]*?)<\/text>|<g\b[^>]*>|<\/g\s*>/gi)) {
+ if (match[1] === undefined) {
+ if (/^<\/g/i.test(match[0])) nodeOwners.pop();
+ else if (!/\/\s*>$/.test(match[0])) {
+ const attrs = parseAttrs(match[0]);
+ nodeOwners.push(attrs['data-node-id'] || nodeOwners.at(-1));
+ }
+ continue;
+ }
const primary = /\bdata-node-label(?:\s*=|\s|$)/i.test(match[1]);
const boundary = /\bdata-boundary-label(?:\s*=|\s|$)/i.test(match[1]);
const context = /\bdata-detail\s*=\s*"context"/i.test(match[1]);
@@ -636,6 +648,7 @@ function collectDesktopReadability(svgAttrs, fragment) {
const projected = projectedNodeTextPx(fontSize, viewBoxWidth);
if (projected >= MIN_PROJECTED_NODE_TEXT_PX) continue;
const candidate = {
+ ...(nodeOwners.at(-1) ? { nodeId: nodeOwners.at(-1) } : {}),
viewBoxWidth,
scale,
text: stripTags(match[2]).trim(),
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
index 0a7bbd47..34ec248b 100644
--- a/archify/test/render-output-checks.test.mjs
+++ b/archify/test/render-output-checks.test.mjs
@@ -433,3 +433,15 @@ test('render output check: endpoint stubs from 8px pass while cramped interior t
});
process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
+
+test('readability node ownership survives nested groups and does not leak after closing', () => {
+ const nested = checkHtml('nested-owner', `
+ <g data-node-id="outer"><g/><g><text data-detail="context" font-size="7">Repeated</text></g></g>
+ `, 'showcase', '0 0 1200 400');
+ assert.equal(nested.result.composition.issues[0].nodeId, 'outer');
+ const loose = checkHtml('closed-owner', `
+ <g data-node-id="outer"><g><text data-node-label font-size="12">Readable</text></g></g>
+ <text data-boundary-label font-size="7">Repeated</text>
+ `, 'showcase', '0 0 1200 400');
+ assert.equal(loose.result.composition.issues[0].nodeId, undefined);
+});
diff --git a/archify/test/repair-receipt.test.mjs b/archify/test/repair-receipt.test.mjs
index faf43293..0b3029b0 100644
--- a/archify/test/repair-receipt.test.mjs
+++ b/archify/test/repair-receipt.test.mjs
@@ -173,9 +173,38 @@ test('repair receipt: public validate reports borderline desktop readability wit
(entry) => entry.code === 'composition/desktop-readability',
);
assert.ok(repair);
- assert.deepEqual(repair.subject, { check: 'composition' });
+ assert.deepEqual(repair.subject, { check: 'composition', nodeId: 'tool-runtime' });
assert.ok(repair.evidence.projectedFontPx < repair.evidence.minimumProjectedFontPx);
assert.ok(repair.supportedFixes.some((fix) => fix.includes('reduce the viewBox width')));
});
process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
+
+test('repair receipt: readability identifies the failing node despite repeated copy', () => {
+ for (const command of ['validate', 'deliver']) {
+ for (const failingIndex of [0, 1]) {
+ const ids = ['billing-worker', 'email-worker'];
+ const input = writeFixture(`readability-${command}-${failingIndex}.json`, {
+ schema_version: 1, diagram_type: 'architecture',
+ meta: { title: 'Worker pools', viewBox: [1200, 400] },
+ components: ids.map((id, i) => ({
+ id, type: 'backend', label: 'Worker', sublabel: 'Processes queued jobs',
+ pos: [80 + i * 420, 100], size: [i === failingIndex ? 100 : 300, 70],
+ })),
+ connections: [],
+ });
+ const output = path.join(tmp, `readability-${command}-${failingIndex}.html`);
+ const result = run([command, 'architecture', input,
+ ...(command === 'deliver' ? [output] : []), '--quality', 'showcase', '--json']);
+ assert.equal(result.status, 1);
+ const failure = receipt(result);
+ assert.equal(failure.stage, 'check');
+ const diagnostics = failure.diagnostics.filter(d => d.code === 'composition/desktop-readability');
+ assert.equal(diagnostics.length, 1);
+ assert.deepEqual(diagnostics[0].subject, { check: 'composition', nodeId: ids[failingIndex] });
+ assert.equal(diagnostics[0].evidence.text, 'Processes queued jobs');
+ assert.equal(diagnostics[0].evidence.projectedFontPx, 5.6575);
+ assert.equal(fs.existsSync(output), false);
+ }
+ }
+});