@warren-dean/code-kit 0.29.0 → 0.30.1
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 +34 -0
- package/README.md +16 -9
- package/bin/code-kit.mjs +421 -57
- package/hooks/guard-bash.mjs +87 -34
- package/hooks/lib/checkout.mjs +78 -1
- package/hooks/lib/checks.mjs +13 -3
- package/hooks/lib/ci.mjs +35 -2
- package/hooks/lib/config.mjs +2 -5
- package/hooks/lib/deferrals.mjs +107 -0
- package/hooks/lib/designs.mjs +100 -42
- package/hooks/lib/events.mjs +11 -10
- package/hooks/lib/glob.mjs +7 -0
- package/hooks/lib/instructions.mjs +1 -1
- package/hooks/lib/journal.mjs +2 -1
- package/hooks/lib/next.mjs +97 -14
- package/hooks/lib/plan.mjs +186 -11
- package/hooks/lib/queue.mjs +51 -12
- package/hooks/lib/regression.mjs +44 -13
- package/hooks/lib/reviews.mjs +43 -2
- package/hooks/lib/rules.mjs +47 -9
- package/hooks/lib/security.mjs +22 -7
- package/hooks/lib/shell.mjs +153 -2
- package/hooks/lib/snapshot.mjs +1 -1
- package/hooks/lib/storymap.mjs +13 -7
- package/hooks/lib/testfiles.mjs +22 -0
- package/hooks/lib/trace.mjs +3 -2
- package/hooks/lib/verify.mjs +65 -13
- package/hooks/lib/worktrees.mjs +25 -3
- package/hooks/mod/board.mjs +2 -0
- package/hooks/mod/loop.mjs +9 -2
- package/hooks/mod/view.mjs +23 -2
- package/package.json +1 -1
- package/skills/design/SKILL.md +4 -4
- package/skills/init/SKILL.md +6 -1
- package/skills/next/SKILL.md +1 -0
- package/skills/review/SKILL.md +11 -3
- package/templates/agent.md +2 -1
- package/templates/claude-md.md +2 -0
package/hooks/lib/security.mjs
CHANGED
|
@@ -9,6 +9,7 @@ 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`;
|
|
@@ -42,8 +43,9 @@ export function securityOutcome(report) {
|
|
|
42
43
|
}
|
|
43
44
|
|
|
44
45
|
// Tests, docs and design files describe the change; the review looks at the code that ships.
|
|
45
|
-
const
|
|
46
|
-
/(^|\/)(
|
|
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);
|
|
47
49
|
|
|
48
50
|
/**
|
|
49
51
|
* What makes a change sensitive, by kind: `path` matches a changed file's path, `code` (one pattern or
|
|
@@ -148,12 +150,19 @@ const examples = (list) =>
|
|
|
148
150
|
/**
|
|
149
151
|
* Why a change needs the security review, in words, one per kind: [{ kind, why, where: [...] }].
|
|
150
152
|
* Empty when it touches nothing sensitive. `files` are the changed files, `added` the added lines,
|
|
151
|
-
* `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.
|
|
152
155
|
*/
|
|
153
|
-
export function securityReasons({
|
|
156
|
+
export function securityReasons({
|
|
157
|
+
files = [],
|
|
158
|
+
added = [],
|
|
159
|
+
cites = [],
|
|
160
|
+
security = new Set(),
|
|
161
|
+
config,
|
|
162
|
+
}) {
|
|
154
163
|
const reasons = [];
|
|
155
|
-
const shipped = files.filter((f) => !
|
|
156
|
-
const lines = added.filter((a) => !
|
|
164
|
+
const shipped = files.filter((f) => !notShipped(f, config));
|
|
165
|
+
const lines = added.filter((a) => !notShipped(a.file, config));
|
|
157
166
|
for (const s of SENSITIVE) {
|
|
158
167
|
const code = [s.code].flat();
|
|
159
168
|
const where = [
|
|
@@ -217,7 +226,13 @@ export function securityReview(root, { base, branch, config }) {
|
|
|
217
226
|
const texts = specs
|
|
218
227
|
? markdownFiles(root, specs).map((f) => readFileSync(join(root, f), 'utf8'))
|
|
219
228
|
: [];
|
|
220
|
-
const reasons = securityReasons({
|
|
229
|
+
const reasons = securityReasons({
|
|
230
|
+
files,
|
|
231
|
+
added,
|
|
232
|
+
cites,
|
|
233
|
+
security: securityRequirementIds(texts),
|
|
234
|
+
config,
|
|
235
|
+
});
|
|
221
236
|
return {
|
|
222
237
|
branch,
|
|
223
238
|
story,
|
package/hooks/lib/shell.mjs
CHANGED
|
@@ -52,7 +52,8 @@ const LEADING =
|
|
|
52
52
|
/**
|
|
53
53
|
* The simple commands `cmd` runs, in order: split at `;`, `&`, `|`, newlines, parentheses and
|
|
54
54
|
* backticks outside quotes, heredoc bodies left out, each without leading `VAR=value` assignments.
|
|
55
|
-
* Each is `{ text, code }`: `text` as written, `code` with its quoted text masked
|
|
55
|
+
* Each is `{ text, code, whole }`: `text` as written, `code` with its quoted text masked, and `whole`
|
|
56
|
+
* as written with its leading assignments and wrappers kept.
|
|
56
57
|
*/
|
|
57
58
|
export function commandsOf(cmd) {
|
|
58
59
|
const text = withoutHeredocs(cmd);
|
|
@@ -66,7 +67,8 @@ export function commandsOf(cmd) {
|
|
|
66
67
|
const skip = body.match(LEADING)?.[0].length ?? 0;
|
|
67
68
|
const from = start + lead + skip;
|
|
68
69
|
const piece = text.slice(from, start + lead + body.length);
|
|
69
|
-
if (piece)
|
|
70
|
+
if (piece)
|
|
71
|
+
found.push({ text: piece, code: mask.slice(from, from + piece.length), whole: body });
|
|
70
72
|
};
|
|
71
73
|
for (let i = 0; i < mask.length; i++)
|
|
72
74
|
if (SEPARATOR.test(mask[i])) {
|
|
@@ -92,3 +94,152 @@ export const GIT = String.raw`git\s+(?:-[Cc]\s+(?:"[^"]*"|'[^']*'|\S+)\s+)*`;
|
|
|
92
94
|
|
|
93
95
|
/** code-kit's command line however it's run: installed, through node (its path quoted or not), or npx. */
|
|
94
96
|
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+)?)`;
|
|
97
|
+
|
|
98
|
+
// What a read may redirect: its errors into its output (2>&1, >&2), or anything into /dev/null.
|
|
99
|
+
const HARMLESS_REDIRECT = /(?:\d+|&)?>>?\s*(?:&\d+|\/dev\/null(?![\w/.-]))/g;
|
|
100
|
+
|
|
101
|
+
/** `cmd` with its harmless redirects (`2>&1`, `>&2`, anything into /dev/null) taken out: they write no file. */
|
|
102
|
+
export const withoutHarmlessRedirects = (cmd) => String(cmd).replace(HARMLESS_REDIRECT, ' ');
|
|
103
|
+
// An assignment before a command (GIT_PAGER=…, GIT_EXTERNAL_DIFF=…, LESSOPEN=…) can make a reader run a
|
|
104
|
+
// program, so a read that sets one isn't only a read.
|
|
105
|
+
const ASSIGNS = /^\s*(?:(?:sudo|exec|time|command|nohup|env)\s+|!\s+)*[A-Za-z_]\w*=/;
|
|
106
|
+
|
|
107
|
+
// Commands that read files or what comes down the pipe and print, and write nothing whatever their
|
|
108
|
+
// arguments. git reads its history: only `-C` before the subcommand (a `-c` setting can name a program
|
|
109
|
+
// to run), and no output file or pager program.
|
|
110
|
+
const READERS = [
|
|
111
|
+
/^(?:cd|pwd|cat|head|tail|wc|grep|egrep|fgrep|cut|jq|nl|tr|ls|stat|diff|cmp|echo|printf|true)(?:\s|$)/,
|
|
112
|
+
// less with no log file of what it shows.
|
|
113
|
+
/^(?!.*\s(?:-[a-zA-Z]*[oO]|--log-file\b|--LOG-FILE\b))less(?:\s|$)/,
|
|
114
|
+
/^(?!.*\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|$)/,
|
|
115
|
+
// git branch only listing branches or naming the current one: no name to create, move or delete.
|
|
116
|
+
/^git(?:\s+(?:-C\s+\S+|--no-pager|-P))*\s+branch(?:\s+(?:--show-current|--list|-l|-a|--all|-r|--remotes|-vv?|--verbose|--no-color|--color|--merged|--no-merged))*\s*$/,
|
|
117
|
+
// rg with no preprocessor; sort with no output file or compressor.
|
|
118
|
+
/^(?!.*\s--pre\b)rg(?:\s|$)/,
|
|
119
|
+
/^(?!.*\s(?:-[a-zA-Z]*o|--output\b|--compress-program\b))sort(?:\s|$)/,
|
|
120
|
+
];
|
|
121
|
+
|
|
122
|
+
/** A command's words, quotes taken off. */
|
|
123
|
+
const wordsOf = (text) =>
|
|
124
|
+
(text.match(/'[^']*'|"(?:\\.|[^"\\])*"|\S+/g) ?? []).map((w) =>
|
|
125
|
+
w.replace(/^(['"])(.*)\1$/s, '$2'),
|
|
126
|
+
);
|
|
127
|
+
|
|
128
|
+
// A sed script that only prints, deletes from what it prints, numbers or quits: `5,20p`, `$p`, `/x/p`.
|
|
129
|
+
const SED_ADDRESS = String.raw`(?:\d+|\$|/(?:[^/\\]|\\.)*/)`;
|
|
130
|
+
const SED_PRINTS = new RegExp(
|
|
131
|
+
String.raw`^(?:\s*(?:${SED_ADDRESS}(?:\s*,\s*${SED_ADDRESS})?)?\s*[pdq=]\s*)(?:;(?:\s*(?:${SED_ADDRESS}(?:\s*,\s*${SED_ADDRESS})?)?\s*[pdq=]\s*))*;?$`,
|
|
132
|
+
);
|
|
133
|
+
|
|
134
|
+
/** Whether a sed command only prints: no in-place edit, no script file, and every script only prints. */
|
|
135
|
+
function sedPrints(text) {
|
|
136
|
+
const words = wordsOf(text).slice(1);
|
|
137
|
+
const scripts = [];
|
|
138
|
+
let expressions = false;
|
|
139
|
+
const files = [];
|
|
140
|
+
for (let i = 0; i < words.length; i++) {
|
|
141
|
+
const w = words[i];
|
|
142
|
+
if (w === '-e' || w === '--expression') {
|
|
143
|
+
expressions = true;
|
|
144
|
+
scripts.push(words[++i] ?? '');
|
|
145
|
+
} else if (w.startsWith('--expression=')) {
|
|
146
|
+
expressions = true;
|
|
147
|
+
scripts.push(w.slice('--expression='.length));
|
|
148
|
+
} else if (w === '--quiet' || w === '--silent' || w === '-n') continue;
|
|
149
|
+
else if (/^-[nErsuz]+$/.test(w)) continue;
|
|
150
|
+
else if (w.startsWith('-'))
|
|
151
|
+
return false; // -i, -I, -f and anything else
|
|
152
|
+
else files.push(w);
|
|
153
|
+
}
|
|
154
|
+
if (!expressions && files.length) scripts.push(files.shift());
|
|
155
|
+
return scripts.length > 0 && scripts.every((s) => SED_PRINTS.test(s));
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** Whether an awk command only prints: -F and -v only, and no redirect, pipe, system() or getline. */
|
|
159
|
+
function awkPrints(text) {
|
|
160
|
+
const words = wordsOf(text).slice(1);
|
|
161
|
+
for (let i = 0; i < words.length; i++) {
|
|
162
|
+
if (!words[i].startsWith('-')) break;
|
|
163
|
+
if (words[i] === '-v') i++;
|
|
164
|
+
else if (!/^-F/.test(words[i])) return false;
|
|
165
|
+
}
|
|
166
|
+
return !/[>|]|\b(?:system|getline|fflush|close)\b/.test(text);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** Whether a uniq command names no output file: at most one file, the one it reads. */
|
|
170
|
+
const uniqPrints = (text) =>
|
|
171
|
+
wordsOf(text)
|
|
172
|
+
.slice(1)
|
|
173
|
+
.filter((w) => !w.startsWith('-')).length <= 1;
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Whether `cmd` only reads and prints, so it can't write any file: every command of the chain is a
|
|
177
|
+
* reader (`cd`, git's history, cat, head, tail, grep, wc, jq, cut, sort, uniq, awk without redirects,
|
|
178
|
+
* sed -n printing lines…), piped or chained into each other, with no command's output in its
|
|
179
|
+
* arguments, no variable set before a command, and no redirect but `2>&1` or into /dev/null.
|
|
180
|
+
*/
|
|
181
|
+
export function readsOnly(cmd) {
|
|
182
|
+
// Taken out first: `&` in `2>&1` would otherwise split the command there.
|
|
183
|
+
const read = withoutHarmlessRedirects(cmd);
|
|
184
|
+
const code = codeOf(read);
|
|
185
|
+
if (/[>`]|\$\(|<\(|<>/.test(code)) return false;
|
|
186
|
+
if (code.split(/[;&|\n()]/).some((piece) => ASSIGNS.test(piece))) return false;
|
|
187
|
+
const parts = commandsOf(read);
|
|
188
|
+
return (
|
|
189
|
+
parts.length > 0 &&
|
|
190
|
+
parts.every(({ text, code: c }) => {
|
|
191
|
+
if (READERS.some((re) => re.test(c))) return true;
|
|
192
|
+
if (/^sed(?:\s|$)/.test(c)) return sedPrints(text);
|
|
193
|
+
if (/^awk(?:\s|$)/.test(c)) return awkPrints(text);
|
|
194
|
+
if (/^uniq(?:\s|$)/.test(c)) return uniqPrints(text);
|
|
195
|
+
return false;
|
|
196
|
+
})
|
|
197
|
+
);
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// What may come before a command it runs: a package runner (`npx`, `pnpm exec`, `uv run`…) or a wrapper
|
|
201
|
+
// (`xargs`, `nice`, `timeout 60`), so a rule naming the command finds it there too.
|
|
202
|
+
const WRAPPER = String.raw`(?:(?:npx|bunx|pnpx)(?:\s+-\S+)*\s+|(?:pnpm|yarn|bun)\s+(?:(?:exec|dlx|x|run)\s+)?(?:-\S+\s+)*|npm\s+(?:exec|x|run)\s+(?:--\s+)?|(?:uv|poetry|pipenv)\s+run\s+|(?:xargs|nice|nohup|time|command|exec)(?:\s+-\S+)*\s+|timeout\s+(?:-\S+\s+)*\S+\s+)`;
|
|
203
|
+
// A shell handed a script (`sh -c '…'`, `bash -lc "…"`): the script's commands run too, as do eval's.
|
|
204
|
+
const SHELL_SCRIPT = /^(?:ba|z|da|k)?sh\s+(?:-[a-zA-Z]+\s+)*-[a-zA-Z]*c[a-zA-Z]*\s/;
|
|
205
|
+
const SCRIPT_FLAG = /^-[a-zA-Z]*c[a-zA-Z]*$/;
|
|
206
|
+
|
|
207
|
+
/** The script a command hands a shell it starts (`sh -c '…'`) or `eval`, or null. */
|
|
208
|
+
function scriptOf({ text, code }) {
|
|
209
|
+
const words = wordsOf(text);
|
|
210
|
+
if (/^eval\s/.test(code)) return words.slice(1).join(' ');
|
|
211
|
+
if (!SHELL_SCRIPT.test(code)) return null;
|
|
212
|
+
const at = words.findIndex((w, i) => i > 0 && SCRIPT_FLAG.test(w));
|
|
213
|
+
return at > 0 ? (words[at + 1] ?? null) : null;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Whether `cmd` runs a command `pattern` names: matched from the start of each command the line runs
|
|
218
|
+
* (after a package runner or wrapper, and inside `sh -c` or `eval`), with quoted text masked unless the
|
|
219
|
+
* pattern itself has quotes, so an argument, a heredoc or a message that mentions the command isn't it.
|
|
220
|
+
*/
|
|
221
|
+
export function runsNamed(cmd, pattern, depth = 0) {
|
|
222
|
+
const source = String(pattern).replace(/^\^/, '');
|
|
223
|
+
const quoted = /["']/.test(source);
|
|
224
|
+
const re = new RegExp(String.raw`^${WRAPPER}*(?:${source})`);
|
|
225
|
+
return commandsOf(cmd).some((c) => {
|
|
226
|
+
// The program's own name counts however it's quoted: `"tool" deploy` runs tool.
|
|
227
|
+
const first = c.text.match(/^(?:'[^']*'|"(?:\\.|[^"\\])*"|\S+)/)?.[0] ?? '';
|
|
228
|
+
const subject = quoted ? c.text : wordsOf(first).join('') + c.code.slice(first.length);
|
|
229
|
+
if (re.test(subject)) return true;
|
|
230
|
+
const script = depth < 3 ? scriptOf(c) : null;
|
|
231
|
+
return script !== null && runsNamed(script, pattern, depth + 1);
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Whether a project's rule for a command (`shell.block`, `shell.restricted`: `{ pattern, command? }`)
|
|
237
|
+
* matches `cmd`. `command: true` matches the commands the line runs (runsNamed). Otherwise the pattern
|
|
238
|
+
* reads the whole line, except that in a line that only reads (readsOnly) quoted text is data: a grep
|
|
239
|
+
* for a blocked command doesn't run it.
|
|
240
|
+
*/
|
|
241
|
+
export function ruleMatches({ pattern, command }, cmd) {
|
|
242
|
+
if (command) return runsNamed(cmd, pattern);
|
|
243
|
+
const quoted = /["']/.test(pattern);
|
|
244
|
+
return new RegExp(pattern).test(!quoted && readsOnly(cmd) ? codeOf(cmd) : cmd);
|
|
245
|
+
}
|
package/hooks/lib/snapshot.mjs
CHANGED
|
@@ -503,7 +503,7 @@ export function buildSnapshot({
|
|
|
503
503
|
const checks = new Map();
|
|
504
504
|
for (const rows of rowsOf.values())
|
|
505
505
|
for (const row of rows) checks.set(row.requirement, row.status);
|
|
506
|
-
const requirements = trail(root, status, base).map((r) => ({
|
|
506
|
+
const requirements = trail(root, status, base, config).map((r) => ({
|
|
507
507
|
id: r.id,
|
|
508
508
|
title: line(r.title),
|
|
509
509
|
stories: r.stories.map((s) => s.id),
|
package/hooks/lib/storymap.mjs
CHANGED
|
@@ -6,6 +6,7 @@ import { existsSync, readFileSync } from 'node:fs';
|
|
|
6
6
|
import { join, posix } from 'node:path';
|
|
7
7
|
import { matchesAny } from './glob.mjs';
|
|
8
8
|
import { CODE, importsOf, layerOf, targetOf } from './layers.mjs';
|
|
9
|
+
import { isTestFile } from './testfiles.mjs';
|
|
9
10
|
|
|
10
11
|
const git = (root, ...args) => {
|
|
11
12
|
try {
|
|
@@ -126,8 +127,6 @@ export function laneOfFile(rel, config) {
|
|
|
126
127
|
: null;
|
|
127
128
|
}
|
|
128
129
|
|
|
129
|
-
const TEST = /(^|\/)(tests?|e2e|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/;
|
|
130
|
-
|
|
131
130
|
/**
|
|
132
131
|
* MAP-1: a story's code: { story, layers, files: [{ path, layer, lane, imports }] }. `layers` are the
|
|
133
132
|
* config's layers in their order, then `tests` and `other` where any file falls there; each file's
|
|
@@ -151,7 +150,9 @@ export function storyMap(root, story, config, from) {
|
|
|
151
150
|
.filter((t) => t && t !== rel),
|
|
152
151
|
),
|
|
153
152
|
];
|
|
154
|
-
const layer =
|
|
153
|
+
const layer = isTestFile(rel, config)
|
|
154
|
+
? 'tests'
|
|
155
|
+
: (layerOf(rel, config.layers)?.name ?? 'other');
|
|
155
156
|
return { path: rel, layer, lane: laneOfFile(rel, config), imports };
|
|
156
157
|
});
|
|
157
158
|
const used = new Set(files.map((f) => f.layer));
|
|
@@ -165,9 +166,10 @@ export function storyMap(root, story, config, from) {
|
|
|
165
166
|
|
|
166
167
|
/**
|
|
167
168
|
* TRAIL-1: each requirement's trail: { id, title, spec, state, stories: [{ id, state, lane }],
|
|
168
|
-
* files, tests }. Files are the code its stories changed, tests aside; tests are the
|
|
169
|
+
* files, tests }. Files are the code its stories changed, tests aside (by `config`'s `tests`); tests are the
|
|
170
|
+
* files that name it.
|
|
169
171
|
*/
|
|
170
|
-
export function trail(root, status, from) {
|
|
172
|
+
export function trail(root, status, from, config) {
|
|
171
173
|
const byStory = new Map();
|
|
172
174
|
const named = namedFiles(root);
|
|
173
175
|
const filesOf = (s) => {
|
|
@@ -178,7 +180,9 @@ export function trail(root, status, from) {
|
|
|
178
180
|
.filter((r) => !r.removed)
|
|
179
181
|
.map((r) => {
|
|
180
182
|
const stories = status.stories.filter((s) => s.requirements.includes(r.id));
|
|
181
|
-
const files = [
|
|
183
|
+
const files = [
|
|
184
|
+
...new Set(stories.flatMap((s) => filesOf(s)).filter((f) => !isTestFile(f, config))),
|
|
185
|
+
];
|
|
182
186
|
return {
|
|
183
187
|
id: r.id,
|
|
184
188
|
title: r.title,
|
|
@@ -221,7 +225,9 @@ export function projectMap(root, config, tracked, { depth = 3, most = 60 } = {})
|
|
|
221
225
|
files: 0,
|
|
222
226
|
};
|
|
223
227
|
nodes.set(path, node);
|
|
224
|
-
const layer =
|
|
228
|
+
const layer = isTestFile(rel, config)
|
|
229
|
+
? 'tests'
|
|
230
|
+
: (layerOf(rel, config.layers)?.name ?? 'other');
|
|
225
231
|
node.layers.set(layer, (node.layers.get(layer) ?? 0) + 1);
|
|
226
232
|
node.files += 1;
|
|
227
233
|
let source = '';
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// What counts as a test (docs/specs/18-regression.md), in one place for every check that asks: a fix's
|
|
2
|
+
// proof (REG-1), weakened tests (REG-2), the tests that name a requirement, the code map's tests layer,
|
|
3
|
+
// what the security review leaves out and which files are screens. A project's `tests` globs replace
|
|
4
|
+
// the conventions; without them, a file is a test when it's named as one or sits in a test folder.
|
|
5
|
+
import { matchesAny } from './glob.mjs';
|
|
6
|
+
|
|
7
|
+
// Named as a test: `*.test.*`, `*.spec.*`, `*.smoke.*`, `test_*.py`, `*_test.go` and `*_test.py`.
|
|
8
|
+
const NAMED = /\.(test|spec|smoke)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
|
|
9
|
+
// Inside a test folder, where a test's helpers, fixtures and harness live too.
|
|
10
|
+
const FOLDER = /(^|\/)(tests?|__tests__|e2e|smoke)\//;
|
|
11
|
+
|
|
12
|
+
/** Whether `rel` is a test or test code: the config's `tests` globs, or named as a test or in a test folder. */
|
|
13
|
+
export const isTestFile = (rel, config) =>
|
|
14
|
+
!rel.endsWith('.md') &&
|
|
15
|
+
(config?.tests?.length ? matchesAny(rel, config.tests) : NAMED.test(rel) || FOLDER.test(rel));
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Whether `rel` is a test itself, by its name, and not a helper beside one: the config's `tests` globs,
|
|
19
|
+
* or the naming conventions. A fix's proof keeps these and takes everything else back (REG-1).
|
|
20
|
+
*/
|
|
21
|
+
export const isNamedTest = (rel, config) =>
|
|
22
|
+
!rel.endsWith('.md') && (config?.tests?.length ? matchesAny(rel, config.tests) : NAMED.test(rel));
|
package/hooks/lib/trace.mjs
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// other tools read (`code-kit trace <path> --json`); Context Graph's adapter uses it to anchor a file's
|
|
4
4
|
// card in the spec and to show the layer rule before an agent drafts an edit.
|
|
5
5
|
import { execFileSync } from 'node:child_process';
|
|
6
|
-
import { matchesAny } from './glob.mjs';
|
|
6
|
+
import { literalPath, matchesAny } from './glob.mjs';
|
|
7
7
|
import { layerOf } from './layers.mjs';
|
|
8
8
|
import { readRequirements, readStories } from './plan.mjs';
|
|
9
9
|
import { ownerOf, reviewerOf } from './rules.mjs';
|
|
@@ -23,7 +23,8 @@ const git = (root, ...args) => {
|
|
|
23
23
|
/** Story ids named by the commits that changed `rel`, and by the current branch if it is a story branch. */
|
|
24
24
|
export function storiesOf(root, rel) {
|
|
25
25
|
const ids = new Set();
|
|
26
|
-
for (const m of git(root, 'log', '--format=%B', '--', rel).matchAll(/\bST-\d+\b/g))
|
|
26
|
+
for (const m of git(root, 'log', '--format=%B', '--', literalPath(rel)).matchAll(/\bST-\d+\b/g))
|
|
27
|
+
ids.add(m[0]);
|
|
27
28
|
const branch = git(root, 'rev-parse', '--abbrev-ref', 'HEAD').trim();
|
|
28
29
|
const onBranch = /^[\w-]+\/(st-\d+)$/i.exec(branch)?.[1];
|
|
29
30
|
if (onBranch) ids.add(onBranch.toUpperCase());
|
package/hooks/lib/verify.mjs
CHANGED
|
@@ -8,19 +8,23 @@ import { BASELINE_FILE, loadBaseline, newProblems } from './baseline.mjs';
|
|
|
8
8
|
import { runChecks } from './checks.mjs';
|
|
9
9
|
import { CONFIG_FILE } from './config.mjs';
|
|
10
10
|
import { isDependencyFile } from './dependencies.mjs';
|
|
11
|
-
import { entryProblems, readRegister } from './designs.mjs';
|
|
12
|
-
import {
|
|
11
|
+
import { entryProblems, freshEntries, readRegister, statesWithoutEvidence } from './designs.mjs';
|
|
12
|
+
import { evidenceRecords } from './reviews.mjs';
|
|
13
|
+
import { storyOfBranch } from './teamfacts.mjs';
|
|
14
|
+
import { literalPath, matchesAny } from './glob.mjs';
|
|
13
15
|
import { layerProblems } from './layers.mjs';
|
|
14
16
|
import { STANDARDS_APPROVAL, standardsFile, standardsWeakenings } from './standards.mjs';
|
|
15
17
|
import { TESTS_APPROVAL, branchWeakenings, fixOf, proveFix } from './regression.mjs';
|
|
16
18
|
import {
|
|
17
19
|
APPROVAL_LOG,
|
|
20
|
+
APPROVALS_DIR,
|
|
18
21
|
SECRETS,
|
|
19
22
|
laneOf,
|
|
20
23
|
ownerOf,
|
|
21
24
|
owns,
|
|
22
25
|
protectedEntry,
|
|
23
26
|
leadNeedsApproval,
|
|
27
|
+
relayCommand,
|
|
24
28
|
screenProblem,
|
|
25
29
|
} from './rules.mjs';
|
|
26
30
|
|
|
@@ -40,6 +44,15 @@ function showAt(root, ref, rel) {
|
|
|
40
44
|
}
|
|
41
45
|
}
|
|
42
46
|
|
|
47
|
+
/** The hash of a file's content at `ref` (git's blob id), or null when it doesn't exist there. */
|
|
48
|
+
function blobAt(root, ref, rel) {
|
|
49
|
+
try {
|
|
50
|
+
return git(root, 'rev-parse', '--verify', '-q', `${ref}:${rel}`).trim();
|
|
51
|
+
} catch {
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
43
56
|
/** The lane a branch belongs to by its name (`<lane>/<story>`), or null. */
|
|
44
57
|
export function laneOfBranch(branch, config) {
|
|
45
58
|
const lane = branch?.split('/')[0];
|
|
@@ -125,7 +138,7 @@ function logEntries(root, base) {
|
|
|
125
138
|
*/
|
|
126
139
|
function signedByPerson(root, from, file, signedBy) {
|
|
127
140
|
if (!signedBy) return false;
|
|
128
|
-
const out = git(root, 'log', '--format=%B%x1e', `${from}..HEAD`, '--', file);
|
|
141
|
+
const out = git(root, 'log', '--format=%B%x1e', `${from}..HEAD`, '--', literalPath(file));
|
|
129
142
|
const messages = out
|
|
130
143
|
.split('\x1e')
|
|
131
144
|
.map((m) => m.trim())
|
|
@@ -176,6 +189,8 @@ const NOISE = [
|
|
|
176
189
|
/^\(node:\d+\) \[?\w*\]? ?(DeprecationWarning|ExperimentalWarning|Warning)\b/,
|
|
177
190
|
/^\(Use `node --trace-(deprecation|warnings) /,
|
|
178
191
|
/^\s*$/,
|
|
192
|
+
// A tool printing a value it never had (pnpm exec, before it says a command isn't installed).
|
|
193
|
+
/^\s*undefined\s*$/,
|
|
179
194
|
];
|
|
180
195
|
const FAILING = /\b(fail(ed|ing|s)?|error|✗|✘|×|expected|received|assert|panic|traceback)\b/i;
|
|
181
196
|
|
|
@@ -194,8 +209,8 @@ export function failureOutput(output) {
|
|
|
194
209
|
|
|
195
210
|
/**
|
|
196
211
|
* The files changed, every problem with the branch, grouped as { ownership, protected, layers,
|
|
197
|
-
* baseline, design, tests, regression, standards, checks }, and the checks `skipped` because a
|
|
198
|
-
* installed. `lane` holds the branch to that lane's paths; `checks: false` leaves the project's
|
|
212
|
+
* baseline, design, evidence, tests, regression, standards, checks }, and the checks `skipped` because a
|
|
213
|
+
* tool isn't installed; `evidenceUnchecked` where the review's records aren't kept (HAND-7: CI). `lane` holds the branch to that lane's paths; `checks: false` leaves the project's
|
|
199
214
|
* checks to CI's own steps. `fixes` runs a fix's tests without the fix (REG-1; with the
|
|
200
215
|
* checks unless said); `branch` names the branch when the checkout is detached.
|
|
201
216
|
*/
|
|
@@ -218,6 +233,7 @@ export function verifyBranch({
|
|
|
218
233
|
layers: [],
|
|
219
234
|
baseline: [],
|
|
220
235
|
design: [],
|
|
236
|
+
evidence: [],
|
|
221
237
|
tests: [],
|
|
222
238
|
regression: [],
|
|
223
239
|
standards: [],
|
|
@@ -241,15 +257,17 @@ export function verifyBranch({
|
|
|
241
257
|
);
|
|
242
258
|
// WHO-1: where the lead merges, its own change to what the person keeps needs the person's approval,
|
|
243
259
|
// unless the base already holds it as the branch does (the setup's rules, put onto the base first).
|
|
260
|
+
// An approval recorded after the change names the content it approved (`blob`), and covers only that.
|
|
244
261
|
else if (
|
|
245
262
|
guarded &&
|
|
246
|
-
logged.get(f)?.approval === 'lead' &&
|
|
247
263
|
!signed &&
|
|
248
264
|
leadNeedsApproval(guarded.approval, config) &&
|
|
265
|
+
(logged.get(f)?.approval === 'lead' ||
|
|
266
|
+
(logged.get(f)?.blob && logged.get(f).blob !== blobAt(root, 'HEAD', f))) &&
|
|
249
267
|
showAt(root, base, f) !== showAt(root, 'HEAD', f)
|
|
250
268
|
)
|
|
251
269
|
found.protected.push(
|
|
252
|
-
`${f} is ${guarded.why}, and the lead changed it without the person's ${guarded.approval} approval. The lead merges here, so nobody else reviews it
|
|
270
|
+
`${f} is ${guarded.why}, and the lead ${logged.get(f)?.approval === 'lead' ? 'changed it without' : 'changed it since it had'} the person's ${guarded.approval} approval. The lead merges here, so nobody else reviews it. Ask the person; once they approve it (they run \`! echo "<what you are approving>" > ${APPROVALS_DIR}/${guarded.approval}\`${config.approvals?.lead ? `, or you record their words with \`${relayCommand(guarded.approval)}\`` : ''}), record their approval for the file as it is with a commit of its own: \`git commit -m "Record the person's ${guarded.approval} approval for ${f}"\`. The commit hook logs it; the file doesn't need to change.`,
|
|
253
271
|
);
|
|
254
272
|
if (matchesAny(f, config.anyActor)) continue;
|
|
255
273
|
if (lane === 'lead') {
|
|
@@ -294,17 +312,51 @@ export function verifyBranch({
|
|
|
294
312
|
}
|
|
295
313
|
|
|
296
314
|
// HAND-2: each register entry the branch adds or changes, and each approved design whose files it
|
|
297
|
-
// changed, names the approved files with their hashes, every state the spec lists.
|
|
315
|
+
// changed, names the approved files with their hashes, every state the spec lists. HAND-11: an entry
|
|
316
|
+
// the base already holds (where the branch left it, as it is now, or the first protected branch's,
|
|
317
|
+
// which a lane may have merged in) is the base's, not the branch's.
|
|
298
318
|
const register = config.designGate?.register;
|
|
319
|
+
let evidenceUnchecked = false;
|
|
299
320
|
if (register) {
|
|
300
|
-
const
|
|
321
|
+
const at = (ref) => readRegister(root, config, showAt(root, ref, register) ?? '{}').entries;
|
|
322
|
+
const entries = readRegister(root, config).entries;
|
|
323
|
+
const protectedBase = config.branches?.protected?.[0];
|
|
324
|
+
const fresh = new Set(
|
|
325
|
+
freshEntries(entries, at(from), at(base), protectedBase ? at(protectedBase) : []),
|
|
326
|
+
);
|
|
301
327
|
const touched = new Set(changed);
|
|
302
|
-
for (const e of
|
|
303
|
-
const fresh = !old.some((o) => JSON.stringify(o) === JSON.stringify(e));
|
|
328
|
+
for (const e of entries) {
|
|
304
329
|
const files = (e.states ?? []).flatMap((st) => [st?.image, st?.code]).filter(Boolean);
|
|
305
|
-
if (fresh || files.some((f) => touched.has(f)))
|
|
330
|
+
if (fresh.has(e) || files.some((f) => touched.has(f)))
|
|
306
331
|
found.design.push(...entryProblems(root, e, config.docs?.specs));
|
|
307
332
|
}
|
|
333
|
+
// HAND-7: a lane's branch that builds screens has the review's screenshot of each approved state.
|
|
334
|
+
const name = branch ?? currentBranchOf(root);
|
|
335
|
+
if (lane && lane !== 'lead' && name) {
|
|
336
|
+
const records = evidenceRecords(root, name);
|
|
337
|
+
if (records === null) evidenceUnchecked = true;
|
|
338
|
+
else {
|
|
339
|
+
const current = (r) =>
|
|
340
|
+
Boolean(r.sha) &&
|
|
341
|
+
spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', r.sha, 'HEAD']).status ===
|
|
342
|
+
0 &&
|
|
343
|
+
spawnSync('git', [
|
|
344
|
+
'-C',
|
|
345
|
+
root,
|
|
346
|
+
'diff',
|
|
347
|
+
'--quiet',
|
|
348
|
+
r.sha,
|
|
349
|
+
'HEAD',
|
|
350
|
+
'--',
|
|
351
|
+
literalPath(r.file),
|
|
352
|
+
]).status === 0;
|
|
353
|
+
const story = storyOfBranch(name) ?? name;
|
|
354
|
+
for (const { entry, state } of statesWithoutEvidence(entries, present, records, current))
|
|
355
|
+
found.evidence.push(
|
|
356
|
+
`${entry.screen ?? entry.file}'s ${state.name} state (${entry.file}) has no screenshot from the review beside its design (${state.image}). The review takes one of the built state at ${state.viewport ?? "the design's viewport"} and records it: code-kit designs evidence ${story} ${entry.file} ${state.name} <screenshot.png>.`,
|
|
357
|
+
);
|
|
358
|
+
}
|
|
359
|
+
}
|
|
308
360
|
}
|
|
309
361
|
|
|
310
362
|
// The baseline only shrinks once the kit is adopted (the adopting change may record it).
|
|
@@ -368,5 +420,5 @@ export function verifyBranch({
|
|
|
368
420
|
unfinished = Boolean(failure.timedOut);
|
|
369
421
|
}
|
|
370
422
|
}
|
|
371
|
-
return { changed, found, skipped, unfinished };
|
|
423
|
+
return { changed, found, skipped, unfinished, evidenceUnchecked };
|
|
372
424
|
}
|
package/hooks/lib/worktrees.mjs
CHANGED
|
@@ -37,6 +37,14 @@ const real = (p) => {
|
|
|
37
37
|
return p;
|
|
38
38
|
}
|
|
39
39
|
};
|
|
40
|
+
/** The folder this process runs in, or null when it has gone. */
|
|
41
|
+
const cwdNow = () => {
|
|
42
|
+
try {
|
|
43
|
+
return real(process.cwd());
|
|
44
|
+
} catch {
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
};
|
|
40
48
|
const alive = (pid) => {
|
|
41
49
|
try {
|
|
42
50
|
process.kill(pid, 0);
|
|
@@ -74,11 +82,12 @@ function hasOwnCommits(root, branch) {
|
|
|
74
82
|
|
|
75
83
|
/**
|
|
76
84
|
* LEAN-6: each worktree but the main checkout: { path, branch, story, merged, clean, changes, report,
|
|
77
|
-
* kind, missing, locked: { reason, pid, live } | null, agentAtWork }. `
|
|
85
|
+
* kind, missing, locked: { reason, pid, live } | null, agentAtWork, here }. `here`: this command runs in
|
|
86
|
+
* it (`cwd`, the process's own folder unless given), so taking it away would leave the shell nowhere. `kind` is `agent` (under
|
|
78
87
|
* .claude/worktrees), `merge` (a temporary merge checkout) or `other` (one the person made). `clean` and
|
|
79
88
|
* `changes` are null where they weren't read: an unmerged worktree stays whatever it holds (cleanOf reads it).
|
|
80
89
|
*/
|
|
81
|
-
export function worktrees(root, config, now = Date.now()) {
|
|
90
|
+
export function worktrees(root, config, now = Date.now(), cwd = cwdNow()) {
|
|
82
91
|
const list = git(root, 'worktree', 'list', '--porcelain');
|
|
83
92
|
if (list.status !== 0) return [];
|
|
84
93
|
const main = list.stdout.split('\n\n')[0];
|
|
@@ -98,6 +107,7 @@ export function worktrees(root, config, now = Date.now()) {
|
|
|
98
107
|
const pid = Number(/\bpid (\d+)/.exec(lockLine?.[1] ?? '')?.[1]) || null;
|
|
99
108
|
const missing = !existsSync(path);
|
|
100
109
|
const where = real(path);
|
|
110
|
+
const here = Boolean(cwd && (cwd === where || cwd.startsWith(`${where}/`)));
|
|
101
111
|
const kind = where.startsWith(`${agents}/`)
|
|
102
112
|
? 'agent'
|
|
103
113
|
: where.startsWith(`${temp}/`) && TEMP_MERGE.test(basename(path))
|
|
@@ -140,6 +150,7 @@ export function worktrees(root, config, now = Date.now()) {
|
|
|
140
150
|
lane && claims.some((c) => c.lane === lane && (c.story ?? null) === (story ?? c.story)),
|
|
141
151
|
),
|
|
142
152
|
age: missing ? null : now - statSync(path).mtimeMs,
|
|
153
|
+
here,
|
|
143
154
|
};
|
|
144
155
|
});
|
|
145
156
|
}
|
|
@@ -174,6 +185,9 @@ export function keptBecause(w) {
|
|
|
174
185
|
if (w.missing) return null;
|
|
175
186
|
if (w.kind === 'merge') return w.age < TEMP_MERGE_MS ? 'a merge may be using it now' : null;
|
|
176
187
|
if (w.kind === 'other') return "it isn't one code-kit made; release it by name if it's done";
|
|
188
|
+
// A merge run from inside a lane's worktree mustn't take away the folder its own shell is in.
|
|
189
|
+
if (w.here)
|
|
190
|
+
return 'this command runs in it; it goes at the next merge or `code-kit worktrees prune` run from elsewhere';
|
|
177
191
|
if (w.locked && !w.locked.pid)
|
|
178
192
|
return `it's locked${w.locked.reason ? ` (${w.locked.reason})` : ''}`;
|
|
179
193
|
if (!w.branch) return 'it has no branch checked out';
|
|
@@ -246,7 +260,15 @@ export function pruneWorktrees(root, config, now = Date.now()) {
|
|
|
246
260
|
const label = w.branch ?? w.path;
|
|
247
261
|
const why = keptBecause(w);
|
|
248
262
|
if (why) {
|
|
249
|
-
kept.push({
|
|
263
|
+
kept.push({
|
|
264
|
+
label,
|
|
265
|
+
why,
|
|
266
|
+
branch: w.branch,
|
|
267
|
+
changes: w.changes,
|
|
268
|
+
kind: w.kind,
|
|
269
|
+
here: w.here,
|
|
270
|
+
merged: w.merged,
|
|
271
|
+
});
|
|
250
272
|
continue;
|
|
251
273
|
}
|
|
252
274
|
if (w.missing) continue;
|
package/hooks/mod/board.mjs
CHANGED
package/hooks/mod/loop.mjs
CHANGED
|
@@ -172,6 +172,11 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
|
|
|
172
172
|
// ONB-6: an older setup brought up to date before the next story; init shows the person the diff.
|
|
173
173
|
if (step.step === 'update')
|
|
174
174
|
return `Before the next story, bring code-kit's setup up to date: run /code-kit:init. ${step.why ?? ''}`.trim();
|
|
175
|
+
// HAND-6: approved designs only in a design tool, exported before the screens built from them.
|
|
176
|
+
if (step.step === 'design' && step.handOver)
|
|
177
|
+
return ids.length
|
|
178
|
+
? `${step.why ?? `${ids.join(', ')} approved designs that are only in the design tool.`} Run /code-kit:design --hand-over ${ids.join(' ')}: the person confirms each is still the design they approved, and you export it.`
|
|
179
|
+
: null;
|
|
175
180
|
// ONB-2: the screens designed, and approved by the person, before they're built.
|
|
176
181
|
if (step.step === 'design')
|
|
177
182
|
return ids.length
|
|
@@ -192,7 +197,8 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
|
|
|
192
197
|
}
|
|
193
198
|
|
|
194
199
|
/** A step's identity: the loop never submits the same step twice while the project stands still. */
|
|
195
|
-
export const stepKey = (step) =>
|
|
200
|
+
export const stepKey = (step) =>
|
|
201
|
+
`${step.step}${step.handOver ? ' --hand-over' : ''}:${step.args ?? ''}`;
|
|
196
202
|
|
|
197
203
|
/** The band's words for a step (LOOP-5): "Dispatch ST-7, ST-9". */
|
|
198
204
|
export function stepLabel(step) {
|
|
@@ -210,7 +216,8 @@ export function stepLabel(step) {
|
|
|
210
216
|
design: 'Design',
|
|
211
217
|
setup: 'Set up',
|
|
212
218
|
update: 'Update the setup',
|
|
213
|
-
|
|
219
|
+
'hand-over': 'Hand over',
|
|
220
|
+
}[step.handOver ? 'hand-over' : step.step] ?? step.step;
|
|
214
221
|
return ids ? `${verb} ${ids}` : verb;
|
|
215
222
|
}
|
|
216
223
|
|