Skip to content

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

fix(evidence): ignore replacement refs for pinned sources (#421)

逺坂凛0857afc82a3f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.zip
index f7fdf0f8..a8821f4d 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index 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 is
local and makes no remote requests; it establishes neither public availability
nor the current reader's access rights.
diff --git a/archify/renderers/shared/repository-evidence.mjs b/archify/renderers/shared/repository-evidence.mjs
index 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.mjs
new file mode 100644
index 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);
+});