@warren-dean/code-kit 0.26.2 → 0.28.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 +24 -0
- package/README.md +8 -6
- package/bin/code-kit.mjs +269 -52
- package/hooks/act.mjs +14 -5
- package/hooks/guard-bash.mjs +82 -17
- package/hooks/lib/adapters/hub/client.mjs +22 -0
- package/hooks/lib/checkout.mjs +105 -0
- package/hooks/lib/checks.mjs +34 -8
- package/hooks/lib/config.mjs +16 -2
- package/hooks/lib/dependencies.mjs +4 -0
- package/hooks/lib/designs.mjs +138 -0
- package/hooks/lib/events.mjs +9 -4
- package/hooks/lib/hook.mjs +61 -2
- package/hooks/lib/next.mjs +26 -5
- package/hooks/lib/plan.mjs +55 -13
- package/hooks/lib/queue.mjs +86 -1
- package/hooks/lib/regression.mjs +54 -44
- package/hooks/lib/rules.mjs +63 -20
- package/hooks/lib/security.mjs +20 -0
- package/hooks/lib/sessions.mjs +49 -9
- package/hooks/lib/snapshot.mjs +227 -22
- package/hooks/lib/team.mjs +27 -1
- package/hooks/lib/verify.mjs +37 -4
- package/hooks/lib/worktrees.mjs +18 -1
- package/hooks/mod/board.mjs +10 -1
- package/hooks/mod/loop.mjs +44 -1
- package/hooks/mod/register.mjs +96 -8
- package/hooks/mod/view.mjs +8 -0
- package/hooks/post-edit-check.mjs +3 -1
- package/hooks/session.mjs +3 -1
- package/hooks/stop-check.mjs +6 -1
- package/package.json +1 -1
- package/skills/design/SKILL.md +36 -7
- package/skills/dispatch/SKILL.md +1 -0
- package/skills/init/SKILL.md +2 -0
- package/skills/review/SKILL.md +2 -1
- package/skills/spec-design/SKILL.md +1 -1
- package/skills/status/SKILL.md +1 -1
- package/templates/agent.md +2 -1
package/hooks/lib/rules.mjs
CHANGED
|
@@ -93,6 +93,18 @@ export function leadDecides(name, config, actor) {
|
|
|
93
93
|
return (rules.protected ?? []).includes(name);
|
|
94
94
|
}
|
|
95
95
|
|
|
96
|
+
/**
|
|
97
|
+
* WHO-1: whether the lead needs an approval in force to change a file protected by `name` itself. Where
|
|
98
|
+
* the person merges, they review the lead's change in the pull request, so it needs none. Where merges
|
|
99
|
+
* are delegated to the lead nobody else sees it, so what the person keeps (not delegated to the lead)
|
|
100
|
+
* needs the person's approval, as it would from a lane. The kit is the lead's to change either way: the
|
|
101
|
+
* person approved the setup, and code-kit writes most of it.
|
|
102
|
+
*/
|
|
103
|
+
export const leadNeedsApproval = (name, config) =>
|
|
104
|
+
name !== 'kit' &&
|
|
105
|
+
Boolean(config?.approvals?.delegate?.merge) &&
|
|
106
|
+
!leadDecides(name, config, { kind: 'lead' });
|
|
107
|
+
|
|
96
108
|
/** HELM-2: whose decision approvals `names` are: the lead's when it may grant every one, else the person's. */
|
|
97
109
|
export const decidedBy = (names, config, actor) =>
|
|
98
110
|
[names].flat().every((n) => leadDecides(n, config, actor)) ? 'lead' : 'person';
|
|
@@ -186,6 +198,25 @@ function noteGiven(root, entries) {
|
|
|
186
198
|
}
|
|
187
199
|
}
|
|
188
200
|
|
|
201
|
+
/**
|
|
202
|
+
* Why an approval for `name` given to `actor` lately isn't in force any more: used up by an earlier
|
|
203
|
+
* commit, or out of time. A sentence for a refusal, or '' when none was given lately.
|
|
204
|
+
*/
|
|
205
|
+
export function approvalEnded(root, name, actor, now = Date.now()) {
|
|
206
|
+
const lane = actor?.kind === 'lane' ? actor.lane : null;
|
|
207
|
+
const last = approvalsGiven(root)
|
|
208
|
+
.filter((e) => e.name === name && (!e.lane || e.lane === lane))
|
|
209
|
+
.at(-1);
|
|
210
|
+
if (!last?.at) return '';
|
|
211
|
+
const at = (t) => new Date(t).toTimeString().slice(0, 5);
|
|
212
|
+
const given = Date.parse(last.at);
|
|
213
|
+
if (now - given > 24 * 3600_000) return '';
|
|
214
|
+
if (last.usedAt)
|
|
215
|
+
return ` The ${name} approval given at ${at(given)} was used up at ${at(last.usedAt)} by an earlier commit${last.usedBy ? ` (${last.usedBy})` : ''}, so another is needed.`;
|
|
216
|
+
const ends = given + approvalMinutes(name) * 60_000;
|
|
217
|
+
return now >= ends ? ` The ${name} approval given at ${at(given)} ran out at ${at(ends)}.` : '';
|
|
218
|
+
}
|
|
219
|
+
|
|
189
220
|
/** The approvals given through code-kit (and those used up), oldest first. */
|
|
190
221
|
export function approvalsGiven(root) {
|
|
191
222
|
try {
|
|
@@ -353,6 +384,7 @@ export function useApproval(root, name, actor) {
|
|
|
353
384
|
...(file !== join(dir, name) ? { lane: actor.lane } : {}),
|
|
354
385
|
reason: a.reason,
|
|
355
386
|
usedAt: new Date().toISOString(),
|
|
387
|
+
...(actor?.label ? { usedBy: actor.label } : {}),
|
|
356
388
|
},
|
|
357
389
|
]);
|
|
358
390
|
return rmSync(file, { force: true });
|
|
@@ -438,6 +470,9 @@ export function recordRequest(root, actor, names, what, why, now = Date.now(), e
|
|
|
438
470
|
why: String(why).slice(0, 300),
|
|
439
471
|
...extra,
|
|
440
472
|
};
|
|
473
|
+
// The file's commits already made in the second it's asked, which don't answer it.
|
|
474
|
+
const before = commitsFrom(root, request.what, request.at);
|
|
475
|
+
if (before?.length) request.before = before;
|
|
441
476
|
if (openRequests(root, now).some((r) => sameRequest(r, request))) return;
|
|
442
477
|
const file = requestsFile(root);
|
|
443
478
|
mkdirSync(dirname(file), { recursive: true });
|
|
@@ -528,32 +563,38 @@ function installedSince(root, r) {
|
|
|
528
563
|
});
|
|
529
564
|
}
|
|
530
565
|
|
|
531
|
-
/**
|
|
532
|
-
function
|
|
533
|
-
|
|
534
|
-
if (/\s/.test(path) || (!path.includes('/') && !path.includes('.'))) return false;
|
|
566
|
+
/** The commits of `path`, on any branch, in or after the second `at` falls in; null when it isn't a path. */
|
|
567
|
+
function commitsFrom(root, path, at) {
|
|
568
|
+
if (/\s/.test(path) || (!path.includes('/') && !path.includes('.'))) return null;
|
|
535
569
|
try {
|
|
536
|
-
|
|
570
|
+
return execFileSync(
|
|
537
571
|
'git',
|
|
538
572
|
[
|
|
539
|
-
'-C',
|
|
540
|
-
|
|
541
|
-
'
|
|
542
|
-
'--all',
|
|
543
|
-
'-1',
|
|
544
|
-
'--format=%ct',
|
|
545
|
-
`--since=@${Math.floor(Date.parse(r.at) / 1000)}`,
|
|
546
|
-
'--',
|
|
547
|
-
path,
|
|
573
|
+
...['-C', root, 'log', '--all', '--format=%H'],
|
|
574
|
+
`--since=@${Math.floor(Date.parse(at) / 1000)}`,
|
|
575
|
+
...['--', path],
|
|
548
576
|
],
|
|
549
577
|
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
|
|
550
|
-
)
|
|
551
|
-
|
|
578
|
+
)
|
|
579
|
+
.split('\n')
|
|
580
|
+
.filter(Boolean);
|
|
552
581
|
} catch {
|
|
553
|
-
return
|
|
582
|
+
return [];
|
|
554
583
|
}
|
|
555
584
|
}
|
|
556
585
|
|
|
586
|
+
/**
|
|
587
|
+
* Whether the file a request named has been committed, on any branch, since it was asked. Git dates are
|
|
588
|
+
* whole seconds, so the commits already there in the second it was asked (the one before the refused
|
|
589
|
+
* commit) are the request's `before`, and don't answer it.
|
|
590
|
+
*/
|
|
591
|
+
function committedSince(root, r) {
|
|
592
|
+
const commits = commitsFrom(root, String(r.what), r.at);
|
|
593
|
+
if (!commits) return false;
|
|
594
|
+
const before = new Set(r.before ?? []);
|
|
595
|
+
return commits.some((c) => !before.has(c));
|
|
596
|
+
}
|
|
597
|
+
|
|
557
598
|
/**
|
|
558
599
|
* CARD-6: every approval given, newest first: { at, name, lane, reason, by, files, branches, used,
|
|
559
600
|
* expired }. From the approvals given through code-kit, the approvals on disk (a person's own `!` echo
|
|
@@ -766,9 +807,11 @@ export function writeProblem(actor, rel, root, config) {
|
|
|
766
807
|
const guarded = protectedEntry(rel, config);
|
|
767
808
|
if (actor.kind === 'readonly' && (guarded || !matchesAny(rel, config.anyActor)))
|
|
768
809
|
return readonlyProblem(actor, rel);
|
|
769
|
-
// The lead writes protected files without an approval
|
|
770
|
-
// and every committed change is in the audit log.
|
|
771
|
-
|
|
810
|
+
// The lead writes protected files without an approval where the person merges: they review them in
|
|
811
|
+
// the pull request, and every committed change is in the audit log. Where the lead merges, what the
|
|
812
|
+
// person keeps needs their approval (WHO-1). Anyone else needs an approval as well.
|
|
813
|
+
const leadFree = actor.kind === 'lead' && !leadNeedsApproval(guarded?.approval, config);
|
|
814
|
+
if (guarded && !leadFree && !approval(root, guarded.approval, actor)) {
|
|
772
815
|
recordRequest(root, actor, guarded.approval, rel, guarded.why);
|
|
773
816
|
const who =
|
|
774
817
|
decidedBy(guarded.approval, config, actor) === 'lead'
|
package/hooks/lib/security.mjs
CHANGED
|
@@ -142,6 +142,26 @@ export function securityReasons({ files = [], added = [], cites = [], security =
|
|
|
142
142
|
return reasons;
|
|
143
143
|
}
|
|
144
144
|
|
|
145
|
+
/** Every kind of reason a change gets the security review for: the sensitive kinds, then the rest. */
|
|
146
|
+
export const SECURITY_KINDS = [...SENSITIVE.map((s) => s.kind), 'dependencies', 'requirements'];
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The security review's rules for a project: whether it has the reviewer agent, the kinds of change
|
|
150
|
+
* that get the review, and the ids of its specs' security requirements, a story citing any of which
|
|
151
|
+
* gets it too. { reviewer, kinds, requirements }.
|
|
152
|
+
*/
|
|
153
|
+
export function securityRules(root, config) {
|
|
154
|
+
const specs = config.docs?.specs;
|
|
155
|
+
const texts = specs
|
|
156
|
+
? markdownFiles(root, specs).map((f) => readFileSync(join(root, f), 'utf8'))
|
|
157
|
+
: [];
|
|
158
|
+
return {
|
|
159
|
+
reviewer: existsSync(join(root, SECURITY_AGENT_FILE)),
|
|
160
|
+
kinds: SECURITY_KINDS,
|
|
161
|
+
requirements: [...securityRequirementIds(texts)],
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
145
165
|
/** The reasons as one sentence: "sign-in or sessions (src/auth/login.ts), dependencies (package.json)". */
|
|
146
166
|
export const reasonsInWords = (reasons) =>
|
|
147
167
|
reasons.map((r) => `${r.why} (${examples(r.where)})`).join('; ');
|
package/hooks/lib/sessions.mjs
CHANGED
|
@@ -11,6 +11,7 @@ import { join } from 'node:path';
|
|
|
11
11
|
import { matchesAny } from './glob.mjs';
|
|
12
12
|
import { CLI, projectWorktrees } from './rules.mjs';
|
|
13
13
|
import { shortSession } from './laneclaims.mjs';
|
|
14
|
+
import { isHandle } from './teamfacts.mjs';
|
|
14
15
|
|
|
15
16
|
export { shortSession };
|
|
16
17
|
export const SESSIONS_DIR = '.claude/state/sessions';
|
|
@@ -20,20 +21,37 @@ export const SESSION_LIVE_MS = 15 * 60_000;
|
|
|
20
21
|
const SEEN_EVERY_MS = 60_000;
|
|
21
22
|
/** The uncommitted files a session wrote, kept for SESS-5: at most this many. */
|
|
22
23
|
const WROTE_KEPT = 500;
|
|
24
|
+
/** The file a session edits is noted again at most this often, unless it's another file. */
|
|
25
|
+
const EDITING_EVERY_MS = 30_000;
|
|
26
|
+
/** The code-kit a session runs, as it starts: the plugin can be updated while other sessions run. */
|
|
27
|
+
const KIT_VERSION = (() => {
|
|
28
|
+
try {
|
|
29
|
+
return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
|
|
30
|
+
} catch {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
})();
|
|
23
34
|
|
|
24
35
|
const main = (root) => projectWorktrees(root)[0] ?? root;
|
|
25
36
|
const dirOf = (root) => join(main(root), SESSIONS_DIR);
|
|
26
37
|
const safe = (id) => String(id).replace(/[^\w.-]/g, '_');
|
|
27
38
|
const fileOf = (root, id) => join(dirOf(root), `${safe(id)}.json`);
|
|
28
39
|
|
|
29
|
-
/** The person at this machine
|
|
30
|
-
export function
|
|
40
|
+
/** The person at this machine by their GitHub login, when code-kit has it cached, or null. */
|
|
41
|
+
export function loginHere(root) {
|
|
31
42
|
try {
|
|
32
43
|
const cached = JSON.parse(readFileSync(join(main(root), '.claude/state/whoami.json'), 'utf8'));
|
|
33
|
-
if (cached?.login) return cached.login;
|
|
44
|
+
if (isHandle(cached?.login)) return cached.login;
|
|
34
45
|
} catch {
|
|
35
|
-
// not cached
|
|
46
|
+
// not cached
|
|
36
47
|
}
|
|
48
|
+
return null;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** The person at this machine: their GitHub login if code-kit has it cached, or the OS user. */
|
|
52
|
+
export function personHere(root) {
|
|
53
|
+
const login = loginHere(root);
|
|
54
|
+
if (login) return login;
|
|
37
55
|
try {
|
|
38
56
|
return userInfo().username || null;
|
|
39
57
|
} catch {
|
|
@@ -89,40 +107,62 @@ export const leadSession = (root, now = Date.now()) =>
|
|
|
89
107
|
/**
|
|
90
108
|
* SESS-2: a session starting (or resumed). It's the lead when no other live session is; otherwise a
|
|
91
109
|
* working session. A resumed session keeps the role it had, unless it was the lead and another session
|
|
92
|
-
* has led since.
|
|
110
|
+
* has led since. `model` is the model it runs on, when Claude Code says (SessionStart's `model`); the
|
|
111
|
+
* session also keeps its person's GitHub login, when code-kit knows it, and the code-kit it runs.
|
|
93
112
|
*/
|
|
94
|
-
export function startSession(root, id, now = Date.now()) {
|
|
113
|
+
export function startSession(root, id, now = Date.now(), { model = null } = {}) {
|
|
95
114
|
const at = new Date(now).toISOString();
|
|
96
115
|
const had = readSession(root, id);
|
|
97
116
|
const lead = leadSession(root, now);
|
|
98
117
|
return write(root, {
|
|
99
118
|
id,
|
|
100
119
|
person: had?.person ?? personHere(root),
|
|
120
|
+
login: loginHere(root) ?? had?.login ?? null,
|
|
101
121
|
role: lead && lead.id !== id ? 'working' : 'lead',
|
|
102
122
|
started: had?.started ?? at,
|
|
103
123
|
seen: at,
|
|
104
124
|
ended: null,
|
|
105
125
|
task: had?.task ?? null,
|
|
106
126
|
wrote: had?.wrote ?? [],
|
|
127
|
+
model: model ?? had?.model ?? null,
|
|
128
|
+
codeKit: KIT_VERSION,
|
|
129
|
+
editing: had?.editing ?? null,
|
|
107
130
|
});
|
|
108
131
|
}
|
|
109
132
|
|
|
110
|
-
/**
|
|
111
|
-
|
|
133
|
+
/**
|
|
134
|
+
* A hook saw the session act: it's still there. A session code-kit hadn't seen starts here. `facts()`
|
|
135
|
+
* gives what's read only when the record is written (the model it runs on now), at most once a minute.
|
|
136
|
+
*/
|
|
137
|
+
export function seeSession(root, id, now = Date.now(), facts = () => ({})) {
|
|
112
138
|
if (!id) return null;
|
|
113
139
|
const had = readSession(root, id);
|
|
114
|
-
if (!had || had.ended) return startSession(root, id, now);
|
|
140
|
+
if (!had || had.ended) return startSession(root, id, now, facts());
|
|
115
141
|
// A lead that went quiet past SESSION_LIVE_MS, while another session took the lead, works now.
|
|
116
142
|
const lead = had.role === 'lead' ? leadSession(root, now) : null;
|
|
117
143
|
const demoted = lead && lead.id !== id;
|
|
118
144
|
if (!demoted && now - Date.parse(had.seen) < SEEN_EVERY_MS) return had;
|
|
145
|
+
const { model } = facts();
|
|
119
146
|
return write(root, {
|
|
120
147
|
...had,
|
|
121
148
|
seen: new Date(now).toISOString(),
|
|
122
149
|
...(demoted ? { role: 'working' } : {}),
|
|
150
|
+
...(model ? { model } : {}),
|
|
123
151
|
});
|
|
124
152
|
}
|
|
125
153
|
|
|
154
|
+
/**
|
|
155
|
+
* The file the session last edited, in any of the project's checkouts: { path, at }, for the team
|
|
156
|
+
* provider's presence and the report. `rel` is relative to the checkout it's in.
|
|
157
|
+
*/
|
|
158
|
+
export function noteEditing(root, id, rel, now = Date.now()) {
|
|
159
|
+
if (!id || !rel) return;
|
|
160
|
+
const had = readSession(root, id) ?? startSession(root, id, now);
|
|
161
|
+
const was = had.editing;
|
|
162
|
+
if (was?.path === rel && now - Date.parse(was.at) < EDITING_EVERY_MS) return;
|
|
163
|
+
write(root, { ...had, editing: { path: rel, at: new Date(now).toISOString() } });
|
|
164
|
+
}
|
|
165
|
+
|
|
126
166
|
/** The session ended: it's no longer live, and leads nothing. Its task stays, stale, for SESS-4. */
|
|
127
167
|
export function endSession(root, id, now = Date.now()) {
|
|
128
168
|
const had = readSession(root, id);
|
package/hooks/lib/snapshot.mjs
CHANGED
|
@@ -9,9 +9,13 @@ import { execFileSync } from 'node:child_process';
|
|
|
9
9
|
import { dirname, join } from 'node:path';
|
|
10
10
|
import { APPROVAL_LOG } from './rules.mjs';
|
|
11
11
|
import { approverOf } from './journal.mjs';
|
|
12
|
-
import { readQueue } from './queue.mjs';
|
|
12
|
+
import { readQueue, waiting } from './queue.mjs';
|
|
13
13
|
import { sendBacks } from './reviews.mjs';
|
|
14
|
-
import { readMilestones, specCheckRows } from './plan.mjs';
|
|
14
|
+
import { readMilestones, readSpecs, specCheckRows } from './plan.mjs';
|
|
15
|
+
import { handedOver, entryProblems, readRegister, toolOf } from './designs.mjs';
|
|
16
|
+
import { SECURITY_KINDS, securityRules } from './security.mjs';
|
|
17
|
+
import { sessions } from './sessions.mjs';
|
|
18
|
+
import { storyOfBranch } from './teamfacts.mjs';
|
|
15
19
|
import { storyTimes } from './timeline.mjs';
|
|
16
20
|
import { trail } from './storymap.mjs';
|
|
17
21
|
import {
|
|
@@ -20,6 +24,7 @@ import {
|
|
|
20
24
|
LEVELS,
|
|
21
25
|
ORIGINS,
|
|
22
26
|
SOURCES,
|
|
27
|
+
laneLayers,
|
|
23
28
|
projectStandards,
|
|
24
29
|
sourceOf,
|
|
25
30
|
} from './standards.mjs';
|
|
@@ -28,9 +33,12 @@ import { slicesOf } from './schedule.mjs';
|
|
|
28
33
|
|
|
29
34
|
/**
|
|
30
35
|
* 2 adds the project's standards (code-kit spec 22); 3 the plan's slices (spec 23, SCHED-2); 4 each
|
|
31
|
-
* story's summary and each requirement's title
|
|
36
|
+
* story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
|
|
37
|
+
* each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
|
|
38
|
+
* 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.
|
|
32
40
|
*/
|
|
33
|
-
export const SNAPSHOT_VERSION =
|
|
41
|
+
export const SNAPSHOT_VERSION = 5;
|
|
34
42
|
|
|
35
43
|
/** A story's stage, as a report names it. */
|
|
36
44
|
export const STAGES = [
|
|
@@ -44,6 +52,10 @@ export const STAGES = [
|
|
|
44
52
|
'done',
|
|
45
53
|
];
|
|
46
54
|
export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
|
|
55
|
+
/** A spec-check report's status for a requirement, and for a story, its worst requirement's. */
|
|
56
|
+
export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
|
|
57
|
+
/** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
|
|
58
|
+
export const DESIGN_STATES = ['handed-over', 'in-tool', 'problems'];
|
|
47
59
|
|
|
48
60
|
/**
|
|
49
61
|
* The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
|
|
@@ -79,6 +91,10 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
79
91
|
claimedBy: 'handle?',
|
|
80
92
|
// Added in version 4.
|
|
81
93
|
summary: 'summary?',
|
|
94
|
+
// Added in version 5: the spec-check report's worst status on its branch (`none` with no report),
|
|
95
|
+
// and its place in the merge queue (1 merges next) while its branch waits there.
|
|
96
|
+
check: `enum:${[...CHECKS, 'none'].join('|')}?`,
|
|
97
|
+
queuePosition: 'count?',
|
|
82
98
|
},
|
|
83
99
|
],
|
|
84
100
|
sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
|
|
@@ -90,10 +106,24 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
90
106
|
stories: ['id'],
|
|
91
107
|
built: ['path'],
|
|
92
108
|
tested: ['path'],
|
|
93
|
-
check: '
|
|
109
|
+
check: `enum:${[...CHECKS, 'none'].join('|')}`,
|
|
110
|
+
},
|
|
111
|
+
],
|
|
112
|
+
// Version 5: each spec, by the id the project gives it, its title, its outcome line and its
|
|
113
|
+
// requirements' ids. Nothing else of its text.
|
|
114
|
+
specs: [{ id: 'name', file: 'path', title: 'title?', outcome: 'summary?', requirements: ['id'] }],
|
|
115
|
+
approvals: [
|
|
116
|
+
{
|
|
117
|
+
what: 'name',
|
|
118
|
+
path: 'path?',
|
|
119
|
+
who: 'enum:person|lead',
|
|
120
|
+
at: 'ms',
|
|
121
|
+
branch: 'name?',
|
|
122
|
+
// Added in version 5: the person's GitHub login, when code-kit knew it; the story of its branch.
|
|
123
|
+
approver: 'handle?',
|
|
124
|
+
story: 'id?',
|
|
94
125
|
},
|
|
95
126
|
],
|
|
96
|
-
approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
|
|
97
127
|
usage: [
|
|
98
128
|
{
|
|
99
129
|
story: 'id?',
|
|
@@ -104,11 +134,48 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
104
134
|
},
|
|
105
135
|
],
|
|
106
136
|
rules: {
|
|
107
|
-
|
|
137
|
+
// `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
|
|
138
|
+
layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
|
|
108
139
|
protected: [{ glob: 'path', approval: 'name' }],
|
|
109
140
|
delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
|
|
110
141
|
designGate: 'bool',
|
|
142
|
+
// Version 5: each lane, its deliverable kind, the layers its paths fall in, and what it owns.
|
|
143
|
+
lanes: [{ name: 'name', label: 'name', layers: ['name'], paths: ['path'], exclude: ['path'] }],
|
|
144
|
+
// Version 5: whether the project has the security reviewer, the kinds of change it reviews, and
|
|
145
|
+
// the security requirements a story citing gets it for.
|
|
146
|
+
security: {
|
|
147
|
+
reviewer: 'bool',
|
|
148
|
+
kinds: [`enum:${SECURITY_KINDS.join('|')}`],
|
|
149
|
+
requirements: ['id'],
|
|
150
|
+
},
|
|
111
151
|
},
|
|
152
|
+
// Version 5: the design register's entries, by screen, the code file, the design story, when it was
|
|
153
|
+
// approved, the tool it was drawn in, its state and its states' names.
|
|
154
|
+
designs: [
|
|
155
|
+
{
|
|
156
|
+
screen: 'name',
|
|
157
|
+
file: 'path',
|
|
158
|
+
story: 'id?',
|
|
159
|
+
approved: 'date?',
|
|
160
|
+
tool: 'name?',
|
|
161
|
+
state: `enum:${DESIGN_STATES.join('|')}`,
|
|
162
|
+
states: ['name'],
|
|
163
|
+
},
|
|
164
|
+
],
|
|
165
|
+
// Version 5: the sessions at work on this machine: the lead or a working one, its person's GitHub
|
|
166
|
+
// login, the code-kit and model it runs, when it started, and the file it last edited, and when.
|
|
167
|
+
sessions: [
|
|
168
|
+
{
|
|
169
|
+
id: 'name',
|
|
170
|
+
role: 'enum:lead|working',
|
|
171
|
+
person: 'handle?',
|
|
172
|
+
codeKit: 'name?',
|
|
173
|
+
model: 'name?',
|
|
174
|
+
started: 'ms',
|
|
175
|
+
editing: 'path?',
|
|
176
|
+
editedAt: 'ms?',
|
|
177
|
+
},
|
|
178
|
+
],
|
|
112
179
|
// Spec 22: each standard that applies, by id and title, how it's applied and where it came from;
|
|
113
180
|
// its why in one line at most, and its evidence only as counts.
|
|
114
181
|
standards: [
|
|
@@ -128,8 +195,19 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
128
195
|
],
|
|
129
196
|
};
|
|
130
197
|
|
|
131
|
-
/**
|
|
132
|
-
|
|
198
|
+
/**
|
|
199
|
+
* Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. Each
|
|
200
|
+
* is a dotted path into the allow-list, `[]` for a list's items; a leaf that may be missing ends in `?`.
|
|
201
|
+
*/
|
|
202
|
+
export const LATER_PARTS = [
|
|
203
|
+
'standards',
|
|
204
|
+
'slices',
|
|
205
|
+
'specs',
|
|
206
|
+
'designs',
|
|
207
|
+
'sessions',
|
|
208
|
+
'rules.lanes',
|
|
209
|
+
'rules.security',
|
|
210
|
+
];
|
|
133
211
|
|
|
134
212
|
export const SUMMARY_MAX = 600;
|
|
135
213
|
|
|
@@ -167,6 +245,8 @@ const KINDS = {
|
|
|
167
245
|
|
|
168
246
|
/** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
|
|
169
247
|
export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
|
|
248
|
+
const later = (k) =>
|
|
249
|
+
LATER_PARTS.includes(`${at}.${k}`.replace(/^snapshot\./, '').replace(/\[\d+\]/g, '[]'));
|
|
170
250
|
if (typeof shape === 'string') {
|
|
171
251
|
const optional = shape.endsWith('?');
|
|
172
252
|
const kind = optional ? shape.slice(0, -1) : shape;
|
|
@@ -185,7 +265,7 @@ export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot'
|
|
|
185
265
|
return [
|
|
186
266
|
...extra.map((k) => `${at}.${k}: not a field a report may hold`),
|
|
187
267
|
...Object.entries(shape)
|
|
188
|
-
.filter(([k]) => !(
|
|
268
|
+
.filter(([k]) => !(later(k) && !(k in value)))
|
|
189
269
|
.flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
|
|
190
270
|
];
|
|
191
271
|
}
|
|
@@ -206,11 +286,40 @@ export const EVENT_PARTS = [
|
|
|
206
286
|
'stories',
|
|
207
287
|
'sendBacks',
|
|
208
288
|
'requirements',
|
|
289
|
+
'specs',
|
|
209
290
|
'approvals',
|
|
210
291
|
'rules',
|
|
211
292
|
'standards',
|
|
293
|
+
'designs',
|
|
212
294
|
];
|
|
213
295
|
|
|
296
|
+
/** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
|
|
297
|
+
const KINDS_BY_NAME = [
|
|
298
|
+
[/^(schemas?|contracts?|api|types|openapi|graphql|protos?)$/, 'API contract'],
|
|
299
|
+
[/^(web|mobile|ui|app|apps|screens?|frontend|client|pages|views?)$/, 'Screens'],
|
|
300
|
+
[/^(data|db|database|migrations?|storage|sql)$/, 'Data'],
|
|
301
|
+
[/^(domain|core|services?|backend|server|workers?|functions|logic|ai|jobs)$/, 'Service'],
|
|
302
|
+
[/^(tests?|qa|e2e|quality)$/, 'Tests'],
|
|
303
|
+
[/^(design|designs|ux)$/, 'Design'],
|
|
304
|
+
[/^(infra|infrastructure|platform|ops|devops|deploy|ci)$/, 'Infrastructure'],
|
|
305
|
+
[/^(docs?|documentation|runbooks?)$/, 'Docs'],
|
|
306
|
+
];
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* A layer's or lane's deliverable kind: its `label`, or else what its name gives ("schemas" →
|
|
310
|
+
* "API contract", "web" → "Screens"), or else its name, capitalised, its hyphens as spaces.
|
|
311
|
+
*/
|
|
312
|
+
export function deliverableKind(name, label = null) {
|
|
313
|
+
if (typeof label === 'string' && label.trim()) return label.trim().slice(0, 120);
|
|
314
|
+
const n = String(name ?? '').toLowerCase();
|
|
315
|
+
const found = KINDS_BY_NAME.find(([re]) => re.test(n))?.[1];
|
|
316
|
+
if (found) return found;
|
|
317
|
+
const words = String(name ?? '')
|
|
318
|
+
.replace(/[-_]+/g, ' ')
|
|
319
|
+
.trim();
|
|
320
|
+
return (words.charAt(0).toUpperCase() + words.slice(1)).slice(0, 120) || 'Code';
|
|
321
|
+
}
|
|
322
|
+
|
|
214
323
|
const git = (root, ...args) => {
|
|
215
324
|
try {
|
|
216
325
|
return execFileSync('git', ['-C', root, ...args], {
|
|
@@ -277,8 +386,6 @@ function checkedRows(root, story) {
|
|
|
277
386
|
return [];
|
|
278
387
|
}
|
|
279
388
|
|
|
280
|
-
const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
|
|
281
|
-
|
|
282
389
|
/**
|
|
283
390
|
* The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
|
|
284
391
|
* branch stories merge into, `claims` the team's claims as last read, `version` code-kit's.
|
|
@@ -293,10 +400,14 @@ export function buildSnapshot({
|
|
|
293
400
|
now = Date.now(),
|
|
294
401
|
}) {
|
|
295
402
|
const times = new Map(storyTimes(root, status.stories, base).map((t) => [t.id, t]));
|
|
296
|
-
const
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
403
|
+
const inQueue = waiting(readQueue(root));
|
|
404
|
+
const queued = new Map(inQueue.map((e) => [e.branch, Date.parse(e.passed)]));
|
|
405
|
+
const place = new Map(inQueue.map((e, i) => [e.branch, i + 1]));
|
|
406
|
+
// Each story's spec-check report, on its branch: the requirements' statuses, and the story's worst.
|
|
407
|
+
const rowsOf = new Map(
|
|
408
|
+
status.stories
|
|
409
|
+
.filter((s) => s.branchExists)
|
|
410
|
+
.map((s) => [s.id, checkedRows(root, s).filter((r) => CHECKS.includes(r.status))]),
|
|
300
411
|
);
|
|
301
412
|
const backs = sendBacks(root);
|
|
302
413
|
const claimed = new Map(claims.map((c) => [c.story, c.by]));
|
|
@@ -332,6 +443,8 @@ export function buildSnapshot({
|
|
|
332
443
|
},
|
|
333
444
|
claimedBy: claimed.get(s.id) ?? null,
|
|
334
445
|
summary: reportedSummary(s.summary),
|
|
446
|
+
check: worstCheck(rowsOf.get(s.id) ?? []),
|
|
447
|
+
queuePosition: place.get(s.branch) ?? null,
|
|
335
448
|
};
|
|
336
449
|
});
|
|
337
450
|
|
|
@@ -352,10 +465,8 @@ export function buildSnapshot({
|
|
|
352
465
|
.map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
|
|
353
466
|
|
|
354
467
|
const checks = new Map();
|
|
355
|
-
for (const
|
|
356
|
-
|
|
357
|
-
for (const row of checkedRows(root, s))
|
|
358
|
-
if (CHECKS.includes(row.status)) checks.set(row.requirement, row.status);
|
|
468
|
+
for (const rows of rowsOf.values())
|
|
469
|
+
for (const row of rows) checks.set(row.requirement, row.status);
|
|
359
470
|
const requirements = trail(root, status, base).map((r) => ({
|
|
360
471
|
id: r.id,
|
|
361
472
|
title: line(r.title),
|
|
@@ -379,12 +490,16 @@ export function buildSnapshot({
|
|
|
379
490
|
const key = `${e.approval}|${e.file ?? ''}|${at}`;
|
|
380
491
|
if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
|
|
381
492
|
seen.add(key);
|
|
493
|
+
const who = approverOf(e);
|
|
494
|
+
const story = KINDS.name(e.branch) ? storyOfBranch(e.branch) : null;
|
|
382
495
|
approvals.push({
|
|
383
496
|
what: e.approval,
|
|
384
497
|
path: KINDS.path(e.file) ? e.file : null,
|
|
385
|
-
who
|
|
498
|
+
who,
|
|
386
499
|
at,
|
|
387
500
|
branch: KINDS.name(e.branch) ? e.branch : null,
|
|
501
|
+
approver: who === 'person' && KINDS.handle(e.approver) ? e.approver : null,
|
|
502
|
+
story: KINDS.id(story) ? story : null,
|
|
388
503
|
});
|
|
389
504
|
}
|
|
390
505
|
|
|
@@ -402,10 +517,15 @@ export function buildSnapshot({
|
|
|
402
517
|
stories,
|
|
403
518
|
sendBacks: sendBackList,
|
|
404
519
|
requirements,
|
|
520
|
+
specs: reportedSpecs(root, config, line),
|
|
405
521
|
approvals,
|
|
406
522
|
usage: recordedUsage(root),
|
|
407
523
|
rules: {
|
|
408
|
-
layers: (config.layers ?? []).map((l) => ({
|
|
524
|
+
layers: (config.layers ?? []).map((l) => ({
|
|
525
|
+
name: l.name,
|
|
526
|
+
mayImport: l.mayImport ?? [],
|
|
527
|
+
label: deliverableKind(l.name, l.label),
|
|
528
|
+
})),
|
|
409
529
|
protected: (config.protected ?? [])
|
|
410
530
|
.filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
|
|
411
531
|
.map((p) => ({ glob: p.glob, approval: p.approval })),
|
|
@@ -415,12 +535,97 @@ export function buildSnapshot({
|
|
|
415
535
|
merge: Boolean(delegate?.merge),
|
|
416
536
|
},
|
|
417
537
|
designGate: Boolean(config.designGate),
|
|
538
|
+
lanes: Object.entries(config.lanes ?? {}).map(([name, lane]) => ({
|
|
539
|
+
name,
|
|
540
|
+
label: deliverableKind(name, lane.label),
|
|
541
|
+
layers: laneLayers(lane, config),
|
|
542
|
+
paths: (lane.paths ?? []).filter((p) => KINDS.path(p)),
|
|
543
|
+
exclude: (lane.exclude ?? []).filter((p) => KINDS.path(p)),
|
|
544
|
+
})),
|
|
545
|
+
security: securityRules(root, config),
|
|
418
546
|
},
|
|
419
547
|
standards: reportedStandards(root, config, line),
|
|
548
|
+
designs: reportedDesigns(root, config),
|
|
549
|
+
sessions: reportedSessions(root, now),
|
|
420
550
|
};
|
|
421
551
|
return snapshot;
|
|
422
552
|
}
|
|
423
553
|
|
|
554
|
+
/** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
|
|
555
|
+
function worstCheck(rows) {
|
|
556
|
+
if (!rows.length) return 'none';
|
|
557
|
+
return [...CHECKS].reverse().find((c) => rows.some((r) => r.status === c));
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
/** Each spec as a report holds it: its id, file, title, outcome line and requirements' ids. */
|
|
561
|
+
function reportedSpecs(root, config, line) {
|
|
562
|
+
const { specs, plan } = config.docs ?? {};
|
|
563
|
+
if (!specs) return [];
|
|
564
|
+
return readSpecs(root, specs, plan)
|
|
565
|
+
.filter((sp) => KINDS.name(sp.id) && KINDS.path(sp.file))
|
|
566
|
+
.map((sp) => ({
|
|
567
|
+
id: sp.id,
|
|
568
|
+
file: sp.file,
|
|
569
|
+
title: line(sp.title),
|
|
570
|
+
outcome: reportedSummary(sp.outcome),
|
|
571
|
+
requirements: sp.requirements,
|
|
572
|
+
}));
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* The design register's entries (spec 24): handed over (its files there, as approved), only in a design
|
|
577
|
+
* tool, or with problems (a file missing or changed, a state the spec lists without a design).
|
|
578
|
+
*/
|
|
579
|
+
function reportedDesigns(root, config) {
|
|
580
|
+
const { entries } = readRegister(root, config);
|
|
581
|
+
const one = (v, max = 120) =>
|
|
582
|
+
typeof v === 'string' && v.trim() ? v.replace(/\s+/g, ' ').trim().slice(0, max) : null;
|
|
583
|
+
return entries
|
|
584
|
+
.filter((e) => e && KINDS.path(e.file))
|
|
585
|
+
.map((e) => {
|
|
586
|
+
const approved = String(e.approved ?? '').slice(0, 10);
|
|
587
|
+
return {
|
|
588
|
+
screen: one(e.screen) ?? e.file.slice(0, 120),
|
|
589
|
+
file: e.file,
|
|
590
|
+
story: KINDS.id(e.story) ? e.story : null,
|
|
591
|
+
approved: KINDS.date(approved) ? approved : null,
|
|
592
|
+
tool: one(toolOf(e, null)),
|
|
593
|
+
state: !handedOver(e)
|
|
594
|
+
? 'in-tool'
|
|
595
|
+
: entryProblems(root, e, config.docs?.specs).length
|
|
596
|
+
? 'problems'
|
|
597
|
+
: 'handed-over',
|
|
598
|
+
states: (handedOver(e) ? e.states : []).map((st) => one(st?.name)).filter(Boolean),
|
|
599
|
+
};
|
|
600
|
+
});
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* The sessions at work on this machine's checkout (SESS-1): what code-kit recorded as each started and
|
|
605
|
+
* acted. A session that has ended, or gone quiet past SESSION_LIVE_MS, isn't at work.
|
|
606
|
+
*/
|
|
607
|
+
function reportedSessions(root, now) {
|
|
608
|
+
const ms = (iso) => {
|
|
609
|
+
const t = Date.parse(iso ?? '');
|
|
610
|
+
return Number.isInteger(t) && t > 0 ? t : null;
|
|
611
|
+
};
|
|
612
|
+
return sessions(root, now)
|
|
613
|
+
.filter((s) => s.live && KINDS.name(s.id) && ms(s.started))
|
|
614
|
+
.map((s) => {
|
|
615
|
+
const editing = s.editing && KINDS.path(s.editing.path) ? s.editing : null;
|
|
616
|
+
return {
|
|
617
|
+
id: s.id,
|
|
618
|
+
role: s.role === 'lead' ? 'lead' : 'working',
|
|
619
|
+
person: KINDS.handle(s.login) ? s.login : null,
|
|
620
|
+
codeKit: KINDS.name(s.codeKit) ? s.codeKit : null,
|
|
621
|
+
model: KINDS.name(s.model) ? s.model : null,
|
|
622
|
+
started: ms(s.started),
|
|
623
|
+
editing: editing?.path ?? null,
|
|
624
|
+
editedAt: editing ? ms(editing.at) : null,
|
|
625
|
+
};
|
|
626
|
+
});
|
|
627
|
+
}
|
|
628
|
+
|
|
424
629
|
/**
|
|
425
630
|
* Spec 22: the standards that apply, as a report holds them. One that the file can't make sense of (an
|
|
426
631
|
* unknown category, no level) is left out: `code-kit standards` tells the project what's wrong with it.
|