@skitterbyte/skitterspec-linear 19.5.0 → 19.6.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/assets/rules/spec-planning.md +45 -7
- package/assets/skills/spec/SKILL.md +37 -6
- package/assets/skills/spec-complete/SKILL.md +29 -0
- package/assets/skills/spec-list/SKILL.md +3 -1
- package/assets/skills/spec-next/SKILL.md +35 -2
- package/assets/skills/spec-push/SKILL.md +8 -0
- package/assets/skills/spec-start/SKILL.md +32 -1
- package/assets/skills/spec-to-main/SKILL.md +10 -0
- package/package.json +1 -1
- package/src/cli.js +312 -16
- package/src/env/epic.js +541 -0
- package/src/env/inflight.js +11 -3
- package/src/env/resolve.js +18 -7
- package/src/env/specstate.js +7 -2
- package/src/env/trust.js +6 -2
- package/src/vendor/linear/api.js +20 -0
- package/src/vendor/linear/cli-sync.js +45 -4
- package/src/vendor/linear/config.js +1 -1
- package/src/vendor/provider-kit/src/apply.js +24 -0
- package/src/vendor/provider-kit/src/epic-rows.js +44 -0
- package/src/vendor/sync-core/index.js +3 -1
- package/src/vendor/sync-core/src/normalize.js +91 -9
package/src/env/epic.js
ADDED
|
@@ -0,0 +1,541 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `skitterspec epic status <epic>` — what an epic's members say about its order.
|
|
5
|
+
*
|
|
6
|
+
* An epic declares neither its members nor their order (spec feat-epics,
|
|
7
|
+
* Decision 2): each member carries `> **Epic:**` and `> **Waits on:**`, and
|
|
8
|
+
* this turns those headers into what can start now, what is blocked and on
|
|
9
|
+
* what, and the waves the members fall into.
|
|
10
|
+
*
|
|
11
|
+
* WAITS ARE MET ONLY ON A POSITIVE SIGNAL, read off the BASE BRANCH
|
|
12
|
+
* (`.claude/rules/negative-checks.md` rule 1): the named spec sitting in
|
|
13
|
+
* `complete/` there, or its phase file reading done there. Everything else is
|
|
14
|
+
* one of two different answers, and they are never merged:
|
|
15
|
+
*
|
|
16
|
+
* - unmet — the spec is on the base branch and has not got there yet
|
|
17
|
+
* - cannot tell — the spec is not on the base branch at all, the phase file
|
|
18
|
+
* is not there, or the entry did not parse
|
|
19
|
+
*
|
|
20
|
+
* WHAT WOULD FOOL THIS: a spec on its own unlanded branch is invisible on the
|
|
21
|
+
* base branch, so a wait on it can only ever read cannot-tell — never met, and
|
|
22
|
+
* never blocked-forever. Buckets are branch-local truth; the base branch is the
|
|
23
|
+
* one place every session agrees on, which is why waits are read there and
|
|
24
|
+
* nowhere else.
|
|
25
|
+
*
|
|
26
|
+
* Pure but for the injected reads, so it is testable without a repository.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
const { phaseIsDone } = require('./resolve.js')
|
|
30
|
+
|
|
31
|
+
const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
|
|
32
|
+
|
|
33
|
+
// A header value off an overview's blockquote block, or null when absent.
|
|
34
|
+
function header(text, name) {
|
|
35
|
+
const m = new RegExp(`^>\\s*\\*\\*${name}:\\*\\*[ \\t]*(.*)$`, 'm').exec(text || '')
|
|
36
|
+
if (!m) return null
|
|
37
|
+
const value = m[1].trim()
|
|
38
|
+
return value && value !== '—' && value !== '-' ? value : null
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const unquote = (value) => (value == null ? value : value.replace(/^`(.*)`$/, '$1').trim())
|
|
42
|
+
|
|
43
|
+
// `<spec>[ phase N], …` → `[{ spec, phase, raw }]`. The twin of sync-core's
|
|
44
|
+
// `parseWaitsOn` — the base depends on no provider package, so it keeps its
|
|
45
|
+
// own copy, and `env-epic-status.test.js` holds the two to one answer.
|
|
46
|
+
//
|
|
47
|
+
// A MALFORMED ENTRY IS KEPT as `{ spec: null }`, never dropped: dropped, a wait
|
|
48
|
+
// nobody can read would look like no wait, and the member would read as ready.
|
|
49
|
+
function parseWaitsOn(value) {
|
|
50
|
+
if (!value) return []
|
|
51
|
+
const trimmed = value.trim()
|
|
52
|
+
if (/^(none|—|-)$/i.test(trimmed)) return []
|
|
53
|
+
return trimmed
|
|
54
|
+
.split(',')
|
|
55
|
+
.map((part) => part.trim())
|
|
56
|
+
.filter(Boolean)
|
|
57
|
+
.map((part) => {
|
|
58
|
+
const m = /^`?([a-z0-9][a-z0-9._-]*)`?(?:\s+phase\s+(\d+))?$/i.exec(part)
|
|
59
|
+
if (!m) return { spec: null, phase: null, raw: part }
|
|
60
|
+
return { spec: m[1], phase: m[2] ? Number(m[2]) : null, raw: part }
|
|
61
|
+
})
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function parseLanes(value) {
|
|
65
|
+
const m = /^(\d+)$/.exec((value || '').trim())
|
|
66
|
+
const n = m ? Number(m[1]) : 0
|
|
67
|
+
return n > 0 ? n : null
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The headers an epic or a member carries. */
|
|
71
|
+
function epicHeaders(text) {
|
|
72
|
+
return {
|
|
73
|
+
epic: unquote(header(text, 'Epic')) || null,
|
|
74
|
+
waitsOn: parseWaitsOn(header(text, 'Waits on')),
|
|
75
|
+
lanes: parseLanes(header(text, 'Lanes')),
|
|
76
|
+
area: parseArea(header(text, 'Area')),
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Split on commas outside `{…}` and `(…)` — `a/{b,c}.ts, d (x, y)` is two parts.
|
|
81
|
+
function splitTopLevel(value) {
|
|
82
|
+
const parts = []
|
|
83
|
+
let depth = 0
|
|
84
|
+
let cur = ''
|
|
85
|
+
for (const ch of value) {
|
|
86
|
+
if (ch === '{' || ch === '(') depth++
|
|
87
|
+
else if ((ch === '}' || ch === ')') && depth > 0) depth--
|
|
88
|
+
if (ch === ',' && depth === 0) {
|
|
89
|
+
parts.push(cur)
|
|
90
|
+
cur = ''
|
|
91
|
+
} else cur += ch
|
|
92
|
+
}
|
|
93
|
+
parts.push(cur)
|
|
94
|
+
return parts.map((p) => p.trim()).filter(Boolean)
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// `a/{b,c}/{d,e}.ts` → every combination. One level of nesting per group,
|
|
98
|
+
// which is how the headers write it.
|
|
99
|
+
function expandBraces(pattern) {
|
|
100
|
+
const m = /\{([^{}]*)\}/.exec(pattern)
|
|
101
|
+
if (!m) return [pattern]
|
|
102
|
+
const head = pattern.slice(0, m.index)
|
|
103
|
+
const tail = pattern.slice(m.index + m[0].length)
|
|
104
|
+
return m[1].split(',').flatMap((alt) => expandBraces(`${head}${alt.trim()}${tail}`))
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* `> **Area:**` → the path patterns it names, brace-expanded. A trailing
|
|
109
|
+
* annotation — `(new)`, `(deep link)`, `` (`bareLive`) `` — is dropped, and so
|
|
110
|
+
* is any entry that does not read as a path (`skills (spec, spec-start)`):
|
|
111
|
+
* prose names no file, so it can clash with nothing. That is a cannot-tell,
|
|
112
|
+
* and a cannot-tell claims no clash — `Area:` is declared, not measured.
|
|
113
|
+
*/
|
|
114
|
+
function parseArea(value) {
|
|
115
|
+
if (!value) return []
|
|
116
|
+
const paths = splitTopLevel(value)
|
|
117
|
+
.map((part) => part.replace(/\s*\([^()]*\)\s*$/, '').replace(/`/g, '').trim())
|
|
118
|
+
.filter((part) => /^[\w.@+\-/*{},[\]]+$/.test(part) && /[/.]/.test(part))
|
|
119
|
+
.flatMap(expandBraces)
|
|
120
|
+
.map((p) => p.replace(/^\.\//, ''))
|
|
121
|
+
return [...new Set(paths)]
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
// One path segment against another, either of which may hold a `*`.
|
|
125
|
+
function segmentsMeet(a, b) {
|
|
126
|
+
if (a === b || a === '**' || b === '**') return true
|
|
127
|
+
const re = (g) => new RegExp(`^${g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`)
|
|
128
|
+
if (a.includes('*') && re(a).test(b.replace(/\*/g, ''))) return true
|
|
129
|
+
if (b.includes('*') && re(b).test(a.replace(/\*/g, ''))) return true
|
|
130
|
+
return false
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Could one file be named by both patterns? A pattern that ends first is read
|
|
135
|
+
* as a directory holding the other — `packages/api/` and `packages/api` both
|
|
136
|
+
* name everything under it, since a header rarely says which it means. A bare
|
|
137
|
+
* filename (no `/`) is matched against the other's last segment.
|
|
138
|
+
*
|
|
139
|
+
* WHAT WOULD FOOL THIS: a directory and a file of the same name read as a
|
|
140
|
+
* clash, and a glob against a glob is matched loosely. Both err towards
|
|
141
|
+
* naming a clash, which only ever warns.
|
|
142
|
+
*/
|
|
143
|
+
function patternsMeet(a, b) {
|
|
144
|
+
const split = (p) => p.replace(/\/+$/, '').split('/').filter(Boolean)
|
|
145
|
+
const sa = split(a)
|
|
146
|
+
const sb = split(b)
|
|
147
|
+
if (sa.length === 1 || sb.length === 1) {
|
|
148
|
+
const [bare, other] = sa.length === 1 ? [sa, sb] : [sb, sa]
|
|
149
|
+
return segmentsMeet(bare[0], other[other.length - 1])
|
|
150
|
+
}
|
|
151
|
+
for (let i = 0; i < Math.min(sa.length, sb.length); i++) {
|
|
152
|
+
if (sa[i] === '**' || sb[i] === '**') return true
|
|
153
|
+
if (!segmentsMeet(sa[i], sb[i])) return false
|
|
154
|
+
}
|
|
155
|
+
return true
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Every pair of open members whose `Area:` patterns meet, with the patterns
|
|
160
|
+
* they share — the "never together" sets. A member with no readable `Area:`
|
|
161
|
+
* claims nothing (stays silent), and finished members are left out: a pair
|
|
162
|
+
* matters only while both may still be built.
|
|
163
|
+
*/
|
|
164
|
+
function clashes(members) {
|
|
165
|
+
const open = members.filter((m) => m.area.length && !['complete', 'cancelled'].includes(m.bucket))
|
|
166
|
+
const out = []
|
|
167
|
+
for (let i = 0; i < open.length; i++) {
|
|
168
|
+
for (let j = i + 1; j < open.length; j++) {
|
|
169
|
+
const shared = new Set()
|
|
170
|
+
for (const a of open[i].area) {
|
|
171
|
+
for (const b of open[j].area) if (patternsMeet(a, b)) shared.add(a.length >= b.length ? a : b)
|
|
172
|
+
}
|
|
173
|
+
if (shared.size) out.push({ specs: [open[i].spec, open[j].spec], paths: [...shared].sort() })
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
return out
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Index the base branch's `specs/` from a `git ls-tree -r --name-only` listing:
|
|
181
|
+
* folder → `{ bucket, phases: Map<n, path> }`. A folder in two buckets (a
|
|
182
|
+
* `git mv` landed half-way) is filed where it is going, the later bucket.
|
|
183
|
+
*/
|
|
184
|
+
function indexSpecTree(listing) {
|
|
185
|
+
const index = new Map()
|
|
186
|
+
for (const line of String(listing || '').split('\n')) {
|
|
187
|
+
const m = /^specs\/([^/]+)\/([^/]+)\/([^/]+)$/.exec(line.trim())
|
|
188
|
+
if (!m || !BUCKETS.includes(m[1])) continue
|
|
189
|
+
const [, bucket, folder, file] = m
|
|
190
|
+
let entry = index.get(folder)
|
|
191
|
+
if (!entry || BUCKETS.indexOf(bucket) > BUCKETS.indexOf(entry.bucket)) {
|
|
192
|
+
entry = { bucket, phases: new Map() }
|
|
193
|
+
index.set(folder, entry)
|
|
194
|
+
}
|
|
195
|
+
if (entry.bucket !== bucket) continue
|
|
196
|
+
const phase = /^(\d\d)-.+\.md$/.exec(file)
|
|
197
|
+
if (phase && file !== '00-overview.md') entry.phases.set(Number(phase[1]), `specs/${bucket}/${folder}/${file}`)
|
|
198
|
+
}
|
|
199
|
+
return index
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Resolve one wait against the base branch.
|
|
204
|
+
* @returns {{ state: 'met' | 'unmet' | 'cannot-tell', why: string }}
|
|
205
|
+
*/
|
|
206
|
+
function resolveWait(wait, index, readFile) {
|
|
207
|
+
if (!wait.spec) return { state: 'cannot-tell', why: `"${wait.raw}" does not read as <spec>[ phase N]` }
|
|
208
|
+
const target = index.get(wait.spec)
|
|
209
|
+
if (!target) return { state: 'cannot-tell', why: `${wait.spec} is not on the base branch` }
|
|
210
|
+
if (target.bucket === 'complete') return { state: 'met', why: `${wait.spec} is complete` }
|
|
211
|
+
if (target.bucket === 'cancelled') return { state: 'unmet', why: `${wait.spec} was cancelled` }
|
|
212
|
+
if (wait.phase === null) return { state: 'unmet', why: `${wait.spec} is ${target.bucket}` }
|
|
213
|
+
const file = target.phases.get(wait.phase)
|
|
214
|
+
if (!file) return { state: 'cannot-tell', why: `${wait.spec} has no phase ${wait.phase} on the base branch` }
|
|
215
|
+
const text = readFile(file)
|
|
216
|
+
if (text === null) return { state: 'cannot-tell', why: `${file} could not be read` }
|
|
217
|
+
return phaseIsDone(text)
|
|
218
|
+
? { state: 'met', why: `${wait.spec} phase ${wait.phase} is done` }
|
|
219
|
+
: { state: 'unmet', why: `${wait.spec} phase ${wait.phase} is not done` }
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Layer members into waves, off their START waits only. A whole-spec wait on
|
|
224
|
+
* another member puts this one in a LATER wave; a wait on one of its phases
|
|
225
|
+
* lets it share the wave — it starts once that phase lands, beside the rest of
|
|
226
|
+
* that spec. A phase file's own wait never moves a wave: it holds that phase,
|
|
227
|
+
* not the spec's start, and is reported as a sync point instead. Waits on specs
|
|
228
|
+
* outside the epic order nothing here.
|
|
229
|
+
*
|
|
230
|
+
* A cycle is found and named, never guessed through: its members and anything
|
|
231
|
+
* waiting on them are left out of the waves.
|
|
232
|
+
*/
|
|
233
|
+
function layer(members) {
|
|
234
|
+
const byName = new Map(members.map((m) => [m.spec, m]))
|
|
235
|
+
const edges = new Map(
|
|
236
|
+
members.map((m) => [m.spec, m.waits.filter((w) => w.spec && byName.has(w.spec) && w.spec !== m.spec)]),
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
const cycles = []
|
|
240
|
+
const state = new Map()
|
|
241
|
+
const stack = []
|
|
242
|
+
const visit = (name) => {
|
|
243
|
+
state.set(name, 'open')
|
|
244
|
+
stack.push(name)
|
|
245
|
+
for (const w of edges.get(name)) {
|
|
246
|
+
if (state.get(w.spec) === 'open') {
|
|
247
|
+
const loop = stack.slice(stack.indexOf(w.spec))
|
|
248
|
+
cycles.push([...loop, w.spec])
|
|
249
|
+
} else if (!state.has(w.spec)) visit(w.spec)
|
|
250
|
+
}
|
|
251
|
+
stack.pop()
|
|
252
|
+
state.set(name, 'done')
|
|
253
|
+
}
|
|
254
|
+
for (const m of members) if (!state.has(m.spec)) visit(m.spec)
|
|
255
|
+
const inCycle = new Set(cycles.flat())
|
|
256
|
+
|
|
257
|
+
const wave = new Map()
|
|
258
|
+
const waveOf = (name, seen = new Set()) => {
|
|
259
|
+
if (wave.has(name)) return wave.get(name)
|
|
260
|
+
if (inCycle.has(name) || seen.has(name)) return null
|
|
261
|
+
seen.add(name)
|
|
262
|
+
let n = 1
|
|
263
|
+
for (const w of edges.get(name)) {
|
|
264
|
+
const dep = waveOf(w.spec, seen)
|
|
265
|
+
if (dep === null) {
|
|
266
|
+
wave.set(name, null)
|
|
267
|
+
return null
|
|
268
|
+
}
|
|
269
|
+
n = Math.max(n, w.phase === null ? dep + 1 : dep)
|
|
270
|
+
}
|
|
271
|
+
wave.set(name, n)
|
|
272
|
+
return n
|
|
273
|
+
}
|
|
274
|
+
for (const m of members) waveOf(m.spec)
|
|
275
|
+
|
|
276
|
+
const waves = []
|
|
277
|
+
for (const m of members) {
|
|
278
|
+
const n = wave.get(m.spec)
|
|
279
|
+
if (n == null) continue
|
|
280
|
+
while (waves.length < n) waves.push([])
|
|
281
|
+
waves[n - 1].push(m.spec)
|
|
282
|
+
}
|
|
283
|
+
return { waves, cycles, unlayered: members.filter((m) => wave.get(m.spec) == null).map((m) => m.spec) }
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/**
|
|
287
|
+
* The whole answer.
|
|
288
|
+
*
|
|
289
|
+
* @param {object} a
|
|
290
|
+
* - `epic` the epic's folder name
|
|
291
|
+
* - `index` `indexSpecTree` of the base branch
|
|
292
|
+
* - `readFile` base-branch path → text, or null
|
|
293
|
+
* - `candidates` base-branch overview paths that may carry an `Epic:` header
|
|
294
|
+
* - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
|
|
295
|
+
* each provisioned spec's own copy, which is where an
|
|
296
|
+
* in-flight spec's bucket and phase progress are true
|
|
297
|
+
*/
|
|
298
|
+
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
|
|
299
|
+
const own = new Map(worktrees.map((w) => [w.folder, w]))
|
|
300
|
+
const members = new Map()
|
|
301
|
+
|
|
302
|
+
for (const file of candidates) {
|
|
303
|
+
const m = /^specs\/([^/]+)\/([^/]+)\/00-overview\.md$/.exec(file)
|
|
304
|
+
if (!m || m[2] === epic) continue
|
|
305
|
+
const text = readFile(file)
|
|
306
|
+
if (text === null) continue
|
|
307
|
+
const h = epicHeaders(text)
|
|
308
|
+
if (h.epic !== epic) continue
|
|
309
|
+
const entry = index.get(m[2])
|
|
310
|
+
const phases = entry ? [...entry.phases].map(([n, p]) => ({ n, text: readFile(p) })) : []
|
|
311
|
+
members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
|
|
312
|
+
}
|
|
313
|
+
// A member authored on its own branch and not landed yet is invisible on the
|
|
314
|
+
// base branch; its worktree copy is what knows it belongs here.
|
|
315
|
+
for (const w of worktrees) {
|
|
316
|
+
const h = epicHeaders(w.overview)
|
|
317
|
+
// The worktree's copy is the newer word on a spec being built: it may have
|
|
318
|
+
// joined, changed its waits, or moved to another epic.
|
|
319
|
+
if (h.epic === epic) members.set(w.folder, { spec: w.folder, waits: h.waitsOn, area: h.area, phases: w.phases || [] })
|
|
320
|
+
else if (h.epic !== null) members.delete(w.folder)
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
const list = [...members.values()].sort((a, b) => a.spec.localeCompare(b.spec))
|
|
324
|
+
for (const m of list) {
|
|
325
|
+
const wt = own.get(m.spec)
|
|
326
|
+
const base = index.get(m.spec)
|
|
327
|
+
// In flight is the positive signal of a worktree whose own copy has not
|
|
328
|
+
// finished; otherwise the base branch's bucket.
|
|
329
|
+
m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : base ? base.bucket : wt ? wt.bucket : null
|
|
330
|
+
m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, index, readFile) }))
|
|
331
|
+
// A phase's own `Waits on:` holds that phase, not the spec's start: the
|
|
332
|
+
// sync point the field example turned on (#154 phase 2 on #159 phase 1).
|
|
333
|
+
// A phase already done has nothing left to wait for.
|
|
334
|
+
m.phaseWaits = m.phases
|
|
335
|
+
.filter((p) => p.text !== null && !phaseIsDone(p.text))
|
|
336
|
+
.flatMap((p) =>
|
|
337
|
+
epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, index, readFile) } })),
|
|
338
|
+
)
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
const epicEntry = index.get(epic)
|
|
342
|
+
const epicOverview = epicEntry ? readFile(`specs/${epicEntry.bucket}/${epic}/00-overview.md`) : null
|
|
343
|
+
const lanes = epicHeaders(epicOverview || (own.get(epic) || {}).overview || '').lanes
|
|
344
|
+
|
|
345
|
+
const of = (bucket) => list.filter((m) => m.bucket === bucket)
|
|
346
|
+
const waiting = of('backlog')
|
|
347
|
+
const ready = waiting.filter((m) => m.resolved.every((w) => w.state === 'met'))
|
|
348
|
+
const blocked = waiting.filter((m) => m.resolved.some((w) => w.state === 'unmet'))
|
|
349
|
+
const cannotTell = waiting.filter((m) => !ready.includes(m) && !blocked.includes(m))
|
|
350
|
+
const inFlight = of('in-progress')
|
|
351
|
+
const { waves, cycles, unlayered } = layer(list.filter((m) => m.bucket !== 'cancelled'))
|
|
352
|
+
// Every edge finer than "this spec waits for that one": a start held on
|
|
353
|
+
// another spec's phase, and a phase of this spec held on anything. `phase`
|
|
354
|
+
// is the member's own phase — null for its start.
|
|
355
|
+
const open = list.filter((m) => m.bucket !== 'cancelled' && m.bucket !== 'complete')
|
|
356
|
+
const syncPoints = [
|
|
357
|
+
...open.flatMap((m) => m.resolved.filter((w) => w.phase !== null).map((wait) => ({ spec: m.spec, phase: null, wait }))),
|
|
358
|
+
...open.flatMap((m) => m.phaseWaits.map(({ at, wait }) => ({ spec: m.spec, phase: at, wait }))),
|
|
359
|
+
]
|
|
360
|
+
|
|
361
|
+
const brief = (m) => ({ spec: m.spec, waits: m.resolved })
|
|
362
|
+
return {
|
|
363
|
+
epic,
|
|
364
|
+
found: Boolean(epicEntry || own.has(epic)),
|
|
365
|
+
lanes,
|
|
366
|
+
freeLanes: lanes === null ? null : Math.max(0, lanes - inFlight.length),
|
|
367
|
+
members: list.map((m) => ({ spec: m.spec, bucket: m.bucket, waits: m.resolved })),
|
|
368
|
+
ready: ready.map(brief),
|
|
369
|
+
blocked: blocked.map((m) => ({ spec: m.spec, by: m.resolved.filter((w) => w.state === 'unmet') })),
|
|
370
|
+
cannotTell: cannotTell.map((m) => ({ spec: m.spec, by: m.resolved.filter((w) => w.state === 'cannot-tell') })),
|
|
371
|
+
inFlight: inFlight.map(brief),
|
|
372
|
+
complete: of('complete').map((m) => m.spec),
|
|
373
|
+
cancelled: of('cancelled').map((m) => m.spec),
|
|
374
|
+
waves,
|
|
375
|
+
syncPoints,
|
|
376
|
+
clashes: clashes(list),
|
|
377
|
+
cycles,
|
|
378
|
+
unlayered,
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
const names = (xs) => xs.map((x) => (typeof x === 'string' ? x : x.spec)).join(', ')
|
|
383
|
+
const reasons = (xs) => xs.map((x) => `${x.spec} (${x.by.map((w) => w.why).join('; ')})`).join(', ')
|
|
384
|
+
|
|
385
|
+
// `feat-a phase 2 after feat-b phase 1 — not done`, or `feat-a starts after …`.
|
|
386
|
+
function syncLine({ spec, phase, wait }) {
|
|
387
|
+
const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
|
|
388
|
+
const mark = { met: 'met', unmet: 'not yet', 'cannot-tell': 'cannot tell' }[wait.state]
|
|
389
|
+
return `${who} after ${wait.raw} (${mark} — ${wait.why})`
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/**
|
|
393
|
+
* The human answer, in the report-block shape: one sentence, then a table of
|
|
394
|
+
* only the rows that have something in them.
|
|
395
|
+
*/
|
|
396
|
+
function formatEpicStatus(s) {
|
|
397
|
+
if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
|
|
398
|
+
const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
|
|
399
|
+
const head = `**${s.epic}** — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${s.found ? '' : ' · epic not on the base branch'}`
|
|
400
|
+
const rows = [
|
|
401
|
+
['Ready now', names(s.ready)],
|
|
402
|
+
['In flight', names(s.inFlight)],
|
|
403
|
+
['Blocked', reasons(s.blocked)],
|
|
404
|
+
['Cannot tell', reasons(s.cannotTell)],
|
|
405
|
+
['Done', names(s.complete)],
|
|
406
|
+
['Cancelled', names(s.cancelled)],
|
|
407
|
+
['Waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
|
|
408
|
+
['Sync points', s.syncPoints.map(syncLine).join(' · ')],
|
|
409
|
+
['Never together', s.clashes.map((c) => `${c.specs.join(' ‖ ')} (${c.paths.join(', ')})`).join(' · ')],
|
|
410
|
+
['Cycle', s.cycles.map((c) => c.join(' → ')).join(' · ')],
|
|
411
|
+
].filter(([, v]) => v)
|
|
412
|
+
if (!s.members.length) rows.push(['Members', `none — no spec carries \`> **Epic:** ${s.epic}\``])
|
|
413
|
+
return `${head}\n\n| | |\n|---|---|\n${rows.map(([k, v]) => `| **${k}** | ${v} |`).join('\n')}\n`
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
/**
|
|
417
|
+
* What starting or building one member should hear about — the half of
|
|
418
|
+
* `epic check` that is about other members in flight. Each warning names the
|
|
419
|
+
* in-flight member and the paths the two share. Never a refusal: `Area:` is
|
|
420
|
+
* declared, not measured (Decision 4). A spec that is no member of anything
|
|
421
|
+
* hears nothing.
|
|
422
|
+
*/
|
|
423
|
+
function memberCheck(status, spec, { phase = null, record = {} } = {}) {
|
|
424
|
+
const flying = new Set(status.inFlight.map((m) => m.spec))
|
|
425
|
+
const warnings = status.clashes
|
|
426
|
+
.filter((c) => c.specs.includes(spec))
|
|
427
|
+
.map((c) => ({ with: c.specs.find((x) => x !== spec), paths: c.paths }))
|
|
428
|
+
.filter((c) => flying.has(c.with))
|
|
429
|
+
.map((c) => ({ kind: 'clash', ...c, message: `${c.with} is in flight and edits ${c.paths.join(', ')} too` }))
|
|
430
|
+
|
|
431
|
+
// THE WAITS this build stands behind: the spec's start, always — a start
|
|
432
|
+
// bypassed at `/spec-start` is not asked again — and, with `phase`, that
|
|
433
|
+
// phase's own. Read where the work happens, which is the whole point
|
|
434
|
+
// (Decision 8): the field example's phase 2 was built because the place it
|
|
435
|
+
// was built never read the plan.
|
|
436
|
+
const member = status.members.find((m) => m.spec === spec)
|
|
437
|
+
const bypassed = new Set(record.bypassed || [])
|
|
438
|
+
const scoped = []
|
|
439
|
+
if (member && !bypassed.has('start')) scoped.push(...member.waits.map((w) => ({ scope: 'start', wait: w })))
|
|
440
|
+
if (phase !== null && !bypassed.has(`phase ${phase}`)) {
|
|
441
|
+
for (const p of status.syncPoints) {
|
|
442
|
+
if (p.spec === spec && p.phase === phase) scoped.push({ scope: `phase ${phase}`, wait: p.wait })
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
const unmet = scoped.filter((s) => s.wait.state === 'unmet')
|
|
446
|
+
for (const s of scoped.filter((x) => x.wait.state === 'cannot-tell')) {
|
|
447
|
+
warnings.push({ kind: 'cannot-tell', message: `cannot tell whether ${s.wait.raw} has landed — ${s.wait.why}` })
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
const result = { spec, epic: status.epic, phase, warnings, blocked: unmet.length > 0 }
|
|
451
|
+
if (!unmet.length) return result
|
|
452
|
+
const what = phase === null ? `${spec}'s start` : `${spec} phase ${phase}`
|
|
453
|
+
result.scopes = [...new Set(unmet.map((s) => s.scope))]
|
|
454
|
+
result.reason =
|
|
455
|
+
`${what} waits on ${unmet.map((s) => `${s.wait.raw} (${s.wait.why})`).join(', ')} — ` +
|
|
456
|
+
`land that first, or build anyway with: skitterspec epic bypass ${spec}${phase === null ? '' : ` --phase ${phase}`}`
|
|
457
|
+
// Offered ONCE per obligation (`.claude/rules/offered-unblocks.md`): spent by
|
|
458
|
+
// being raised, recorded by `--offered`, so a re-run is a plain refusal.
|
|
459
|
+
const key = phase === null ? 'start' : `phase ${phase}`
|
|
460
|
+
if (!(record.offered || []).includes(key)) {
|
|
461
|
+
result.offer = {
|
|
462
|
+
kind: 'bypass',
|
|
463
|
+
label: 'Build it anyway — the wait is recorded as passed over',
|
|
464
|
+
command: `skitterspec epic bypass ${spec}${phase === null ? '' : ` --phase ${phase}`}`,
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
return result
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
/**
|
|
471
|
+
* The dated Changelog line a bypass leaves on the member spec — where the next
|
|
472
|
+
* reader of that spec, and phase 7's re-verify, will find it.
|
|
473
|
+
*/
|
|
474
|
+
function bypassLine(check, date) {
|
|
475
|
+
const what = check.phase === null ? 'Started' : `Built phase ${check.phase}`
|
|
476
|
+
return `- ${date} — ${what} past an unmet wait (epic check bypass, ${check.epic}): ${check.reason.split(' — land that first')[0]}.`
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
// Append `line` to the overview's `## Changelog`, which ends the file in every
|
|
480
|
+
// spec the skills write; a spec without one gains the section.
|
|
481
|
+
function appendChangelog(text, line) {
|
|
482
|
+
const body = text.replace(/\s*$/, '')
|
|
483
|
+
return /^## Changelog\s*$/m.test(body) ? `${body}\n${line}\n` : `${body}\n\n## Changelog\n\n${line}\n`
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
/**
|
|
487
|
+
* Waits a landing's rebase will MEET — the field case behind Decision 9: a
|
|
488
|
+
* phase built before the phase it waited on had landed, then rebased over it,
|
|
489
|
+
* lands in the right order without ever having run with the dependency
|
|
490
|
+
* underneath. A rebase satisfies the order, not the intent.
|
|
491
|
+
*
|
|
492
|
+
* Asked of two readings of the base branch — `before` at the spec's fork
|
|
493
|
+
* point, `after` at the base it is about to land on — and of the spec's own
|
|
494
|
+
* DONE phases (a phase not yet built will be built on top anyway). A wait is
|
|
495
|
+
* listed only on a positive signal from BOTH reads: unmet before, met after.
|
|
496
|
+
* Cannot-tell on either side is reported as such and never claimed — the cost
|
|
497
|
+
* of a wrong "met by this rebase" is a re-run nobody needed, but the cost of
|
|
498
|
+
* inventing one is a re-run claim nobody can check.
|
|
499
|
+
*
|
|
500
|
+
* @param {object} a
|
|
501
|
+
* - `overview` the spec's own overview text (its start waits)
|
|
502
|
+
* - `phases` `[{ n, text }]`, the spec's own phase files
|
|
503
|
+
* - `before` `{ index, readFile }` at the fork point
|
|
504
|
+
* - `after` `{ index, readFile }` at the base being landed on
|
|
505
|
+
* @returns {{ met: [{ phase, wait }], cannotTell: [{ phase, wait }] }}
|
|
506
|
+
* `phase` is the spec's phase number, or null for its start's waits.
|
|
507
|
+
*/
|
|
508
|
+
function waitsMetByRebase({ overview, phases = [], before, after }) {
|
|
509
|
+
const built = phases.filter((p) => p.text !== null && phaseIsDone(p.text))
|
|
510
|
+
const scoped = [
|
|
511
|
+
...(built.length ? epicHeaders(overview || '').waitsOn.map((w) => ({ phase: null, w })) : []),
|
|
512
|
+
...built.flatMap((p) => epicHeaders(p.text).waitsOn.map((w) => ({ phase: p.n, w }))),
|
|
513
|
+
]
|
|
514
|
+
const met = []
|
|
515
|
+
const cannotTell = []
|
|
516
|
+
for (const { phase, w } of scoped) {
|
|
517
|
+
const was = resolveWait(w, before.index, before.readFile)
|
|
518
|
+
const now = resolveWait(w, after.index, after.readFile)
|
|
519
|
+
if (now.state !== 'met' || was.state === 'met') continue
|
|
520
|
+
const wait = { ...w, why: now.why }
|
|
521
|
+
if (was.state === 'unmet') met.push({ phase, wait })
|
|
522
|
+
else cannotTell.push({ phase, wait: { ...wait, why: `${was.why} at the fork point` } })
|
|
523
|
+
}
|
|
524
|
+
return { met, cannotTell }
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
module.exports = {
|
|
528
|
+
waitsMetByRebase,
|
|
529
|
+
epicStatus,
|
|
530
|
+
formatEpicStatus,
|
|
531
|
+
epicHeaders,
|
|
532
|
+
parseWaitsOn,
|
|
533
|
+
parseArea,
|
|
534
|
+
patternsMeet,
|
|
535
|
+
indexSpecTree,
|
|
536
|
+
resolveWait,
|
|
537
|
+
layer,
|
|
538
|
+
memberCheck,
|
|
539
|
+
bypassLine,
|
|
540
|
+
appendChangelog,
|
|
541
|
+
}
|
package/src/env/inflight.js
CHANGED
|
@@ -81,9 +81,17 @@ function formatInFlight(rows, { dir }) {
|
|
|
81
81
|
const width = Math.max(...rows.map((r) => r.spec.length))
|
|
82
82
|
const live = rows.filter(isInFlight).length
|
|
83
83
|
const out = [live ? `${live} spec${live === 1 ? '' : 's'} in flight` : 'no specs in flight']
|
|
84
|
-
|
|
85
|
-
out.push(
|
|
86
|
-
out.push(
|
|
84
|
+
const row = (r, indent) => {
|
|
85
|
+
out.push(`${indent}${r.spec.padEnd(width)} ${detailOf(r)}`)
|
|
86
|
+
out.push(`${indent} ${path.relative(dir, r.worktree) || r.worktree}`)
|
|
87
|
+
}
|
|
88
|
+
// Members are listed under their epic, read off each spec's own copy; a spec
|
|
89
|
+
// in no epic — the common case — prints exactly as it always has.
|
|
90
|
+
for (const r of rows.filter((x) => !x.epic)) row(r, ' ')
|
|
91
|
+
const epics = [...new Set(rows.map((r) => r.epic).filter(Boolean))].sort()
|
|
92
|
+
for (const epic of epics) {
|
|
93
|
+
out.push(` ${epic}`)
|
|
94
|
+
for (const r of rows.filter((x) => x.epic === epic)) row(r, ' ')
|
|
87
95
|
}
|
|
88
96
|
// SAID ONLY WHEN TRUE. On an idle repo, or one whose worktrees all agree with
|
|
89
97
|
// this checkout, the line would explain a discrepancy that is not there.
|
package/src/env/resolve.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Pure spec/branch resolution for per-spec isolation.
|
|
5
5
|
*
|
|
6
6
|
* Given a spec argument (a folder name or path) it locates the spec folder under
|
|
7
|
-
* `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` prefix into
|
|
7
|
+
* `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`/`epic-` prefix into
|
|
8
8
|
* `{ type, slug }`, derives the
|
|
9
9
|
* git branch from the config's `branch.pattern` (provider-neutral; `{identifier}`
|
|
10
10
|
* is filled from a tracker id when one is configured, else it falls back to
|
|
@@ -77,8 +77,10 @@ function readPhases(specDir, { overviewFile = '00-overview.md' } = {}) {
|
|
|
77
77
|
.map((e) => e.name)
|
|
78
78
|
.sort()
|
|
79
79
|
// No phase files is not "no phases" — it is a legacy layout whose phases live
|
|
80
|
-
// inline in the overview, and this reader cannot see them.
|
|
81
|
-
|
|
80
|
+
// inline in the overview, and this reader cannot see them. The one exception
|
|
81
|
+
// is an epic, whose prefix says positively that it has none: there is no
|
|
82
|
+
// phase for `/spec-next` to build, and that is an answer, not a cannot-tell.
|
|
83
|
+
if (!files.length) return isEpic(specDir) ? { total: 0, done: 0, hasNextPhase: false, live: null } : null
|
|
82
84
|
|
|
83
85
|
let done = 0
|
|
84
86
|
for (const name of files) {
|
|
@@ -296,15 +298,23 @@ function phaseIsDone(text) {
|
|
|
296
298
|
return /^#\s.*✅\s*$/m.test(text)
|
|
297
299
|
}
|
|
298
300
|
|
|
299
|
-
// Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`
|
|
300
|
-
// Unknown prefix → type defaults to `feat` and the whole folder name is
|
|
301
|
-
// slug.
|
|
301
|
+
// Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`/`epic-`
|
|
302
|
+
// prefix. Unknown prefix → type defaults to `feat` and the whole folder name is
|
|
303
|
+
// the slug.
|
|
302
304
|
function splitPrefix(folder) {
|
|
303
|
-
const m = /^(feat|bug|hotfix|chore|issue|incident)-(.+)$/.exec(folder)
|
|
305
|
+
const m = /^(feat|bug|hotfix|chore|issue|incident|epic)-(.+)$/.exec(folder)
|
|
304
306
|
if (m) return { type: m[1], slug: m[2] }
|
|
305
307
|
return { type: 'feat', slug: folder }
|
|
306
308
|
}
|
|
307
309
|
|
|
310
|
+
// An epic is a spec of specs: a folder with an overview and no phase files of
|
|
311
|
+
// its own, its progress being its members'. Decided off the folder prefix — the
|
|
312
|
+
// positive signal every other kind uses — never off the absence of phase files,
|
|
313
|
+
// which is also what a legacy inline-phase spec looks like.
|
|
314
|
+
function isEpic(folder) {
|
|
315
|
+
return splitPrefix(path.basename(String(folder || ''))).type === 'epic'
|
|
316
|
+
}
|
|
317
|
+
|
|
308
318
|
// Repo identity used for token expansion.
|
|
309
319
|
function repoInfo(dir) {
|
|
310
320
|
const repo = path.basename(dir)
|
|
@@ -831,6 +841,7 @@ module.exports = {
|
|
|
831
841
|
assertPrimaryOnMain,
|
|
832
842
|
branchFor,
|
|
833
843
|
splitPrefix,
|
|
844
|
+
isEpic,
|
|
834
845
|
repoInfo,
|
|
835
846
|
expandTokens,
|
|
836
847
|
findSpecFolder,
|
package/src/env/specstate.js
CHANGED
|
@@ -24,6 +24,7 @@ const fs = require('node:fs')
|
|
|
24
24
|
const path = require('node:path')
|
|
25
25
|
|
|
26
26
|
const { phaseProgress } = require('./phases.js')
|
|
27
|
+
const { isEpic } = require('./resolve.js')
|
|
27
28
|
|
|
28
29
|
// Most live first: a spec that exists in two buckets mid-`git mv` is reported
|
|
29
30
|
// where it is going, not where it was.
|
|
@@ -64,7 +65,7 @@ function tryRead(io, fn) {
|
|
|
64
65
|
* @param {string} root the checkout to read — a spec's worktree, normally
|
|
65
66
|
* @param {string} folder the spec's folder name (`feat-x`)
|
|
66
67
|
* @param {object} [io] `{ readdir, readFile }`, each throwing on failure
|
|
67
|
-
* @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer }
|
|
68
|
+
* @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer, epic }
|
|
68
69
|
* | { found: false, reason }}
|
|
69
70
|
*/
|
|
70
71
|
function readSpecState(root, folder, io = defaultIo) {
|
|
@@ -76,7 +77,10 @@ function readSpecState(root, folder, io = defaultIo) {
|
|
|
76
77
|
if (overview === null) return { found: false, reason: `${bucket}/${folder} has no readable 00-overview.md` }
|
|
77
78
|
const phaseFiles = files.filter((f) => /^(?!00-)\d{2}-.*\.md$/.test(f)).sort()
|
|
78
79
|
const phases = phaseFiles.map((f) => ({ file: f, content: tryRead(io, () => io.readFile(path.join(dir, f))) }))
|
|
79
|
-
|
|
80
|
+
// An epic has no phases by construction (its prefix says so), so zero is
|
|
81
|
+
// an answer for it — where any other folder without phase files is a
|
|
82
|
+
// legacy overview to read inline.
|
|
83
|
+
const progress = phases.length || isEpic(folder) ? phaseProgress(phases) : inlineProgress(overview)
|
|
80
84
|
return state(bucket, false, overview, progress)
|
|
81
85
|
}
|
|
82
86
|
const bare = tryRead(io, () => io.readFile(path.join(root, 'specs', bucket, `${folder}.md`)))
|
|
@@ -95,6 +99,7 @@ function state(bucket, legacy, text, progress) {
|
|
|
95
99
|
currentPhase: progress ? progress.current : null,
|
|
96
100
|
status: header(text, 'Status'),
|
|
97
101
|
developer: header(text, 'Developer'),
|
|
102
|
+
epic: (header(text, 'Epic') || '').replace(/^`(.*)`$/, '$1') || null,
|
|
98
103
|
}
|
|
99
104
|
}
|
|
100
105
|
|