@gtrabanco/agentic-workflow 0.1.0 → 0.2.0
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/README.md +6 -2
- package/bin/{agwo.mjs → agentic-workflow.mjs} +49 -7
- package/package.json +17 -5
- package/src/doc/chunks.mjs +150 -0
- package/src/doc/config.mjs +64 -0
- package/src/doc/embeddings.mjs +162 -0
- package/src/doc/envelope.mjs +120 -0
- package/src/doc/grammar.mjs +109 -0
- package/src/doc/manifest.mjs +84 -0
- package/src/doc/query.mjs +279 -0
- package/src/doc/retrieval.mjs +82 -0
- package/src/doc/sqlite.mjs +34 -0
- package/src/doc/store.mjs +57 -0
- package/src/doc/sync.mjs +159 -0
- package/src/edit/schema.mjs +1 -1
- package/test/edit.test.mjs +0 -358
- package/test/fixtures.mjs +0 -326
- package/test/path-guard.engine.test.mjs +0 -304
- package/test/turn-contract.engine.test.mjs +0 -103
- package/test/turn-contract.parity.test.mjs +0 -20
package/test/fixtures.mjs
DELETED
|
@@ -1,326 +0,0 @@
|
|
|
1
|
-
// Shared throwaway-repo fixture matrix for the turn-contract suites.
|
|
2
|
-
//
|
|
3
|
-
// The engine suite, the two-engine parity suite, and the grammar conformance
|
|
4
|
-
// test all drive the SAME matrix so a per-box outcome and the receipt grammar
|
|
5
|
-
// are asserted once and reused (D-52-9 proportionality, no combinatorial
|
|
6
|
-
// flag x state sweep). Everything lives in one temp directory; `gh` is a
|
|
7
|
-
// PATH-stub because no suite contacts a forge.
|
|
8
|
-
|
|
9
|
-
import { spawnSync } from "node:child_process";
|
|
10
|
-
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
11
|
-
import os from "node:os";
|
|
12
|
-
import path from "node:path";
|
|
13
|
-
import { fileURLToPath } from "node:url";
|
|
14
|
-
|
|
15
|
-
const here = path.dirname(fileURLToPath(import.meta.url));
|
|
16
|
-
export const REPO_ROOT = path.resolve(here, "..", "..", "..");
|
|
17
|
-
export const ENGINE = path.join(REPO_ROOT, "packages/agentic-workflow/bin/turn-contract.mjs");
|
|
18
|
-
export const SHIM = path.join(REPO_ROOT, "template/.agentic-workflow/hooks/turn-contract.sh");
|
|
19
|
-
|
|
20
|
-
const GIT_CONFIG = ["-c", "user.email=t@example.com", "-c", "user.name=test", "-c", "commit.gpgsign=false"];
|
|
21
|
-
|
|
22
|
-
export function git(cwd, ...args) {
|
|
23
|
-
const r = spawnSync("git", [...GIT_CONFIG, "-C", cwd, ...args], { encoding: "utf8" });
|
|
24
|
-
if (r.status !== 0) throw new Error(`git ${args.join(" ")} in ${cwd} failed: ${r.stderr}`);
|
|
25
|
-
return r.stdout.trimEnd();
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
function gitInit(dir, branch) {
|
|
29
|
-
const r = spawnSync("git", ["init", "-q", "-b", branch, dir], { encoding: "utf8" });
|
|
30
|
-
if (r.status !== 0) throw new Error(`git init ${dir} failed: ${r.stderr}`);
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
function newRepo(root, name, branch) {
|
|
34
|
-
const dir = path.join(root, name);
|
|
35
|
-
gitInit(dir, branch);
|
|
36
|
-
writeFileSync(path.join(dir, "README.md"), "base\n");
|
|
37
|
-
git(dir, "add", "README.md");
|
|
38
|
-
git(dir, "commit", "-qm", "base");
|
|
39
|
-
return dir;
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
export { newRepo, commitFile };
|
|
43
|
-
|
|
44
|
-
function commitFile(dir, rel, content) {
|
|
45
|
-
const target = path.join(dir, rel);
|
|
46
|
-
mkdirSync(path.dirname(target), { recursive: true });
|
|
47
|
-
writeFileSync(target, content);
|
|
48
|
-
git(dir, "add", rel);
|
|
49
|
-
git(dir, "commit", "-qm", `add ${rel}`);
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
function bareRemote(root, dir, branch) {
|
|
53
|
-
const bare = path.join(root, `${path.basename(dir)}-remote.git`);
|
|
54
|
-
const r = spawnSync("git", ["init", "-q", "--bare", bare], { encoding: "utf8" });
|
|
55
|
-
if (r.status !== 0) throw new Error(`git init --bare failed: ${r.stderr}`);
|
|
56
|
-
git(dir, "remote", "add", "origin", bare);
|
|
57
|
-
git(dir, "push", "-qu", "origin", branch);
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
function unitBranch(root, name, branch, acceptance = "frozen") {
|
|
61
|
-
const dir = newRepo(root, name, "main");
|
|
62
|
-
git(dir, "checkout", "-q", "-b", branch);
|
|
63
|
-
// Feature 61: the unit document is the frozen surface at HEAD.
|
|
64
|
-
commitFile(dir, `docs/features/${branch.split("/")[1]}/SPEC.md`, `unit doc\n`);
|
|
65
|
-
return dir;
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
function ghStub(root) {
|
|
69
|
-
const dir = path.join(root, "bin");
|
|
70
|
-
mkdirSync(dir, { recursive: true });
|
|
71
|
-
const file = path.join(dir, "gh");
|
|
72
|
-
writeFileSync(
|
|
73
|
-
file,
|
|
74
|
-
[
|
|
75
|
-
"#!/usr/bin/env bash",
|
|
76
|
-
"# PATH-stub for gh. `pr list --head <branch>` answers with $GH_STUB_JSON (the",
|
|
77
|
-
"# pull requests of that branch); `pr view <arg>` answers with",
|
|
78
|
-
"# $GH_STUB_VIEW_JSON — real gh reads an all-numeric argument as a PR NUMBER",
|
|
79
|
-
"# and exits nonzero when no pull request matches the branch.",
|
|
80
|
-
"# $GH_STUB_EXIT forces a failure exit from either invocation;",
|
|
81
|
-
"# $GH_STUB_VIEW_EXIT forces one from `pr view` only (the real 'no PR for",
|
|
82
|
-
"# this branch' answer, which is what makes a missing PR",
|
|
83
|
-
"# indistinguishable from an unreachable gh in the pre-F9 query).",
|
|
84
|
-
'case "$1 $2" in',
|
|
85
|
-
' "pr list")\n printf \'%s\\n\' "${GH_STUB_JSON:-[]}"\n exit_code="${GH_STUB_EXIT:-0}"\n ;;',
|
|
86
|
-
' "pr view")\n printf \'%s\\n\' "${GH_STUB_VIEW_JSON:-}"\n exit_code="${GH_STUB_VIEW_EXIT:-${GH_STUB_EXIT:-0}}"\n ;;',
|
|
87
|
-
" *) exit 3 ;;",
|
|
88
|
-
"esac",
|
|
89
|
-
'[ "$exit_code" -eq 0 ] || exit "$exit_code"',
|
|
90
|
-
"",
|
|
91
|
-
].join("\n"),
|
|
92
|
-
);
|
|
93
|
-
chmodSync(file, 0o755);
|
|
94
|
-
return dir;
|
|
95
|
-
}
|
|
96
|
-
|
|
97
|
-
function buildFixtures(root) {
|
|
98
|
-
const fx = {};
|
|
99
|
-
|
|
100
|
-
// Unit-shaped, clean, no upstream -> the ok path.
|
|
101
|
-
fx.ok = unitBranch(root, "ok", "feat/ok");
|
|
102
|
-
|
|
103
|
-
// On the default branch.
|
|
104
|
-
fx.default = newRepo(root, "default", "main");
|
|
105
|
-
|
|
106
|
-
// Not a repository at all.
|
|
107
|
-
fx.notrepo = path.join(root, "notrepo");
|
|
108
|
-
mkdirSync(fx.notrepo, { recursive: true });
|
|
109
|
-
|
|
110
|
-
// Branch with no own commit.
|
|
111
|
-
fx.nocommits = newRepo(root, "nocommits", "main");
|
|
112
|
-
git(fx.nocommits, "checkout", "-q", "-b", "feat/none");
|
|
113
|
-
|
|
114
|
-
// Unborn branch, zero commits anywhere (dev scenario verifier:empty-repo).
|
|
115
|
-
fx.empty = path.join(root, "empty");
|
|
116
|
-
gitInit(fx.empty, "feature/x");
|
|
117
|
-
|
|
118
|
-
// Unit branch exists but the unit doc is absent at HEAD.
|
|
119
|
-
fx.missing = newRepo(root, "missing", "main");
|
|
120
|
-
git(fx.missing, "checkout", "-q", "-b", "feat/missing");
|
|
121
|
-
commitFile(fx.missing, "docs/features/missing/.gitkeep", "");
|
|
122
|
-
|
|
123
|
-
// Not unit-shaped -> box2 not applicable.
|
|
124
|
-
fx.plain = newRepo(root, "plain", "main");
|
|
125
|
-
git(fx.plain, "checkout", "-q", "-b", "chore/plain");
|
|
126
|
-
commitFile(fx.plain, "note.txt", "x\n");
|
|
127
|
-
|
|
128
|
-
// Unit path exists as a regular FILE, not a directory -> the unit directory
|
|
129
|
-
// does not exist, so box2 is not-applicable (ED-52-2) in BOTH engines
|
|
130
|
-
// (F5, review cycle 2).
|
|
131
|
-
fx.unitfile = newRepo(root, "unitfile", "main");
|
|
132
|
-
git(fx.unitfile, "checkout", "-q", "-b", "feat/unitfile");
|
|
133
|
-
commitFile(fx.unitfile, "docs/features/unitfile", "not a directory\n");
|
|
134
|
-
|
|
135
|
-
// Dirty tree.
|
|
136
|
-
fx.dirty = unitBranch(root, "dirty", "feat/dirty");
|
|
137
|
-
writeFileSync(path.join(fx.dirty, "README.md"), "base\ndirty\n");
|
|
138
|
-
|
|
139
|
-
// Pushed branch plus one local commit -> ahead of remote.
|
|
140
|
-
fx.ahead = unitBranch(root, "ahead", "feat/ahead");
|
|
141
|
-
bareRemote(root, fx.ahead, "feat/ahead");
|
|
142
|
-
commitFile(fx.ahead, "extra.txt", "local only\n");
|
|
143
|
-
|
|
144
|
-
// Dirty AND ahead simultaneously -> dirty wins inside box5.
|
|
145
|
-
fx.dirtyahead = unitBranch(root, "dirtyahead", "feat/dirtyahead");
|
|
146
|
-
bareRemote(root, fx.dirtyahead, "feat/dirtyahead");
|
|
147
|
-
commitFile(fx.dirtyahead, "extra.txt", "local only\n");
|
|
148
|
-
writeFileSync(path.join(fx.dirtyahead, "README.md"), "base\ndirty\n");
|
|
149
|
-
|
|
150
|
-
// Dirty tree with spaces / unicode filenames (dev scenario).
|
|
151
|
-
fx.unicode = unitBranch(root, "unicode", "feat/unicode");
|
|
152
|
-
writeFileSync(path.join(fx.unicode, "a b.txt"), "x\n");
|
|
153
|
-
writeFileSync(path.join(fx.unicode, "café.txt"), "x\n");
|
|
154
|
-
|
|
155
|
-
// Pushed branch with an upstream -> box4 exercises the gh stub.
|
|
156
|
-
fx.b4 = unitBranch(root, "b4", "feat/b4");
|
|
157
|
-
bareRemote(root, fx.b4, "feat/b4");
|
|
158
|
-
|
|
159
|
-
// Corrupt index: `git status` itself errors while branch/rev-list still
|
|
160
|
-
// answer -> box5 must fail closed, never print a fake ok (F1, review cycle 1).
|
|
161
|
-
fx.corrupt = unitBranch(root, "corrupt", "feat/corrupt");
|
|
162
|
-
writeFileSync(path.join(fx.corrupt, ".git/index"), "not a git index\n");
|
|
163
|
-
|
|
164
|
-
// Listing past the engine's 1 MiB read cap and past the shim's pipe buffer:
|
|
165
|
-
// both truncate, and both must still fail closed (F6, fold cycle 2). Long
|
|
166
|
-
// path segments keep the fixture cheap — 320 files ≈ 1.2 MB of porcelain.
|
|
167
|
-
fx.bigstatus = unitBranch(root, "bigstatus", "feat/bigstatus");
|
|
168
|
-
const longDir = Array.from({ length: 19 }, () => "d".repeat(200)).join("/");
|
|
169
|
-
commitFile(fx.bigstatus, `${longDir}/tracked.txt`, "x\n");
|
|
170
|
-
for (let i = 0; i < 320; i += 1) writeFileSync(path.join(fx.bigstatus, longDir, `f${i}`), "x\n");
|
|
171
|
-
|
|
172
|
-
// Repo-local `status.showUntrackedFiles=no` must not hide an untracked file
|
|
173
|
-
// from box5 (F8, fold cycle 3).
|
|
174
|
-
fx.hidden = unitBranch(root, "hidden", "feat/hidden");
|
|
175
|
-
git(fx.hidden, "config", "status.showUntrackedFiles", "no");
|
|
176
|
-
writeFileSync(path.join(fx.hidden, "untracked.txt"), "x\n");
|
|
177
|
-
|
|
178
|
-
// All-numeric branch name: a bare `gh pr view <branch>` argument is read by
|
|
179
|
-
// gh as a PR NUMBER, so box4 would judge the unrelated PR that shares the
|
|
180
|
-
// name instead of this branch (F11, fold cycle 3).
|
|
181
|
-
fx.numeric = newRepo(root, "numeric", "main");
|
|
182
|
-
git(fx.numeric, "checkout", "-q", "-b", "123");
|
|
183
|
-
commitFile(fx.numeric, "note.txt", "x\n");
|
|
184
|
-
bareRemote(root, fx.numeric, "123");
|
|
185
|
-
|
|
186
|
-
// Engine-only: the phase-lint clause of box2 (the shim cannot run it).
|
|
187
|
-
fx.lintfail = unitBranch(root, "lintfail", "feat/lintfail");
|
|
188
|
-
commitFile(fx.lintfail, "docs/features/lintfail/TASKS.md", "# TASKS\n");
|
|
189
|
-
commitFile(fx.lintfail, "scripts/phase-lint.mjs", "process.exit(1);\n");
|
|
190
|
-
fx.lintpass = unitBranch(root, "lintpass", "feat/lintpass");
|
|
191
|
-
commitFile(fx.lintpass, "docs/features/lintpass/TASKS.md", "# TASKS\n");
|
|
192
|
-
commitFile(fx.lintpass, "scripts/phase-lint.mjs", "process.exit(0);\n");
|
|
193
|
-
|
|
194
|
-
return fx;
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
function baseEnv(ghDir) {
|
|
198
|
-
return {
|
|
199
|
-
...process.env,
|
|
200
|
-
PATH: `${ghDir}:${process.env.PATH}`,
|
|
201
|
-
AGENTIC_WORKFLOW_RUNTIME: "node",
|
|
202
|
-
};
|
|
203
|
-
}
|
|
204
|
-
|
|
205
|
-
export function makeContext() {
|
|
206
|
-
const root = mkdtempSync(path.join(os.tmpdir(), "tc-fixtures-"));
|
|
207
|
-
const ghDir = ghStub(root);
|
|
208
|
-
const fx = buildFixtures(root);
|
|
209
|
-
return {
|
|
210
|
-
root,
|
|
211
|
-
ghDir,
|
|
212
|
-
fx,
|
|
213
|
-
cleanup: () => rmSync(root, { recursive: true, force: true }),
|
|
214
|
-
runEngine(cwd, args = [], env = {}) {
|
|
215
|
-
const r = spawnSync(process.execPath, [ENGINE, ...args], {
|
|
216
|
-
cwd,
|
|
217
|
-
encoding: "utf8",
|
|
218
|
-
env: { ...baseEnv(ghDir), ...env },
|
|
219
|
-
});
|
|
220
|
-
return { code: r.status, stdout: r.stdout, stderr: r.stderr };
|
|
221
|
-
},
|
|
222
|
-
runShim(cwd, args = [], env = {}) {
|
|
223
|
-
const r = spawnSync("bash", [SHIM, ...args], {
|
|
224
|
-
cwd,
|
|
225
|
-
encoding: "utf8",
|
|
226
|
-
env: { ...baseEnv(ghDir), ...env },
|
|
227
|
-
});
|
|
228
|
-
return { code: r.status, stdout: r.stdout, stderr: r.stderr };
|
|
229
|
-
},
|
|
230
|
-
};
|
|
231
|
-
}
|
|
232
|
-
|
|
233
|
-
// The shared matrix for BOTH engines (no phase-lint fixture: that clause is
|
|
234
|
-
// engine-only, ED-52-3).
|
|
235
|
-
export function receiptCases(ctx) {
|
|
236
|
-
const head = git(ctx.fx.b4, "rev-parse", "HEAD");
|
|
237
|
-
return [
|
|
238
|
-
{ name: "box1 default branch", dir: ctx.fx.default, code: 1, line: "TURN-CONTRACT fail box1: branch-default" },
|
|
239
|
-
{ name: "box1 not a repo", dir: ctx.fx.notrepo, code: 1, line: "TURN-CONTRACT fail box1: not-a-repo" },
|
|
240
|
-
{ name: "box2 unit-doc missing", dir: ctx.fx.missing, code: 1, line: "TURN-CONTRACT fail box2: unit-doc-missing" },
|
|
241
|
-
{ name: "box2 not applicable", dir: ctx.fx.plain, code: 0, line: "TURN-CONTRACT ok" },
|
|
242
|
-
{ name: "box2 unit path is a file", dir: ctx.fx.unitfile, code: 0, line: "TURN-CONTRACT ok" },
|
|
243
|
-
{ name: "box3 no commits", dir: ctx.fx.nocommits, code: 1, line: "TURN-CONTRACT fail box3: no-commits" },
|
|
244
|
-
{ name: "box3 empty repo", dir: ctx.fx.empty, code: 1, line: "TURN-CONTRACT fail box3: no-commits" },
|
|
245
|
-
{ name: "box4 not applicable", dir: ctx.fx.ok, code: 0, line: "TURN-CONTRACT ok" },
|
|
246
|
-
{ name: "box4 no upstream", dir: ctx.fx.ok, args: ["--finished"], code: 1, line: "TURN-CONTRACT fail box4: pr-not-open" },
|
|
247
|
-
{
|
|
248
|
-
name: "box4 gh unreachable",
|
|
249
|
-
dir: ctx.fx.b4,
|
|
250
|
-
args: ["--finished"],
|
|
251
|
-
env: { GH_STUB_EXIT: "1" },
|
|
252
|
-
code: 1,
|
|
253
|
-
line: "TURN-CONTRACT fail box4: pr-unreachable",
|
|
254
|
-
},
|
|
255
|
-
{
|
|
256
|
-
name: "box4 no PR for the branch",
|
|
257
|
-
dir: ctx.fx.b4,
|
|
258
|
-
args: ["--finished"],
|
|
259
|
-
// The branch is pushed and has no PR: `pr list` answers that with exit 0
|
|
260
|
-
// and an empty result; the pre-F9 query (`pr view`) exits nonzero for the
|
|
261
|
-
// same state, which is why it reports a missing PR as pr-unreachable.
|
|
262
|
-
env: { GH_STUB_JSON: "[]", GH_STUB_VIEW_EXIT: "1" },
|
|
263
|
-
code: 1,
|
|
264
|
-
line: "TURN-CONTRACT fail box4: pr-not-open",
|
|
265
|
-
},
|
|
266
|
-
{
|
|
267
|
-
name: "box4 merged PR is not an open PR",
|
|
268
|
-
dir: ctx.fx.b4,
|
|
269
|
-
args: ["--finished"],
|
|
270
|
-
env: {
|
|
271
|
-
GH_STUB_JSON: JSON.stringify([{ headRefOid: head, state: "MERGED" }]),
|
|
272
|
-
GH_STUB_VIEW_JSON: JSON.stringify({ headRefOid: head, state: "MERGED" }),
|
|
273
|
-
},
|
|
274
|
-
code: 1,
|
|
275
|
-
line: "TURN-CONTRACT fail box4: pr-not-open",
|
|
276
|
-
},
|
|
277
|
-
{
|
|
278
|
-
name: "box4 head mismatch",
|
|
279
|
-
dir: ctx.fx.b4,
|
|
280
|
-
args: ["--finished"],
|
|
281
|
-
env: { GH_STUB_JSON: JSON.stringify([{ headRefOid: "0".repeat(40), state: "OPEN" }]) },
|
|
282
|
-
code: 1,
|
|
283
|
-
line: "TURN-CONTRACT fail box4: pr-head-mismatch",
|
|
284
|
-
},
|
|
285
|
-
{
|
|
286
|
-
name: "box4 open PR at HEAD",
|
|
287
|
-
dir: ctx.fx.b4,
|
|
288
|
-
args: ["--finished"],
|
|
289
|
-
env: { GH_STUB_JSON: JSON.stringify([{ headRefOid: head, state: "OPEN" }]) },
|
|
290
|
-
code: 0,
|
|
291
|
-
line: "TURN-CONTRACT ok",
|
|
292
|
-
},
|
|
293
|
-
{
|
|
294
|
-
name: "box4 numeric branch is not a PR number",
|
|
295
|
-
dir: ctx.fx.numeric,
|
|
296
|
-
args: ["--finished"],
|
|
297
|
-
env: {
|
|
298
|
-
GH_STUB_JSON: "[]",
|
|
299
|
-
GH_STUB_VIEW_JSON: JSON.stringify({ headRefOid: "0".repeat(40), state: "OPEN" }),
|
|
300
|
-
},
|
|
301
|
-
code: 1,
|
|
302
|
-
line: "TURN-CONTRACT fail box4: pr-not-open",
|
|
303
|
-
},
|
|
304
|
-
{ name: "box5 dirty tree", dir: ctx.fx.dirty, code: 1, line: "TURN-CONTRACT fail box5: dirty-tree" },
|
|
305
|
-
{ name: "box5 ahead of remote", dir: ctx.fx.ahead, code: 1, line: "TURN-CONTRACT fail box5: ahead-of-remote" },
|
|
306
|
-
{ name: "box5 dirty precedes ahead", dir: ctx.fx.dirtyahead, code: 1, line: "TURN-CONTRACT fail box5: dirty-tree" },
|
|
307
|
-
{ name: "box5 unicode/space names", dir: ctx.fx.unicode, code: 1, line: "TURN-CONTRACT fail box5: dirty-tree" },
|
|
308
|
-
{
|
|
309
|
-
name: "box5 ignores status.showUntrackedFiles=no",
|
|
310
|
-
dir: ctx.fx.hidden,
|
|
311
|
-
code: 1,
|
|
312
|
-
line: "TURN-CONTRACT fail box5: dirty-tree",
|
|
313
|
-
},
|
|
314
|
-
{ name: "box5 unreadable status fails closed", dir: ctx.fx.corrupt, code: 1, line: "TURN-CONTRACT fail box5: dirty-tree" },
|
|
315
|
-
{ name: "box5 huge listing fails closed", dir: ctx.fx.bigstatus, code: 1, line: "TURN-CONTRACT fail box5: dirty-tree" },
|
|
316
|
-
{ name: "clean feature branch", dir: ctx.fx.ok, code: 0, line: "TURN-CONTRACT ok" },
|
|
317
|
-
];
|
|
318
|
-
}
|
|
319
|
-
|
|
320
|
-
// Engine-only cases: the phase-lint clause of box2.
|
|
321
|
-
export function engineOnlyCases(ctx) {
|
|
322
|
-
return [
|
|
323
|
-
{ name: "box2 phase-lint failed", dir: ctx.fx.lintfail, code: 1, line: "TURN-CONTRACT fail box2: phase-lint-failed" },
|
|
324
|
-
{ name: "box2 phase-lint green", dir: ctx.fx.lintpass, code: 0, line: "TURN-CONTRACT ok" },
|
|
325
|
-
];
|
|
326
|
-
}
|
|
@@ -1,304 +0,0 @@
|
|
|
1
|
-
// Engine suite for packages/agentic-workflow/src/path-policy.mjs.
|
|
2
|
-
//
|
|
3
|
-
// The freeze × class × operation matrix, creation-vs-modification, the
|
|
4
|
-
// justification / approval / unmatched-record / malformed-declaration cases,
|
|
5
|
-
// the shipped-default fallback and degradation cases, and the
|
|
6
|
-
// `path-guard:empty-diff` pin (AC1, AC3, AC5, AC6).
|
|
7
|
-
|
|
8
|
-
import assert from "node:assert/strict";
|
|
9
|
-
import { execFileSync, spawnSync } from "node:child_process";
|
|
10
|
-
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
11
|
-
import os from "node:os";
|
|
12
|
-
import path from "node:path";
|
|
13
|
-
import { fileURLToPath } from "node:url";
|
|
14
|
-
import test from "node:test";
|
|
15
|
-
|
|
16
|
-
import {
|
|
17
|
-
CHANGED_PATH_LIMIT,
|
|
18
|
-
DEGRADATION_CODES,
|
|
19
|
-
PATH_GUARD_REASONS,
|
|
20
|
-
REQUIREMENTS,
|
|
21
|
-
SHIPPED_PATH_POLICY,
|
|
22
|
-
evaluatePathGuard,
|
|
23
|
-
freezeStateFor,
|
|
24
|
-
globToRegExp,
|
|
25
|
-
parsePlanDeclaration,
|
|
26
|
-
parsePathPolicy,
|
|
27
|
-
parseRecords,
|
|
28
|
-
pathMatchesGlob,
|
|
29
|
-
resolvePathPolicy,
|
|
30
|
-
serializeShippedPolicy,
|
|
31
|
-
} from "../src/path-policy.mjs";
|
|
32
|
-
|
|
33
|
-
const here = path.dirname(fileURLToPath(import.meta.url));
|
|
34
|
-
const CLI = path.join(here, "..", "bin", "path-guard.mjs");
|
|
35
|
-
const GIT_CONFIG = ["-c", "user.email=t@example.com", "-c", "user.name=test", "-c", "commit.gpgsign=false"];
|
|
36
|
-
const TMP = [];
|
|
37
|
-
|
|
38
|
-
function repo(name) {
|
|
39
|
-
const dir = mkdtempSync(path.join(os.tmpdir(), `path-guard-${name}-`));
|
|
40
|
-
TMP.push(dir);
|
|
41
|
-
execFileSync("git", ["init", "-q", "-b", "feat/unit", dir]);
|
|
42
|
-
execFileSync("git", [...GIT_CONFIG, "-C", dir, "commit", "-q", "--allow-empty", "-m", "base"]);
|
|
43
|
-
return dir;
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
function commitFile(dir, rel, content = "x\n") {
|
|
47
|
-
const target = path.join(dir, rel);
|
|
48
|
-
mkdirSync(path.dirname(target), { recursive: true });
|
|
49
|
-
writeFileSync(target, content);
|
|
50
|
-
execFileSync("git", [...GIT_CONFIG, "-C", dir, "add", rel]);
|
|
51
|
-
execFileSync("git", [...GIT_CONFIG, "-C", dir, "commit", "-q", "-m", `add ${rel}`]);
|
|
52
|
-
}
|
|
53
|
-
|
|
54
|
-
function runCli(dir, args) {
|
|
55
|
-
const result = spawnSync(process.execPath, [CLI, ...args], { cwd: dir, encoding: "utf8" });
|
|
56
|
-
return { code: result.status, stdout: result.stdout, stderr: result.stderr };
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
test.after(() => {
|
|
60
|
-
for (const dir of TMP) rmSync(dir, { recursive: true, force: true });
|
|
61
|
-
});
|
|
62
|
-
|
|
63
|
-
const DECLARED = `path-protection-plan@1
|
|
64
|
-
freeze-after: P4
|
|
65
|
-
kind | path | justification
|
|
66
|
-
created | ** | all paths declared for the matrix`;
|
|
67
|
-
|
|
68
|
-
const DECLARATION = parsePlanDeclaration(DECLARED).declaration;
|
|
69
|
-
const POLICY = resolvePathPolicy(SHIPPED_PATH_POLICY, null);
|
|
70
|
-
|
|
71
|
-
function evaluate(changes, { phase = "P1", records = [], declaration = DECLARATION, policy = POLICY } = {}) {
|
|
72
|
-
return evaluatePathGuard({ changes, policy, declaration, records, phase });
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
function justification(paths, phase = "P1") {
|
|
76
|
-
return { kind: "justification", paths: [paths].flat(), phase, date: "2026-09-18", authority: "execute-phase", justification: "why" };
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
function approval(paths, phase = "P5") {
|
|
80
|
-
return { kind: "approval", paths: [paths].flat(), phase, date: "2026-09-18", authority: "human-owner", justification: "owner said yes" };
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
/* ------------------------------------------------------------- vocabularies */
|
|
84
|
-
|
|
85
|
-
test("the shipped defaults are frozen and carry the five classes", () => {
|
|
86
|
-
assert.deepEqual(Object.keys(SHIPPED_PATH_POLICY.classes), ["tests", "e2e", "test-file", "fixtures", "policy-config"]);
|
|
87
|
-
assert.equal(SHIPPED_PATH_POLICY.classes["policy-config"].freeze, false);
|
|
88
|
-
assert.equal(Object.isFrozen(SHIPPED_PATH_POLICY.classes.tests.globs), true);
|
|
89
|
-
assert.equal(serializeShippedPolicy().endsWith("\n"), true);
|
|
90
|
-
});
|
|
91
|
-
|
|
92
|
-
test("the closed reason set is exactly the ten declared reasons", () => {
|
|
93
|
-
assert.deepEqual([...PATH_GUARD_REASONS].sort(), [
|
|
94
|
-
"approval-required",
|
|
95
|
-
"approved",
|
|
96
|
-
"clean",
|
|
97
|
-
"justified",
|
|
98
|
-
"malformed-config",
|
|
99
|
-
"malformed-declaration",
|
|
100
|
-
"missing-config",
|
|
101
|
-
"protected-modification",
|
|
102
|
-
"undeclared-test",
|
|
103
|
-
"unmatched-record",
|
|
104
|
-
]);
|
|
105
|
-
assert.equal(Object.isFrozen(PATH_GUARD_REASONS), true);
|
|
106
|
-
assert.equal(DEGRADATION_CODES.includes("ignored-removal"), true);
|
|
107
|
-
assert.equal(CHANGED_PATH_LIMIT, 10000);
|
|
108
|
-
assert.deepEqual(REQUIREMENTS, ["none", "justification", "approval"]);
|
|
109
|
-
});
|
|
110
|
-
|
|
111
|
-
/* ------------------------------------------------------- freeze-state logic */
|
|
112
|
-
|
|
113
|
-
test("freeze state flips at the declared boundary", () => {
|
|
114
|
-
assert.equal(freezeStateFor("P4", "P4"), "pre-freeze");
|
|
115
|
-
assert.equal(freezeStateFor("P5", "P4"), "post-freeze");
|
|
116
|
-
assert.equal(freezeStateFor("P1", null), "pre-freeze");
|
|
117
|
-
});
|
|
118
|
-
|
|
119
|
-
/* --------------------------------------------------------------- glob match */
|
|
120
|
-
|
|
121
|
-
test("glob matching crosses directories for ** and stays inside for *", () => {
|
|
122
|
-
assert.equal(pathMatchesGlob("tests/a/b.mjs", "tests/**"), true);
|
|
123
|
-
assert.equal(pathMatchesGlob("a/b/foo.test.mjs", "**/*.test.*"), true);
|
|
124
|
-
assert.equal(pathMatchesGlob("foo.test.mjs", "**/*.test.*"), true);
|
|
125
|
-
assert.equal(pathMatchesGlob("a/foo.spec.mjs", "**/*.test.*"), false);
|
|
126
|
-
assert.equal(globToRegExp("a?c").test("abc"), true);
|
|
127
|
-
});
|
|
128
|
-
|
|
129
|
-
/* ------------------------------------------------------- policy validation */
|
|
130
|
-
|
|
131
|
-
test("parsePathPolicy fails closed on a wrong schema, unknown key, or bad requirement", () => {
|
|
132
|
-
assert.equal(parsePathPolicy("not json").ok, false);
|
|
133
|
-
assert.equal(parsePathPolicy("{}").ok, false);
|
|
134
|
-
const good = JSON.parse(serializeShippedPolicy());
|
|
135
|
-
assert.equal(parsePathPolicy(JSON.stringify(good)).ok, true);
|
|
136
|
-
assert.equal(parsePathPolicy(JSON.stringify({ ...good, extra: 1 })).ok, false);
|
|
137
|
-
good.matrix["pre-freeze"].modify = "sometimes";
|
|
138
|
-
assert.equal(parsePathPolicy(JSON.stringify(good)).ok, false);
|
|
139
|
-
});
|
|
140
|
-
|
|
141
|
-
/* ------------------------------------------------------- resolution / fallback */
|
|
142
|
-
|
|
143
|
-
test("a missing override resolves to the shipped defaults with no degradation", () => {
|
|
144
|
-
const resolved = resolvePathPolicy(SHIPPED_PATH_POLICY, null);
|
|
145
|
-
assert.deepEqual(resolved.degradations, []);
|
|
146
|
-
assert.deepEqual(resolved.classes.tests.globs, ["tests/**"]);
|
|
147
|
-
});
|
|
148
|
-
|
|
149
|
-
test("an override may only add globs and raise requirements", () => {
|
|
150
|
-
const override = JSON.parse(serializeShippedPolicy());
|
|
151
|
-
override.classes.tests.globs.push("spec/**");
|
|
152
|
-
override.matrix["pre-freeze"].modify = "approval";
|
|
153
|
-
const resolved = resolvePathPolicy(SHIPPED_PATH_POLICY, override);
|
|
154
|
-
assert.equal(resolved.classes.tests.globs.includes("spec/**"), true);
|
|
155
|
-
assert.equal(resolved.matrix["pre-freeze"].modify, "approval");
|
|
156
|
-
assert.deepEqual(resolved.degradations, []);
|
|
157
|
-
});
|
|
158
|
-
|
|
159
|
-
test("a removal or lowering is ignored and reported", () => {
|
|
160
|
-
const override = JSON.parse(serializeShippedPolicy());
|
|
161
|
-
override.classes.tests.globs = [];
|
|
162
|
-
override.matrix["post-freeze"].modify = "justification";
|
|
163
|
-
const resolved = resolvePathPolicy(SHIPPED_PATH_POLICY, override);
|
|
164
|
-
assert.equal(resolved.classes.tests.globs.includes("tests/**"), true, "the shipped glob stays in force");
|
|
165
|
-
assert.equal(resolved.matrix["post-freeze"].modify, "approval", "the shipped requirement stays in force");
|
|
166
|
-
const codes = resolved.degradations.map((entry) => entry.code);
|
|
167
|
-
assert.equal(codes.includes("ignored-removal"), true);
|
|
168
|
-
assert.equal(codes.includes("ignored-lowering"), true);
|
|
169
|
-
});
|
|
170
|
-
|
|
171
|
-
/* ---------------------------------------------------- matrix: freeze × class */
|
|
172
|
-
|
|
173
|
-
const CLASS_PATHS = {
|
|
174
|
-
tests: "tests/a.mjs",
|
|
175
|
-
e2e: "e2e/a.mjs",
|
|
176
|
-
"test-file": "src/a.test.mjs",
|
|
177
|
-
fixtures: "fixtures/a.json",
|
|
178
|
-
"policy-config": ".agentic-workflow/path-policy.json",
|
|
179
|
-
};
|
|
180
|
-
|
|
181
|
-
test("pre-freeze freeze-class matrix: create passes, modify/delete/rename need a justification", () => {
|
|
182
|
-
for (const name of ["tests", "e2e", "test-file", "fixtures"]) {
|
|
183
|
-
const path0 = CLASS_PATHS[name];
|
|
184
|
-
assert.equal(evaluate([{ path: path0, operation: "create" }]).reason, "clean", `${name} create`);
|
|
185
|
-
for (const operation of ["modify", "delete", "rename"]) {
|
|
186
|
-
const fail = evaluate([{ path: path0, operation }]);
|
|
187
|
-
assert.equal(fail.verdict, "fail", `${name} ${operation} without record`);
|
|
188
|
-
assert.equal(fail.reason, "protected-modification", `${name} ${operation} reason`);
|
|
189
|
-
const pass = evaluate([{ path: path0, operation }], { records: [justification(path0)] });
|
|
190
|
-
assert.equal(pass.verdict, "pass", `${name} ${operation} with justification`);
|
|
191
|
-
assert.equal(pass.reason, "justified");
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
});
|
|
195
|
-
|
|
196
|
-
test("post-freeze freeze-class matrix: modify/delete/rename need a justification plus an approval", () => {
|
|
197
|
-
for (const name of ["tests", "e2e", "test-file", "fixtures"]) {
|
|
198
|
-
const path0 = CLASS_PATHS[name];
|
|
199
|
-
for (const operation of ["modify", "delete", "rename"]) {
|
|
200
|
-
assert.equal(
|
|
201
|
-
evaluate([{ path: path0, operation }], { phase: "P5" }).reason,
|
|
202
|
-
"protected-modification",
|
|
203
|
-
`${name} ${operation} without record`,
|
|
204
|
-
);
|
|
205
|
-
assert.equal(
|
|
206
|
-
evaluate([{ path: path0, operation }], { phase: "P5", records: [justification(path0, "P5")] }).reason,
|
|
207
|
-
"approval-required",
|
|
208
|
-
`${name} ${operation} with justification only`,
|
|
209
|
-
);
|
|
210
|
-
const approved = evaluate([{ path: path0, operation }], {
|
|
211
|
-
phase: "P5",
|
|
212
|
-
records: [justification(path0, "P5"), approval(path0, "P5")],
|
|
213
|
-
});
|
|
214
|
-
assert.equal(approved.verdict, "pass", `${name} ${operation} approved`);
|
|
215
|
-
assert.equal(approved.reason, "approved");
|
|
216
|
-
}
|
|
217
|
-
const create = evaluate([{ path: path0, operation: "create" }], { phase: "P5", records: [justification(path0, "P5")] });
|
|
218
|
-
assert.equal(create.verdict, "pass", `${name} create post-freeze needs only a justification`);
|
|
219
|
-
}
|
|
220
|
-
});
|
|
221
|
-
|
|
222
|
-
test("the policy config is protected at all times", () => {
|
|
223
|
-
const path0 = CLASS_PATHS["policy-config"];
|
|
224
|
-
for (const phase of ["P1", "P5"]) {
|
|
225
|
-
assert.equal(evaluate([{ path: path0, operation: "modify" }], { phase }).reason, "protected-modification");
|
|
226
|
-
const pass = evaluate([{ path: path0, operation: "modify" }], {
|
|
227
|
-
phase,
|
|
228
|
-
records: [justification(path0, phase), approval(path0, phase)],
|
|
229
|
-
});
|
|
230
|
-
assert.equal(pass.verdict, "pass");
|
|
231
|
-
assert.equal(pass.reason, "approved");
|
|
232
|
-
}
|
|
233
|
-
});
|
|
234
|
-
|
|
235
|
-
/* ----------------------------------------------- creation ≠ modification */
|
|
236
|
-
|
|
237
|
-
test("a declared create passes pre-freeze; an undeclared create is undeclared-test", () => {
|
|
238
|
-
const declared = evaluate([{ path: "tests/a.mjs", operation: "create" }]);
|
|
239
|
-
assert.equal(declared.verdict, "pass");
|
|
240
|
-
|
|
241
|
-
const narrow = parsePlanDeclaration(`path-protection-plan@1
|
|
242
|
-
freeze-after: P4
|
|
243
|
-
kind | path | justification
|
|
244
|
-
created | tests/declared.mjs | only this one`).declaration;
|
|
245
|
-
const undeclared = evaluate([{ path: "tests/other.mjs", operation: "create" }], { declaration: narrow });
|
|
246
|
-
assert.equal(undeclared.verdict, "fail");
|
|
247
|
-
assert.equal(undeclared.reason, "undeclared-test");
|
|
248
|
-
});
|
|
249
|
-
|
|
250
|
-
/* ---------------------------------------------------- records and closure */
|
|
251
|
-
|
|
252
|
-
test("an unmatched record fails the gate", () => {
|
|
253
|
-
const result = evaluate([], { records: [justification("tests/void.mjs")] });
|
|
254
|
-
assert.equal(result.verdict, "fail");
|
|
255
|
-
assert.equal(result.reason, "unmatched-record");
|
|
256
|
-
});
|
|
257
|
-
|
|
258
|
-
test("a record from another phase never satisfies this phase", () => {
|
|
259
|
-
const result = evaluate([{ path: "tests/a.mjs", operation: "modify" }], {
|
|
260
|
-
phase: "P2",
|
|
261
|
-
records: [justification("tests/a.mjs", "P1")],
|
|
262
|
-
});
|
|
263
|
-
assert.equal(result.reason, "protected-modification");
|
|
264
|
-
});
|
|
265
|
-
|
|
266
|
-
test("a malformed declaration fails closed", () => {
|
|
267
|
-
assert.equal(evaluate([], { declaration: null }).reason, "malformed-declaration");
|
|
268
|
-
assert.equal(parsePlanDeclaration("no block here").ok, false);
|
|
269
|
-
assert.equal(parsePlanDeclaration("path-protection-plan@1\nkind | path | justification\ncreated | x | y").ok, false);
|
|
270
|
-
});
|
|
271
|
-
|
|
272
|
-
test("records require the sanctioned authority per kind", () => {
|
|
273
|
-
assert.equal(parseRecords("").ok, true);
|
|
274
|
-
assert.equal(parseRecords("").records.length, 0);
|
|
275
|
-
const bad = `path-protection-records@1
|
|
276
|
-
kind | paths | phase | date | authority | justification
|
|
277
|
-
approval | tests/a.mjs | P5 | 2026-09-18 | execute-phase | auto`;
|
|
278
|
-
assert.equal(parseRecords(bad).ok, false);
|
|
279
|
-
const good = `path-protection-records@1
|
|
280
|
-
kind | paths | phase | date | authority | justification
|
|
281
|
-
approval | tests/a.mjs | P5 | 2026-09-18 | human-owner | owner`;
|
|
282
|
-
assert.equal(parseRecords(good).ok, true);
|
|
283
|
-
});
|
|
284
|
-
|
|
285
|
-
/* ------------------------------------------------------- empty-diff pin (CLI) */
|
|
286
|
-
|
|
287
|
-
test("path-guard:empty-diff — a clean tree yields pass — clean, exit 0", () => {
|
|
288
|
-
const dir = repo("empty");
|
|
289
|
-
const unit = "docs/features/60-demo";
|
|
290
|
-
commitFile(dir, `${unit}/PLAN.md`, `\`\`\`text\n${DECLARED}\n\`\`\`\n`);
|
|
291
|
-
const result = runCli(dir, ["--unit", unit, "--phase", "P1"]);
|
|
292
|
-
assert.equal(result.code, 0, result.stderr);
|
|
293
|
-
assert.match(result.stdout, /^PATH-GUARD pass — clean\n/);
|
|
294
|
-
assert.match(result.stdout, /offenders: none\n/);
|
|
295
|
-
assert.match(result.stdout, /checked: 0\n/);
|
|
296
|
-
});
|
|
297
|
-
|
|
298
|
-
test("unknown arguments are a usage error on stderr, exit 2", () => {
|
|
299
|
-
const dir = repo("usage");
|
|
300
|
-
const result = runCli(dir, ["--unit", "u", "--phase", "P1", "--bogus"]);
|
|
301
|
-
assert.equal(result.code, 2);
|
|
302
|
-
assert.match(result.stderr, /unknown argument: --bogus/);
|
|
303
|
-
assert.equal(result.stdout, "");
|
|
304
|
-
});
|