artifact-graph 0.8.2 → 0.8.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/INSTALL.md +21 -0
- package/README.md +22 -0
- package/README.zh-CN.md +20 -0
- package/contracts/e2e-test/schema.json +315 -0
- package/dist/cli.d.ts +9 -0
- package/dist/cli.js +10199 -0
- package/dist/index.cjs +8652 -0
- package/dist/index.d.cts +1500 -0
- package/dist/index.d.ts +1500 -0
- package/dist/index.js +8536 -0
- package/package.json +1 -1
- package/templates/git-hooks/pre-commit.sh +5 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,38 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.8.4
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Version-lock audit and refresh Markdown now explains findings in Chinese, labels each item as a
|
|
8
|
+
blocking error or non-blocking warning, and includes concrete review, refresh, cleanup, and staging
|
|
9
|
+
commands.
|
|
10
|
+
- `missing_lock` remains non-blocking by default and is promoted only by
|
|
11
|
+
`--strict-missing-lock`; runner liveness findings are warnings and no longer fail commits on their
|
|
12
|
+
own. Markdown summaries and CLI exit codes now share the same policy decision.
|
|
13
|
+
- `version-lock refresh --all --remove-orphans` is documented in CLI help and remediation output as
|
|
14
|
+
the safe cleanup path after deleting, renaming, or splitting artifacts. Structural orphan locks
|
|
15
|
+
remain blocking until the user explicitly reviews and removes them.
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- Pre-commit guidance now distinguishes a successful refresh that changed the lock file from a
|
|
20
|
+
validation failure, and gives the exact review, stage, and retry steps.
|
|
21
|
+
|
|
22
|
+
## 0.8.3
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- Restored the complete npm runtime payload: `dist/cli.js`, ESM/CJS modules, declarations, and
|
|
27
|
+
`contracts/e2e-test/schema.json` are now present in the published tarball. Versions 0.8.0 through
|
|
28
|
+
0.8.2 omitted these generated entry points and cannot provide the declared CLI or library exports.
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- The release build now rebuilds `dist/`, verifies every `package.json.files` path against the
|
|
33
|
+
release-skill public snapshot, requires every manifest entry point, installs the packed consumer,
|
|
34
|
+
and configures a post-publish CLI smoke check.
|
|
35
|
+
|
|
3
36
|
## 0.8.2
|
|
4
37
|
|
|
5
38
|
### Changed
|
package/INSTALL.md
CHANGED
|
@@ -90,6 +90,27 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
|
|
|
90
90
|
> Use `version-lock refresh --all` for the initial lock. The `--changed-only --staged` variant is for
|
|
91
91
|
> pre-commit hooks on existing projects — not for first-time initialization.
|
|
92
92
|
|
|
93
|
+
## Cleaning Up Orphan Locks
|
|
94
|
+
|
|
95
|
+
After deleting or splitting an artifact (or removing a traceability edge), the affected version
|
|
96
|
+
locks become orphans. Refresh retains them by default; clean them up explicitly and review the
|
|
97
|
+
result before staging:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# pnpm
|
|
101
|
+
pnpm exec artifact-graph version-lock refresh --all --remove-orphans --format markdown
|
|
102
|
+
git diff artifacts/traceability-version-lock.json # review the removed lock entries
|
|
103
|
+
git add artifacts/traceability-version-lock.json # stage, then commit again
|
|
104
|
+
|
|
105
|
+
# npm
|
|
106
|
+
npx artifact-graph version-lock refresh --all --remove-orphans --format markdown
|
|
107
|
+
git diff artifacts/traceability-version-lock.json
|
|
108
|
+
git add artifacts/traceability-version-lock.json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`version-lock audit` reports structural orphan locks and stale hashes as blocking issues with
|
|
112
|
+
remediation steps; runner liveness findings are non-blocking warnings.
|
|
113
|
+
|
|
93
114
|
## Smoke Test
|
|
94
115
|
|
|
95
116
|
Run these commands to confirm the installation is working:
|
package/README.md
CHANGED
|
@@ -73,6 +73,28 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
|
|
|
73
73
|
having an empty relation list; run `refresh --all` once to establish the complete relation baseline.
|
|
74
74
|
- Install opt-in Git hooks with `artifact-graph hooks install-git --hook all`.
|
|
75
75
|
|
|
76
|
+
### Cleaning Up Orphan Locks After Deleting or Splitting Artifacts
|
|
77
|
+
|
|
78
|
+
When an artifact, source file, or traceability edge no longer exists — typically after deleting
|
|
79
|
+
or splitting an artifact — its version locks become orphans. `version-lock refresh` retains
|
|
80
|
+
orphan locks by default so cleanup stays an explicit, reviewable decision:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
# pnpm
|
|
84
|
+
pnpm exec artifact-graph version-lock refresh --all --remove-orphans --format markdown
|
|
85
|
+
git diff artifacts/traceability-version-lock.json # review the removed lock entries
|
|
86
|
+
git add artifacts/traceability-version-lock.json # stage, then commit again
|
|
87
|
+
|
|
88
|
+
# npm
|
|
89
|
+
npx artifact-graph version-lock refresh --all --remove-orphans --format markdown
|
|
90
|
+
git diff artifacts/traceability-version-lock.json
|
|
91
|
+
git add artifacts/traceability-version-lock.json
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`version-lock audit` marks structural orphan locks and stale hashes as blocking issues and prints
|
|
95
|
+
these same remediation steps. Runner liveness findings (a test file no longer active in any
|
|
96
|
+
configured runner) are warnings only and do not block.
|
|
97
|
+
|
|
76
98
|
## Review Result Protocol
|
|
77
99
|
|
|
78
100
|
The package publishes `schemas/review-result.schema.json`, plus matching TypeScript types and a
|
package/README.zh-CN.md
CHANGED
|
@@ -69,6 +69,26 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
|
|
|
69
69
|
`artifactRelations` 时视为空数组；首次启用时执行一次 `refresh --all` 建立完整关系基线。
|
|
70
70
|
- 用 `artifact-graph hooks install-git --hook all` 安装可选 Git hooks。
|
|
71
71
|
|
|
72
|
+
### 制品删除或拆分后的孤立锁清理
|
|
73
|
+
|
|
74
|
+
当制品、源码文件或追溯边不再存在时（常见于制品删除或拆分之后），对应的版本锁会成为
|
|
75
|
+
孤立锁。`version-lock refresh` 默认保留孤立锁，让清理始终是一次显式、可审查的操作：
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# pnpm
|
|
79
|
+
pnpm exec artifact-graph version-lock refresh --all --remove-orphans --format markdown
|
|
80
|
+
git diff artifacts/traceability-version-lock.json # 审查被移除的锁条目
|
|
81
|
+
git add artifacts/traceability-version-lock.json # 暂存后重新提交
|
|
82
|
+
|
|
83
|
+
# npm
|
|
84
|
+
npx artifact-graph version-lock refresh --all --remove-orphans --format markdown
|
|
85
|
+
git diff artifacts/traceability-version-lock.json
|
|
86
|
+
git add artifacts/traceability-version-lock.json
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`version-lock audit` 会把结构性孤立锁和陈旧哈希标记为阻断问题，并输出上述解决步骤；
|
|
90
|
+
runner liveness 发现（测试文件不再处于任何已配置 runner 的激活范围）只是警告，不会阻断。
|
|
91
|
+
|
|
72
92
|
## Review Result Protocol
|
|
73
93
|
|
|
74
94
|
包内发布了 `schemas/review-result.schema.json`，以及配套的 TypeScript 类型和 `validateReviewResult`
|
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "artifact.e2e-test@1",
|
|
4
|
+
"title": "Artifact Contract: E2E Test Specification",
|
|
5
|
+
"description": "Minimal schema for E2E test specification artifacts",
|
|
6
|
+
"version": "1.0.0",
|
|
7
|
+
"contractIdentity": {
|
|
8
|
+
"major": "artifact.e2e-test@1",
|
|
9
|
+
"authority": "artifact",
|
|
10
|
+
"namespace": "artifact",
|
|
11
|
+
"revisionDigest": "sha256:374b99424519e42b40b621774fb602d62dfa23f48f792095f717bbabbe9e3f2a",
|
|
12
|
+
"relationRules": {
|
|
13
|
+
"derives_from": {
|
|
14
|
+
"allowedTargetTypes": ["scenario", "design", "decision"],
|
|
15
|
+
"min": 1,
|
|
16
|
+
"max": 10,
|
|
17
|
+
"anchorPolicy": "optional"
|
|
18
|
+
},
|
|
19
|
+
"verifies": {
|
|
20
|
+
"allowedTargetTypes": ["feature", "scenario"],
|
|
21
|
+
"min": 1,
|
|
22
|
+
"max": 5,
|
|
23
|
+
"anchorPolicy": "required"
|
|
24
|
+
},
|
|
25
|
+
"implemented_by": {
|
|
26
|
+
"allowedTargetTypes": ["code"],
|
|
27
|
+
"min": 0,
|
|
28
|
+
"max": 5,
|
|
29
|
+
"anchorPolicy": "optional"
|
|
30
|
+
},
|
|
31
|
+
"references": {
|
|
32
|
+
"allowedTargetTypes": ["feature", "scenario", "decision", "design", "e2e_test", "test"],
|
|
33
|
+
"min": 0,
|
|
34
|
+
"max": 20,
|
|
35
|
+
"anchorPolicy": "optional"
|
|
36
|
+
},
|
|
37
|
+
"covers": {
|
|
38
|
+
"allowedTargetTypes": ["feature", "scenario"],
|
|
39
|
+
"min": 0,
|
|
40
|
+
"max": 10,
|
|
41
|
+
"anchorPolicy": "optional"
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
"semanticMarkers": {
|
|
45
|
+
"scope": {
|
|
46
|
+
"jsonPointer": "/scope",
|
|
47
|
+
"markdownMarker": "scope",
|
|
48
|
+
"required": true
|
|
49
|
+
},
|
|
50
|
+
"system_boundary": {
|
|
51
|
+
"jsonPointer": "/system_boundary",
|
|
52
|
+
"markdownMarker": "system-boundary",
|
|
53
|
+
"required": true
|
|
54
|
+
},
|
|
55
|
+
"coverage": {
|
|
56
|
+
"jsonPointer": "/coverage",
|
|
57
|
+
"markdownMarker": "coverage",
|
|
58
|
+
"required": true
|
|
59
|
+
},
|
|
60
|
+
"environment_data": {
|
|
61
|
+
"jsonPointer": "/environment_data",
|
|
62
|
+
"markdownMarker": "environment-data",
|
|
63
|
+
"required": true
|
|
64
|
+
},
|
|
65
|
+
"test_cases": {
|
|
66
|
+
"jsonPointer": "/test_cases",
|
|
67
|
+
"markdownMarker": "test-cases",
|
|
68
|
+
"required": true
|
|
69
|
+
},
|
|
70
|
+
"evidence_contract": {
|
|
71
|
+
"jsonPointer": "/evidence_contract",
|
|
72
|
+
"markdownMarker": "evidence-contract",
|
|
73
|
+
"required": true
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
"type": "object",
|
|
78
|
+
"required": ["metadata", "scope", "system_boundary", "coverage", "environment_data", "relations", "test_cases", "evidence_contract"],
|
|
79
|
+
"properties": {
|
|
80
|
+
"metadata": {
|
|
81
|
+
"type": "object",
|
|
82
|
+
"required": ["id", "title", "status"],
|
|
83
|
+
"properties": {
|
|
84
|
+
"id": {
|
|
85
|
+
"type": "string",
|
|
86
|
+
"pattern": "^[A-Za-z0-9._-]+:(TC-\\d+[a-z]?|FILE)$"
|
|
87
|
+
},
|
|
88
|
+
"title": {
|
|
89
|
+
"type": "string",
|
|
90
|
+
"minLength": 1
|
|
91
|
+
},
|
|
92
|
+
"status": {
|
|
93
|
+
"type": "string",
|
|
94
|
+
"enum": ["planned", "active", "done", "deprecated"]
|
|
95
|
+
},
|
|
96
|
+
"test_batch": {
|
|
97
|
+
"type": "string"
|
|
98
|
+
}
|
|
99
|
+
},
|
|
100
|
+
"additionalProperties": false
|
|
101
|
+
},
|
|
102
|
+
"scope": {
|
|
103
|
+
"type": "object",
|
|
104
|
+
"required": ["business_goal", "actors"],
|
|
105
|
+
"properties": {
|
|
106
|
+
"business_goal": {
|
|
107
|
+
"type": "string",
|
|
108
|
+
"minLength": 1
|
|
109
|
+
},
|
|
110
|
+
"actors": {
|
|
111
|
+
"type": "array",
|
|
112
|
+
"items": { "type": "string" },
|
|
113
|
+
"minItems": 1
|
|
114
|
+
},
|
|
115
|
+
"system_boundaries": {
|
|
116
|
+
"type": "array",
|
|
117
|
+
"items": { "type": "string" }
|
|
118
|
+
},
|
|
119
|
+
"non_goals": {
|
|
120
|
+
"type": "array",
|
|
121
|
+
"items": { "type": "string" }
|
|
122
|
+
}
|
|
123
|
+
},
|
|
124
|
+
"additionalProperties": false
|
|
125
|
+
},
|
|
126
|
+
"system_boundary": {
|
|
127
|
+
"type": "object",
|
|
128
|
+
"required": ["components"],
|
|
129
|
+
"properties": {
|
|
130
|
+
"components": {
|
|
131
|
+
"type": "array",
|
|
132
|
+
"items": { "type": "string" },
|
|
133
|
+
"minItems": 1
|
|
134
|
+
},
|
|
135
|
+
"external_dependencies": {
|
|
136
|
+
"type": "array",
|
|
137
|
+
"items": { "type": "string" }
|
|
138
|
+
},
|
|
139
|
+
"trust_boundaries": {
|
|
140
|
+
"type": "array",
|
|
141
|
+
"items": { "type": "string" }
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
"additionalProperties": false
|
|
145
|
+
},
|
|
146
|
+
"coverage": {
|
|
147
|
+
"type": "object",
|
|
148
|
+
"required": [],
|
|
149
|
+
"properties": {
|
|
150
|
+
"ac_coverage": {
|
|
151
|
+
"type": "object",
|
|
152
|
+
"additionalProperties": {
|
|
153
|
+
"type": "array",
|
|
154
|
+
"items": { "type": "string" }
|
|
155
|
+
}
|
|
156
|
+
},
|
|
157
|
+
"related_scenarios": {
|
|
158
|
+
"type": "array",
|
|
159
|
+
"items": { "type": "string" }
|
|
160
|
+
},
|
|
161
|
+
"related_features": {
|
|
162
|
+
"type": "array",
|
|
163
|
+
"items": { "type": "string" }
|
|
164
|
+
},
|
|
165
|
+
"related_decisions": {
|
|
166
|
+
"type": "array",
|
|
167
|
+
"items": { "type": "string" }
|
|
168
|
+
}
|
|
169
|
+
},
|
|
170
|
+
"additionalProperties": false
|
|
171
|
+
},
|
|
172
|
+
"environment_data": {
|
|
173
|
+
"type": "object",
|
|
174
|
+
"properties": {
|
|
175
|
+
"topology": {
|
|
176
|
+
"type": "string"
|
|
177
|
+
},
|
|
178
|
+
"fixtures": {
|
|
179
|
+
"type": "array",
|
|
180
|
+
"items": { "type": "string" }
|
|
181
|
+
},
|
|
182
|
+
"identities": {
|
|
183
|
+
"type": "array",
|
|
184
|
+
"items": { "type": "string" }
|
|
185
|
+
},
|
|
186
|
+
"isolation_strategy": {
|
|
187
|
+
"type": "string"
|
|
188
|
+
}
|
|
189
|
+
},
|
|
190
|
+
"additionalProperties": false
|
|
191
|
+
},
|
|
192
|
+
"relations": {
|
|
193
|
+
"type": "array",
|
|
194
|
+
"description": "Machine-readable relation declarations: kind, target type/id, optional anchor, and contract-level cardinality rules",
|
|
195
|
+
"minItems": 2,
|
|
196
|
+
"items": {
|
|
197
|
+
"type": "object",
|
|
198
|
+
"required": ["kind", "target_type", "target_id"],
|
|
199
|
+
"properties": {
|
|
200
|
+
"kind": {
|
|
201
|
+
"type": "string",
|
|
202
|
+
"enum": ["derives_from", "verifies", "implemented_by", "references", "covers"]
|
|
203
|
+
},
|
|
204
|
+
"target_type": {
|
|
205
|
+
"type": "string",
|
|
206
|
+
"enum": ["feature", "scenario", "decision", "design", "e2e_test", "test", "code"]
|
|
207
|
+
},
|
|
208
|
+
"target_id": {
|
|
209
|
+
"type": "string",
|
|
210
|
+
"minLength": 1
|
|
211
|
+
},
|
|
212
|
+
"anchor": {
|
|
213
|
+
"type": "string",
|
|
214
|
+
"description": "Optional anchor point (e.g., section marker, line reference)"
|
|
215
|
+
}
|
|
216
|
+
},
|
|
217
|
+
"additionalProperties": false
|
|
218
|
+
}
|
|
219
|
+
},
|
|
220
|
+
"test_cases": {
|
|
221
|
+
"type": "array",
|
|
222
|
+
"items": {
|
|
223
|
+
"$ref": "#/definitions/testCase"
|
|
224
|
+
},
|
|
225
|
+
"minItems": 1
|
|
226
|
+
},
|
|
227
|
+
"evidence_contract": {
|
|
228
|
+
"type": "object",
|
|
229
|
+
"required": ["required_artifacts"],
|
|
230
|
+
"properties": {
|
|
231
|
+
"required_artifacts": {
|
|
232
|
+
"type": "array",
|
|
233
|
+
"items": { "type": "string" },
|
|
234
|
+
"minItems": 1
|
|
235
|
+
},
|
|
236
|
+
"runner_binding": {
|
|
237
|
+
"type": "string"
|
|
238
|
+
},
|
|
239
|
+
"proof_requirements": {
|
|
240
|
+
"type": "array",
|
|
241
|
+
"items": { "type": "string" }
|
|
242
|
+
}
|
|
243
|
+
},
|
|
244
|
+
"additionalProperties": false
|
|
245
|
+
}
|
|
246
|
+
},
|
|
247
|
+
"additionalProperties": false,
|
|
248
|
+
"definitions": {
|
|
249
|
+
"testCase": {
|
|
250
|
+
"type": "object",
|
|
251
|
+
"required": ["case_id", "goal", "preconditions", "actions", "oracles", "cleanup", "priority", "trace_targets"],
|
|
252
|
+
"properties": {
|
|
253
|
+
"case_id": {
|
|
254
|
+
"type": "string",
|
|
255
|
+
"pattern": "^TC-\\d+[a-z]?$"
|
|
256
|
+
},
|
|
257
|
+
"goal": {
|
|
258
|
+
"type": "string",
|
|
259
|
+
"minLength": 1
|
|
260
|
+
},
|
|
261
|
+
"preconditions": {
|
|
262
|
+
"type": "array",
|
|
263
|
+
"items": { "type": "string" },
|
|
264
|
+
"minItems": 1
|
|
265
|
+
},
|
|
266
|
+
"actions": {
|
|
267
|
+
"type": "array",
|
|
268
|
+
"items": {
|
|
269
|
+
"type": "object",
|
|
270
|
+
"required": ["step", "action"],
|
|
271
|
+
"properties": {
|
|
272
|
+
"step": { "type": "integer", "minimum": 1 },
|
|
273
|
+
"action": { "type": "string", "minLength": 1 },
|
|
274
|
+
"expected_result": { "type": "string" }
|
|
275
|
+
},
|
|
276
|
+
"additionalProperties": false
|
|
277
|
+
},
|
|
278
|
+
"minItems": 1
|
|
279
|
+
},
|
|
280
|
+
"oracles": {
|
|
281
|
+
"type": "array",
|
|
282
|
+
"items": {
|
|
283
|
+
"type": "object",
|
|
284
|
+
"required": ["observable", "criterion"],
|
|
285
|
+
"properties": {
|
|
286
|
+
"observable": { "type": "string", "minLength": 1 },
|
|
287
|
+
"criterion": { "type": "string", "minLength": 1 },
|
|
288
|
+
"timeout_ms": { "type": "integer", "minimum": 0 }
|
|
289
|
+
},
|
|
290
|
+
"additionalProperties": false
|
|
291
|
+
},
|
|
292
|
+
"minItems": 1
|
|
293
|
+
},
|
|
294
|
+
"cleanup": {
|
|
295
|
+
"type": "array",
|
|
296
|
+
"items": { "type": "string" }
|
|
297
|
+
},
|
|
298
|
+
"priority": {
|
|
299
|
+
"type": "string",
|
|
300
|
+
"enum": ["critical", "high", "medium", "low"]
|
|
301
|
+
},
|
|
302
|
+
"trace_targets": {
|
|
303
|
+
"type": "array",
|
|
304
|
+
"items": { "type": "string" },
|
|
305
|
+
"minItems": 1
|
|
306
|
+
},
|
|
307
|
+
"path_class": {
|
|
308
|
+
"type": "string",
|
|
309
|
+
"enum": ["happy", "error", "recovery", "edge", "security", "performance"]
|
|
310
|
+
}
|
|
311
|
+
},
|
|
312
|
+
"additionalProperties": false
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
}
|
package/dist/cli.d.ts
ADDED