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(evidence): ignore replacement refs for pinned sources (#421)
逺坂凛0857afc82a3f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9fd3fb91..d267195e 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+- **固定提交的来源校验 (#420)。** 校验忽略本地 Git replacement refs,始终读取指定提交的原始对象,避免替换后的文件或行范围造成误接受或误拒绝;保留原有来源链接、诊断与用户 Git 配置。- **Compare 输入快照一致性 (#400)。** 原始输入校验使用首次读取的字节快照,使其与回执哈希和差异计算保持一致;读取后原文件发生变化不会影响本次比较,非法原始字段仍会被拒绝。- **DSH plugin refresh.** Adapter 0.2.0 pins the current Archify development snapshot, includes the newer runtime and CLI fixes, and targets DSH 0.1.2-rc.1. Release metadata replaces the frozen 0.1.0 packaging source; the tarball uses the canonical clean-Skill stager and documents independent plugin upgrades.- **Machine-readable CLI argument failures (#330).** `validate --json` and `deliver --json` now keep invalid or missing option values, unknown options and diagram types, unsupported option combinations, and usage errors inside one versioned failure receipt on stdout. These failures use the `arguments` stage, stable diagnostic codes, and exit status 2, while human-mode stderr behavior remains unchanged.diff --git a/archify.zip b/archify.zipindex f7fdf0f8..a8821f4d 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdindex 70fb1584..6c5c8df3 100644--- a/archify/references/authoring-contract.md+++ b/archify/references/authoring-contract.md@@ -189,7 +189,11 @@ proximity or naming alone.Declare `meta.repository.url` and one full 40-character `revision`, then attach`components[].sources` with repository-relative `path`, optional `line`,`end_line`, and `label`. Verification reads blobs at that commit, independently-of working-tree edits. A matching local origin, available commit, bounded path,+of working-tree edits. Verification ignores local Git replacement refs, including+those selected by `GIT_REPLACE_REF_BASE`, and always reads the original objects+at the pinned SHA. It does not change repository configuration or delete+replacement refs.+A matching local origin, available commit, bounded path,blob, and valid line range are required in every link mode. Verification islocal and makes no remote requests; it establishes neither public availabilitynor the current reader's access rights.diff --git a/archify/renderers/shared/repository-evidence.mjs b/archify/renderers/shared/repository-evidence.mjsindex fdfa5311..e0b805ec 100644--- a/archify/renderers/shared/repository-evidence.mjs+++ b/archify/renderers/shared/repository-evidence.mjs@@ -19,7 +19,8 @@ function evidenceFailure(code, message, { subject = {}, evidence = {}, supported}function runGit(repoRoot, args) {- const result = spawnSync('git', ['-C', repoRoot, ...args], {+ // 固定 SHA 的来源必须读取原始对象,不能使用本地 replacement refs 的替换内容。+ const result = spawnSync('git', ['--no-replace-objects', '-C', repoRoot, ...args], {encoding: 'utf8',maxBuffer: 16 * 1024 * 1024,});diff --git a/archify/test/repository-evidence-replacement.test.mjs b/archify/test/repository-evidence-replacement.test.mjsnew file mode 100644index 00000000..bc58b943--- /dev/null+++ b/archify/test/repository-evidence-replacement.test.mjs@@ -0,0 +1,136 @@+import assert from 'node:assert/strict';+import { execFileSync, spawnSync } from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import test from 'node:test';+import { fileURLToPath } from 'node:url';++const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const cli = path.join(skillRoot, 'bin', 'archify.mjs');+const repositoryUrl = 'https://github.com/example/evidence-replacement';+const shortFile = 'first\n';+const longFile = 'first\nsecond\nthird\n';+const cases = [+ { name: 'commit replacement adds a missing file', kind: 'commit', original: null, replacement: longFile, code: 'file-missing' },+ { name: 'commit replacement adds out-of-range lines', kind: 'commit', original: shortFile, replacement: longFile, code: 'line-out-of-range' },+ { name: 'commit replacement removes a valid file', kind: 'commit', original: longFile, replacement: null },+ { name: 'commit replacement shortens valid lines', kind: 'commit', original: longFile, replacement: shortFile },+ { name: 'blob replacement adds out-of-range lines', kind: 'blob', original: shortFile, replacement: longFile, code: 'line-out-of-range' },+ { name: 'blob replacement shortens valid lines', kind: 'blob', original: longFile, replacement: shortFile },+ { name: 'custom replacement namespace adds out-of-range lines', kind: 'commit', original: shortFile, replacement: longFile, code: 'line-out-of-range', refBase: 'refs/test-replacements/' },+];++function fixture(t, scenario) {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-evidence-replacement-'));+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));+ const repo = path.join(root, 'repo');+ fs.mkdirSync(repo);+ // 隔离调用者的 Git 环境与配置,不改动真实 HOME 或全局配置。+ const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));+ Object.assign(env, {+ GIT_CONFIG_NOSYSTEM: '1',+ GIT_CONFIG_GLOBAL: os.devNull,+ GIT_TERMINAL_PROMPT: '0',+ ...(scenario.refBase ? { GIT_REPLACE_REF_BASE: scenario.refBase } : {}),+ });+ const git = (...args) => execFileSync('git', ['-C', repo, ...args], {+ env, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'],+ }).trim();+ git('init', '--template=');+ git('config', 'user.name', 'Archify Tests');+ git('config', 'user.email', '[email protected]');+ git('config', 'commit.gpgSign', 'false');+ git('config', 'core.autocrlf', 'false');+ git('remote', 'add', 'origin', `${repositoryUrl}.git`);+ fs.writeFileSync(path.join(repo, 'anchor.txt'), 'keep the repository nonempty\n');+ const source = path.join(repo, 'source.js');+ if (scenario.original !== null) fs.writeFileSync(source, scenario.original);+ git('add', 'anchor.txt', ...(scenario.original === null ? [] : ['source.js']));+ git('commit', '-m', 'original evidence');+ const revision = git('rev-parse', 'HEAD');++ const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', 'web-app.architecture.json'), 'utf8'));+ diagram.meta.repository = { url: repositoryUrl, revision };+ diagram.components[0].sources = [{ path: 'source.js', line: 2, end_line: 3 }];+ const input = path.join(root, 'diagram.json');+ const output = path.join(root, 'diagram.html');+ fs.writeFileSync(input, JSON.stringify(diagram));+ const run = (command) => spawnSync(process.execPath, [+ cli, command, 'architecture', input, ...(command === 'deliver' ? [output] : []),+ '--repo-root', repo, '--json',+ ], { env, cwd: skillRoot, encoding: 'utf8', timeout: 20000 });++ function installReplacement() {+ let replaced = revision;+ let replacement;+ if (scenario.kind === 'blob') {+ replaced = git('rev-parse', `${revision}:source.js`);+ const blob = path.join(root, 'replacement-blob');+ fs.writeFileSync(blob, scenario.replacement);+ replacement = git('hash-object', '-w', blob);+ } else {+ if (scenario.replacement === null) fs.unlinkSync(source);+ else fs.writeFileSync(source, scenario.replacement);+ git('add', '-A');+ git('commit', '-m', 'replacement evidence');+ replacement = git('rev-parse', 'HEAD');+ }+ git('replace', replaced, replacement);+ const ref = `${scenario.refBase || 'refs/replace/'}${replaced}`;+ assert.equal(git('rev-parse', ref), replacement);+ // 证明夹具确实改变 Git 读取结果,而非只创建无效的 replacement ref。+ if (scenario.replacement === null) {+ assert.throws(() => git('show', `${revision}:source.js`));+ } else {+ assert.equal(git('show', `${revision}:source.js`), scenario.replacement.trim());+ }+ return () => assert.equal(git('rev-parse', ref), replacement, 'CLI must preserve replacement refs');+ }+ return { root, source, revision, output, run, installReplacement, nodeId: diagram.components[0].id };+}++function checkEvidence(data, scenario, checkRefs = () => {}) {+ for (const command of ['validate', 'deliver']) {+ fs.writeFileSync(data.output, 'trusted previous artifact');+ const result = data.run(command);+ checkRefs();+ assert.ifError(result.error);+ assert.equal(result.status, scenario.code ? 1 : 0, `${command}: ${result.stderr || result.stdout}`);+ const receipt = JSON.parse(result.stdout);+ if (scenario.code) {+ assert.ok(receipt.diagnostics.some(({ code }) => code === `repository-evidence/${scenario.code}`), JSON.stringify(receipt));+ assert.equal(fs.readFileSync(data.output, 'utf8'), 'trusted previous artifact');+ } else if (command === 'deliver') {+ assert.equal(receipt.evidence.revision, data.revision);+ assert.equal(receipt.evidence.verified, true);+ const html = fs.readFileSync(data.output, 'utf8');+ const payload = html.match(/<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/);+ assert.ok(payload, 'verified evidence payload missing');+ const evidence = JSON.parse(payload[1]);+ assert.equal(evidence.repository.revision, data.revision);+ assert.equal(evidence.verified, true);+ const [source] = evidence.nodes[data.nodeId];+ assert.equal(source.line, 2);+ assert.equal(source.endLine, 3);+ assert.equal(source.href, `${repositoryUrl}/blob/${data.revision}/source.js#L2-L3`);+ }+ }+}++for (const scenario of cases) {+ test(`pinned evidence ignores ${scenario.name}`, { timeout: 60000 }, (t) => {+ const data = fixture(t, scenario);+ checkEvidence(data, scenario);+ const checkRefs = data.installReplacement();+ checkEvidence(data, scenario, checkRefs);+ });+}++test('pinned evidence ignores dirty working files without replacement refs', { timeout: 60000 }, (t) => {+ const scenario = { original: longFile };+ const data = fixture(t, scenario);+ checkEvidence(data, scenario);+ fs.writeFileSync(data.source, shortFile);+ checkEvidence(data, scenario);+});