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
Merge current dev and adapt migration semantic regressions
To3akaRina94d1f91cdfb
diff --cc CHANGELOG.mdindex 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### Changeddiff --cc archify.zipindex 4cb19058,274b280e..ef2f8a37Binary files differdiff --cc test/workflow-migration-semantics.test.mjsindex 822b46a3,00000000..58b34c53mode 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);+});