@skitterbyte/skitterspec-linear 18.1.0 → 18.1.2
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 +37 -0
- package/assets/core/env.config.md +5 -2
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/package.json +1 -1
- package/src/cli.js +10 -4
- package/src/env/hotfix.js +29 -3
- package/src/env/proxy.js +33 -0
- package/src/init.js +3 -3
- package/src/vendor/linear/cli-sync.js +33 -283
- package/src/vendor/provider-kit/src/apply.js +10 -0
- package/src/vendor/provider-kit/src/assignment.js +277 -0
- package/src/vendor/provider-kit/src/http.js +30 -11
- package/src/vendor/provider-kit/src/released.js +56 -13
- package/src/vendor/provider-kit/src/releases.js +380 -0
- package/src/vendor/sync-core/index.js +2 -1
- package/src/vendor/sync-core/src/compare.js +32 -0
- package/src/vendor/sync-core/src/normalize.js +10 -1
|
@@ -0,0 +1,380 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The release seam — `spec-sync release create | deployed | complete`.
|
|
5
|
+
*
|
|
6
|
+
* A release today is a git tag and nothing more, while `released` already
|
|
7
|
+
* knows exactly which tickets a tag contains. These verbs write that down where
|
|
8
|
+
* people look: a release object on the tracker holding its tickets, which the
|
|
9
|
+
* host project's CI moves through its deploy stages.
|
|
10
|
+
*
|
|
11
|
+
* SKITTERSPEC DECIDES A RELEASE'S CONTENTS, never the tracker. The ticket set
|
|
12
|
+
* is `ticketsInRange` + `partitionStageMoves` over previous-tag → this-tag:
|
|
13
|
+
* the `Refs:` trailers, bookkeeping commits ignored, foreign refs excluded.
|
|
14
|
+
* That is one definition of "what shipped", shared with `released`.
|
|
15
|
+
*
|
|
16
|
+
* EVERY VERB IS A DRY RUN UNLESS `--apply`. CI passes it; a person reading the
|
|
17
|
+
* plan does not have to.
|
|
18
|
+
*
|
|
19
|
+
* IDEMPOTENT BY LOOKUP, not by memory. `create` finds the release for the tag
|
|
20
|
+
* first and updates it; a retry on the same tag never mints a duplicate. A
|
|
21
|
+
* lookup that FAILED is a cannot-tell, and refuses rather than creating
|
|
22
|
+
* (`.claude/rules/negative-checks.md` rule 4) — creating on "I could not see
|
|
23
|
+
* one" is exactly how duplicates are made.
|
|
24
|
+
*
|
|
25
|
+
* Tracker calls arrive as OPTIONAL adapter ops, feature-detected: a provider
|
|
26
|
+
* without them makes every verb refuse in one line. The ops:
|
|
27
|
+
*
|
|
28
|
+
* - `releaseFind(tag)` → release | null (throws = cannot tell)
|
|
29
|
+
* - `releaseCreate({ tag, name, body, prerelease })` → release
|
|
30
|
+
* - `releaseUpdate(release, { name, body })`
|
|
31
|
+
* - `releaseAttach(release, tickets)` → `{ attached, already }`
|
|
32
|
+
* - `releaseStage(release, optionName, tickets)` → `{ set }`
|
|
33
|
+
* - `releaseComplete(release)`
|
|
34
|
+
* - `releaseTagExists(tag)` OPTIONAL → true | false (throws = cannot tell)
|
|
35
|
+
*
|
|
36
|
+
* A release object carries at least `{ id, url, body }`.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
const { execFileSync } = require('node:child_process')
|
|
40
|
+
|
|
41
|
+
const { ticketsInRange, partitionStageMoves, stageOrderWarning } = require('./released.js')
|
|
42
|
+
|
|
43
|
+
const REQUIRED_OPS = ['releaseFind', 'releaseCreate', 'releaseUpdate', 'releaseAttach', 'releaseStage', 'releaseComplete']
|
|
44
|
+
|
|
45
|
+
// The line a release body carries so the next verb can read where the release
|
|
46
|
+
// is without asking anything else. An HTML comment: invisible where the body is
|
|
47
|
+
// rendered as markdown, and never confused with prose a person wrote.
|
|
48
|
+
const MARKER_RE = /<!--\s*skitterspec:release\s+v1\s+stage=([A-Za-z0-9_.-]*)\s*-->/
|
|
49
|
+
|
|
50
|
+
function stageOf(body) {
|
|
51
|
+
const m = MARKER_RE.exec(String(body || ''))
|
|
52
|
+
return m ? m[1] || null : null
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function withStage(body, key) {
|
|
56
|
+
const line = `<!-- skitterspec:release v1 stage=${key || ''} -->`
|
|
57
|
+
const text = String(body || '')
|
|
58
|
+
return MARKER_RE.test(text) ? text.replace(MARKER_RE, line) : `${text.replace(/\s+$/, '')}\n\n${line}\n`
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function gitReader(dir) {
|
|
62
|
+
return (argv) => {
|
|
63
|
+
try {
|
|
64
|
+
return execFileSync('git', ['-C', dir, ...argv], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }).trim()
|
|
65
|
+
} catch {
|
|
66
|
+
return null
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* The series a tag belongs to: the configured `tagPrefix` it starts with,
|
|
73
|
+
* longest first so `skitterspec-github@` is not read as `skitterspec`.
|
|
74
|
+
*/
|
|
75
|
+
function seriesFor(series, tag) {
|
|
76
|
+
return (
|
|
77
|
+
[...(series || [])]
|
|
78
|
+
.filter((s) => s && s.tagPrefix)
|
|
79
|
+
.sort((a, b) => b.tagPrefix.length - a.tagPrefix.length)
|
|
80
|
+
.find((s) => String(tag).startsWith(s.tagPrefix)) || null
|
|
81
|
+
)
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Previous tag in the same series → this tag.
|
|
86
|
+
*
|
|
87
|
+
* `git describe --match '<prefix>*' <tag>^` walks back from the commit BEFORE
|
|
88
|
+
* this tag, so a hotfix tag cut from a release tag ranges from that base, and
|
|
89
|
+
* a tag never ranges from itself.
|
|
90
|
+
*
|
|
91
|
+
* WHAT WOULD FOOL THIS: a shallow clone. `describe` there finds no previous tag
|
|
92
|
+
* and the range silently becomes "everything" — every ticket in history landing
|
|
93
|
+
* on one release. So shallowness is asked about first, as a positive signal,
|
|
94
|
+
* and refused with the fix (CI checkout `fetch-depth: 0`).
|
|
95
|
+
*/
|
|
96
|
+
function resolveRange(dir, tag, prefix, git = gitReader(dir)) {
|
|
97
|
+
if (git(['rev-parse', '--is-shallow-repository']) === 'true') {
|
|
98
|
+
return {
|
|
99
|
+
ok: false,
|
|
100
|
+
error: 'this clone is shallow, so the previous tag cannot be found — check out with fetch-depth: 0',
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
if (!git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`])) {
|
|
104
|
+
return { ok: false, error: `no tag ${tag} in this repo` }
|
|
105
|
+
}
|
|
106
|
+
const previous = git(['describe', '--tags', '--abbrev=0', '--match', `${prefix}*`, `${tag}^`])
|
|
107
|
+
if (previous) return { ok: true, range: `${previous}..${tag}`, previous }
|
|
108
|
+
return { ok: true, range: tag, previous: null, first: true }
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Compose the release body: the notes, then the issues, then the marker. Pure,
|
|
113
|
+
* so a re-run on unchanged inputs produces the same text — which is what lets
|
|
114
|
+
* `create` say "no change" rather than rewrite a release on every CI retry.
|
|
115
|
+
*/
|
|
116
|
+
function composeBody({ notes, tickets, links, stage, describe }) {
|
|
117
|
+
const parts = []
|
|
118
|
+
if (notes && String(notes).trim()) parts.push(String(notes).trim())
|
|
119
|
+
if (tickets.length) {
|
|
120
|
+
parts.push(['## Issues', '', ...tickets.map((t) => `- ${describe ? describe(t) : t.ref}`)].join('\n'))
|
|
121
|
+
}
|
|
122
|
+
if (links && links.length) {
|
|
123
|
+
parts.push(['## Links', '', ...links.map((l) => `- [${l.label || l.url}](${l.url})`)].join('\n'))
|
|
124
|
+
}
|
|
125
|
+
return withStage(parts.join('\n\n'), stage)
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
// `--link <url>[=label]`, repeatable. http(s) only: this lands in a body a
|
|
129
|
+
// tracker renders as a link, and a `javascript:` url there is script.
|
|
130
|
+
function parseLinks(raw) {
|
|
131
|
+
const out = []
|
|
132
|
+
const bad = []
|
|
133
|
+
for (const item of raw || []) {
|
|
134
|
+
const s = String(item)
|
|
135
|
+
const eq = s.indexOf('=', s.indexOf('://') + 3)
|
|
136
|
+
const url = eq > 0 ? s.slice(0, eq) : s
|
|
137
|
+
const label = eq > 0 ? s.slice(eq + 1) : null
|
|
138
|
+
if (/^https?:\/\//i.test(url)) out.push({ url, label })
|
|
139
|
+
else bad.push(s)
|
|
140
|
+
}
|
|
141
|
+
return { links: out, bad }
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* @param {object} p
|
|
146
|
+
* - `tracker` the tracker's name in messages
|
|
147
|
+
* - `program` 'spec-sync'
|
|
148
|
+
* - `readCommits(dir, range)` → `{ ok, commits | error }` (the provider's `released` reader)
|
|
149
|
+
* - `ticketOptions(config)` → the `ticketsInRange` options (ignorePaths, refPattern, …)
|
|
150
|
+
* - `teamKey(config)` → the foreign-ref key for `partitionStageMoves` ('' for none)
|
|
151
|
+
* - `listSpecs(dir, config)` → `[{ identifier, bucket, spec }]`
|
|
152
|
+
* - `series(config)` → `[{ tagPrefix, envs: { key: optionName } }]`
|
|
153
|
+
* - `adapterFor(config, flags)` → `{ ok, adapter | error }`
|
|
154
|
+
* - `describe(ticket)` OPTIONAL → the issue line in the body
|
|
155
|
+
* - `impossibleOverMcp` OPTIONAL — the transport answer for a provider whose
|
|
156
|
+
* MCP server cannot write releases; `(config, flags) → string | null`
|
|
157
|
+
*/
|
|
158
|
+
function makeReleaseCommands(p) {
|
|
159
|
+
const prog = `${p.program || 'spec-sync'} release`
|
|
160
|
+
|
|
161
|
+
function refuse(out, msg) {
|
|
162
|
+
out.write(`${prog}: ${msg}\n`)
|
|
163
|
+
return 1
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
// Everything a verb needs before touching the tracker, refused in one line
|
|
167
|
+
// each so CI logs say exactly what was missing.
|
|
168
|
+
function prepare(dir, config, tagArg, flags, out) {
|
|
169
|
+
if (!tagArg) return { code: refuse(out, 'pass the tag, e.g. skitterspec@1.4.0') }
|
|
170
|
+
const series = p.series(config)
|
|
171
|
+
if (!series.length) return { code: refuse(out, `no releases.series configured — add one to the ${p.tracker} config`) }
|
|
172
|
+
let tag = String(tagArg)
|
|
173
|
+
// A bare version is accepted when exactly one series is configured — the
|
|
174
|
+
// common single-package repo — and refused otherwise rather than guessed.
|
|
175
|
+
if (!seriesFor(series, tag)) {
|
|
176
|
+
if (series.length === 1 && /^v?\d/.test(tag)) tag = `${series[0].tagPrefix}${tag}`
|
|
177
|
+
else return { code: refuse(out, `${tag} matches no releases.series tagPrefix (${series.map((s) => s.tagPrefix).join(', ')})`) }
|
|
178
|
+
}
|
|
179
|
+
const s = seriesFor(series, tag)
|
|
180
|
+
if (p.impossibleOverMcp) {
|
|
181
|
+
const why = p.impossibleOverMcp(config, flags)
|
|
182
|
+
if (why) return { code: refuse(out, why) }
|
|
183
|
+
}
|
|
184
|
+
const got = p.adapterFor(config, flags)
|
|
185
|
+
if (!got.ok) return { code: refuse(out, got.error) }
|
|
186
|
+
const missing = REQUIRED_OPS.filter((op) => typeof got.adapter[op] !== 'function')
|
|
187
|
+
if (missing.length) return { code: refuse(out, `the ${p.tracker} provider has no release support (${missing.join(', ')})`) }
|
|
188
|
+
return { tag, series: s, adapter: got.adapter }
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
// The tickets a tag's range contains, split into what the release holds and
|
|
192
|
+
// what it reports. Recomputed by every verb — stateless, so `deployed` and
|
|
193
|
+
// `complete` act on the same set `create` attached without storing it.
|
|
194
|
+
function ticketsOf(dir, config, tag, s) {
|
|
195
|
+
const range = resolveRange(dir, tag, s.tagPrefix)
|
|
196
|
+
if (!range.ok) return range
|
|
197
|
+
const read = p.readCommits(dir, range.range)
|
|
198
|
+
if (!read.ok) return { ok: false, error: read.error }
|
|
199
|
+
const report = ticketsInRange(read.commits, p.ticketOptions(config))
|
|
200
|
+
const parts = partitionStageMoves({ tickets: report.tickets, teamKey: p.teamKey(config), specs: p.listSpecs(dir, config) })
|
|
201
|
+
// Movable AND unfinished: code that landed via /spec-to-main really is in
|
|
202
|
+
// this release. Attaching never touches workflow state — push owns that.
|
|
203
|
+
const attach = [...parts.movable, ...parts.unfinished]
|
|
204
|
+
return { ok: true, range, report, parts, attach }
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
function planLines(t, tag) {
|
|
208
|
+
const lines = [
|
|
209
|
+
` range: ${t.range.range}${t.range.first ? ' (no previous release in this series — everything up to the tag)' : ''}`,
|
|
210
|
+
` attach: ${t.attach.map((x) => x.ref).join(', ') || 'none'}`,
|
|
211
|
+
]
|
|
212
|
+
if (t.parts.unfinished.length) lines.push(` (in flight: ${t.parts.unfinished.map((x) => x.ref).join(', ')} — attached, state left to push)`)
|
|
213
|
+
if (t.parts.foreign.length) lines.push(` foreign: ${t.parts.foreign.map((x) => x.ref).join(', ')} — not attached`)
|
|
214
|
+
if (t.parts.unlinked.length) lines.push(` unlinked: ${t.parts.unlinked.map((x) => x.ref).join(', ')} — no spec claims them, not attached`)
|
|
215
|
+
lines.push(` ${t.report.unreferenced} commit(s) carry no Refs: trailer${t.report.ignored ? `, ${t.report.ignored} bookkeeping ignored` : ''}`)
|
|
216
|
+
// Without this line a range from before a tracker move reads as mostly
|
|
217
|
+
// missing: those commits are neither unreferenced nor attached.
|
|
218
|
+
if (t.report.historical) lines.push(` ${t.report.historical} commit(s) reference an earlier tracker — not attached`)
|
|
219
|
+
return lines
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
async function find(adapter, tag, out) {
|
|
223
|
+
try {
|
|
224
|
+
return { ok: true, release: await adapter.releaseFind(tag) }
|
|
225
|
+
} catch (error) {
|
|
226
|
+
refuse(out, `could not look up the release for ${tag} (${String(error.message).split('\n')[0]}) — refusing rather than risk a duplicate`)
|
|
227
|
+
return { ok: false }
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
async function create(dir, config, tagArg, flags, out) {
|
|
232
|
+
const prep = prepare(dir, config, tagArg, flags, out)
|
|
233
|
+
if (prep.code != null) return prep.code
|
|
234
|
+
const { tag, series: s, adapter } = prep
|
|
235
|
+
const t = ticketsOf(dir, config, tag, s)
|
|
236
|
+
if (!t.ok) return refuse(out, t.error)
|
|
237
|
+
const { links, bad } = parseLinks(flags.links)
|
|
238
|
+
if (bad.length) return refuse(out, `--link must be http(s): ${bad.join(', ')}`)
|
|
239
|
+
let notes = null
|
|
240
|
+
if (flags.notes) {
|
|
241
|
+
try {
|
|
242
|
+
notes = require('node:fs').readFileSync(flags.notes, 'utf-8')
|
|
243
|
+
} catch (error) {
|
|
244
|
+
return refuse(out, `cannot read --notes: ${error.message}`)
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
const envKeys = Object.keys(s.envs || {})
|
|
248
|
+
const stage = flags.stage || envKeys[0] || null
|
|
249
|
+
if (stage && envKeys.length && !envKeys.includes(stage)) {
|
|
250
|
+
return refuse(out, `--stage ${stage} is not an env of ${s.tagPrefix} (${envKeys.join(', ')})`)
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// A tracker that would CREATE a missing tag from the default branch must
|
|
254
|
+
// not be handed one it has not got — the release would point at the wrong
|
|
255
|
+
// commit. Positive signals only: `false` refuses, a throw is a cannot-tell
|
|
256
|
+
// and the create goes ahead exactly as it would have.
|
|
257
|
+
if (adapter.releaseTagExists) {
|
|
258
|
+
let exists = null
|
|
259
|
+
try {
|
|
260
|
+
exists = await adapter.releaseTagExists(tag)
|
|
261
|
+
} catch {
|
|
262
|
+
exists = null
|
|
263
|
+
}
|
|
264
|
+
if (exists === false) return refuse(out, `${tag} is not on the ${p.tracker} remote yet — push the tag first`)
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
const found = await find(adapter, tag, out)
|
|
268
|
+
if (!found.ok) return 1
|
|
269
|
+
const existing = found.release
|
|
270
|
+
// A release already past its first stage keeps the stage it is at: a CI
|
|
271
|
+
// retry of `create` must not drag a deployed release back.
|
|
272
|
+
const keep = existing ? stageOf(existing.body) : null
|
|
273
|
+
const body = composeBody({ notes, tickets: await describeAll(adapter, t.attach), links, stage: keep || stage, describe: p.describe })
|
|
274
|
+
|
|
275
|
+
const header = [`${prog} create: ${tag}${flags.apply ? '' : ' (dry run — pass --apply to write)'}`, ...planLines(t, tag)]
|
|
276
|
+
if (!flags.apply) {
|
|
277
|
+
header.push(` would ${existing ? (existing.body === body ? 'leave the release unchanged' : 'update the release') : 'create the release'}${existing && existing.url ? ` (${existing.url})` : ''}`)
|
|
278
|
+
return emit(out, flags, header, { tag, range: t.range.range, attach: t.attach.map((x) => x.ref), apply: false, existing: !!existing })
|
|
279
|
+
}
|
|
280
|
+
let release = existing
|
|
281
|
+
if (!release) {
|
|
282
|
+
release = await adapter.releaseCreate({ tag, name: tag, body, prerelease: true })
|
|
283
|
+
header.push(` created: ${release.url || release.id}`)
|
|
284
|
+
} else if (release.body !== body) {
|
|
285
|
+
await adapter.releaseUpdate(release, { name: tag, body })
|
|
286
|
+
header.push(` updated: ${release.url || release.id}`)
|
|
287
|
+
} else {
|
|
288
|
+
header.push(` unchanged: ${release.url || release.id}`)
|
|
289
|
+
}
|
|
290
|
+
const attached = await adapter.releaseAttach(release, t.attach)
|
|
291
|
+
header.push(` issues: ${attached.attached} noted, ${attached.already} already noted`)
|
|
292
|
+
return emit(out, flags, header, { tag, range: t.range.range, attach: t.attach.map((x) => x.ref), apply: true, url: release.url || null })
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
async function deployed(dir, config, tagArg, envKey, flags, out) {
|
|
296
|
+
const prep = prepare(dir, config, tagArg, flags, out)
|
|
297
|
+
if (prep.code != null) return prep.code
|
|
298
|
+
const { tag, series: s, adapter } = prep
|
|
299
|
+
const envs = s.envs || {}
|
|
300
|
+
if (!envKey || !(envKey in envs)) {
|
|
301
|
+
return refuse(out, `pass an env of ${s.tagPrefix}: ${Object.keys(envs).join(', ') || '(none configured)'}`)
|
|
302
|
+
}
|
|
303
|
+
const found = await find(adapter, tag, out)
|
|
304
|
+
if (!found.ok) return 1
|
|
305
|
+
if (!found.release) return refuse(out, `no release for ${tag} yet — run \`release create ${tag}\` first`)
|
|
306
|
+
const t = ticketsOf(dir, config, tag, s)
|
|
307
|
+
if (!t.ok) return refuse(out, t.error)
|
|
308
|
+
const lines = [`${prog} deployed: ${tag} → ${envKey}${flags.apply ? '' : ' (dry run — pass --apply to write)'}`]
|
|
309
|
+
// WARNS, NEVER REFUSES: a rollback and a hotfix straight to prod are both
|
|
310
|
+
// legitimate. The order is the series' own env order.
|
|
311
|
+
const ladder = Object.keys(envs).map((key) => ({ key, state: key }))
|
|
312
|
+
const from = stageOf(found.release.body)
|
|
313
|
+
const warn = from ? stageOrderWarning(ladder, from, envKey) : null
|
|
314
|
+
if (warn) lines.push(` !! ${warn}`)
|
|
315
|
+
lines.push(` issues: ${t.attach.map((x) => x.ref).join(', ') || 'none'} → "${envs[envKey]}"`)
|
|
316
|
+
if (!flags.apply) return emit(out, flags, lines, { tag, env: envKey, apply: false, warn })
|
|
317
|
+
const staged = await adapter.releaseStage(found.release, envs[envKey], t.attach)
|
|
318
|
+
await adapter.releaseUpdate(found.release, { name: tag, body: withStage(found.release.body, envKey) })
|
|
319
|
+
lines.push(` set: ${staged.set} issue(s)`)
|
|
320
|
+
return emit(out, flags, lines, { tag, env: envKey, apply: true, warn, set: staged.set })
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
async function complete(dir, config, tagArg, flags, out) {
|
|
324
|
+
const prep = prepare(dir, config, tagArg, flags, out)
|
|
325
|
+
if (prep.code != null) return prep.code
|
|
326
|
+
const { tag, adapter } = prep
|
|
327
|
+
const found = await find(adapter, tag, out)
|
|
328
|
+
if (!found.ok) return 1
|
|
329
|
+
if (!found.release) return refuse(out, `no release for ${tag} yet — run \`release create ${tag}\` first`)
|
|
330
|
+
const lines = [`${prog} complete: ${tag}${flags.apply ? '' : ' (dry run — pass --apply to write)'}`]
|
|
331
|
+
if (!flags.apply) {
|
|
332
|
+
lines.push(` would mark ${found.release.url || found.release.id} complete`)
|
|
333
|
+
return emit(out, flags, lines, { tag, apply: false })
|
|
334
|
+
}
|
|
335
|
+
await adapter.releaseComplete(found.release)
|
|
336
|
+
lines.push(` completed: ${found.release.url || found.release.id}`)
|
|
337
|
+
return emit(out, flags, lines, { tag, apply: true })
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// Titles for the body, best-effort: a ticket the tracker cannot read is
|
|
341
|
+
// still listed, by ref. The body is information, not a gate.
|
|
342
|
+
async function describeAll(adapter, tickets) {
|
|
343
|
+
const out = []
|
|
344
|
+
for (const t of tickets) {
|
|
345
|
+
let title = null
|
|
346
|
+
if (adapter.readIssue) {
|
|
347
|
+
try {
|
|
348
|
+
const issue = await adapter.readIssue(t.ref)
|
|
349
|
+
title = issue && issue.title ? issue.title : null
|
|
350
|
+
} catch {
|
|
351
|
+
title = null
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
out.push({ ...t, title })
|
|
355
|
+
}
|
|
356
|
+
return out
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
function emit(out, flags, lines, json) {
|
|
360
|
+
out.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
|
|
361
|
+
return 0
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
async function run(dir, config, args, flags, out) {
|
|
365
|
+
const [verb, tag, env] = args
|
|
366
|
+
if (verb === 'create') return create(dir, config, tag, flags, out)
|
|
367
|
+
if (verb === 'deployed') return deployed(dir, config, tag, env, flags, out)
|
|
368
|
+
if (verb === 'complete') return complete(dir, config, tag, flags, out)
|
|
369
|
+
out.write(
|
|
370
|
+
`Usage: ${prog} create <tag> [--notes <f>] [--link <url>[=label]] [--stage <env>] [--apply] [--json]\n` +
|
|
371
|
+
` ${prog} deployed <tag> <env> [--apply] [--json]\n` +
|
|
372
|
+
` ${prog} complete <tag> [--apply] [--json]\n`,
|
|
373
|
+
)
|
|
374
|
+
return verb ? 1 : 0
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
return { run, create, deployed, complete }
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
module.exports = { makeReleaseCommands, resolveRange, seriesFor, composeBody, stageOf, withStage, parseLinks, REQUIRED_OPS }
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
16
|
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
|
|
17
|
-
const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited } = require('./src/compare.js')
|
|
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')
|
|
20
20
|
const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
|
|
@@ -66,6 +66,7 @@ module.exports = {
|
|
|
66
66
|
// Did someone else edit the tracker's description since the last push?
|
|
67
67
|
// Three-valued; `null` is cannot-tell and must never be reported as drift.
|
|
68
68
|
remoteDescriptionEdited,
|
|
69
|
+
remoteSubIssueEdited,
|
|
69
70
|
// Provider seams: the frontmatter field vocabulary and the markdown dialect
|
|
70
71
|
// a provider's config supplies (`config.fields` / `config.dialect`).
|
|
71
72
|
fieldsOf,
|
|
@@ -137,6 +137,30 @@ function remoteDescriptionEdited(snapshot, remote, config) {
|
|
|
137
137
|
|
|
138
138
|
return hashField(stream(text, config)) !== recorded
|
|
139
139
|
}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* The same question for one phase SUB-ISSUE: has its body been edited on the
|
|
143
|
+
* tracker since the last push? It matters most where the tracker renders a
|
|
144
|
+
* phase's task list as clickable boxes — GitHub does — because ticking one
|
|
145
|
+
* there is an edit the next push replaces.
|
|
146
|
+
*
|
|
147
|
+
* The same three answers and the same cannot-tells as above, plus one of its
|
|
148
|
+
* own: no `subIssueStreams` in the snapshot, or none for this id. Every
|
|
149
|
+
* snapshot written before this existed lacks it, and a phase whose body was
|
|
150
|
+
* never sent (no goal) has nothing recorded.
|
|
151
|
+
*
|
|
152
|
+
* @param {object|null} snapshot the committed last-pushed snapshot
|
|
153
|
+
* @param {string} id the sub-issue's id as the snapshot keys it
|
|
154
|
+
* @param {object|null} remote what the tracker currently holds for it
|
|
155
|
+
* @returns {boolean|null}
|
|
156
|
+
*/
|
|
157
|
+
function remoteSubIssueEdited(snapshot, id, remote, config) {
|
|
158
|
+
const streams = snapshot && snapshot.subIssueStreams
|
|
159
|
+
if (!streams || typeof streams !== 'object' || Array.isArray(streams)) return null
|
|
160
|
+
const recorded = streams[String(id)]
|
|
161
|
+
if (typeof recorded !== 'string' || !recorded) return null
|
|
162
|
+
return remoteDescriptionEdited({ issueFields: { descriptionStream: recorded } }, remote, config)
|
|
163
|
+
}
|
|
140
164
|
// A phase SUB-ISSUE: its name, goal and state (all repo-owned).
|
|
141
165
|
const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
|
|
142
166
|
|
|
@@ -160,6 +184,13 @@ function snapshotOf(projection, config) {
|
|
|
160
184
|
issue: specIssueHash(p),
|
|
161
185
|
issueFields: specIssueFieldHashes(p, config),
|
|
162
186
|
subIssues: byId(p.subIssues, subIssueHash),
|
|
187
|
+
// Recorded and never planned on, like `descriptionStream`: `planChanges`
|
|
188
|
+
// reads `subIssues` by name, so this key cannot make a push pending. Only a
|
|
189
|
+
// phase whose body is actually sent (a string goal) gets one.
|
|
190
|
+
subIssueStreams: byId(
|
|
191
|
+
(p.subIssues || []).filter((s) => s && typeof s.goal === 'string'),
|
|
192
|
+
(s) => hashField(stream(s.goal, config)),
|
|
193
|
+
),
|
|
163
194
|
}
|
|
164
195
|
}
|
|
165
196
|
|
|
@@ -295,6 +326,7 @@ function isEmptyPlan(plan) {
|
|
|
295
326
|
module.exports = {
|
|
296
327
|
planChanges,
|
|
297
328
|
remoteDescriptionEdited,
|
|
329
|
+
remoteSubIssueEdited,
|
|
298
330
|
issueChanges,
|
|
299
331
|
specIssueFieldHashes,
|
|
300
332
|
snapshotOf,
|
|
@@ -570,6 +570,15 @@ const UNSTARTED_BUCKETS = ['backlog', 'cancelled']
|
|
|
570
570
|
// Buckets where a spec is FINISHED, and so has nobody working on it.
|
|
571
571
|
const TERMINAL_BUCKETS = ['complete', 'cancelled']
|
|
572
572
|
|
|
573
|
+
// A phase's state once its SPEC's bucket has a say. Cancelling a spec abandons
|
|
574
|
+
// every phase not already done — left alone, those sub-issues stay open in
|
|
575
|
+
// Backlog under a closed parent, which reads as work still owed. A phase that
|
|
576
|
+
// was finished keeps `complete`: it shipped before the spec was dropped.
|
|
577
|
+
function phaseStateUnder(workflowState, phaseState) {
|
|
578
|
+
if (workflowState === 'cancelled' && phaseState !== 'complete') return 'cancelled'
|
|
579
|
+
return phaseState
|
|
580
|
+
}
|
|
581
|
+
|
|
573
582
|
/**
|
|
574
583
|
* The Linear user this spec is assigned to, AS PROJECTED — which is not simply
|
|
575
584
|
* what the frontmatter records.
|
|
@@ -714,7 +723,7 @@ function normalizeLocal(snapshotDir, config) {
|
|
|
714
723
|
ref: p.phase,
|
|
715
724
|
name: p.name,
|
|
716
725
|
goal: subIssueBody(p, tasksMode, config.sync.localOnlySections, dialect),
|
|
717
|
-
state: p.state,
|
|
726
|
+
state: phaseStateUnder(workflowState, p.state),
|
|
718
727
|
})),
|
|
719
728
|
workflowState,
|
|
720
729
|
// Who is building this. `toFieldSet` drops it unless the repo listed
|