@warren-dean/code-kit 0.27.0 → 0.29.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 +18 -0
- package/README.md +8 -7
- package/bin/code-kit.mjs +87 -13
- package/hooks/act.mjs +30 -2
- package/hooks/guard-bash.mjs +6 -0
- package/hooks/lib/adapters/hub/client.mjs +29 -1
- package/hooks/lib/config.mjs +11 -0
- package/hooks/lib/designs.mjs +6 -5
- package/hooks/lib/events.mjs +49 -0
- package/hooks/lib/hook.mjs +33 -14
- package/hooks/lib/next.mjs +32 -6
- package/hooks/lib/plan.mjs +29 -0
- package/hooks/lib/queue.mjs +16 -6
- package/hooks/lib/security.mjs +48 -0
- package/hooks/lib/sessions.mjs +49 -9
- package/hooks/lib/snapshot.mjs +347 -25
- package/hooks/lib/team.mjs +35 -13
- package/hooks/lib/teamfacts.mjs +80 -2
- package/hooks/mod/board.mjs +10 -1
- package/hooks/mod/register.mjs +4 -3
- package/hooks/mod/view.mjs +29 -10
- package/hooks/post-edit-check.mjs +3 -1
- package/hooks/session.mjs +3 -1
- package/package.json +1 -1
- package/skills/dispatch/SKILL.md +1 -1
- package/skills/init/SKILL.md +2 -0
- package/skills/review/SKILL.md +1 -1
package/hooks/lib/snapshot.mjs
CHANGED
|
@@ -9,9 +9,14 @@ 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, securityReview, securityRules } from './security.mjs';
|
|
17
|
+
import { securityReviews } from './events.mjs';
|
|
18
|
+
import { sessions } from './sessions.mjs';
|
|
19
|
+
import { isHandle, storyOfBranch } from './teamfacts.mjs';
|
|
15
20
|
import { storyTimes } from './timeline.mjs';
|
|
16
21
|
import { trail } from './storymap.mjs';
|
|
17
22
|
import {
|
|
@@ -20,6 +25,7 @@ import {
|
|
|
20
25
|
LEVELS,
|
|
21
26
|
ORIGINS,
|
|
22
27
|
SOURCES,
|
|
28
|
+
laneLayers,
|
|
23
29
|
projectStandards,
|
|
24
30
|
sourceOf,
|
|
25
31
|
} from './standards.mjs';
|
|
@@ -28,9 +34,14 @@ import { slicesOf } from './schedule.mjs';
|
|
|
28
34
|
|
|
29
35
|
/**
|
|
30
36
|
* 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
|
|
37
|
+
* story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
|
|
38
|
+
* each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
|
|
39
|
+
* approver and story, the security review's rules, each story's spec-check result and place in the
|
|
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.
|
|
32
43
|
*/
|
|
33
|
-
export const SNAPSHOT_VERSION =
|
|
44
|
+
export const SNAPSHOT_VERSION = 6;
|
|
34
45
|
|
|
35
46
|
/** A story's stage, as a report names it. */
|
|
36
47
|
export const STAGES = [
|
|
@@ -44,6 +55,12 @@ export const STAGES = [
|
|
|
44
55
|
'done',
|
|
45
56
|
];
|
|
46
57
|
export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
|
|
58
|
+
/** A spec-check report's status for a requirement, and for a story, its worst requirement's. */
|
|
59
|
+
export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
|
|
60
|
+
/** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
|
|
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'];
|
|
47
64
|
|
|
48
65
|
/**
|
|
49
66
|
* The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
|
|
@@ -79,6 +96,10 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
79
96
|
claimedBy: 'handle?',
|
|
80
97
|
// Added in version 4.
|
|
81
98
|
summary: 'summary?',
|
|
99
|
+
// Added in version 5: the spec-check report's worst status on its branch (`none` with no report),
|
|
100
|
+
// and its place in the merge queue (1 merges next) while its branch waits there.
|
|
101
|
+
check: `enum:${[...CHECKS, 'none'].join('|')}?`,
|
|
102
|
+
queuePosition: 'count?',
|
|
82
103
|
},
|
|
83
104
|
],
|
|
84
105
|
sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
|
|
@@ -90,25 +111,99 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
90
111
|
stories: ['id'],
|
|
91
112
|
built: ['path'],
|
|
92
113
|
tested: ['path'],
|
|
93
|
-
check: '
|
|
114
|
+
check: `enum:${[...CHECKS, 'none'].join('|')}`,
|
|
115
|
+
},
|
|
116
|
+
],
|
|
117
|
+
// Version 5: each spec, by the id the project gives it, its title, its outcome line and its
|
|
118
|
+
// requirements' ids. Nothing else of its text.
|
|
119
|
+
specs: [{ id: 'name', file: 'path', title: 'title?', outcome: 'summary?', requirements: ['id'] }],
|
|
120
|
+
approvals: [
|
|
121
|
+
{
|
|
122
|
+
what: 'name',
|
|
123
|
+
path: 'path?',
|
|
124
|
+
who: 'enum:person|lead',
|
|
125
|
+
at: 'ms',
|
|
126
|
+
branch: 'name?',
|
|
127
|
+
// Added in version 5: the person's GitHub login, when code-kit knew it; the story of its branch.
|
|
128
|
+
approver: 'handle?',
|
|
129
|
+
story: 'id?',
|
|
94
130
|
},
|
|
95
131
|
],
|
|
96
|
-
approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
|
|
97
132
|
usage: [
|
|
98
133
|
{
|
|
99
134
|
story: 'id?',
|
|
100
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?',
|
|
101
138
|
input: 'count',
|
|
102
139
|
output: 'count',
|
|
103
140
|
cache: 'count',
|
|
104
141
|
},
|
|
105
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'] }],
|
|
106
164
|
rules: {
|
|
107
|
-
|
|
165
|
+
// `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
|
|
166
|
+
layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
|
|
108
167
|
protected: [{ glob: 'path', approval: 'name' }],
|
|
109
168
|
delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
|
|
110
169
|
designGate: 'bool',
|
|
170
|
+
// Version 5: each lane, its deliverable kind, the layers its paths fall in, and what it owns.
|
|
171
|
+
lanes: [{ name: 'name', label: 'name', layers: ['name'], paths: ['path'], exclude: ['path'] }],
|
|
172
|
+
// Version 5: whether the project has the security reviewer, the kinds of change it reviews, and
|
|
173
|
+
// the security requirements a story citing gets it for.
|
|
174
|
+
security: {
|
|
175
|
+
reviewer: 'bool',
|
|
176
|
+
kinds: [`enum:${SECURITY_KINDS.join('|')}`],
|
|
177
|
+
requirements: ['id'],
|
|
178
|
+
},
|
|
111
179
|
},
|
|
180
|
+
// Version 5: the design register's entries, by screen, the code file, the design story, when it was
|
|
181
|
+
// approved, the tool it was drawn in, its state and its states' names.
|
|
182
|
+
designs: [
|
|
183
|
+
{
|
|
184
|
+
screen: 'name',
|
|
185
|
+
file: 'path',
|
|
186
|
+
story: 'id?',
|
|
187
|
+
approved: 'date?',
|
|
188
|
+
tool: 'name?',
|
|
189
|
+
state: `enum:${DESIGN_STATES.join('|')}`,
|
|
190
|
+
states: ['name'],
|
|
191
|
+
},
|
|
192
|
+
],
|
|
193
|
+
// Version 5: the sessions at work on this machine: the lead or a working one, its person's GitHub
|
|
194
|
+
// login, the code-kit and model it runs, when it started, and the file it last edited, and when.
|
|
195
|
+
sessions: [
|
|
196
|
+
{
|
|
197
|
+
id: 'name',
|
|
198
|
+
role: 'enum:lead|working',
|
|
199
|
+
person: 'handle?',
|
|
200
|
+
codeKit: 'name?',
|
|
201
|
+
model: 'name?',
|
|
202
|
+
started: 'ms',
|
|
203
|
+
editing: 'path?',
|
|
204
|
+
editedAt: 'ms?',
|
|
205
|
+
},
|
|
206
|
+
],
|
|
112
207
|
// Spec 22: each standard that applies, by id and title, how it's applied and where it came from;
|
|
113
208
|
// its why in one line at most, and its evidence only as counts.
|
|
114
209
|
standards: [
|
|
@@ -128,8 +223,22 @@ export const SNAPSHOT_SCHEMA = {
|
|
|
128
223
|
],
|
|
129
224
|
};
|
|
130
225
|
|
|
131
|
-
/**
|
|
132
|
-
|
|
226
|
+
/**
|
|
227
|
+
* Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. Each
|
|
228
|
+
* is a dotted path into the allow-list, `[]` for a list's items; a leaf that may be missing ends in `?`.
|
|
229
|
+
*/
|
|
230
|
+
export const LATER_PARTS = [
|
|
231
|
+
'standards',
|
|
232
|
+
'slices',
|
|
233
|
+
'specs',
|
|
234
|
+
'designs',
|
|
235
|
+
'sessions',
|
|
236
|
+
'rules.lanes',
|
|
237
|
+
'rules.security',
|
|
238
|
+
'securityReviews',
|
|
239
|
+
'intents',
|
|
240
|
+
'claims',
|
|
241
|
+
];
|
|
133
242
|
|
|
134
243
|
export const SUMMARY_MAX = 600;
|
|
135
244
|
|
|
@@ -167,6 +276,8 @@ const KINDS = {
|
|
|
167
276
|
|
|
168
277
|
/** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
|
|
169
278
|
export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
|
|
279
|
+
const later = (k) =>
|
|
280
|
+
LATER_PARTS.includes(`${at}.${k}`.replace(/^snapshot\./, '').replace(/\[\d+\]/g, '[]'));
|
|
170
281
|
if (typeof shape === 'string') {
|
|
171
282
|
const optional = shape.endsWith('?');
|
|
172
283
|
const kind = optional ? shape.slice(0, -1) : shape;
|
|
@@ -185,7 +296,7 @@ export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot'
|
|
|
185
296
|
return [
|
|
186
297
|
...extra.map((k) => `${at}.${k}: not a field a report may hold`),
|
|
187
298
|
...Object.entries(shape)
|
|
188
|
-
.filter(([k]) => !(
|
|
299
|
+
.filter(([k]) => !(later(k) && !(k in value)))
|
|
189
300
|
.flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
|
|
190
301
|
];
|
|
191
302
|
}
|
|
@@ -206,11 +317,42 @@ export const EVENT_PARTS = [
|
|
|
206
317
|
'stories',
|
|
207
318
|
'sendBacks',
|
|
208
319
|
'requirements',
|
|
320
|
+
'specs',
|
|
209
321
|
'approvals',
|
|
210
322
|
'rules',
|
|
211
323
|
'standards',
|
|
324
|
+
'designs',
|
|
325
|
+
'securityReviews',
|
|
326
|
+
'intents',
|
|
327
|
+
];
|
|
328
|
+
|
|
329
|
+
/** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
|
|
330
|
+
const KINDS_BY_NAME = [
|
|
331
|
+
[/^(schemas?|contracts?|api|types|openapi|graphql|protos?)$/, 'API contract'],
|
|
332
|
+
[/^(web|mobile|ui|app|apps|screens?|frontend|client|pages|views?)$/, 'Screens'],
|
|
333
|
+
[/^(data|db|database|migrations?|storage|sql)$/, 'Data'],
|
|
334
|
+
[/^(domain|core|services?|backend|server|workers?|functions|logic|ai|jobs)$/, 'Service'],
|
|
335
|
+
[/^(tests?|qa|e2e|quality)$/, 'Tests'],
|
|
336
|
+
[/^(design|designs|ux)$/, 'Design'],
|
|
337
|
+
[/^(infra|infrastructure|platform|ops|devops|deploy|ci)$/, 'Infrastructure'],
|
|
338
|
+
[/^(docs?|documentation|runbooks?)$/, 'Docs'],
|
|
212
339
|
];
|
|
213
340
|
|
|
341
|
+
/**
|
|
342
|
+
* A layer's or lane's deliverable kind: its `label`, or else what its name gives ("schemas" →
|
|
343
|
+
* "API contract", "web" → "Screens"), or else its name, capitalised, its hyphens as spaces.
|
|
344
|
+
*/
|
|
345
|
+
export function deliverableKind(name, label = null) {
|
|
346
|
+
if (typeof label === 'string' && label.trim()) return label.trim().slice(0, 120);
|
|
347
|
+
const n = String(name ?? '').toLowerCase();
|
|
348
|
+
const found = KINDS_BY_NAME.find(([re]) => re.test(n))?.[1];
|
|
349
|
+
if (found) return found;
|
|
350
|
+
const words = String(name ?? '')
|
|
351
|
+
.replace(/[-_]+/g, ' ')
|
|
352
|
+
.trim();
|
|
353
|
+
return (words.charAt(0).toUpperCase() + words.slice(1)).slice(0, 120) || 'Code';
|
|
354
|
+
}
|
|
355
|
+
|
|
214
356
|
const git = (root, ...args) => {
|
|
215
357
|
try {
|
|
216
358
|
return execFileSync('git', ['-C', root, ...args], {
|
|
@@ -257,8 +399,9 @@ export function recordedUsage(root) {
|
|
|
257
399
|
for (const e of entries) {
|
|
258
400
|
if (!AGENT_KINDS.includes(e.kind)) continue;
|
|
259
401
|
const story = KINDS.id(e.story) ? e.story : null;
|
|
260
|
-
const
|
|
261
|
-
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 };
|
|
262
405
|
for (const k of ['input', 'output', 'cache'])
|
|
263
406
|
was[k] += Number.isInteger(e[k]) && e[k] > 0 ? e[k] : 0;
|
|
264
407
|
sums.set(key, was);
|
|
@@ -277,11 +420,10 @@ function checkedRows(root, story) {
|
|
|
277
420
|
return [];
|
|
278
421
|
}
|
|
279
422
|
|
|
280
|
-
const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
|
|
281
|
-
|
|
282
423
|
/**
|
|
283
424
|
* The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
|
|
284
|
-
* 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.
|
|
285
427
|
*/
|
|
286
428
|
export function buildSnapshot({
|
|
287
429
|
root,
|
|
@@ -289,14 +431,19 @@ export function buildSnapshot({
|
|
|
289
431
|
status,
|
|
290
432
|
base,
|
|
291
433
|
claims = [],
|
|
434
|
+
pulls = [],
|
|
292
435
|
version,
|
|
293
436
|
now = Date.now(),
|
|
294
437
|
}) {
|
|
295
438
|
const times = new Map(storyTimes(root, status.stories, base).map((t) => [t.id, t]));
|
|
296
|
-
const
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
439
|
+
const inQueue = waiting(readQueue(root));
|
|
440
|
+
const queued = new Map(inQueue.map((e) => [e.branch, Date.parse(e.passed)]));
|
|
441
|
+
const place = new Map(inQueue.map((e, i) => [e.branch, i + 1]));
|
|
442
|
+
// Each story's spec-check report, on its branch: the requirements' statuses, and the story's worst.
|
|
443
|
+
const rowsOf = new Map(
|
|
444
|
+
status.stories
|
|
445
|
+
.filter((s) => s.branchExists)
|
|
446
|
+
.map((s) => [s.id, checkedRows(root, s).filter((r) => CHECKS.includes(r.status))]),
|
|
300
447
|
);
|
|
301
448
|
const backs = sendBacks(root);
|
|
302
449
|
const claimed = new Map(claims.map((c) => [c.story, c.by]));
|
|
@@ -332,6 +479,8 @@ export function buildSnapshot({
|
|
|
332
479
|
},
|
|
333
480
|
claimedBy: claimed.get(s.id) ?? null,
|
|
334
481
|
summary: reportedSummary(s.summary),
|
|
482
|
+
check: worstCheck(rowsOf.get(s.id) ?? []),
|
|
483
|
+
queuePosition: place.get(s.branch) ?? null,
|
|
335
484
|
};
|
|
336
485
|
});
|
|
337
486
|
|
|
@@ -352,10 +501,8 @@ export function buildSnapshot({
|
|
|
352
501
|
.map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
|
|
353
502
|
|
|
354
503
|
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);
|
|
504
|
+
for (const rows of rowsOf.values())
|
|
505
|
+
for (const row of rows) checks.set(row.requirement, row.status);
|
|
359
506
|
const requirements = trail(root, status, base).map((r) => ({
|
|
360
507
|
id: r.id,
|
|
361
508
|
title: line(r.title),
|
|
@@ -379,12 +526,16 @@ export function buildSnapshot({
|
|
|
379
526
|
const key = `${e.approval}|${e.file ?? ''}|${at}`;
|
|
380
527
|
if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
|
|
381
528
|
seen.add(key);
|
|
529
|
+
const who = approverOf(e);
|
|
530
|
+
const story = KINDS.name(e.branch) ? storyOfBranch(e.branch) : null;
|
|
382
531
|
approvals.push({
|
|
383
532
|
what: e.approval,
|
|
384
533
|
path: KINDS.path(e.file) ? e.file : null,
|
|
385
|
-
who
|
|
534
|
+
who,
|
|
386
535
|
at,
|
|
387
536
|
branch: KINDS.name(e.branch) ? e.branch : null,
|
|
537
|
+
approver: who === 'person' && KINDS.handle(e.approver) ? e.approver : null,
|
|
538
|
+
story: KINDS.id(story) ? story : null,
|
|
388
539
|
});
|
|
389
540
|
}
|
|
390
541
|
|
|
@@ -402,10 +553,15 @@ export function buildSnapshot({
|
|
|
402
553
|
stories,
|
|
403
554
|
sendBacks: sendBackList,
|
|
404
555
|
requirements,
|
|
556
|
+
specs: reportedSpecs(root, config, line),
|
|
405
557
|
approvals,
|
|
406
558
|
usage: recordedUsage(root),
|
|
407
559
|
rules: {
|
|
408
|
-
layers: (config.layers ?? []).map((l) => ({
|
|
560
|
+
layers: (config.layers ?? []).map((l) => ({
|
|
561
|
+
name: l.name,
|
|
562
|
+
mayImport: l.mayImport ?? [],
|
|
563
|
+
label: deliverableKind(l.name, l.label),
|
|
564
|
+
})),
|
|
409
565
|
protected: (config.protected ?? [])
|
|
410
566
|
.filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
|
|
411
567
|
.map((p) => ({ glob: p.glob, approval: p.approval })),
|
|
@@ -415,12 +571,178 @@ export function buildSnapshot({
|
|
|
415
571
|
merge: Boolean(delegate?.merge),
|
|
416
572
|
},
|
|
417
573
|
designGate: Boolean(config.designGate),
|
|
574
|
+
lanes: Object.entries(config.lanes ?? {}).map(([name, lane]) => ({
|
|
575
|
+
name,
|
|
576
|
+
label: deliverableKind(name, lane.label),
|
|
577
|
+
layers: laneLayers(lane, config),
|
|
578
|
+
paths: (lane.paths ?? []).filter((p) => KINDS.path(p)),
|
|
579
|
+
exclude: (lane.exclude ?? []).filter((p) => KINDS.path(p)),
|
|
580
|
+
})),
|
|
581
|
+
security: securityRules(root, config),
|
|
418
582
|
},
|
|
419
583
|
standards: reportedStandards(root, config, line),
|
|
584
|
+
designs: reportedDesigns(root, config),
|
|
585
|
+
sessions: reportedSessions(root, now),
|
|
586
|
+
securityReviews: reportedSecurityReviews(root, config, status, base),
|
|
587
|
+
intents: reportedIntents(claims, pulls),
|
|
588
|
+
claims: reportedClaims(claims),
|
|
420
589
|
};
|
|
421
590
|
return snapshot;
|
|
422
591
|
}
|
|
423
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
|
+
|
|
671
|
+
/** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
|
|
672
|
+
function worstCheck(rows) {
|
|
673
|
+
if (!rows.length) return 'none';
|
|
674
|
+
return [...CHECKS].reverse().find((c) => rows.some((r) => r.status === c));
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
/** Each spec as a report holds it: its id, file, title, outcome line and requirements' ids. */
|
|
678
|
+
function reportedSpecs(root, config, line) {
|
|
679
|
+
const { specs, plan } = config.docs ?? {};
|
|
680
|
+
if (!specs) return [];
|
|
681
|
+
return readSpecs(root, specs, plan)
|
|
682
|
+
.filter((sp) => KINDS.name(sp.id) && KINDS.path(sp.file))
|
|
683
|
+
.map((sp) => ({
|
|
684
|
+
id: sp.id,
|
|
685
|
+
file: sp.file,
|
|
686
|
+
title: line(sp.title),
|
|
687
|
+
outcome: reportedSummary(sp.outcome),
|
|
688
|
+
requirements: sp.requirements,
|
|
689
|
+
}));
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
/**
|
|
693
|
+
* The design register's entries (spec 24): handed over (its files there, as approved), only in a design
|
|
694
|
+
* tool, or with problems (a file missing or changed, a state the spec lists without a design).
|
|
695
|
+
*/
|
|
696
|
+
function reportedDesigns(root, config) {
|
|
697
|
+
const { entries } = readRegister(root, config);
|
|
698
|
+
const one = (v, max = 120) =>
|
|
699
|
+
typeof v === 'string' && v.trim() ? v.replace(/\s+/g, ' ').trim().slice(0, max) : null;
|
|
700
|
+
return entries
|
|
701
|
+
.filter((e) => e && KINDS.path(e.file))
|
|
702
|
+
.map((e) => {
|
|
703
|
+
const approved = String(e.approved ?? '').slice(0, 10);
|
|
704
|
+
return {
|
|
705
|
+
screen: one(e.screen) ?? e.file.slice(0, 120),
|
|
706
|
+
file: e.file,
|
|
707
|
+
story: KINDS.id(e.story) ? e.story : null,
|
|
708
|
+
approved: KINDS.date(approved) ? approved : null,
|
|
709
|
+
tool: one(toolOf(e, null)),
|
|
710
|
+
state: !handedOver(e)
|
|
711
|
+
? 'in-tool'
|
|
712
|
+
: entryProblems(root, e, config.docs?.specs).length
|
|
713
|
+
? 'problems'
|
|
714
|
+
: 'handed-over',
|
|
715
|
+
states: (handedOver(e) ? e.states : []).map((st) => one(st?.name)).filter(Boolean),
|
|
716
|
+
};
|
|
717
|
+
});
|
|
718
|
+
}
|
|
719
|
+
|
|
720
|
+
/**
|
|
721
|
+
* The sessions at work on this machine's checkout (SESS-1): what code-kit recorded as each started and
|
|
722
|
+
* acted. A session that has ended, or gone quiet past SESSION_LIVE_MS, isn't at work.
|
|
723
|
+
*/
|
|
724
|
+
function reportedSessions(root, now) {
|
|
725
|
+
const ms = (iso) => {
|
|
726
|
+
const t = Date.parse(iso ?? '');
|
|
727
|
+
return Number.isInteger(t) && t > 0 ? t : null;
|
|
728
|
+
};
|
|
729
|
+
return sessions(root, now)
|
|
730
|
+
.filter((s) => s.live && KINDS.name(s.id) && ms(s.started))
|
|
731
|
+
.map((s) => {
|
|
732
|
+
const editing = s.editing && KINDS.path(s.editing.path) ? s.editing : null;
|
|
733
|
+
return {
|
|
734
|
+
id: s.id,
|
|
735
|
+
role: s.role === 'lead' ? 'lead' : 'working',
|
|
736
|
+
person: KINDS.handle(s.login) ? s.login : null,
|
|
737
|
+
codeKit: KINDS.name(s.codeKit) ? s.codeKit : null,
|
|
738
|
+
model: KINDS.name(s.model) ? s.model : null,
|
|
739
|
+
started: ms(s.started),
|
|
740
|
+
editing: editing?.path ?? null,
|
|
741
|
+
editedAt: editing ? ms(editing.at) : null,
|
|
742
|
+
};
|
|
743
|
+
});
|
|
744
|
+
}
|
|
745
|
+
|
|
424
746
|
/**
|
|
425
747
|
* Spec 22: the standards that apply, as a report holds them. One that the file can't make sense of (an
|
|
426
748
|
* unknown category, no level) is left out: `code-kit standards` tells the project what's wrong with it.
|
package/hooks/lib/team.mjs
CHANGED
|
@@ -33,6 +33,8 @@ export {
|
|
|
33
33
|
};
|
|
34
34
|
|
|
35
35
|
const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
36
|
+
/** An intent's number, as the provider keeps it. */
|
|
37
|
+
export const isIntentId = (n) => Number.isInteger(n) && n > 0;
|
|
36
38
|
|
|
37
39
|
/** What's wrong with `team` and the lanes' `owners`, as the config's other problems are worded. */
|
|
38
40
|
export function teamProblems(c) {
|
|
@@ -154,9 +156,11 @@ export function whoami(root, now = Date.now()) {
|
|
|
154
156
|
|
|
155
157
|
// --- the provider (TEAM-2) ----------------------------------------------------------------------------
|
|
156
158
|
//
|
|
157
|
-
// The core talks to the team through one interface: whoami, claim(story, lease), release(story),
|
|
159
|
+
// The core talks to the team through one interface: whoami, claim(story, lease, intent), release(story),
|
|
158
160
|
// state() and intend(about, touches), report(snapshot) (HUBR-1) and standards() (STD-6: an
|
|
159
|
-
// organisation's standards and this project's waivers, `{ standards, waivers, version }`).
|
|
161
|
+
// organisation's standards and this project's waivers, `{ standards, waivers, version }`). A provider
|
|
162
|
+
// that checks drift says in its state what holds a merge (`mergeHolds`) and lists its open `findings`
|
|
163
|
+
// (HUBR-9); GitHub's checks none, so it holds nothing. The GitHub
|
|
160
164
|
// provider is built in; any other is a command named in the config, called with the operation's name
|
|
161
165
|
// and its input as JSON on stdin, answering JSON.
|
|
162
166
|
|
|
@@ -173,7 +177,14 @@ function claimOf(message) {
|
|
|
173
177
|
try {
|
|
174
178
|
const c = JSON.parse(message);
|
|
175
179
|
return isStoryId(c.story) && isHandle(c.by)
|
|
176
|
-
? {
|
|
180
|
+
? {
|
|
181
|
+
story: c.story,
|
|
182
|
+
by: c.by,
|
|
183
|
+
at: c.at,
|
|
184
|
+
lease: Array.isArray(c.lease) ? c.lease : [],
|
|
185
|
+
// HUBR-2: the intent the story carries out, when its claim names one.
|
|
186
|
+
...(isIntentId(c.intent) ? { intent: c.intent } : {}),
|
|
187
|
+
}
|
|
177
188
|
: null;
|
|
178
189
|
} catch {
|
|
179
190
|
return null;
|
|
@@ -197,10 +208,12 @@ export function teamProvider(root, team) {
|
|
|
197
208
|
const r = command[op](...args);
|
|
198
209
|
if (!down(r) && r !== null) return r;
|
|
199
210
|
const g = github[op](...args);
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
211
|
+
if (op !== 'state' || !g) return g;
|
|
212
|
+
// The state says it came through GitHub, and why, for the band; kept so, so the hooks, `next` and
|
|
213
|
+
// the queue reading it later know the provider didn't answer (HUBR-9: no drift was checked).
|
|
214
|
+
const fell = { ...g, fallback: r?.why ?? "The team provider can't be reached." };
|
|
215
|
+
writeCache(root, fell);
|
|
216
|
+
return fell;
|
|
204
217
|
};
|
|
205
218
|
// A claim taken while the provider was down lives only on GitHub; one the provider doesn't know is
|
|
206
219
|
// released there too, so it can't outlive its story (a merged story's claim, stuck and going stale).
|
|
@@ -403,7 +416,8 @@ function githubProvider(root, team) {
|
|
|
403
416
|
|
|
404
417
|
const provider = {
|
|
405
418
|
whoami: () => ({ login: me() }),
|
|
406
|
-
|
|
419
|
+
/** `intent`: the intent the story carries out (HUBR-2); a claim again keeps the one it has. */
|
|
420
|
+
claim(story, lease = [], intent = null) {
|
|
407
421
|
if (!isStoryId(story)) return { ok: false, why: `"${story}" isn't a story id.` };
|
|
408
422
|
const by = me();
|
|
409
423
|
if (!by) return { ok: false, why: 'Sign in to GitHub first (gh auth login).' };
|
|
@@ -423,8 +437,9 @@ function githubProvider(root, team) {
|
|
|
423
437
|
const tree = git(['mktree'], { input: '' }).stdout.trim();
|
|
424
438
|
// A lease only grows while the story is open: a claim again adds to it.
|
|
425
439
|
lease = [...new Set([...(held?.lease ?? []), ...lease])];
|
|
426
|
-
const
|
|
427
|
-
const
|
|
440
|
+
const named = isIntentId(intent) ? intent : (held?.intent ?? null);
|
|
441
|
+
const claim = { story, by, at, lease, ...(named ? { intent: named } : {}) };
|
|
442
|
+
const sha = git(['commit-tree', tree, '-m', JSON.stringify(claim)], { env }).stdout.trim();
|
|
428
443
|
const pushed = pushClaim(story, sha, held?.sha ?? '');
|
|
429
444
|
if (!ok(pushed)) {
|
|
430
445
|
// Someone claimed it between our fetch and push: say who.
|
|
@@ -433,7 +448,7 @@ function githubProvider(root, team) {
|
|
|
433
448
|
return holder && holder.by !== by ? { ok: false, holder } : notReached();
|
|
434
449
|
}
|
|
435
450
|
provider.forget();
|
|
436
|
-
return { ok: true, claim
|
|
451
|
+
return { ok: true, claim };
|
|
437
452
|
},
|
|
438
453
|
/** `merged`: the story merged, so its claim ends whoever releases it. */
|
|
439
454
|
release(story, { merged = false } = {}) {
|
|
@@ -575,7 +590,13 @@ function githubProvider(root, team) {
|
|
|
575
590
|
GIT_COMMITTER_EMAIL: email,
|
|
576
591
|
};
|
|
577
592
|
const tree = git(['mktree'], { input: '' }).stdout.trim();
|
|
578
|
-
const message = JSON.stringify({
|
|
593
|
+
const message = JSON.stringify({
|
|
594
|
+
story,
|
|
595
|
+
by: to,
|
|
596
|
+
at,
|
|
597
|
+
lease: held.lease,
|
|
598
|
+
...(held.intent ? { intent: held.intent } : {}),
|
|
599
|
+
});
|
|
579
600
|
const sha = git(['commit-tree', tree, '-m', message], { env }).stdout.trim();
|
|
580
601
|
if (!ok(pushClaim(story, sha, held.sha))) return notReached();
|
|
581
602
|
provider.forget();
|
|
@@ -770,7 +791,8 @@ function commandProvider(root, team, command) {
|
|
|
770
791
|
};
|
|
771
792
|
return {
|
|
772
793
|
whoami: () => call('whoami'),
|
|
773
|
-
claim: (story, lease = []
|
|
794
|
+
claim: (story, lease = [], intent = null) =>
|
|
795
|
+
call('claim', { story, lease, ...(isIntentId(intent) ? { intent } : {}) }),
|
|
774
796
|
release: (story, { merged = false } = {}) => call('release', { story, merged }),
|
|
775
797
|
state: ({ fresh = false } = {}) => {
|
|
776
798
|
const s = call('state', { fresh });
|