@warren-dean/code-kit 0.28.0 → 0.30.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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +31 -0
- package/README.md +17 -9
- package/bin/code-kit.mjs +498 -60
- package/hooks/act.mjs +30 -2
- package/hooks/guard-bash.mjs +59 -25
- package/hooks/lib/adapters/hub/client.mjs +7 -1
- package/hooks/lib/checkout.mjs +78 -1
- package/hooks/lib/checks.mjs +13 -3
- package/hooks/lib/deferrals.mjs +107 -0
- package/hooks/lib/designs.mjs +100 -42
- package/hooks/lib/events.mjs +49 -0
- package/hooks/lib/instructions.mjs +1 -1
- package/hooks/lib/next.mjs +124 -15
- package/hooks/lib/plan.mjs +186 -11
- package/hooks/lib/queue.mjs +61 -12
- package/hooks/lib/regression.mjs +18 -11
- package/hooks/lib/reviews.mjs +43 -2
- package/hooks/lib/rules.mjs +11 -2
- package/hooks/lib/security.mjs +50 -7
- package/hooks/lib/shell.mjs +97 -0
- package/hooks/lib/snapshot.mjs +125 -8
- package/hooks/lib/storymap.mjs +13 -7
- package/hooks/lib/team.mjs +35 -13
- package/hooks/lib/teamfacts.mjs +80 -2
- package/hooks/lib/testfiles.mjs +22 -0
- package/hooks/lib/verify.mjs +55 -11
- package/hooks/lib/worktrees.mjs +25 -3
- package/hooks/mod/board.mjs +12 -1
- package/hooks/mod/loop.mjs +9 -2
- package/hooks/mod/register.mjs +4 -3
- package/hooks/mod/view.mjs +51 -11
- package/package.json +1 -1
- package/skills/design/SKILL.md +4 -4
- package/skills/dispatch/SKILL.md +1 -1
- package/skills/init/SKILL.md +5 -0
- package/skills/next/SKILL.md +1 -0
- package/skills/review/SKILL.md +12 -4
- package/templates/agent.md +2 -1
- package/templates/claude-md.md +2 -0
package/hooks/lib/queue.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// The merge queue (docs/specs/09-merge-queue.md): branches that passed the lead's review, merged one at
|
|
2
2
|
// a time in the order they passed, each verified against the base as it is then. Kept in the main
|
|
3
3
|
// checkout, beside the requests and reviews, so every worktree and a restarted session see the same.
|
|
4
|
-
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
5
5
|
import { dirname, join } from 'node:path';
|
|
6
6
|
import { projectWorktrees } from './rules.mjs';
|
|
7
7
|
import { GIT, commandsOf } from './shell.mjs';
|
|
@@ -80,11 +80,12 @@ export function dequeue(root, branch) {
|
|
|
80
80
|
* review, so it's reviewed again), or waiting again.
|
|
81
81
|
*/
|
|
82
82
|
export function settle(root, branch, state, reason = null, now = Date.now()) {
|
|
83
|
-
const entries = readQueue(root).map((e) =>
|
|
84
|
-
e.branch
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
83
|
+
const entries = readQueue(root).map((e) => {
|
|
84
|
+
if (e.branch !== branch || !['waiting', 'merging'].includes(e.state)) return e;
|
|
85
|
+
// The merge that settled it is over: its process no longer marks the entry.
|
|
86
|
+
const { pid: _pid, ...rest } = e;
|
|
87
|
+
return { ...rest, state, at: new Date(now).toISOString(), ...(reason ? { reason } : {}) };
|
|
88
|
+
});
|
|
88
89
|
// Merged and sent-back entries move behind the waiting ones' history, in the order they settled.
|
|
89
90
|
const settled = entries.filter((e) => e.branch === branch && e.state === state);
|
|
90
91
|
writeQueue(root, [...entries.filter((e) => !settled.includes(e)), ...settled]);
|
|
@@ -121,10 +122,14 @@ export function mergingNow(entry) {
|
|
|
121
122
|
/**
|
|
122
123
|
* MQ-7: what the queue merges next. A branch queued `with` others merges only together with them, once
|
|
123
124
|
* each is queued too: verified as one tree, merged one after another. Until then it waits, and the
|
|
124
|
-
* queue goes on with the next.
|
|
125
|
-
* `
|
|
125
|
+
* queue goes on with the next. HUBR-9: a branch the team provider's drift findings hold (`drift`,
|
|
126
|
+
* Map(branch → findings), from `driftHolds`) waits too, with its group, until they clear. MQ-8: so does
|
|
127
|
+
* a branch whose story the lead holds (`deferred`, Map(branch → hold), from `activeDeferrals`). `{ head,
|
|
128
|
+
* partners, held, drifting, deferred }`: `head` null when nothing can merge yet; `held` lists each
|
|
129
|
+
* waiting branch with the partners it still needs queued; `drifting` each one waiting on findings,
|
|
130
|
+
* with them; `deferred` each one whose group holds a held story, with that hold.
|
|
126
131
|
*/
|
|
127
|
-
export function nextToMerge(entries) {
|
|
132
|
+
export function nextToMerge(entries, drift = new Map(), deferredBy = new Map()) {
|
|
128
133
|
const queue = waiting(entries);
|
|
129
134
|
const queued = new Set(queue.map((e) => e.branch));
|
|
130
135
|
// A partner already merged on its own is no longer waited for.
|
|
@@ -148,8 +153,18 @@ export function nextToMerge(entries) {
|
|
|
148
153
|
return group;
|
|
149
154
|
};
|
|
150
155
|
const held = [];
|
|
156
|
+
const drifting = [];
|
|
157
|
+
const deferred = [];
|
|
158
|
+
let head = null;
|
|
159
|
+
let partners = [];
|
|
151
160
|
for (const e of queue) {
|
|
152
161
|
const group = groupOf(e);
|
|
162
|
+
// A group lands as one, so a finding on any of its branches holds them all.
|
|
163
|
+
const findings = [...group].flatMap((b) => drift.get(b) ?? []);
|
|
164
|
+
if (findings.length) drifting.push({ branch: e.branch, findings });
|
|
165
|
+
const hold = [...group].map((b) => deferredBy.get(b)).find(Boolean);
|
|
166
|
+
if (hold) deferred.push({ branch: e.branch, hold });
|
|
167
|
+
if (head || hold) continue;
|
|
153
168
|
const missing = [...group]
|
|
154
169
|
.flatMap((b) => queue.find((y) => y.branch === b)?.with ?? [])
|
|
155
170
|
.filter((b) => !queued.has(b) && !merged.has(b));
|
|
@@ -157,10 +172,44 @@ export function nextToMerge(entries) {
|
|
|
157
172
|
held.push({ branch: e.branch, missing: [...new Set(missing)] });
|
|
158
173
|
continue;
|
|
159
174
|
}
|
|
160
|
-
|
|
161
|
-
|
|
175
|
+
if (findings.length) continue;
|
|
176
|
+
head = e;
|
|
177
|
+
partners = queue.filter((x) => x.branch !== e.branch && group.has(x.branch));
|
|
162
178
|
}
|
|
163
|
-
return { head
|
|
179
|
+
return { head, partners, held, drifting, deferred };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export const PAUSE_FILE = '.claude/state/merge-queue-paused.json';
|
|
183
|
+
|
|
184
|
+
const pauseFile = (root) => join(projectWorktrees(root)[0] ?? root, PAUSE_FILE);
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* MQ-8: the lead's deliberate pause of the whole queue, { reason, at, session } or null: while it's
|
|
188
|
+
* paused, the queue merges nothing and nothing offers a merge; branches are still queued.
|
|
189
|
+
*/
|
|
190
|
+
export function queuePause(root) {
|
|
191
|
+
try {
|
|
192
|
+
const p = JSON.parse(readFileSync(pauseFile(root), 'utf8'));
|
|
193
|
+
return p && typeof p.reason === 'string' ? p : null;
|
|
194
|
+
} catch {
|
|
195
|
+
return null;
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** MQ-8: pauses the queue with why; a pause already in force takes the new reason. */
|
|
200
|
+
export function pauseQueue(root, reason, session = null, now = Date.now()) {
|
|
201
|
+
const file = pauseFile(root);
|
|
202
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
203
|
+
const pause = { reason, at: new Date(now).toISOString(), ...(session ? { session } : {}) };
|
|
204
|
+
writeFileSync(file, `${JSON.stringify(pause, null, 2)}\n`);
|
|
205
|
+
return pause;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** MQ-8: lets the queue merge again; the pause it ended, or null when it wasn't paused. */
|
|
209
|
+
export function resumeQueue(root) {
|
|
210
|
+
const was = queuePause(root);
|
|
211
|
+
if (was) rmSync(pauseFile(root), { force: true });
|
|
212
|
+
return was;
|
|
164
213
|
}
|
|
165
214
|
|
|
166
215
|
/** MQ-7: a queued branch's partners, which it merges together with. */
|
package/hooks/lib/regression.mjs
CHANGED
|
@@ -10,19 +10,13 @@ import { freshCheckout } from './checkout.mjs';
|
|
|
10
10
|
import { runChecks } from './checks.mjs';
|
|
11
11
|
import { matchesAny } from './glob.mjs';
|
|
12
12
|
import { readStories } from './plan.mjs';
|
|
13
|
+
import { isNamedTest, isTestFile } from './testfiles.mjs';
|
|
13
14
|
|
|
14
15
|
/** The approval that lets a test be weakened: the person's only. */
|
|
15
16
|
export const TESTS_APPROVAL = 'tests';
|
|
16
17
|
|
|
17
|
-
// Test files by the usual conventions, when the config names none (`tests`).
|
|
18
|
-
const TEST =
|
|
19
|
-
/(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
|
|
20
18
|
export const SNAPSHOT = /(^|\/)__snapshots__\/|\.snap$/;
|
|
21
19
|
|
|
22
|
-
/** Whether `rel` is a test: the config's `tests` globs, or the usual conventions. */
|
|
23
|
-
export const isTestFile = (rel, config) =>
|
|
24
|
-
!rel.endsWith('.md') && (config?.tests?.length ? matchesAny(rel, config.tests) : TEST.test(rel));
|
|
25
|
-
|
|
26
20
|
// A case's name: it('…') / test('…') in JavaScript, def test_… in Python, func Test… in Go, @Test in JVM.
|
|
27
21
|
const JS_CASE =
|
|
28
22
|
/\b(?:it|test)(?:\.(?:each\s*\([^)]*\)|concurrent|serial|skip|only|todo|fixme|fails))*\s*\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/g;
|
|
@@ -255,16 +249,30 @@ export const onlyUnreachable = (output) =>
|
|
|
255
249
|
*/
|
|
256
250
|
export function proveFix({ root, from, base, changed, config, fix }) {
|
|
257
251
|
const what = `This branch fixes ${fix.what}${fix.story ? ` (${fix.story})` : ''}`;
|
|
258
|
-
|
|
252
|
+
// A test file, named as one or in a test folder (a smoke folder's scripts), brings the fix a test.
|
|
253
|
+
const brought = changed.filter(
|
|
259
254
|
(f) => isTestFile(f, config) && !SNAPSHOT.test(f) && showAt(root, 'HEAD', f) !== null,
|
|
260
255
|
);
|
|
261
|
-
if (!
|
|
256
|
+
if (!brought.length)
|
|
262
257
|
return [
|
|
263
258
|
`${what}, but it adds or changes no test. Add a test that fails without the fix: it's what stops the bug coming back.`,
|
|
264
259
|
];
|
|
265
260
|
// A fix made wholly in the tests (a flaky test, a broken helper) has no code to take back: its tests
|
|
266
261
|
// are the fix. REG-2 still holds them, so it can't be made by weakening one.
|
|
267
262
|
if (changed.every((f) => isTestFile(f, config) || SNAPSHOT.test(f))) return [];
|
|
263
|
+
// The tests that prove it are the ones named as tests; a helper or harness module beside them is code
|
|
264
|
+
// the fix may have changed, so it goes back with the rest. Only where the fix brings no named test do
|
|
265
|
+
// the files in its test folders stand as its tests.
|
|
266
|
+
const named = brought.filter((f) => isNamedTest(f, config));
|
|
267
|
+
const tests = named.length ? named : brought;
|
|
268
|
+
// What goes back: everything but those tests and the snapshots, except test code the branch adds,
|
|
269
|
+
// which the code without the fix never had and its tests need to load.
|
|
270
|
+
const revert = changed.filter(
|
|
271
|
+
(f) =>
|
|
272
|
+
!tests.includes(f) &&
|
|
273
|
+
!SNAPSHOT.test(f) &&
|
|
274
|
+
!(isTestFile(f, config) && showAt(root, from, f) === null),
|
|
275
|
+
);
|
|
268
276
|
const covering = config.checks.filter((c) =>
|
|
269
277
|
tests.some((f) => matchesAny(f, c.files) && !matchesAny(f, c.exclude)),
|
|
270
278
|
);
|
|
@@ -289,8 +297,7 @@ export function proveFix({ root, from, base, changed, config, fix }) {
|
|
|
289
297
|
return [
|
|
290
298
|
`${what}, but its tests don't pass in a fresh checkout of the branch (${withFix.title.replace(/ Fix it:$/, '')}), so code-kit can't tell whether they fail without it. If they need an install or a build first, set regression.prepare.${withFix.output ? `\n${String(withFix.output).trim().split('\n').slice(-20).join('\n')}` : ''}`,
|
|
291
299
|
];
|
|
292
|
-
for (const f of
|
|
293
|
-
if (isTestFile(f, config) || SNAPSHOT.test(f)) continue;
|
|
300
|
+
for (const f of revert) {
|
|
294
301
|
if (showAt(root, from, f) !== null) git(dir, 'checkout', from, '--', f);
|
|
295
302
|
else rmSync(join(dir, f), { force: true });
|
|
296
303
|
}
|
package/hooks/lib/reviews.mjs
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// The lead's send-backs: which commit of a branch a review sent back. Until the branch moves past it,
|
|
2
2
|
// status reads the story as waiting for its lane's fix, not as finished again (and next proposes the
|
|
3
|
-
// fix, not a second review of the same commits).
|
|
4
|
-
|
|
3
|
+
// fix, not a second review of the same commits). And the screenshots a review compared with each
|
|
4
|
+
// screen's approved design (HAND-7). Kept beside the requests, in the main checkout.
|
|
5
|
+
import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
|
|
5
6
|
import { dirname, join } from 'node:path';
|
|
6
7
|
import { projectWorktrees } from './rules.mjs';
|
|
7
8
|
|
|
@@ -55,3 +56,43 @@ export function sendBacks(root) {
|
|
|
55
56
|
}
|
|
56
57
|
});
|
|
57
58
|
}
|
|
59
|
+
|
|
60
|
+
/** HAND-7: where the review keeps the screenshots it compared, in the main checkout. */
|
|
61
|
+
export const EVIDENCE_DIR = '.claude/state/reviews';
|
|
62
|
+
export const evidenceDir = (root) => join(projectWorktrees(root)[0] ?? root, EVIDENCE_DIR);
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* HAND-7: records that the review of `branch` at commit `sha` took a screenshot of a screen's approved
|
|
66
|
+
* state and set it beside the design: `{ story, file, screen, state, image, sha256, viewport, size }`.
|
|
67
|
+
*/
|
|
68
|
+
export function recordEvidence(root, record, now = Date.now()) {
|
|
69
|
+
const file = reviewsFile(root);
|
|
70
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
71
|
+
appendFileSync(
|
|
72
|
+
file,
|
|
73
|
+
`${JSON.stringify({ at: new Date(now).toISOString(), verdict: 'evidence', ...record })}\n`,
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* HAND-7: the screenshots the reviews recorded for `branch`, oldest first; null where the project's
|
|
79
|
+
* state isn't kept (CI, a fresh clone), so nothing can be said about them.
|
|
80
|
+
*/
|
|
81
|
+
export function evidenceRecords(root, branch) {
|
|
82
|
+
const file = reviewsFile(root);
|
|
83
|
+
if (!existsSync(dirname(file))) return null;
|
|
84
|
+
let lines = [];
|
|
85
|
+
try {
|
|
86
|
+
lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
|
|
87
|
+
} catch {
|
|
88
|
+
return [];
|
|
89
|
+
}
|
|
90
|
+
return lines.flatMap((line) => {
|
|
91
|
+
try {
|
|
92
|
+
const r = JSON.parse(line);
|
|
93
|
+
return r.verdict === 'evidence' && r.branch === branch ? [r] : [];
|
|
94
|
+
} catch {
|
|
95
|
+
return [];
|
|
96
|
+
}
|
|
97
|
+
});
|
|
98
|
+
}
|
package/hooks/lib/rules.mjs
CHANGED
|
@@ -905,7 +905,8 @@ function specCheckProblem(rel, root) {
|
|
|
905
905
|
return `Run the spec-check skill before writing code on this branch. Save its report (the requirement table, questions and recommendation) to ${report}, then continue.`;
|
|
906
906
|
}
|
|
907
907
|
|
|
908
|
-
// Screens are designed first: a screen file can be written once the register
|
|
908
|
+
// Screens are designed first: a screen file can be written once the register holds its approved
|
|
909
|
+
// design as files (HAND-6). An entry naming only a design tool's artboard isn't one: no lane can read it.
|
|
909
910
|
export function screenProblem(rel, root, config) {
|
|
910
911
|
const gate = config.designGate;
|
|
911
912
|
if (!gate) return null;
|
|
@@ -919,6 +920,14 @@ export function screenProblem(rel, root, config) {
|
|
|
919
920
|
} catch {
|
|
920
921
|
return `${gate.register} is missing or invalid, so no screen can be built yet.`;
|
|
921
922
|
}
|
|
922
|
-
|
|
923
|
+
// Handed over, as designs.mjs's handedOver() says: kept here, so the path guard loads no more than this.
|
|
924
|
+
const listed = (Array.isArray(screens) ? screens : []).filter((s) => s?.file === rel);
|
|
925
|
+
if (listed.some((s) => Array.isArray(s.states) && s.states.length > 0)) return null;
|
|
926
|
+
if (listed.length) {
|
|
927
|
+
const s = listed[0];
|
|
928
|
+
const tool =
|
|
929
|
+
s.source?.tool ?? String(s.design ?? '').match(/^([a-z][\w-]*):/i)?.[1] ?? 'the design tool';
|
|
930
|
+
return `${rel} is a screen, and its approved design${s.screen ? ` (${s.screen})` : ''} is only in ${tool}, not as files a lane can build from, so it can't be built yet.\nThe lead hands it over first with /code-kit:design --hand-over, which exports every state into design/ and rewrites its entry in ${gate.register}; then build it from those files. Until then, write a change request for the lead and work on what doesn't need the screen.`;
|
|
931
|
+
}
|
|
923
932
|
return `${rel} is a screen, and its design is not approved yet.\n${gate.howTo}\nOnce a person approves it, the lead adds { "file": "${rel}", ... } to ${gate.register}.`;
|
|
924
933
|
}
|
package/hooks/lib/security.mjs
CHANGED
|
@@ -9,13 +9,43 @@ import { join } from 'node:path';
|
|
|
9
9
|
import { isDependencyFile } from './dependencies.mjs';
|
|
10
10
|
import { markdownFiles, readStories } from './plan.mjs';
|
|
11
11
|
import { storyOfBranch } from './teamfacts.mjs';
|
|
12
|
+
import { isTestFile } from './testfiles.mjs';
|
|
12
13
|
|
|
13
14
|
export const SECURITY_AGENT = 'security-reviewer';
|
|
14
15
|
export const SECURITY_AGENT_FILE = `.claude/agents/${SECURITY_AGENT}.md`;
|
|
15
16
|
|
|
17
|
+
/** Whether an agent type is the security reviewer: the project's, or a plugin's (`<plugin>:security-reviewer`). */
|
|
18
|
+
export const isSecurityReviewer = (type) =>
|
|
19
|
+
new RegExp(`(^|:)${SECURITY_AGENT}$`).test(String(type ?? ''));
|
|
20
|
+
|
|
21
|
+
const GRADES = ['blocker', 'concern', 'nit'];
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* HUBR-2: what the security reviewer's report found, from its last fenced json block (its template's
|
|
25
|
+
* `{"findings": [...]}`): { findings, blockers }, the findings graded blocker, concern or nit counted, or
|
|
26
|
+
* null when the report has no block that reads.
|
|
27
|
+
*/
|
|
28
|
+
export function securityOutcome(report) {
|
|
29
|
+
const blocks = [...String(report ?? '').matchAll(/```json\s*\n([\s\S]*?)```/g)];
|
|
30
|
+
if (!blocks.length) return null;
|
|
31
|
+
let data;
|
|
32
|
+
try {
|
|
33
|
+
data = JSON.parse(blocks.at(-1)[1]);
|
|
34
|
+
} catch {
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
if (!Array.isArray(data?.findings)) return null;
|
|
38
|
+
const graded = data.findings.filter((f) => GRADES.includes(f?.severity));
|
|
39
|
+
return {
|
|
40
|
+
findings: graded.length,
|
|
41
|
+
blockers: graded.filter((f) => f.severity === 'blocker').length,
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
16
45
|
// Tests, docs and design files describe the change; the review looks at the code that ships.
|
|
17
|
-
const
|
|
18
|
-
/(^|\/)(
|
|
46
|
+
const DESCRIBES =
|
|
47
|
+
/(^|\/)(docs?|design)\/|\.stories\.[^/]+$|\.(md|mdx|txt|png|jpe?g|gif|svg|webp)$/i;
|
|
48
|
+
const notShipped = (f, config) => isTestFile(f, config) || DESCRIBES.test(f);
|
|
19
49
|
|
|
20
50
|
/**
|
|
21
51
|
* What makes a change sensitive, by kind: `path` matches a changed file's path, `code` (one pattern or
|
|
@@ -120,12 +150,19 @@ const examples = (list) =>
|
|
|
120
150
|
/**
|
|
121
151
|
* Why a change needs the security review, in words, one per kind: [{ kind, why, where: [...] }].
|
|
122
152
|
* Empty when it touches nothing sensitive. `files` are the changed files, `added` the added lines,
|
|
123
|
-
* `cites` the story's requirements and `security` the IDs of the specs' security requirements
|
|
153
|
+
* `cites` the story's requirements and `security` the IDs of the specs' security requirements; the
|
|
154
|
+
* `config`'s `tests` say which files are tests.
|
|
124
155
|
*/
|
|
125
|
-
export function securityReasons({
|
|
156
|
+
export function securityReasons({
|
|
157
|
+
files = [],
|
|
158
|
+
added = [],
|
|
159
|
+
cites = [],
|
|
160
|
+
security = new Set(),
|
|
161
|
+
config,
|
|
162
|
+
}) {
|
|
126
163
|
const reasons = [];
|
|
127
|
-
const shipped = files.filter((f) => !
|
|
128
|
-
const lines = added.filter((a) => !
|
|
164
|
+
const shipped = files.filter((f) => !notShipped(f, config));
|
|
165
|
+
const lines = added.filter((a) => !notShipped(a.file, config));
|
|
129
166
|
for (const s of SENSITIVE) {
|
|
130
167
|
const code = [s.code].flat();
|
|
131
168
|
const where = [
|
|
@@ -189,7 +226,13 @@ export function securityReview(root, { base, branch, config }) {
|
|
|
189
226
|
const texts = specs
|
|
190
227
|
? markdownFiles(root, specs).map((f) => readFileSync(join(root, f), 'utf8'))
|
|
191
228
|
: [];
|
|
192
|
-
const reasons = securityReasons({
|
|
229
|
+
const reasons = securityReasons({
|
|
230
|
+
files,
|
|
231
|
+
added,
|
|
232
|
+
cites,
|
|
233
|
+
security: securityRequirementIds(texts),
|
|
234
|
+
config,
|
|
235
|
+
});
|
|
193
236
|
return {
|
|
194
237
|
branch,
|
|
195
238
|
story,
|
package/hooks/lib/shell.mjs
CHANGED
|
@@ -92,3 +92,100 @@ export const GIT = String.raw`git\s+(?:-[Cc]\s+(?:"[^"]*"|'[^']*'|\S+)\s+)*`;
|
|
|
92
92
|
|
|
93
93
|
/** code-kit's command line however it's run: installed, through node (its path quoted or not), or npx. */
|
|
94
94
|
export const CODE_KIT = String.raw`(?:code-kit|node\s+(?:"[^"]*code-kit(?:\.mjs)?"|'[^']*code-kit(?:\.mjs)?'|\S*code-kit(?:\.mjs)?)|npx\s+(?:--yes\s+|-y\s+)?@warren-dean\/code-kit(?:@\S+)?)`;
|
|
95
|
+
|
|
96
|
+
// What a read may redirect: its errors into its output (2>&1, >&2), or anything into /dev/null.
|
|
97
|
+
const HARMLESS_REDIRECT = /(?:\d+|&)?>>?\s*(?:&\d+|\/dev\/null(?![\w/.-]))/g;
|
|
98
|
+
// An assignment before a command (GIT_PAGER=…, GIT_EXTERNAL_DIFF=…, LESSOPEN=…) can make a reader run a
|
|
99
|
+
// program, so a read that sets one isn't only a read.
|
|
100
|
+
const ASSIGNS = /^\s*(?:(?:sudo|exec|time|command|nohup|env)\s+|!\s+)*[A-Za-z_]\w*=/;
|
|
101
|
+
|
|
102
|
+
// Commands that read files or what comes down the pipe and print, and write nothing whatever their
|
|
103
|
+
// arguments. git reads its history: only `-C` before the subcommand (a `-c` setting can name a program
|
|
104
|
+
// to run), and no output file or pager program.
|
|
105
|
+
const READERS = [
|
|
106
|
+
/^(?:cd|pwd|cat|head|tail|wc|grep|egrep|fgrep|cut|jq|nl|tr|ls|stat|diff|cmp|echo|printf|true)(?:\s|$)/,
|
|
107
|
+
// less with no log file of what it shows.
|
|
108
|
+
/^(?!.*\s(?:-[a-zA-Z]*[oO]|--log-file\b|--LOG-FILE\b))less(?:\s|$)/,
|
|
109
|
+
/^(?!.*\s(?:--output\b|-O|--open-files-in-pager\b))git(?:\s+(?:-C\s+\S+|--no-pager|-P))*\s+(?:diff|log|show|blame|grep|status|cat-file|ls-files|shortlog|rev-parse)(?:\s|$)/,
|
|
110
|
+
// rg with no preprocessor; sort with no output file or compressor.
|
|
111
|
+
/^(?!.*\s--pre\b)rg(?:\s|$)/,
|
|
112
|
+
/^(?!.*\s(?:-[a-zA-Z]*o|--output\b|--compress-program\b))sort(?:\s|$)/,
|
|
113
|
+
];
|
|
114
|
+
|
|
115
|
+
/** A command's words, quotes taken off. */
|
|
116
|
+
const wordsOf = (text) =>
|
|
117
|
+
(text.match(/'[^']*'|"(?:\\.|[^"\\])*"|\S+/g) ?? []).map((w) =>
|
|
118
|
+
w.replace(/^(['"])(.*)\1$/s, '$2'),
|
|
119
|
+
);
|
|
120
|
+
|
|
121
|
+
// A sed script that only prints, deletes from what it prints, numbers or quits: `5,20p`, `$p`, `/x/p`.
|
|
122
|
+
const SED_ADDRESS = String.raw`(?:\d+|\$|/(?:[^/\\]|\\.)*/)`;
|
|
123
|
+
const SED_PRINTS = new RegExp(
|
|
124
|
+
String.raw`^(?:\s*(?:${SED_ADDRESS}(?:\s*,\s*${SED_ADDRESS})?)?\s*[pdq=]\s*)(?:;(?:\s*(?:${SED_ADDRESS}(?:\s*,\s*${SED_ADDRESS})?)?\s*[pdq=]\s*))*;?$`,
|
|
125
|
+
);
|
|
126
|
+
|
|
127
|
+
/** Whether a sed command only prints: no in-place edit, no script file, and every script only prints. */
|
|
128
|
+
function sedPrints(text) {
|
|
129
|
+
const words = wordsOf(text).slice(1);
|
|
130
|
+
const scripts = [];
|
|
131
|
+
let expressions = false;
|
|
132
|
+
const files = [];
|
|
133
|
+
for (let i = 0; i < words.length; i++) {
|
|
134
|
+
const w = words[i];
|
|
135
|
+
if (w === '-e' || w === '--expression') {
|
|
136
|
+
expressions = true;
|
|
137
|
+
scripts.push(words[++i] ?? '');
|
|
138
|
+
} else if (w.startsWith('--expression=')) {
|
|
139
|
+
expressions = true;
|
|
140
|
+
scripts.push(w.slice('--expression='.length));
|
|
141
|
+
} else if (w === '--quiet' || w === '--silent' || w === '-n') continue;
|
|
142
|
+
else if (/^-[nErsuz]+$/.test(w)) continue;
|
|
143
|
+
else if (w.startsWith('-'))
|
|
144
|
+
return false; // -i, -I, -f and anything else
|
|
145
|
+
else files.push(w);
|
|
146
|
+
}
|
|
147
|
+
if (!expressions && files.length) scripts.push(files.shift());
|
|
148
|
+
return scripts.length > 0 && scripts.every((s) => SED_PRINTS.test(s));
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/** Whether an awk command only prints: -F and -v only, and no redirect, pipe, system() or getline. */
|
|
152
|
+
function awkPrints(text) {
|
|
153
|
+
const words = wordsOf(text).slice(1);
|
|
154
|
+
for (let i = 0; i < words.length; i++) {
|
|
155
|
+
if (!words[i].startsWith('-')) break;
|
|
156
|
+
if (words[i] === '-v') i++;
|
|
157
|
+
else if (!/^-F/.test(words[i])) return false;
|
|
158
|
+
}
|
|
159
|
+
return !/[>|]|\b(?:system|getline|fflush|close)\b/.test(text);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Whether a uniq command names no output file: at most one file, the one it reads. */
|
|
163
|
+
const uniqPrints = (text) =>
|
|
164
|
+
wordsOf(text)
|
|
165
|
+
.slice(1)
|
|
166
|
+
.filter((w) => !w.startsWith('-')).length <= 1;
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Whether `cmd` only reads and prints, so it can't write any file: every command of the chain is a
|
|
170
|
+
* reader (`cd`, git's history, cat, head, tail, grep, wc, jq, cut, sort, uniq, awk without redirects,
|
|
171
|
+
* sed -n printing lines…), piped or chained into each other, with no command's output in its
|
|
172
|
+
* arguments, no variable set before a command, and no redirect but `2>&1` or into /dev/null.
|
|
173
|
+
*/
|
|
174
|
+
export function readsOnly(cmd) {
|
|
175
|
+
// Taken out first: `&` in `2>&1` would otherwise split the command there.
|
|
176
|
+
const read = String(cmd).replace(HARMLESS_REDIRECT, ' ');
|
|
177
|
+
const code = codeOf(read);
|
|
178
|
+
if (/[>`]|\$\(|<\(|<>/.test(code)) return false;
|
|
179
|
+
if (code.split(/[;&|\n()]/).some((piece) => ASSIGNS.test(piece))) return false;
|
|
180
|
+
const parts = commandsOf(read);
|
|
181
|
+
return (
|
|
182
|
+
parts.length > 0 &&
|
|
183
|
+
parts.every(({ text, code: c }) => {
|
|
184
|
+
if (READERS.some((re) => re.test(c))) return true;
|
|
185
|
+
if (/^sed(?:\s|$)/.test(c)) return sedPrints(text);
|
|
186
|
+
if (/^awk(?:\s|$)/.test(c)) return awkPrints(text);
|
|
187
|
+
if (/^uniq(?:\s|$)/.test(c)) return uniqPrints(text);
|
|
188
|
+
return false;
|
|
189
|
+
})
|
|
190
|
+
);
|
|
191
|
+
}
|
package/hooks/lib/snapshot.mjs
CHANGED
|
@@ -13,9 +13,10 @@ import { readQueue, waiting } from './queue.mjs';
|
|
|
13
13
|
import { sendBacks } from './reviews.mjs';
|
|
14
14
|
import { readMilestones, readSpecs, specCheckRows } from './plan.mjs';
|
|
15
15
|
import { handedOver, entryProblems, readRegister, toolOf } from './designs.mjs';
|
|
16
|
-
import { SECURITY_KINDS, securityRules } from './security.mjs';
|
|
16
|
+
import { SECURITY_KINDS, securityReview, securityRules } from './security.mjs';
|
|
17
|
+
import { securityReviews } from './events.mjs';
|
|
17
18
|
import { sessions } from './sessions.mjs';
|
|
18
|
-
import { storyOfBranch } from './teamfacts.mjs';
|
|
19
|
+
import { isHandle, storyOfBranch } from './teamfacts.mjs';
|
|
19
20
|
import { storyTimes } from './timeline.mjs';
|
|
20
21
|
import { trail } from './storymap.mjs';
|
|
21
22
|
import {
|
|
@@ -36,9 +37,11 @@ import { slicesOf } from './schedule.mjs';
|
|
|
36
37
|
* story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
|
|
37
38
|
* each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
|
|
38
39
|
* approver and story, the security review's rules, each story's spec-check result and place in the
|
|
39
|
-
* merge queue, the design register's entries, and the sessions at work
|
|
40
|
+
* merge queue, the design register's entries, and the sessions at work; 6 each usage row's model, the
|
|
41
|
+
* security reviews each story needed and whether they ran, the pull request of each intent a claim
|
|
42
|
+
* carries out, and the team's claims with when each was last renewed.
|
|
40
43
|
*/
|
|
41
|
-
export const SNAPSHOT_VERSION =
|
|
44
|
+
export const SNAPSHOT_VERSION = 6;
|
|
42
45
|
|
|
43
46
|
/** A story's stage, as a report names it. */
|
|
44
47
|
export const STAGES = [
|
|
@@ -56,6 +59,8 @@ export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'ba
|
|
|
56
59
|
export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
|
|
57
60
|
/** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
|
|
58
61
|
export const DESIGN_STATES = ['handed-over', 'in-tool', 'problems'];
|
|
62
|
+
/** What a security review that ran found: nothing, findings, or a report without a findings block that reads. */
|
|
63
|
+
export const SECURITY_RESULTS = ['pass', 'findings', 'unread'];
|
|
59
64
|
|
|
60
65
|
/**
|
|
61
66
|
* The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
|
|
@@ -128,11 +133,34 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
128
133
|
{
|
|
129
134
|
story: 'id?',
|
|
130
135
|
kind: `enum:${AGENT_KINDS.join('|')}`,
|
|
136
|
+
// Added in version 6: the model the requests ran on, as Claude Code names it.
|
|
137
|
+
model: 'name?',
|
|
131
138
|
input: 'count',
|
|
132
139
|
output: 'count',
|
|
133
140
|
cache: 'count',
|
|
134
141
|
},
|
|
135
142
|
],
|
|
143
|
+
// Version 6: each story that needs the security review on its branch, or whose security reviewer ran:
|
|
144
|
+
// why it needs it (the kinds of change), whether the reviewer ran, when it reported, and what it found.
|
|
145
|
+
securityReviews: [
|
|
146
|
+
{
|
|
147
|
+
story: 'id',
|
|
148
|
+
branch: 'name?',
|
|
149
|
+
needed: 'bool?',
|
|
150
|
+
reasons: [`enum:${SECURITY_KINDS.join('|')}`],
|
|
151
|
+
ran: 'bool',
|
|
152
|
+
at: 'ms?',
|
|
153
|
+
result: `enum:${SECURITY_RESULTS.join('|')}?`,
|
|
154
|
+
findings: 'count?',
|
|
155
|
+
blockers: 'count?',
|
|
156
|
+
},
|
|
157
|
+
],
|
|
158
|
+
// Version 6: each intent a claim says its story carries out, and that story's open pull request.
|
|
159
|
+
intents: [{ id: 'count', story: 'id', pull: 'count?', draft: 'bool?' }],
|
|
160
|
+
// Version 6: the team's claims: who holds each story, since when, what it leases, when it was last
|
|
161
|
+
// renewed (claimed again, its lease grown, its branch pushed) and whether it's stale. No lease renews
|
|
162
|
+
// on a schedule.
|
|
163
|
+
claims: [{ story: 'id', by: 'handle', at: 'ms', active: 'ms?', stale: 'bool', lease: ['path'] }],
|
|
136
164
|
rules: {
|
|
137
165
|
// `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
|
|
138
166
|
layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
|
|
@@ -207,6 +235,9 @@ export const LATER_PARTS = [
|
|
|
207
235
|
'sessions',
|
|
208
236
|
'rules.lanes',
|
|
209
237
|
'rules.security',
|
|
238
|
+
'securityReviews',
|
|
239
|
+
'intents',
|
|
240
|
+
'claims',
|
|
210
241
|
];
|
|
211
242
|
|
|
212
243
|
export const SUMMARY_MAX = 600;
|
|
@@ -291,6 +322,8 @@ export const EVENT_PARTS = [
|
|
|
291
322
|
'rules',
|
|
292
323
|
'standards',
|
|
293
324
|
'designs',
|
|
325
|
+
'securityReviews',
|
|
326
|
+
'intents',
|
|
294
327
|
];
|
|
295
328
|
|
|
296
329
|
/** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
|
|
@@ -366,8 +399,9 @@ export function recordedUsage(root) {
|
|
|
366
399
|
for (const e of entries) {
|
|
367
400
|
if (!AGENT_KINDS.includes(e.kind)) continue;
|
|
368
401
|
const story = KINDS.id(e.story) ? e.story : null;
|
|
369
|
-
const
|
|
370
|
-
const
|
|
402
|
+
const model = KINDS.name(e.model) && e.model ? e.model : null;
|
|
403
|
+
const key = `${story}|${e.kind}|${model}`;
|
|
404
|
+
const was = sums.get(key) ?? { story, kind: e.kind, model, input: 0, output: 0, cache: 0 };
|
|
371
405
|
for (const k of ['input', 'output', 'cache'])
|
|
372
406
|
was[k] += Number.isInteger(e[k]) && e[k] > 0 ? e[k] : 0;
|
|
373
407
|
sums.set(key, was);
|
|
@@ -388,7 +422,8 @@ function checkedRows(root, story) {
|
|
|
388
422
|
|
|
389
423
|
/**
|
|
390
424
|
* The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
|
|
391
|
-
* branch stories merge into, `claims` the team's claims
|
|
425
|
+
* branch stories merge into, `claims` and `pulls` the team's claims and open pull requests as last
|
|
426
|
+
* read, `version` code-kit's.
|
|
392
427
|
*/
|
|
393
428
|
export function buildSnapshot({
|
|
394
429
|
root,
|
|
@@ -396,6 +431,7 @@ export function buildSnapshot({
|
|
|
396
431
|
status,
|
|
397
432
|
base,
|
|
398
433
|
claims = [],
|
|
434
|
+
pulls = [],
|
|
399
435
|
version,
|
|
400
436
|
now = Date.now(),
|
|
401
437
|
}) {
|
|
@@ -467,7 +503,7 @@ export function buildSnapshot({
|
|
|
467
503
|
const checks = new Map();
|
|
468
504
|
for (const rows of rowsOf.values())
|
|
469
505
|
for (const row of rows) checks.set(row.requirement, row.status);
|
|
470
|
-
const requirements = trail(root, status, base).map((r) => ({
|
|
506
|
+
const requirements = trail(root, status, base, config).map((r) => ({
|
|
471
507
|
id: r.id,
|
|
472
508
|
title: line(r.title),
|
|
473
509
|
stories: r.stories.map((s) => s.id),
|
|
@@ -547,10 +583,91 @@ export function buildSnapshot({
|
|
|
547
583
|
standards: reportedStandards(root, config, line),
|
|
548
584
|
designs: reportedDesigns(root, config),
|
|
549
585
|
sessions: reportedSessions(root, now),
|
|
586
|
+
securityReviews: reportedSecurityReviews(root, config, status, base),
|
|
587
|
+
intents: reportedIntents(claims, pulls),
|
|
588
|
+
claims: reportedClaims(claims),
|
|
550
589
|
};
|
|
551
590
|
return snapshot;
|
|
552
591
|
}
|
|
553
592
|
|
|
593
|
+
/**
|
|
594
|
+
* Version 6: each story that needs the security review on its branch now (security.mjs, for a branch
|
|
595
|
+
* still at work), or whose security reviewer ran (the event log's record of its findings).
|
|
596
|
+
*/
|
|
597
|
+
function reportedSecurityReviews(root, config, status, base) {
|
|
598
|
+
const ran = securityReviews(root);
|
|
599
|
+
const out = [];
|
|
600
|
+
for (const s of status.stories) {
|
|
601
|
+
if (!KINDS.id(s.id)) continue;
|
|
602
|
+
const review = ran.get(s.id) ?? null;
|
|
603
|
+
let need = null;
|
|
604
|
+
if (s.branchExists && s.state !== 'done')
|
|
605
|
+
try {
|
|
606
|
+
need = securityReview(root, { base, branch: s.branch, config });
|
|
607
|
+
} catch {
|
|
608
|
+
// the branch can't be compared with the base: whether it needs the review isn't known
|
|
609
|
+
}
|
|
610
|
+
if (!review && !need?.needed) continue;
|
|
611
|
+
const counted = review && !review.unread;
|
|
612
|
+
const count = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
|
|
613
|
+
out.push({
|
|
614
|
+
story: s.id,
|
|
615
|
+
branch: KINDS.name(s.branch) ? s.branch : null,
|
|
616
|
+
needed: need ? need.needed : null,
|
|
617
|
+
reasons: need
|
|
618
|
+
? [...new Set(need.reasons.map((r) => r.kind))].filter((k) => SECURITY_KINDS.includes(k))
|
|
619
|
+
: [],
|
|
620
|
+
ran: Boolean(review),
|
|
621
|
+
at: review ? msOf(review.at) : null,
|
|
622
|
+
result: !review ? null : review.unread ? 'unread' : review.findings ? 'findings' : 'pass',
|
|
623
|
+
findings: counted ? count(review.findings) : null,
|
|
624
|
+
blockers: counted ? count(review.blockers) : null,
|
|
625
|
+
});
|
|
626
|
+
}
|
|
627
|
+
return out;
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
const msOf = (iso) => {
|
|
631
|
+
const t = Date.parse(iso ?? '');
|
|
632
|
+
return Number.isInteger(t) && t > 0 ? t : null;
|
|
633
|
+
};
|
|
634
|
+
|
|
635
|
+
/**
|
|
636
|
+
* Version 6: each intent a claim names (`code-kit team claim <story> --intent <n>`), with its story and
|
|
637
|
+
* that story's open pull request, by its branch, draft or not; none while it has no pull request open.
|
|
638
|
+
*/
|
|
639
|
+
function reportedIntents(claims, pulls) {
|
|
640
|
+
return claims
|
|
641
|
+
.filter((c) => Number.isInteger(c?.intent) && c.intent > 0 && KINDS.id(c.story))
|
|
642
|
+
.map((c) => {
|
|
643
|
+
const pr = pulls.find((p) => storyOfBranch(p?.branch) === c.story);
|
|
644
|
+
return {
|
|
645
|
+
id: c.intent,
|
|
646
|
+
story: c.story,
|
|
647
|
+
pull: Number.isInteger(pr?.number) && pr.number > 0 ? pr.number : null,
|
|
648
|
+
draft: pr ? Boolean(pr.draft) : null,
|
|
649
|
+
};
|
|
650
|
+
});
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
/**
|
|
654
|
+
* Version 6: the team's claims as the provider last gave them: when each was taken, when it was last
|
|
655
|
+
* renewed by work (`active`: claimed again, its lease grown or its branch pushed) and whether that's
|
|
656
|
+
* longer ago than the team's stale days. A claim never renews on a schedule.
|
|
657
|
+
*/
|
|
658
|
+
function reportedClaims(claims) {
|
|
659
|
+
return claims
|
|
660
|
+
.filter((c) => KINDS.id(c?.story) && isHandle(c.by) && msOf(c.at))
|
|
661
|
+
.map((c) => ({
|
|
662
|
+
story: c.story,
|
|
663
|
+
by: c.by,
|
|
664
|
+
at: msOf(c.at),
|
|
665
|
+
active: msOf(c.active),
|
|
666
|
+
stale: c.stale === true,
|
|
667
|
+
lease: (Array.isArray(c.lease) ? c.lease : []).filter((p) => KINDS.path(p)),
|
|
668
|
+
}));
|
|
669
|
+
}
|
|
670
|
+
|
|
554
671
|
/** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
|
|
555
672
|
function worstCheck(rows) {
|
|
556
673
|
if (!rows.length) return 'none';
|