@skitterbyte/skitterspec-linear 18.3.0 → 19.0.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/MIGRATION.md +141 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/linear.config.md +53 -47
- package/assets/rules/spec-planning.md +13 -3
- package/assets/rules/spec-reports.md +19 -4
- package/assets/skills/spec/SKILL.md +1 -1
- package/assets/skills/spec-bug/SKILL.md +4 -2
- package/assets/skills/spec-hotfix/SKILL.md +4 -2
- package/assets/skills/spec-linear-setup/SKILL.md +9 -35
- package/assets/skills/spec-list/SKILL.md +13 -1
- package/assets/skills/spec-next/SKILL.md +3 -1
- package/assets/skills/spec-push/SKILL.md +1 -1
- package/assets/skills/spec-status/SKILL.md +30 -26
- package/assets/skills/spec-sync/SKILL.md +6 -5
- package/package.json +1 -1
- package/src/cli.js +14 -6
- package/src/env/review.js +47 -2
- package/src/vendor/linear/api.js +20 -1
- package/src/vendor/linear/cli-sync.js +36 -267
- package/src/vendor/linear/config.js +8 -47
- package/src/vendor/linear/doctor.js +4 -66
- package/src/vendor/provider-kit/src/config.js +101 -48
- package/src/vendor/provider-kit/src/list-assignee.js +71 -0
- package/src/vendor/provider-kit/src/list-rows.js +35 -0
- package/src/vendor/provider-kit/src/released.js +27 -77
- package/src/vendor/provider-kit/src/specs.js +89 -7
- package/src/vendor/sync-core/index.js +3 -4
- package/src/vendor/sync-core/src/compare.js +6 -6
- package/src/vendor/sync-core/src/normalize.js +30 -57
- package/assets/core/ci-stages.md +0 -110
- package/src/vendor/provider-kit/src/releases.js +0 -380
|
@@ -30,10 +30,7 @@
|
|
|
30
30
|
*/
|
|
31
31
|
|
|
32
32
|
// The states, the row shape and the combining rule are the kit's
|
|
33
|
-
// (`provider-kit/src/doctor.js`); the checks below are Linear's.
|
|
34
|
-
// last rung never closes an issue is a real problem for most projects and a
|
|
35
|
-
// deliberate choice for some, and only the project knows which — which is what
|
|
36
|
-
// the kit's `warn` state exists for.
|
|
33
|
+
// (`provider-kit/src/doctor.js`); the checks below are Linear's.
|
|
37
34
|
const { DOCTOR_STATES: STATES, doctorRow: row, combineDoctorChecks } = require('../provider-kit/src/doctor.js')
|
|
38
35
|
|
|
39
36
|
/**
|
|
@@ -56,73 +53,14 @@ function runChecks(state = {}) {
|
|
|
56
53
|
keyCheck(state.key, state.tracker),
|
|
57
54
|
identityCheck(state.identity, state.tracker),
|
|
58
55
|
remoteCheck(state.remote),
|
|
59
|
-
ladderCheck(state.ladder, state.tracker),
|
|
60
56
|
mcpCheck(state.mcp, state.tracker, state.project, state.remote),
|
|
61
57
|
]
|
|
58
|
+
// A retired config key is a stale file, not a broken one (provider-kit
|
|
59
|
+
// `retiredKeysRow`): present only when the config still carries one.
|
|
60
|
+
if (state.retired) checks.push(state.retired)
|
|
62
61
|
return combineDoctorChecks(checks)
|
|
63
62
|
}
|
|
64
63
|
|
|
65
|
-
/**
|
|
66
|
-
* The deployment ladder's shape, when one is declared.
|
|
67
|
-
*
|
|
68
|
-
* WHAT COULD FOOL THIS CHECK, and why it is a `warn` rather than a refusal: a
|
|
69
|
-
* workspace can close an issue by automation (a merged PR, a linked release)
|
|
70
|
-
* rather than by the last rung's own type, and a ladder that stops at a
|
|
71
|
-
* `started` state is then perfectly healthy. Only the project knows which it is.
|
|
72
|
-
*
|
|
73
|
-
* It needs the workspace's state TYPES, which only the API transport returns —
|
|
74
|
-
* `--workspace-states` and the MCP path carry names alone. Without them the row
|
|
75
|
-
* is `skipped`: not knowing a type is not evidence of a bad one.
|
|
76
|
-
*/
|
|
77
|
-
function ladderCheck(s = {}, tracker = {}) {
|
|
78
|
-
if (!tracker.present) return row('ladder', 'ladder', 'skipped', 'no tracker configured')
|
|
79
|
-
const stages = Array.isArray(s.stages) ? s.stages : []
|
|
80
|
-
if (!stages.length) {
|
|
81
|
-
return row('ladder', 'ladder', 'skipped', 'no deployment ladder declared')
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
const summary = stages.map((st) => `${st.key} -> ${st.state}`).join(', ')
|
|
85
|
-
const states = Array.isArray(s.workspaceStates) ? s.workspaceStates : null
|
|
86
|
-
if (!states) {
|
|
87
|
-
return row('ladder', 'ladder', 'skipped', `${stages.length} rung(s), unchecked: ${summary}`)
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
const byName = new Map(
|
|
91
|
-
states.filter((st) => st && typeof st.name === 'string').map((st) => [st.name.toLowerCase().trim(), st]),
|
|
92
|
-
)
|
|
93
|
-
// A list that arrived EMPTY, or held nothing with a name, cannot prove a rung
|
|
94
|
-
// is absent — it is a lookup that saw nothing, not a workspace without these
|
|
95
|
-
// states. Accusing every rung off that would be the exact absence-as-evidence
|
|
96
|
-
// mistake the negative-checks rule exists for.
|
|
97
|
-
if (!byName.size) {
|
|
98
|
-
return row('ladder', 'ladder', 'skipped', `${stages.length} rung(s), unchecked: ${summary}`)
|
|
99
|
-
}
|
|
100
|
-
const unknown = stages.filter((st) => !byName.has(String(st.state).toLowerCase().trim()))
|
|
101
|
-
if (unknown.length) {
|
|
102
|
-
return row(
|
|
103
|
-
'ladder',
|
|
104
|
-
'ladder',
|
|
105
|
-
'broken',
|
|
106
|
-
`rung state(s) not in this workspace: ${unknown.map((st) => `${st.key} -> "${st.state}"`).join(', ')}` +
|
|
107
|
-
' — Linear silently ignores an unknown state, so these would move nothing',
|
|
108
|
-
'/spec-linear-setup',
|
|
109
|
-
)
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
const last = stages[stages.length - 1]
|
|
113
|
-
const type = (byName.get(String(last.state).toLowerCase().trim()) || {}).type
|
|
114
|
-
if (type !== 'completed') {
|
|
115
|
-
return row(
|
|
116
|
-
'ladder',
|
|
117
|
-
'ladder',
|
|
118
|
-
'warn',
|
|
119
|
-
`ends at "${last.state}" (type: ${type || 'unknown'}) — an issue finishing the ladder never reaches a ` +
|
|
120
|
-
'completed state. Add a final rung, or ignore this if Linear automation closes them.',
|
|
121
|
-
)
|
|
122
|
-
}
|
|
123
|
-
return row('ladder', 'ladder', 'ok', `${stages.length} rung(s): ${summary}`)
|
|
124
|
-
}
|
|
125
|
-
|
|
126
64
|
function scaffoldCheck(s = {}) {
|
|
127
65
|
if (!s.specsDir) {
|
|
128
66
|
return row('scaffold', 'scaffold', 'missing', 'no specs/ folder', 'skitterspec init')
|
|
@@ -98,52 +98,6 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
|
|
|
98
98
|
}
|
|
99
99
|
}
|
|
100
100
|
|
|
101
|
-
// Merge (and validate) `release.stages` — the project's deployment ladder.
|
|
102
|
-
//
|
|
103
|
-
// Loud on a malformed entry: this list names tracker states, and a tracker
|
|
104
|
-
// that silently ignores an unknown state would let a half-typed ladder push
|
|
105
|
-
// clean and move nothing — so a bad shape fails here, at load, rather than at
|
|
106
|
-
// the first deploy nobody is watching. An ABSENT `release` block is not an
|
|
107
|
-
// error: it is the opt-out, and the whole feature is unused without it.
|
|
108
|
-
function mergeReleaseStages(base, parsed) {
|
|
109
|
-
const value = parsed.stages
|
|
110
|
-
if (value === undefined) return
|
|
111
|
-
if (!Array.isArray(value)) {
|
|
112
|
-
throw new Error(
|
|
113
|
-
`Invalid ${configFile}: release.stages = ${JSON.stringify(value)} ` +
|
|
114
|
-
'(expected an array of { key, state })',
|
|
115
|
-
)
|
|
116
|
-
}
|
|
117
|
-
const stages = []
|
|
118
|
-
const seen = new Set()
|
|
119
|
-
value.forEach((entry, i) => {
|
|
120
|
-
if (!isObject(entry)) {
|
|
121
|
-
throw new Error(
|
|
122
|
-
`Invalid ${configFile}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
|
|
123
|
-
'(expected { key, state })',
|
|
124
|
-
)
|
|
125
|
-
}
|
|
126
|
-
for (const field of ['key', 'state']) {
|
|
127
|
-
if (typeof entry[field] !== 'string' || !entry[field].trim()) {
|
|
128
|
-
throw new Error(
|
|
129
|
-
`Invalid ${configFile}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
|
|
130
|
-
'(expected a non-empty string)',
|
|
131
|
-
)
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
const key = entry.key.trim()
|
|
135
|
-
if (seen.has(key)) {
|
|
136
|
-
throw new Error(
|
|
137
|
-
`Invalid ${configFile}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
|
|
138
|
-
'(a stage key is how CI names the rung, so it must be unique)',
|
|
139
|
-
)
|
|
140
|
-
}
|
|
141
|
-
seen.add(key)
|
|
142
|
-
stages.push({ key, state: entry.state.trim() })
|
|
143
|
-
})
|
|
144
|
-
base.stages = stages
|
|
145
|
-
}
|
|
146
|
-
|
|
147
101
|
// Merge (and validate) release.ignorePaths — the path prefixes whose commits
|
|
148
102
|
// are bookkeeping. Loud on anything but an array of non-empty strings: a bad
|
|
149
103
|
// value that quietly fell back would let a project believe it had opted out
|
|
@@ -186,13 +140,112 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
|
|
|
186
140
|
}
|
|
187
141
|
}
|
|
188
142
|
|
|
143
|
+
// Merge (and validate) `states`. A bucket's value is a string — the one state
|
|
144
|
+
// push writes, exactly as it always was — or a non-empty array whose FIRST
|
|
145
|
+
// name is the one push writes and whose rest are read-only aliases: tracker
|
|
146
|
+
// states that also mean this bucket ("Blocked" for in-progress). The first
|
|
147
|
+
// name lands in `states[bucket]`, so every writer is unchanged; the rest go
|
|
148
|
+
// to `stateAliases[bucket]`, read only by code that interprets a remote state.
|
|
149
|
+
//
|
|
150
|
+
// An ALIAS in two buckets is refused: it would make a remote state mean two
|
|
151
|
+
// things, and which one won would be an accident of iteration order. Two
|
|
152
|
+
// buckets sharing one written name stays legal, as it always was — a tracker
|
|
153
|
+
// with no Cancelled state maps cancelled to "Done" — so only a name that an
|
|
154
|
+
// alias contributes is checked.
|
|
155
|
+
function mergeStates(base, parsed) {
|
|
156
|
+
const value = parsed.states
|
|
157
|
+
if (!isObject(value)) return
|
|
158
|
+
const aliases = {}
|
|
159
|
+
for (const bucket of Object.keys(base.states)) {
|
|
160
|
+
const entry = value[bucket]
|
|
161
|
+
if (entry === undefined) continue
|
|
162
|
+
if (typeof entry === 'string') {
|
|
163
|
+
if (entry.trim()) base.states[bucket] = entry.trim()
|
|
164
|
+
continue
|
|
165
|
+
}
|
|
166
|
+
if (!Array.isArray(entry) || !entry.length || entry.some((n) => typeof n !== 'string' || !n.trim())) {
|
|
167
|
+
throw new Error(
|
|
168
|
+
`Invalid ${configFile}: states.${bucket} = ${JSON.stringify(entry)} ` +
|
|
169
|
+
'(expected a state name, or a non-empty array of them — the first is what push writes)',
|
|
170
|
+
)
|
|
171
|
+
}
|
|
172
|
+
const names = entry.map((n) => n.trim())
|
|
173
|
+
base.states[bucket] = names[0]
|
|
174
|
+
aliases[bucket] = names.slice(1)
|
|
175
|
+
}
|
|
176
|
+
const owner = new Map()
|
|
177
|
+
for (const bucket of Object.keys(base.states)) {
|
|
178
|
+
const key = base.states[bucket].toLowerCase()
|
|
179
|
+
if (!owner.has(key)) owner.set(key, bucket)
|
|
180
|
+
}
|
|
181
|
+
for (const bucket of Object.keys(aliases)) {
|
|
182
|
+
for (const name of aliases[bucket]) {
|
|
183
|
+
const key = name.toLowerCase()
|
|
184
|
+
if (owner.has(key) && owner.get(key) !== bucket) {
|
|
185
|
+
throw new Error(
|
|
186
|
+
`Invalid ${configFile}: states name ${JSON.stringify(name)} is in both ` +
|
|
187
|
+
`${owner.get(key)} and ${bucket} (a tracker state can mean only one bucket)`,
|
|
188
|
+
)
|
|
189
|
+
}
|
|
190
|
+
owner.set(key, bucket)
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
base.stateAliases = aliases
|
|
194
|
+
}
|
|
195
|
+
|
|
189
196
|
return {
|
|
197
|
+
mergeStates,
|
|
190
198
|
mergeFieldOwnership,
|
|
191
199
|
mergePhaseMapping,
|
|
192
|
-
mergeReleaseStages,
|
|
193
200
|
mergeReleaseIgnorePaths,
|
|
194
201
|
mergeKeyedFields,
|
|
195
202
|
}
|
|
196
203
|
}
|
|
197
204
|
|
|
198
|
-
|
|
205
|
+
// Keys no provider reads any more. The merge already ignores them, as it does
|
|
206
|
+
// every unknown key — so a config still carrying one is a stale file, not a
|
|
207
|
+
// broken one, and `doctor` says so as a `warn` without touching the exit code.
|
|
208
|
+
//
|
|
209
|
+
// WHAT WOULD FOOL THIS: it reads the committed file, so a key set only in a
|
|
210
|
+
// working-tree edit is still reported — which is the file a person would edit.
|
|
211
|
+
const RETIRED_KEYS = Object.freeze([
|
|
212
|
+
{ path: ['releases'], name: 'releases' },
|
|
213
|
+
{ path: ['release', 'stages'], name: 'release.stages' },
|
|
214
|
+
])
|
|
215
|
+
|
|
216
|
+
// The retired keys present in a parsed config. Not an object, or none present,
|
|
217
|
+
// is `[]`: nothing to say is the safe answer to every cannot-tell.
|
|
218
|
+
function retiredKeys(parsed) {
|
|
219
|
+
if (!isObject(parsed)) return []
|
|
220
|
+
return RETIRED_KEYS.filter(({ path }) => {
|
|
221
|
+
let node = parsed
|
|
222
|
+
for (const key of path) {
|
|
223
|
+
if (!isObject(node) || !(key in node)) return false
|
|
224
|
+
node = node[key]
|
|
225
|
+
}
|
|
226
|
+
return true
|
|
227
|
+
}).map((k) => k.name)
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
// A doctor row naming the retired keys in the config at `file`, or null when
|
|
231
|
+
// there are none — or when the file cannot be read or parsed, which is the
|
|
232
|
+
// loader's to report, not this row's.
|
|
233
|
+
function retiredKeysRow(file, configFile, row) {
|
|
234
|
+
let parsed = null
|
|
235
|
+
try {
|
|
236
|
+
parsed = JSON.parse(require('node:fs').readFileSync(file, 'utf-8'))
|
|
237
|
+
} catch {
|
|
238
|
+
return null
|
|
239
|
+
}
|
|
240
|
+
const names = retiredKeys(parsed)
|
|
241
|
+
if (!names.length) return null
|
|
242
|
+
return row(
|
|
243
|
+
'retired',
|
|
244
|
+
'Retired config',
|
|
245
|
+
'warn',
|
|
246
|
+
`${names.join(', ')} in ${configFile} is no longer read — release and deploy state is the host project's to write (see \`spec-sync released --json\`)`,
|
|
247
|
+
`remove ${names.join(', ')} from ${configFile}`,
|
|
248
|
+
)
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS }
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `spec-sync list --mine | --by <user>` — whose tickets to list.
|
|
5
|
+
*
|
|
6
|
+
* Linear defined the contract (`linear/src/cli-sync.js`, decision 9 of
|
|
7
|
+
* `feat-linear-assignment`); this is the same contract for every provider that
|
|
8
|
+
* lists over the API, so the two sentences below mean the same thing anywhere:
|
|
9
|
+
*
|
|
10
|
+
* - `--mine` with an UNKNOWN identity lists nothing and exits 0. Identity is
|
|
11
|
+
* an ordinary unknown (a bot token, an offline machine). What must never
|
|
12
|
+
* happen is dropping the filter and printing everyone's work under a
|
|
13
|
+
* heading that promised yours.
|
|
14
|
+
* - `--by` that matches nobody, or more than one person, exits 1. The
|
|
15
|
+
* argument is wrong and only the caller can fix it — the same shape as an
|
|
16
|
+
* unknown `--state` — and a fallback to everyone would be the same lie.
|
|
17
|
+
*
|
|
18
|
+
* Returns `{ assignee: { id, name } | null }` to carry on with, or
|
|
19
|
+
* `{ code, lines }` to print and stop.
|
|
20
|
+
*/
|
|
21
|
+
async function resolveListAssignee({ flags, config, env, adapter, resolveIdentity, displayNameOf, tracker, prog }) {
|
|
22
|
+
if (flags.mine && flags.by) {
|
|
23
|
+
return {
|
|
24
|
+
code: 1,
|
|
25
|
+
lines: [
|
|
26
|
+
`${prog} list: --mine and --by both filter by assignee, so they cannot be combined`,
|
|
27
|
+
' use --mine for your own, or --by <user> for someone else.',
|
|
28
|
+
],
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
if (flags.mine) {
|
|
32
|
+
const who = await resolveIdentity(config, env, { adapter })
|
|
33
|
+
if (!who || !who.ok) {
|
|
34
|
+
return {
|
|
35
|
+
code: 0,
|
|
36
|
+
lines: [
|
|
37
|
+
`${prog} list: --mine needs to know who you are, and it does not (${(who && who.reason) || 'no identity'})`,
|
|
38
|
+
' run `spec-sync whoami --set <id>` to say so, or use --by <user>.',
|
|
39
|
+
],
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
return { assignee: { id: who.id, name: who.name || who.id } }
|
|
43
|
+
}
|
|
44
|
+
if (flags.by) {
|
|
45
|
+
const term = String(flags.by)
|
|
46
|
+
let found
|
|
47
|
+
try {
|
|
48
|
+
found = await adapter.searchUsers(term, { limit: 50 })
|
|
49
|
+
} catch (error) {
|
|
50
|
+
return { code: 1, lines: [`${prog} list: could not search users (${error.message})`] }
|
|
51
|
+
}
|
|
52
|
+
const users = (found && found.users) || []
|
|
53
|
+
if (!users.length) {
|
|
54
|
+
return {
|
|
55
|
+
code: 1,
|
|
56
|
+
lines: [`${prog} list: no ${tracker} user matches ${JSON.stringify(term)}`, ' `spec-sync users <term>` lists who there is.'],
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
if (users.length > 1) {
|
|
60
|
+
const lines = [`${prog} list: ${users.length} users match ${JSON.stringify(term)}`]
|
|
61
|
+
for (const u of users.slice(0, 10)) lines.push(` ${displayNameOf(u) || '(unnamed)'}${u.email ? ` ${u.email}` : ''}`)
|
|
62
|
+
if (users.length > 10) lines.push(` … and ${users.length - 10} more`)
|
|
63
|
+
lines.push(' narrow it — an email address matches exactly one person.')
|
|
64
|
+
return { code: 1, lines }
|
|
65
|
+
}
|
|
66
|
+
return { assignee: { id: users[0].id, name: displayNameOf(users[0]) || users[0].id } }
|
|
67
|
+
}
|
|
68
|
+
return { assignee: null }
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
module.exports = { resolveListAssignee }
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Shared pieces of `spec-sync list`: what `--state` means, and how a row's
|
|
5
|
+
* board state and its spec's own status are put side by side.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
const { remoteStateReading, stateNamesFor, LIFECYCLE_BUCKETS } = require('../../sync-core')
|
|
9
|
+
|
|
10
|
+
// `--state` takes a lifecycle bucket as well as a tracker state. A bucket
|
|
11
|
+
// expands to every tracker name it has (`stateNamesFor`, aliases included); any
|
|
12
|
+
// other value is a tracker state, matched as it always was.
|
|
13
|
+
function expandStateArgs(args, config) {
|
|
14
|
+
return (args || []).flatMap((arg) => (LIFECYCLE_BUCKETS.includes(arg) ? stateNamesFor(arg, config) : [arg]))
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
// The spec's status beside the board's, and whether they disagree. A board
|
|
18
|
+
// state that maps to no bucket never disagrees: it is somewhere push does not
|
|
19
|
+
// manage, which is not a claim about the spec. Nor does a row whose spec is not
|
|
20
|
+
// on this machine — there is nothing to disagree WITH.
|
|
21
|
+
function specColumn(stateName, spec, config) {
|
|
22
|
+
const specStatus = spec ? spec.bucket : null
|
|
23
|
+
const seen = stateName == null ? null : remoteStateReading({ state: { name: stateName } }, config)
|
|
24
|
+
const disagrees = Boolean(specStatus && seen && seen.mapped && seen.bucket !== specStatus)
|
|
25
|
+
return { specStatus, disagrees }
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// The cell itself: `in-progress`, `≠ backlog` when it disagrees, `—` when the
|
|
29
|
+
// spec is not here.
|
|
30
|
+
function specCell({ specStatus, disagrees }) {
|
|
31
|
+
if (!specStatus) return '—'
|
|
32
|
+
return disagrees ? `≠ ${specStatus}` : specStatus
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
module.exports = { expandStateArgs, specColumn, specCell }
|
|
@@ -24,7 +24,7 @@ const IDENTIFIER_RE = /\b[A-Z][A-Z0-9]*-\d+\b/g
|
|
|
24
24
|
// how `owner/repo#123` names ANOTHER repo's issue. Prose is excluded by the
|
|
25
25
|
// trailer anchor (only a `Refs:` line is scanned); the cross-repo form is
|
|
26
26
|
// excluded by the lookbehind, so a ref into some other repo never lands on this
|
|
27
|
-
// one's release
|
|
27
|
+
// one's release.
|
|
28
28
|
const GITHUB_REF_RE = /(?<![\w/.-])#\d+\b/g
|
|
29
29
|
// A `Refs:` trailer line. Anchored, so it is a line of its own — never prose
|
|
30
30
|
// that happens to mention the word.
|
|
@@ -175,95 +175,45 @@ function ticketsInRange(commits, options = {}) {
|
|
|
175
175
|
}
|
|
176
176
|
|
|
177
177
|
/**
|
|
178
|
-
*
|
|
179
|
-
*
|
|
178
|
+
* Name the spec behind each ticket a range contains, so a consumer can act on
|
|
179
|
+
* a release without a second lookup.
|
|
180
180
|
*
|
|
181
|
-
*
|
|
182
|
-
* be
|
|
181
|
+
* A ref no spec has stamped keeps `spec: null` and `url: null` — never a guess
|
|
182
|
+
* from a similar folder name. It may be tracker-only work, or a typo in a
|
|
183
|
+
* trailer, and a consumer acting on an invented match is worse than one told
|
|
184
|
+
* there was none.
|
|
183
185
|
*
|
|
184
|
-
*
|
|
185
|
-
*
|
|
186
|
-
* this repo was never configured for is the worst failure available here.
|
|
187
|
-
* - **unlinked** — the ref is this team's, but no spec in the repo claims it.
|
|
188
|
-
* It may be tracker-only work, or a typo in a trailer. Either way nothing
|
|
189
|
-
* here knows what it is, so it is reported, not moved.
|
|
190
|
-
* - **unfinished** — a spec that has not reached the ceded bucket. Its code
|
|
191
|
-
* really is in the release (it landed via `/spec-to-main`), but push still
|
|
192
|
-
* owns its workflow state and would bounce it straight back. Exactly one
|
|
193
|
-
* writer per issue at any moment beats a visible flip-flop.
|
|
194
|
-
*
|
|
195
|
-
* Pure: it takes the spec list as data, so the rules are testable without a repo.
|
|
186
|
+
* Pure: it takes the spec list as data (`listSpecs` rows), so it is testable
|
|
187
|
+
* without a repo.
|
|
196
188
|
*/
|
|
197
|
-
function
|
|
198
|
-
const
|
|
199
|
-
for (const
|
|
200
|
-
if (
|
|
201
|
-
}
|
|
202
|
-
const key = String(teamKey || '').trim().toUpperCase()
|
|
203
|
-
const movable = []
|
|
204
|
-
const foreign = []
|
|
205
|
-
const unlinked = []
|
|
206
|
-
const unfinished = []
|
|
207
|
-
for (const ticket of tickets || []) {
|
|
208
|
-
const ref = ticket && ticket.ref
|
|
209
|
-
if (!ref) continue
|
|
210
|
-
if (key && !ref.toUpperCase().startsWith(`${key}-`)) {
|
|
211
|
-
foreign.push(ticket)
|
|
212
|
-
} else if (!bucketOf.has(ref)) {
|
|
213
|
-
unlinked.push(ticket)
|
|
214
|
-
} else if (bucketOf.get(ref) !== cededBucket) {
|
|
215
|
-
unfinished.push({ ...ticket, bucket: bucketOf.get(ref) })
|
|
216
|
-
} else {
|
|
217
|
-
movable.push(ticket)
|
|
218
|
-
}
|
|
189
|
+
function nameTickets(tickets, specs) {
|
|
190
|
+
const byRef = new Map()
|
|
191
|
+
for (const s of specs || []) {
|
|
192
|
+
if (s && s.identifier && !byRef.has(s.identifier)) byRef.set(s.identifier, s)
|
|
219
193
|
}
|
|
220
|
-
return
|
|
194
|
+
return (tickets || []).map((t) => {
|
|
195
|
+
const s = byRef.get(t.ref)
|
|
196
|
+
return { ...t, spec: s ? s.spec : null, url: s ? s.url || null : null }
|
|
197
|
+
})
|
|
221
198
|
}
|
|
222
199
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
* normal case and says nothing.
|
|
231
|
-
*
|
|
232
|
-
* `lifecycleStates` is the bucket map's own state names, and a state among them
|
|
233
|
-
* means the issue is at its LIFECYCLE position, not on a rung — even when the
|
|
234
|
-
* two names coincide. They routinely do: `states.complete` and a final `prod`
|
|
235
|
-
* rung are both naturally "Done", and without this a spec that had merely been
|
|
236
|
-
* completed would read as already deployed to prod, so its first real deploy
|
|
237
|
-
* would be warned about as a move backwards. Bucket wins over ladder here for
|
|
238
|
-
* the same reason it wins in `bucketForState`.
|
|
239
|
-
*
|
|
240
|
-
* @returns {string|null}
|
|
241
|
-
*/
|
|
242
|
-
function stageOrderWarning(stages, fromState, toKey, lifecycleStates = []) {
|
|
243
|
-
const list = Array.isArray(stages) ? stages : []
|
|
244
|
-
const to = list.findIndex((s) => s && s.key === toKey)
|
|
245
|
-
if (to < 0) return null
|
|
246
|
-
const want = String(fromState || '').toLowerCase().trim()
|
|
247
|
-
if (!want) return null
|
|
248
|
-
const lifecycle = new Set(
|
|
249
|
-
(Array.isArray(lifecycleStates) ? lifecycleStates : [])
|
|
250
|
-
.filter((n) => typeof n === 'string')
|
|
251
|
-
.map((n) => n.toLowerCase().trim()),
|
|
200
|
+
// The answer a removed release verb gives (`release`, `stage`). Exit 1, not a
|
|
201
|
+
// quiet 0: a pipeline still calling one must learn it no longer mirrors
|
|
202
|
+
// anything, rather than go on believing it does.
|
|
203
|
+
function refuseRemovedVerb(out, program, verb) {
|
|
204
|
+
out.write(
|
|
205
|
+
`${program} ${verb}: removed — skitterspec no longer writes release or deploy state; ` +
|
|
206
|
+
`\`${program} released <range> --json\` lists the tickets a range contains, for your own tooling to act on\n`,
|
|
252
207
|
)
|
|
253
|
-
|
|
254
|
-
const from = list.findIndex((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want)
|
|
255
|
-
if (from < 0) return null
|
|
256
|
-
if (to < from) return `moves back from "${list[from].key}"`
|
|
257
|
-
if (to > from + 1) return `skips ${to - from - 1} rung(s) from "${list[from].key}"`
|
|
258
|
-
return null
|
|
208
|
+
return 1
|
|
259
209
|
}
|
|
260
210
|
|
|
261
211
|
module.exports = {
|
|
262
212
|
ticketsInRange,
|
|
213
|
+
refuseRemovedVerb,
|
|
214
|
+
nameTickets,
|
|
263
215
|
refsInBody,
|
|
264
216
|
onlyIgnoredPaths,
|
|
265
|
-
partitionStageMoves,
|
|
266
|
-
stageOrderWarning,
|
|
267
217
|
IDENTIFIER_RE,
|
|
268
218
|
GITHUB_REF_RE,
|
|
269
219
|
}
|
|
@@ -14,7 +14,16 @@
|
|
|
14
14
|
const fs = require('node:fs')
|
|
15
15
|
const path = require('node:path')
|
|
16
16
|
|
|
17
|
-
const {
|
|
17
|
+
const { execFileSync } = require('node:child_process')
|
|
18
|
+
|
|
19
|
+
const {
|
|
20
|
+
BUCKETS,
|
|
21
|
+
findSpecFolder,
|
|
22
|
+
resolveSpec,
|
|
23
|
+
liveWorktreePaths,
|
|
24
|
+
resolvePrimaryCheckout,
|
|
25
|
+
} = require('../../../env/resolve.js')
|
|
26
|
+
const { loadEnvConfig } = require('../../../env/config.js')
|
|
18
27
|
const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
|
|
19
28
|
|
|
20
29
|
function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
@@ -45,22 +54,32 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
45
54
|
// Read a spec's stamped identifier without throwing: an unlinked spec, an
|
|
46
55
|
// unreadable file and a spec with no frontmatter all read as `null`.
|
|
47
56
|
function linkedIdentifier(overviewPath, config) {
|
|
48
|
-
|
|
57
|
+
return linkedFields(overviewPath, config).identifier
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// The stamped identifier AND url, each `null` when absent. The url is only
|
|
61
|
+
// ever what a push stamped — never built from the identifier, because a url
|
|
62
|
+
// constructed here would be a guess about a tracker's address scheme.
|
|
63
|
+
function linkedFields(overviewPath, config) {
|
|
64
|
+
const fields = fieldsOf(config)
|
|
49
65
|
let raw
|
|
50
66
|
try {
|
|
51
67
|
raw = fs.readFileSync(overviewPath, 'utf-8')
|
|
52
68
|
} catch {
|
|
53
|
-
return null
|
|
69
|
+
return { identifier: null, url: null }
|
|
54
70
|
}
|
|
55
71
|
const { data } = parseFrontmatter(raw)
|
|
56
|
-
return
|
|
72
|
+
return {
|
|
73
|
+
identifier: data[fields.identifier] ? String(data[fields.identifier]) : null,
|
|
74
|
+
url: fields.url && data[fields.url] ? String(data[fields.url]) : null,
|
|
75
|
+
}
|
|
57
76
|
}
|
|
58
77
|
|
|
59
78
|
// Every spec under specs/<bucket>/, paired with the tracker issue it is
|
|
60
79
|
// linked to (`null` when it has never been pushed). Folder specs read
|
|
61
80
|
// `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
|
|
62
81
|
// itself. Sorted for stable output.
|
|
63
|
-
function listSpecs(dir, config) {
|
|
82
|
+
function listSpecs(dir, config, options = {}) {
|
|
64
83
|
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
65
84
|
const specs = []
|
|
66
85
|
for (const bucket of BUCKETS) {
|
|
@@ -83,12 +102,75 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
83
102
|
} else {
|
|
84
103
|
continue
|
|
85
104
|
}
|
|
86
|
-
|
|
105
|
+
const linked = linkedFields(overviewPath, config)
|
|
106
|
+
const row = { spec: name, bucket, identifier: linked.identifier }
|
|
107
|
+
// Opt-in, so every listing that never asked for a url keeps its shape.
|
|
108
|
+
if (options.urls) row.url = linked.url
|
|
109
|
+
specs.push(row)
|
|
87
110
|
}
|
|
88
111
|
}
|
|
89
112
|
return specs.sort((a, b) => a.spec.localeCompare(b.spec))
|
|
90
113
|
}
|
|
91
114
|
|
|
115
|
+
// `listSpecs`, but each spec's BUCKET read from where that spec actually
|
|
116
|
+
// lives. `/spec-start` moves a spec to `in-progress/` on its own branch, so
|
|
117
|
+
// on the base branch an in-flight spec still reads `backlog` — and a spec
|
|
118
|
+
// authored in its own worktree and not yet landed is not here at all. Each
|
|
119
|
+
// live worktree is read too, and a spec found in ITS OWN worktree (the path
|
|
120
|
+
// `resolveSpec` names for it) wins over every other copy. `source` says
|
|
121
|
+
// which: `here`, `worktree`, or `other-tree` for a spec only some other
|
|
122
|
+
// worktree carries.
|
|
123
|
+
//
|
|
124
|
+
// WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is
|
|
125
|
+
// still live, so a finished spec can read from a stale tree. And with no
|
|
126
|
+
// `env.config.json` there is no worktree layout to resolve, so this is
|
|
127
|
+
// exactly `listSpecs` — the current tree's answer, as before.
|
|
128
|
+
function listSpecsLive(dir, config) {
|
|
129
|
+
const here = listSpecs(dir, config).map((s) => ({ ...s, source: 'here' }))
|
|
130
|
+
const git = (args) => {
|
|
131
|
+
try {
|
|
132
|
+
return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
|
|
133
|
+
} catch {
|
|
134
|
+
return null
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
let primary
|
|
138
|
+
let env
|
|
139
|
+
try {
|
|
140
|
+
primary = resolvePrimaryCheckout(dir, git) || dir
|
|
141
|
+
env = loadEnvConfig(primary)
|
|
142
|
+
} catch {
|
|
143
|
+
return here
|
|
144
|
+
}
|
|
145
|
+
if (!env.present) return here
|
|
146
|
+
// Compared as REAL paths: git reports a worktree resolved through
|
|
147
|
+
// symlinks (macOS /var → /private/var) where `resolveSpec` does not.
|
|
148
|
+
const real = (p) => {
|
|
149
|
+
try {
|
|
150
|
+
return fs.realpathSync(p)
|
|
151
|
+
} catch {
|
|
152
|
+
return path.resolve(p)
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
const self = real(dir)
|
|
156
|
+
const byName = new Map(here.map((s) => [s.spec, s]))
|
|
157
|
+
for (const listed of liveWorktreePaths(git)) {
|
|
158
|
+
const tree = real(listed)
|
|
159
|
+
if (tree === self) continue
|
|
160
|
+
for (const s of listSpecs(tree, config)) {
|
|
161
|
+
let own = null
|
|
162
|
+
try {
|
|
163
|
+
own = real(resolveSpec(s.spec, primary, env.config, { searchDirs: [tree] }).worktreePath)
|
|
164
|
+
} catch {
|
|
165
|
+
own = null
|
|
166
|
+
}
|
|
167
|
+
if (own === tree) byName.set(s.spec, { ...s, source: 'worktree' })
|
|
168
|
+
else if (!byName.has(s.spec)) byName.set(s.spec, { ...s, source: 'other-tree' })
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
return [...byName.values()].sort((a, b) => a.spec.localeCompare(b.spec))
|
|
172
|
+
}
|
|
173
|
+
|
|
92
174
|
// Resolve a spec argument to its folder, or null with a message on stdout.
|
|
93
175
|
// EVERY failure path here must print and EVERY caller must return a non-zero
|
|
94
176
|
// code: a push skill checks $? before it applies a plan, so a resolve failure
|
|
@@ -160,7 +242,7 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
160
242
|
return lines
|
|
161
243
|
}
|
|
162
244
|
|
|
163
|
-
return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
|
|
245
|
+
return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr, verifyLines }
|
|
164
246
|
}
|
|
165
247
|
|
|
166
248
|
module.exports = { makeSpecHelpers }
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* stored matches what was sent — it merges nothing (see `src/verify.js`).
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
-
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState,
|
|
16
|
+
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
|
|
17
17
|
const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
|
|
18
18
|
const { readBase, writeBase } = require('./src/base.js')
|
|
19
19
|
const { push, recordPush, projectionOf } = require('./src/push.js')
|
|
@@ -41,12 +41,11 @@ module.exports = {
|
|
|
41
41
|
push,
|
|
42
42
|
recordPush,
|
|
43
43
|
remoteWorkflowState,
|
|
44
|
+
remoteStateReading,
|
|
45
|
+
stateNamesFor,
|
|
44
46
|
titleFromText,
|
|
45
47
|
validateStates,
|
|
46
48
|
stateSuggestions,
|
|
47
|
-
stageForState,
|
|
48
|
-
remoteStage,
|
|
49
|
-
LADDER_ORIGIN_BUCKET,
|
|
50
49
|
hashField,
|
|
51
50
|
stableStringify,
|
|
52
51
|
readBase,
|