Skip to content

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

Merge current dev and adapt migration semantic regressions

To3akaRina94d1f91cdfb
diff --cc CHANGELOG.md
index ffb3b6e6,c6c4f822..b1c259f9
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -8,8 -8,45 +8,47 @@@ All notable changes are documented here
### Fixed
+- **Workflow migration semantic contracts (#497).** Layout planning no longer checks full-topology requirements against a temporary graph with routed edges removed. Migrated documents retain their authored contracts and must pass complete validation before publication.
+
+ - **Timeline 时区刻度(#926)。** 刻度按显示时区在各真实时刻的 UTC 偏移对齐,修复跨夏令时后日刻度漂移到 01:00/23:00、半小时跳变后小时刻度漂移的问题。回拨的重复时刻保持独立,跳过的小时或日期不生成虚构刻度;事件时间、标签精度、时间轴比例与断轴规则保持不变。
+
+ ### Changed
+ - **发布后的开发基线。** 在已发布的 3.1.0 代码和验证产物基础上开启 3.1.1-dev.1 开发周期,同步开发身份与可重现的示例、比较图和网站产物。稳定更新清单继续指向已发布的 3.1.0;本次不创建发布或更改已发布版本。
+
+ ## [3.1.0] — 2026-10-14
+
+ ### Release highlights
+ - **Ten diagram types.** ERD, Class/interface, Tree, Timeline and Waterfall join Architecture, Workflow, Sequence, Dataflow and Lifecycle, with typed JSON, source evidence and standalone Viewer exports.
+ - **Live by default.** Each diagram type uses a matching motion choreography; readers can switch to Still. Motion remains separate from authored topology and export geometry.
+ - **Readable authoring and recovery.** Bounded route/label coordination, clearer node cards, wrapped Sequence notes, main-path Lifecycle layouts, long-page radar navigation and executable geometry diagnostics reduce avoidable repair work.
+ - **Verified delivery and portability.** Finalize reports input, artifact and browser gates separately; repository evidence, atomic delivery, clipboard/export continuity and Windows path handling fail closed with actionable diagnostics.
+ - **Guide and handoff.** Concise artifact-first delivery and a localized optional GitHub link inside the reader-opened Guide.
+
+ ### Known limitations
+ - Large Sequence diagrams may require readable page scrolling; floating controls can overlap content at some initial viewport positions.
+ - Some complex Dataflow inputs share visual corridors; long Class generic types can wrap awkwardly. Automatic validation does not establish perceptual quality.
+ - Waterfall durations need recorded trace evidence to be called measured; author-supplied illustrative values remain labelled.
+ - The independently published DSH plugin remains pinned to Archify 3.0.1. Synchronization requires a separate plugin release and host acceptance; the 3.1.0 Skill release does not update it.
+
+ ### Added
+ - **Traditional Chinese (Taiwan) Viewer catalog.** `meta.locale: "zh-TW"` now selects a bundled catalog covering all 487 Viewer keys with Taiwan terminology (for example 循序圖, 資料流, 匯出, 檢視), instead of falling back to English. Enrollment is data only: `locales/zh-TW.json` plus one manifest entry. `zh-Hant` and `zh-HK` remain distinct, unbundled tags.
+ - **GitLab source links.** Repository evidence on gitlab.com, or on a self-managed host declared with `provider: "gitlab"`, now generates revision-pinned web links (`/-/blob/<revision>/<path>#L<a>-<b>`, `/-/tree/<revision>`) instead of requiring `link_mode: "local-only"`. Nested groups are accepted, SSH and HTTPS origins on the same host match, paths compare case-insensitively, and cited Markdown line ranges open the plain view. Verification is unchanged and `local-only` remains available.
+
+ ### Fixed
+
+ - **WebM 录制失败清理 (#622)。** 画布、捕获流、编码器启动、逐帧绘制或停止失败时,录制 Promise 现在会拒绝并释放已创建的流、临时 URL、动画帧和定时器;晚到的编码事件不能再将失败录制报告为成功。正常编码与最佳努力的最终片段 flush 行为保持不变。
+
+ - **类图混合关系的主干冲突(#791)。** 自动继承/实现主干会检查组外路线的端口、走廊和交叉;冲突组回退到独立路由,避免依赖箭头被继承三角覆盖或实线覆盖实现虚线。无冲突主干、显式几何及关系语义保持不变;空 `via: []` 与省略路径点统一处理,避免合法输入在回退后产生非法斜线。
+ - **SVG 路径检查(#641)。** 统一解析关系线和结构边界的 `M/L/H/V/Q/Z` 路径,正确保留子路径与闭合语义;截断参数、非法数值和不支持的命令现在有限失败并给出定位诊断,避免检查挂起、漏检或虚构跨子路径线段。非共线 `Q` 前后的直线保留真实连续性,避免虚假交叉、标签遮挡和漏检;曲线采样点不会增加微线段预算。普通有效产物的 9 项检查保持不变。
+ - **Inactive brand icon declarations.** Capture ignores icon markup in comments, raw text (including `noscript` for `text/html`), quoted attributes and templates, so inactive page edits cannot replace the selected image or break its pinned digest. Complete link attributes keep quoted delimiters and distinguish `href` from `data-href`; XHTML `noscript` discovery and links after empty elements are preserved. Old pins to inactive markup may require inspecting and explicitly recapturing the intended icon; digest checking remains enforced.
+ - **Brand ICO data bounds (#585).** Capture and pinned re-fetches reject empty, directory-overlapping or out-of-bounds image ranges in ICO directory entries, while preserving valid PNG/DIB payloads and normal icon fallback.
+
+ ### Changed
+ - **Pending DSH 1.0.0 bundle synchronized to stable Archify 3.0.1.** The immutable source includes the post-tag Skill installation fix (#704), with both packaged version identities verified. Isolated acceptance verifies the published 0.1.0 upgrade path on DSH 0.1.2-rc.1 and keeps mutating example checks outside pnpm store hard links. Archify releases now record a DSH sync or explicit deferral decision. The plugin remains unpublished; public installation still uses DSH plugin 0.1.0 with Archify 2.14.0 until a separate verified release.
+ - **Bundled Viewer catalogs selected by `meta.locale`.** `archify/locales/manifest.json` enrolls package-owned catalogs (`en`, `zh-CN`, `es`, `ko`); English and Simplified Chinese moved from renderer tuples into the same data. Each message resolves as valid `meta.translations` value → selected bundled catalog → English, so a one-key override keeps the rest of the language. Enrolling another language is a data-only change. Catalogs load relative to the installed package, never from the working directory, and standalone HTML still embeds only the resolved Viewer messages. (#588)
+ - **Intentional differences from 3.0.1.** Locale-only `es`/`ko` now render Spanish/Korean UI instead of English. A partial `meta.translations` (including for `zh-CN`) now falls through to the same-language bundled catalog before English; in 3.0.1 every unsupplied key became English. Equivalent tag casing such as `zh-cn` selects the bundled catalog and emits its canonical tag; region and script variants such as `zh-Hant` still fall back to English. An unbundled tag whose translations are all unusable now falls back to English `lang` as well. Omitted-locale, `en`, `zh-CN`, and complete-catalog inputs render unchanged.
+ - **Locale diagnostics.** `i18n/translation-coverage` now reports the final resolved coverage and lists missing keys with their English source text; rejected overrides (unknown keys, placeholder mismatches) are reported separately as `i18n/invalid-translation` and keep the lower-priority message. Passing `validate --json`, `deliver`, and `finalize` receipts now carry these `i18n/*` warnings in `diagnostics[]` (gates and exit codes are unchanged); previously `finalize` did not surface them at all.
+
## [3.0.1] — 2026-09-28
### Changed
diff --cc archify.zip
index 4cb19058,274b280e..ef2f8a37
Binary files differ
diff --cc test/workflow-migration-semantics.test.mjs
index 822b46a3,00000000..58b34c53
mode 100644,000000..100644
--- a/test/workflow-migration-semantics.test.mjs
+++ b/test/workflow-migration-semantics.test.mjs
@@@ -1,155 -1,0 +1,155 @@@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
- import { intrinsicWorkflow, planningWorkflow } from '../renderers/workflow/workflow-migration-geometry.mjs';
- import { compileWorkflow } from '../renderers/workflow/workflow-compiler.mjs';
++import { intrinsicWorkflow, planningWorkflow } from '../archify/renderers/workflow/workflow-migration-geometry.mjs';
++import { compileWorkflow } from '../archify/renderers/workflow/workflow-compiler.mjs';
+
- const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
++const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'archify');
+const cli = path.join(skillRoot, 'bin/archify.mjs');
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const contracts = {
+ requiredEdges: [{ from: 'a', to: 'b' }],
+ requiredPaths: [{ from: 'a', to: 'b' }],
+ allowedRoots: ['a', 'c', 'obstacle'],
+ allowedTerminals: ['b', 'd', 'obstacle'],
+};
+
+function document(semanticChecks) {
+ return {
+ schema_version: 1,
+ diagram_type: 'workflow',
+ meta: { title: 'Fallback semantic contract', output: 'fallback.html', viewBox: [720, 520], legend: { mode: 'hidden' } },
+ lanes: [
+ { id: 'pin', label: 'Pinned label' },
+ { id: 'straight', label: 'Straight constraint' },
+ { id: 'blocker', label: 'Blocker' },
+ ],
+ nodes: [
+ { id: 'a', lane: 'pin', col: 0, type: 'backend', label: 'A' },
+ { id: 'b', lane: 'pin', col: 1, type: 'backend', label: 'B' },
+ { id: 'c', lane: 'straight', col: 0, type: 'backend', label: 'C' },
+ { id: 'd', lane: 'straight', col: 1, type: 'backend', label: 'D' },
+ { id: 'obstacle', lane: 'blocker', col: 4, type: 'database', label: 'Obstacle' },
+ ],
+ mainPath: ['a', 'b'],
+ semanticChecks: structuredClone(semanticChecks),
+ edges: [
+ { id: 'pin-edge', from: 'a', to: 'b', label: 'p', labelAt: [562, 367], route: 'bottom-channel', fromSide: 'bottom', toSide: 'bottom' },
+ { id: 'straight-edge', from: 'c', to: 'd', label: 'x', route: 'straight' },
+ ],
+ };
+}
+
+function fixture(t, checks) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-migration-semantics-'));
+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+ const source = path.join(root, 'source.workflow.json');
+ const destination = path.join(root, 'destination.workflow.json');
+ const original = document(checks);
+ const bytes = Buffer.from(`${JSON.stringify(original, null, 2)}\n`);
+ fs.writeFileSync(source, bytes);
+ return { root, source, destination, original, bytes };
+}
+
+function run(command, source, destination) {
+ const result = spawnSync(process.execPath, [
+ cli, command, 'workflow', source,
+ ...(command === 'migrate' ? [destination, '--to-schema', '2'] : []), '--json',
+ ], { cwd: skillRoot, encoding: 'utf8', timeout: 30000 });
+ assert.ifError(result.error);
+ return { ...result, report: JSON.parse(result.stdout) };
+}
+
+for (const [name, checks] of [...Object.entries(contracts).map(([key, value]) => [key, { [key]: value }]), ['combined contracts', contracts]]) {
+ test(`fallback migration preserves valid ${name}`, { timeout: 60000 }, (t) => {
+ const data = fixture(t, checks);
+ const validated = run('validate', data.source);
+ assert.equal(validated.status, 0, validated.stderr || validated.stdout);
+ const result = run('migrate', data.source, data.destination);
+ assert.deepEqual(fs.readFileSync(data.source), data.bytes, 'source bytes must remain unchanged');
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ assert.equal(result.report.ok, true);
+ const output = fs.readFileSync(data.destination);
+ const migrated = JSON.parse(output);
+ assert.equal(migrated.schema_version, 2);
+ assert.deepEqual(migrated.semanticChecks, checks);
+ assert.deepEqual(migrated.mainPath, data.original.mainPath);
+ assert.deepEqual(migrated.edges[0].labelAt, [643.52, 367]);
+ const expected = structuredClone(data.original);
+ expected.schema_version = 2;
+ expected.edges[0].labelAt[0] = 643.52;
+ // Capacity expansion is allowed; no other authored field may change.
+ expected.meta.viewBox = migrated.meta.viewBox;
+ assert.deepEqual(migrated, expected);
+ assert.ok(migrated.meta.viewBox.every((value, index) => value >= data.original.meta.viewBox[index]));
+ assert.deepEqual(result.report.changedCoordinates, [{ path: '/edges/0/labelAt/0', from: 562, to: 643.52 }]);
+ assert.deepEqual(result.report.newSchemaDiagnostics, []);
+ assert.equal(result.report.source.sha256, hash(data.bytes));
+ assert.equal(result.report.destination.sha256, hash(output));
+ const destinationValidation = run('validate', data.destination);
+ assert.equal(destinationValidation.status, 0, destinationValidation.stdout);
+
+ if (name === 'combined contracts') {
+ const repeated = path.join(data.root, 'repeated.workflow.json');
+ const repeat = run('migrate', data.destination, repeated);
+ assert.equal(repeat.status, 0, repeat.stderr || repeat.stdout);
+ assert.deepEqual(fs.readFileSync(repeated), output, 'schema-v2 migration must be byte-idempotent');
+ assert.deepEqual(fs.readFileSync(data.destination), output);
+ assert.deepEqual(repeat.report.changedCoordinates, []);
+ }
+ });
+}
+
+for (const [field, value, code] of [
+ ['requiredEdges', [{ from: 'a', to: 'c' }], 'workflow/required-edge'],
+ ['requiredPaths', [{ from: 'b', to: 'a' }], 'workflow/required-path'],
+ ['allowedRoots', ['c', 'obstacle'], 'workflow/unexpected-root'],
+ ['allowedTerminals', ['d', 'obstacle'], 'workflow/unexpected-terminal'],
+]) {
+ test(`authored invalid ${field} still rejects validation and migration`, { timeout: 60000 }, (t) => {
+ const data = fixture(t, { [field]: value });
+ const previous = Buffer.from('{"existing":"trusted destination"}\n');
+ fs.writeFileSync(data.destination, previous);
+ for (const command of ['validate', 'migrate']) {
+ const result = run(command, data.source, data.destination);
+ assert.notEqual(result.status, 0);
+ assert.equal(result.report.ok, false);
+ assert.ok(result.report.diagnostics.some((entry) => entry.code === code), result.stdout);
+ assert.deepEqual(fs.readFileSync(data.source), data.bytes);
+ assert.deepEqual(fs.readFileSync(data.destination), previous);
+ }
+ assert.equal(fs.readdirSync(data.root).some((name) => name.startsWith('.archify-migration-')), false);
+ });
+}
+
+test('only the incomplete planning projection omits semantic contracts without mutating the source', () => {
+ const authored = document(contracts);
+ const before = structuredClone(authored);
+ const intrinsic = intrinsicWorkflow(authored);
+ assert.deepEqual(intrinsic.semanticChecks, contracts);
+ assert.deepEqual(intrinsic.edges, authored.edges);
+ assert.equal(compileWorkflow({ workflow: intrinsic }).ok, false, 'legacy absolute pins require fallback planning');
+ const planned = planningWorkflow(authored);
+ assert.deepEqual(planned.edges.map(({ id }) => id), ['straight-edge']);
+ assert.equal(planned.mainPath, undefined);
+ assert.equal(planned.semanticChecks, undefined);
+ assert.equal(compileWorkflow({ workflow: planned }).ok, true);
+ assert.deepEqual(authored, before);
+});
+
+test('planning keeps semantic contracts when it retains every authored edge', () => {
+ const authored = document(contracts);
+ authored.edges[0] = { id: 'pin-edge', from: 'a', to: 'b', label: 'p', route: 'auto' };
+ const before = structuredClone(authored);
+ const planned = planningWorkflow(authored);
+ assert.deepEqual(planned.semanticChecks, contracts);
+ assert.deepEqual(planned.edges.map(({ id }) => id), authored.edges.map(({ id }) => id));
+ assert.deepEqual(planned.mainPath, authored.mainPath);
+ assert.equal(compileWorkflow({ workflow: planned }).ok, true);
+ assert.deepEqual(authored, before);
+});