@skitterbyte/skitterspec-jira 1.0.0 → 1.2.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 +54 -2
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/rules/spec-reports.md +19 -4
- package/assets/skills/no-spec/SKILL.md +6 -3
- package/assets/skills/spec-bug/SKILL.md +3 -1
- package/assets/skills/spec-complete/SKILL.md +6 -3
- package/assets/skills/spec-hotfix/SKILL.md +3 -1
- package/assets/skills/spec-next/SKILL.md +3 -1
- package/assets/skills/spec-to-main/SKILL.md +5 -3
- package/bin/skitterspec-jira.js +7 -0
- package/package.json +1 -1
- package/src/cli.js +82 -16
- package/src/env/config.js +111 -14
- package/src/env/glob.js +34 -0
- package/src/env/hotfix.js +33 -5
- package/src/env/integrate.js +52 -11
- package/src/env/live.js +1 -26
- package/src/env/proxy.js +33 -0
- package/src/env/review.js +47 -2
- package/src/init.js +3 -3
- 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 +595 -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,277 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Assignment — who is building a spec, mirrored to the tracker's assignee.
|
|
5
|
+
*
|
|
6
|
+
* Three commands every provider with assignment shares, hoisted from the
|
|
7
|
+
* Linear provider when GitHub became the second consumer:
|
|
8
|
+
*
|
|
9
|
+
* - `assign <spec> --to <id> [--name <n>] | --release` stamps (or clears) the
|
|
10
|
+
* assignee fields in the overview frontmatter. It writes the REPO and
|
|
11
|
+
* nothing else; the next push carries it, like any other field.
|
|
12
|
+
* - `whoami [--set <id> [--name <n>]] [--unset]` reports — and caches — who
|
|
13
|
+
* the operator is in the tracker, which is the fact assignment rests on.
|
|
14
|
+
* - `users [<query>]` finds a person to hand a spec to.
|
|
15
|
+
*
|
|
16
|
+
* Everything tracker-shaped arrives as a hook (`makeAssignmentCommands`): the
|
|
17
|
+
* tracker's name for messages, the frontmatter fields, the store scope, how a
|
|
18
|
+
* credential resolves and how an adapter is made. The behaviour is the Linear
|
|
19
|
+
* provider's, unchanged — its tests still pin every message.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
const path = require('node:path')
|
|
23
|
+
|
|
24
|
+
const { ownsField, writeFrontmatter, deleteFrontmatter, fieldsOf } = require('../../sync-core')
|
|
25
|
+
const { resolveTransport } = require('./transport.js')
|
|
26
|
+
const { makeSpecHelpers } = require('./specs.js')
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* @param {object} p
|
|
30
|
+
* - `tracker` the tracker's name in messages ("Linear", "GitHub")
|
|
31
|
+
* - `configFile` the provider config path, for refusals
|
|
32
|
+
* - `bin` the command a person types (for the hints)
|
|
33
|
+
* - `idHint` how a user id is described ("<linear-user-id>", "<login>")
|
|
34
|
+
* - `scopeOf(config)` → `{ id, label }` the credentials-store scope, or `{ id: '' , missing }` with
|
|
35
|
+
* `missing` the refusal text when the config cannot name one
|
|
36
|
+
* - `storePath(env)`, `writeUser(file, scope, user)`, `removeUser(file, scope)`
|
|
37
|
+
* - `resolveIdentity(config, env, deps)` the provider's identity binding
|
|
38
|
+
* - `resolveCredential(config, env)` → `{ ok, error? }`
|
|
39
|
+
* - `makeAdapter(config, credential, flags)` → an adapter with `searchUsers`
|
|
40
|
+
* - `displayNameOf(user)`
|
|
41
|
+
* - `validateAssignee(config, id, flags)` OPTIONAL — async, resolves to a
|
|
42
|
+
* refusal string or null. Absent means "do not check", which is the Linear
|
|
43
|
+
* provider's behaviour.
|
|
44
|
+
* - `usersOverMcp` the hint printed when users must be searched over MCP
|
|
45
|
+
* - `unknownHint` OPTIONAL extra lines for the unknown-identity whoami report
|
|
46
|
+
*/
|
|
47
|
+
function makeAssignmentCommands(p) {
|
|
48
|
+
const helpers = makeSpecHelpers({ program: 'spec-sync' })
|
|
49
|
+
|
|
50
|
+
async function assign(dir, config, specArg, flags, out) {
|
|
51
|
+
const snapshotDir = helpers.resolveOrExit(specArg, dir, out)
|
|
52
|
+
if (!snapshotDir) return 1
|
|
53
|
+
const fields = fieldsOf(config)
|
|
54
|
+
|
|
55
|
+
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
56
|
+
const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
|
|
57
|
+
const rel = path.relative(dir, snapshotDir)
|
|
58
|
+
|
|
59
|
+
const problems = []
|
|
60
|
+
if (flags.release && flags.to) problems.push('--release and --to are opposites — pass one')
|
|
61
|
+
if (!flags.release && !flags.to) problems.push('nothing to do — pass --to <user-id> or --release')
|
|
62
|
+
// An unlinked spec has no issue to assign. Refusing beats stamping a field
|
|
63
|
+
// that would sit in the file doing nothing until someone noticed.
|
|
64
|
+
if (!identifier) problems.push(`${rel} is not linked to ${p.tracker} — /spec-push it first`)
|
|
65
|
+
// AND THE SAME REASONING FOR THE FIELD ITSELF. A field the repo does not own
|
|
66
|
+
// is dropped from the projection, so a stamp written here would never reach
|
|
67
|
+
// the tracker — while the success line says `next: push it`. That is not a
|
|
68
|
+
// silent skip, it is an untrue assertion. Applies to `--release` too.
|
|
69
|
+
if (!ownsField(config, 'assignee')) {
|
|
70
|
+
problems.push(
|
|
71
|
+
'this repo does not own the assignee field — set sync.fieldOwnership.assignee ' +
|
|
72
|
+
`to "push" in ${p.configFile}`,
|
|
73
|
+
)
|
|
74
|
+
}
|
|
75
|
+
// A POSITIVE refusal only: the hook answers "this id cannot be assigned"
|
|
76
|
+
// or null, and every cannot-tell inside it must be null.
|
|
77
|
+
if (!problems.length && flags.to && p.validateAssignee) {
|
|
78
|
+
const refusal = await p.validateAssignee(config, flags.to, flags)
|
|
79
|
+
if (refusal) problems.push(refusal)
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
if (problems.length) {
|
|
83
|
+
out.write(
|
|
84
|
+
['spec-sync assign: refusing to write — nothing was changed', ...problems.map((x) => ` ${x}`)].join('\n') + '\n',
|
|
85
|
+
)
|
|
86
|
+
return 1
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
if (flags.release) {
|
|
90
|
+
const removed = deleteFrontmatter(snapshotDir, config, [fields.assigneeId, fields.assigneeName].filter(Boolean))
|
|
91
|
+
if (flags.json) {
|
|
92
|
+
out.write(JSON.stringify({ spec: rel, issue: identifier, released: removed.length > 0 }, null, 2) + '\n')
|
|
93
|
+
return 0
|
|
94
|
+
}
|
|
95
|
+
out.write(
|
|
96
|
+
(removed.length
|
|
97
|
+
? `spec-sync assign: ${rel} released (${identifier})\n`
|
|
98
|
+
: `spec-sync assign: ${rel} records no assignee — nothing to release\n`) +
|
|
99
|
+
` next: push it, so ${p.tracker} is unassigned too\n`,
|
|
100
|
+
)
|
|
101
|
+
return 0
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
writeFrontmatter(snapshotDir, config, {
|
|
105
|
+
[fields.assigneeId]: flags.to,
|
|
106
|
+
// Display only — the projection never sends it. It exists so a reader (and
|
|
107
|
+
// `/spec-claim`) can name the person without a tracker round trip.
|
|
108
|
+
...(fields.assigneeName ? { [fields.assigneeName]: flags.name || null } : {}),
|
|
109
|
+
})
|
|
110
|
+
if (flags.json) {
|
|
111
|
+
out.write(JSON.stringify({ spec: rel, issue: identifier, id: flags.to, name: flags.name || null }, null, 2) + '\n')
|
|
112
|
+
return 0
|
|
113
|
+
}
|
|
114
|
+
const who = flags.name ? `${flags.name} (${flags.to})` : flags.to
|
|
115
|
+
out.write(`spec-sync assign: ${rel} assigned to ${who} (${identifier})\n next: push it, so ${p.tracker} agrees\n`)
|
|
116
|
+
return 0
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Exit 0 even when the answer is "unknown": this answers a question, and
|
|
121
|
+
* "nobody is identified here" is a valid answer — a shared key, an offline
|
|
122
|
+
* machine. A successful DERIVE is cached; a cache read is not re-written, and
|
|
123
|
+
* the caching lives here so that asking never has a side effect.
|
|
124
|
+
*/
|
|
125
|
+
async function whoami(dir, config, flags, out) {
|
|
126
|
+
const env = flags.env || process.env
|
|
127
|
+
const file = p.storePath(env)
|
|
128
|
+
const scope = p.scopeOf(config)
|
|
129
|
+
|
|
130
|
+
// The store is keyed by scope, so without one there is nowhere to read from
|
|
131
|
+
// or write to. That IS a broken config, so it exits non-zero.
|
|
132
|
+
if (!scope.id) {
|
|
133
|
+
out.write(scope.missing + '\n')
|
|
134
|
+
return 1
|
|
135
|
+
}
|
|
136
|
+
const label = scope.label || scope.id
|
|
137
|
+
|
|
138
|
+
if (flags.unset) {
|
|
139
|
+
const r = p.removeUser(file, scope.id, {})
|
|
140
|
+
if (!r.ok) {
|
|
141
|
+
out.write(`spec-sync whoami: ${r.reason}\n`)
|
|
142
|
+
return 1
|
|
143
|
+
}
|
|
144
|
+
out.write(
|
|
145
|
+
r.removed
|
|
146
|
+
? `spec-sync whoami: forgot the identity for ${label} (the ${p.credentialNoun || 'API key'} is untouched)\n`
|
|
147
|
+
: `spec-sync whoami: no identity stored for ${label} — nothing to forget\n`,
|
|
148
|
+
)
|
|
149
|
+
return 0
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
if (flags.set) {
|
|
153
|
+
const r = p.writeUser(file, scope.id, { id: flags.set, name: flags.name }, {})
|
|
154
|
+
if (!r.ok) {
|
|
155
|
+
out.write(`spec-sync whoami: ${r.reason}\n`)
|
|
156
|
+
return 1
|
|
157
|
+
}
|
|
158
|
+
if (flags.json) {
|
|
159
|
+
out.write(JSON.stringify({ id: flags.set, name: flags.name || null, source: 'set', store: r.path }, null, 2) + '\n')
|
|
160
|
+
return 0
|
|
161
|
+
}
|
|
162
|
+
const shown = flags.name ? `${flags.name} (${flags.set})` : flags.set
|
|
163
|
+
out.write(`spec-sync whoami: identity for ${label} set to ${shown} in ${r.path} (600)\n`)
|
|
164
|
+
return 0
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
const identity = await p.resolveIdentity(config, env, { adapter: flags.adapter, fetch: flags.fetch })
|
|
168
|
+
|
|
169
|
+
if (identity.ok && identity.source === 'viewer') {
|
|
170
|
+
// A failed write is not fatal: we HAVE the answer, and re-deriving it next
|
|
171
|
+
// time is a slower success, not a wrong one.
|
|
172
|
+
const cached = p.writeUser(file, scope.id, { id: identity.id, name: identity.name }, {})
|
|
173
|
+
if (!cached.ok) identity.cacheWarning = cached.reason
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
if (flags.json) {
|
|
177
|
+
out.write(
|
|
178
|
+
JSON.stringify(
|
|
179
|
+
{
|
|
180
|
+
[p.scopeJsonKey || 'team']: label,
|
|
181
|
+
store: file,
|
|
182
|
+
ok: identity.ok,
|
|
183
|
+
id: identity.id || null,
|
|
184
|
+
name: identity.name || null,
|
|
185
|
+
source: identity.source,
|
|
186
|
+
reason: identity.ok ? null : identity.reason || null,
|
|
187
|
+
},
|
|
188
|
+
null,
|
|
189
|
+
2,
|
|
190
|
+
) + '\n',
|
|
191
|
+
)
|
|
192
|
+
return 0
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
if (!identity.ok) {
|
|
196
|
+
out.write(
|
|
197
|
+
[
|
|
198
|
+
'spec-sync whoami: unknown — no identity for this workspace',
|
|
199
|
+
` ${identity.reason}`,
|
|
200
|
+
' Set one by hand:',
|
|
201
|
+
` ${p.bin} spec-sync whoami --set ${p.idHint} --name "<your name>"`,
|
|
202
|
+
` Find the id with: ${p.bin} spec-sync users <name-or-email>`,
|
|
203
|
+
].join('\n') + '\n',
|
|
204
|
+
)
|
|
205
|
+
return 0
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
const where = identity.source === 'store' ? `cached in ${file}` : `derived from the ${p.credentialNoun || 'API key'}`
|
|
209
|
+
const lines = [
|
|
210
|
+
`spec-sync whoami: ${identity.name || '(unnamed)'} <${identity.id}>`,
|
|
211
|
+
` ${(p.scopeLineLabel || 'team:').padEnd(7)} ${label}`,
|
|
212
|
+
` source: ${where}`,
|
|
213
|
+
]
|
|
214
|
+
if (identity.cacheWarning) lines.push(` note: not cached — ${identity.cacheWarning}`)
|
|
215
|
+
out.write(lines.join('\n') + '\n')
|
|
216
|
+
return 0
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* The engine answers on the API path and steps aside on the MCP path — the
|
|
221
|
+
* same contract `states` follows.
|
|
222
|
+
*/
|
|
223
|
+
async function users(dir, config, query, flags, out) {
|
|
224
|
+
const cred = p.resolveCredential(config, flags.env || process.env)
|
|
225
|
+
const transport = resolveTransport(flags, config, cred.ok || !!flags.adapter)
|
|
226
|
+
|
|
227
|
+
if (transport === 'mcp') {
|
|
228
|
+
if (flags.json) {
|
|
229
|
+
out.write(JSON.stringify({ transport: 'mcp', reason: cred.ok ? 'requested' : cred.error, users: null }, null, 2) + '\n')
|
|
230
|
+
return 0
|
|
231
|
+
}
|
|
232
|
+
out.write(
|
|
233
|
+
['spec-sync users: transport = mcp', ` ${cred.ok ? '--via mcp was requested' : cred.error}`, ` ${p.usersOverMcp}`].join('\n') +
|
|
234
|
+
'\n',
|
|
235
|
+
)
|
|
236
|
+
return 0
|
|
237
|
+
}
|
|
238
|
+
if (!cred.ok && !flags.adapter) {
|
|
239
|
+
out.write(`spec-sync users: refusing — ${cred.error}\n`)
|
|
240
|
+
return 1
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
const adapter = flags.adapter || p.makeAdapter(config, cred, flags)
|
|
244
|
+
let page
|
|
245
|
+
try {
|
|
246
|
+
page = await adapter.searchUsers(query || '', { limit: flags.limit || 50, cursor: flags.cursor || null })
|
|
247
|
+
} catch (error) {
|
|
248
|
+
out.write(`spec-sync users: ${error.message}\n`)
|
|
249
|
+
return 1
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
const list = (page && page.users) || []
|
|
253
|
+
if (flags.json) {
|
|
254
|
+
out.write(JSON.stringify({ transport: 'api', users: list, nextCursor: (page && page.nextCursor) || null }, null, 2) + '\n')
|
|
255
|
+
return 0
|
|
256
|
+
}
|
|
257
|
+
if (!list.length) {
|
|
258
|
+
out.write(`spec-sync users: no match for ${JSON.stringify(query || '')}\n`)
|
|
259
|
+
return 0
|
|
260
|
+
}
|
|
261
|
+
const lines = [`spec-sync users: ${list.length} match(es)`]
|
|
262
|
+
for (const u of list) {
|
|
263
|
+
// A deactivated user still resolves by id and can still be assigned, so
|
|
264
|
+
// the marker is the difference between a valid pick and a silently dead one.
|
|
265
|
+
const inactive = u && u.active === false ? ' [deactivated]' : ''
|
|
266
|
+
const email = u && u.email ? ` ${u.email}` : ''
|
|
267
|
+
lines.push(` ${p.displayNameOf(u) || '(unnamed)'} <${u && u.id}>${email}${inactive}`)
|
|
268
|
+
}
|
|
269
|
+
if (page && page.nextCursor) lines.push(` … more — re-run with --cursor ${page.nextCursor}`)
|
|
270
|
+
out.write(lines.join('\n') + '\n')
|
|
271
|
+
return 0
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
return { assign, whoami, users }
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
module.exports = { makeAssignmentCommands }
|
|
@@ -14,31 +14,50 @@
|
|
|
14
14
|
const MAX_RETRIES = 5
|
|
15
15
|
const MAX_BACKOFF_MS = 60_000
|
|
16
16
|
|
|
17
|
-
// How long to wait before retrying a
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
// How long to wait before retrying a rate-limited response: `Retry-After`
|
|
18
|
+
// (seconds) first, then `X-RateLimit-Reset` (an epoch second — GitHub's
|
|
19
|
+
// primary limit names the moment it lifts rather than a duration), then
|
|
20
|
+
// exponential backoff. A reset already in the past falls through to backoff
|
|
21
|
+
// rather than waiting zero and hammering.
|
|
22
|
+
function retryDelay(res, attempt, maxBackoffMs = MAX_BACKOFF_MS, now = Date.now) {
|
|
23
|
+
const get = res.headers && typeof res.headers.get === 'function' ? (h) => res.headers.get(h) : () => null
|
|
24
|
+
const header = get('retry-after')
|
|
20
25
|
const seconds = header != null ? Number(header) : NaN
|
|
21
26
|
if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, maxBackoffMs)
|
|
27
|
+
const reset = Number(get('x-ratelimit-reset'))
|
|
28
|
+
if (Number.isFinite(reset) && reset > 0) {
|
|
29
|
+
const wait = reset * 1000 - now()
|
|
30
|
+
if (wait > 0) return Math.min(wait, maxBackoffMs)
|
|
31
|
+
}
|
|
22
32
|
return Math.min(1000 * 2 ** attempt, maxBackoffMs)
|
|
23
33
|
}
|
|
24
34
|
|
|
35
|
+
// The default answer to "is this response a rate limit?": a 429. A provider
|
|
36
|
+
// whose tracker also signals limits another way (GitHub: a 403 carrying
|
|
37
|
+
// `Retry-After` or a zero `X-RateLimit-Remaining`) passes its own `isLimited`.
|
|
38
|
+
const isTooManyRequests = (res) => res.status === 429
|
|
39
|
+
|
|
25
40
|
/**
|
|
26
41
|
* Run `attempt()` (→ a fetch Response) until it is not rate-limited or the
|
|
27
42
|
* retries run out. Returns `{ response, exhausted }` — `exhausted` true when
|
|
28
|
-
* the LAST response is still
|
|
29
|
-
* marks it retryable: rate limiting is the failure where waiting
|
|
30
|
-
* answer, and the one a refusal must stay distinguishable from).
|
|
43
|
+
* the LAST response is still rate-limited, so the caller phrases its own
|
|
44
|
+
* refusal (and marks it retryable: rate limiting is the failure where waiting
|
|
45
|
+
* is the whole answer, and the one a refusal must stay distinguishable from).
|
|
31
46
|
*/
|
|
32
|
-
async function withRateLimitRetry(
|
|
47
|
+
async function withRateLimitRetry(
|
|
48
|
+
attempt,
|
|
49
|
+
{ sleep, maxRetries = MAX_RETRIES, maxBackoffMs = MAX_BACKOFF_MS, isLimited = isTooManyRequests, now } = {},
|
|
50
|
+
) {
|
|
33
51
|
const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
|
|
34
52
|
for (let n = 0; ; n++) {
|
|
35
53
|
const response = await attempt()
|
|
36
|
-
|
|
37
|
-
|
|
54
|
+
const limited = isLimited(response)
|
|
55
|
+
if (limited && n < maxRetries) {
|
|
56
|
+
await wait(retryDelay(response, n, maxBackoffMs, now))
|
|
38
57
|
continue
|
|
39
58
|
}
|
|
40
|
-
return { response, exhausted:
|
|
59
|
+
return { response, exhausted: limited }
|
|
41
60
|
}
|
|
42
61
|
}
|
|
43
62
|
|
|
44
|
-
module.exports = { withRateLimitRetry, retryDelay, MAX_RETRIES, MAX_BACKOFF_MS }
|
|
63
|
+
module.exports = { withRateLimitRetry, retryDelay, isTooManyRequests, MAX_RETRIES, MAX_BACKOFF_MS }
|
|
@@ -7,16 +7,25 @@
|
|
|
7
7
|
* names never reach it. A commit's `Refs:` trailer is therefore the only place
|
|
8
8
|
* the ticket survives into the range a release scans — see the
|
|
9
9
|
* `commit-trailers` rule. Nothing here is tracker-specific: the identifier
|
|
10
|
-
* shape
|
|
11
|
-
*
|
|
10
|
+
* shape defaults to `KEY-123` (Linear, Jira), and a provider whose refs look
|
|
11
|
+
* different (GitHub's `#123`) passes its own `refPattern`.
|
|
12
12
|
*
|
|
13
13
|
* The parsing half is pure and takes commits as data, so the rules below are
|
|
14
14
|
* testable without git. Reading the range, and enriching refs with issue titles,
|
|
15
15
|
* belong to the caller.
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
|
-
// An issue identifier: uppercase team key, dash, number.
|
|
18
|
+
// An issue identifier: uppercase team key, dash, number. The default, used
|
|
19
|
+
// whenever a caller passes no `refPattern`.
|
|
19
20
|
const IDENTIFIER_RE = /\b[A-Z][A-Z0-9]*-\d+\b/g
|
|
21
|
+
// A GitHub issue ref in the same repo: `#123`.
|
|
22
|
+
//
|
|
23
|
+
// WHAT WOULD FOOL IT: `#` is also how a commit says "issue number" in prose and
|
|
24
|
+
// how `owner/repo#123` names ANOTHER repo's issue. Prose is excluded by the
|
|
25
|
+
// trailer anchor (only a `Refs:` line is scanned); the cross-repo form is
|
|
26
|
+
// excluded by the lookbehind, so a ref into some other repo never lands on this
|
|
27
|
+
// one's release — the GitHub twin of `partitionStageMoves`' foreign team key.
|
|
28
|
+
const GITHUB_REF_RE = /(?<![\w/.-])#\d+\b/g
|
|
20
29
|
// A `Refs:` trailer line. Anchored, so it is a line of its own — never prose
|
|
21
30
|
// that happens to mention the word.
|
|
22
31
|
const TRAILER_RE = /^Refs:[ \t]*(.+?)[ \t]*$/
|
|
@@ -34,7 +43,8 @@ const TRAILER_RE = /^Refs:[ \t]*(.+?)[ \t]*$/
|
|
|
34
43
|
* which is worse than missing a ticket: the missing one is noticed when someone
|
|
35
44
|
* looks for it, the invented one never is.
|
|
36
45
|
*/
|
|
37
|
-
function refsInBody(body) {
|
|
46
|
+
function refsInBody(body, refPattern) {
|
|
47
|
+
const pattern = asGlobal(refPattern) || IDENTIFIER_RE
|
|
38
48
|
const found = []
|
|
39
49
|
let fenced = false
|
|
40
50
|
for (const raw of String(body || '').split('\n')) {
|
|
@@ -48,11 +58,19 @@ function refsInBody(body) {
|
|
|
48
58
|
if (/^ {4,}|\t/.test(line)) continue
|
|
49
59
|
const m = TRAILER_RE.exec(line.trim() === line ? line : line.trimStart())
|
|
50
60
|
if (!m) continue
|
|
51
|
-
for (const id of m[1].match(
|
|
61
|
+
for (const id of m[1].match(pattern) || []) found.push(id)
|
|
52
62
|
}
|
|
53
63
|
return found
|
|
54
64
|
}
|
|
55
65
|
|
|
66
|
+
// `String.prototype.match` only returns every hit for a GLOBAL regex; a
|
|
67
|
+
// provider passing `/#\d+/` would otherwise get its first ref and lose the rest
|
|
68
|
+
// in silence. Anything that is not a RegExp is no pattern at all.
|
|
69
|
+
function asGlobal(pattern) {
|
|
70
|
+
if (!(pattern instanceof RegExp)) return null
|
|
71
|
+
return pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`)
|
|
72
|
+
}
|
|
73
|
+
|
|
56
74
|
/**
|
|
57
75
|
* Whether a commit's changed paths are ENTIRELY bookkeeping.
|
|
58
76
|
*
|
|
@@ -103,10 +121,18 @@ function onlyIgnoredPaths(paths, ignorePaths) {
|
|
|
103
121
|
* Fold commits into the report a release needs.
|
|
104
122
|
*
|
|
105
123
|
* @param {Array<{sha?:string, subject?:string, body?:string, paths?:string[]}>} commits
|
|
106
|
-
* @param {{ignorePaths?:string[]}} [options]
|
|
107
|
-
* see `onlyIgnoredPaths`. Omitted (or
|
|
108
|
-
* report is what it was before the
|
|
109
|
-
*
|
|
124
|
+
* @param {{ignorePaths?:string[], refPattern?:RegExp, foreignPatterns?:RegExp[]}} [options]
|
|
125
|
+
* `ignorePaths` marks bookkeeping — see `onlyIgnoredPaths`. Omitted (or
|
|
126
|
+
* empty) means nothing is ignored, so the report is what it was before the
|
|
127
|
+
* filter existed. `refPattern` is this provider's ref shape (see
|
|
128
|
+
* `refsInBody`). `foreignPatterns` are OTHER trackers' ref shapes this repo
|
|
129
|
+
* used before — a repo that moved from Linear to GitHub still has
|
|
130
|
+
* `Refs: SKS-29` all through its history, and those commits were referenced,
|
|
131
|
+
* just not to this tracker. They are counted as `historical` rather than
|
|
132
|
+
* `unreferenced`, which exists to surface a MISSED trailer.
|
|
133
|
+
* @returns {{tickets: Array<{ref:string, commits:number}>, unreferenced:number, ignored:number, total:number, historical?:number}}
|
|
134
|
+
* `historical` is present only when `foreignPatterns` was given, so a
|
|
135
|
+
* provider that never moved trackers sees exactly the shape it always did.
|
|
110
136
|
* `tickets` is deduped in FIRST-SEEN order: a ticket touched by eight commits
|
|
111
137
|
* is listed once, where it first appears, not eight times. `ignored` is
|
|
112
138
|
* reported rather than merely subtracted — a filter that removes commits in
|
|
@@ -114,9 +140,12 @@ function onlyIgnoredPaths(paths, ignorePaths) {
|
|
|
114
140
|
*/
|
|
115
141
|
function ticketsInRange(commits, options = {}) {
|
|
116
142
|
const ignorePaths = (options && options.ignorePaths) || []
|
|
143
|
+
const refPattern = options && options.refPattern
|
|
144
|
+
const foreign = ((options && options.foreignPatterns) || []).map(asGlobal).filter(Boolean)
|
|
117
145
|
const seen = new Map()
|
|
118
146
|
let unreferenced = 0
|
|
119
147
|
let ignored = 0
|
|
148
|
+
let historical = 0
|
|
120
149
|
for (const commit of commits || []) {
|
|
121
150
|
if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
|
|
122
151
|
// Not counted as unreferenced either: that number exists to surface a
|
|
@@ -124,19 +153,25 @@ function ticketsInRange(commits, options = {}) {
|
|
|
124
153
|
ignored++
|
|
125
154
|
continue
|
|
126
155
|
}
|
|
127
|
-
const refs = [...new Set(refsInBody(commit && commit.body))]
|
|
156
|
+
const refs = [...new Set(refsInBody(commit && commit.body, refPattern))]
|
|
128
157
|
if (!refs.length) {
|
|
129
|
-
|
|
158
|
+
// A POSITIVE signal, never an absence: only a trailer that actually
|
|
159
|
+
// carries an older tracker's ref makes a commit historical. A commit with
|
|
160
|
+
// no trailer at all is still the gap `unreferenced` is there to name.
|
|
161
|
+
if (foreign.some((p) => refsInBody(commit && commit.body, p).length)) historical++
|
|
162
|
+
else unreferenced++
|
|
130
163
|
continue
|
|
131
164
|
}
|
|
132
165
|
for (const ref of refs) seen.set(ref, (seen.get(ref) || 0) + 1)
|
|
133
166
|
}
|
|
134
|
-
|
|
167
|
+
const report = {
|
|
135
168
|
tickets: [...seen.entries()].map(([ref, count]) => ({ ref, commits: count })),
|
|
136
169
|
unreferenced,
|
|
137
170
|
ignored,
|
|
138
171
|
total: (commits || []).length,
|
|
139
172
|
}
|
|
173
|
+
if (foreign.length) report.historical = historical
|
|
174
|
+
return report
|
|
140
175
|
}
|
|
141
176
|
|
|
142
177
|
/**
|
|
@@ -223,4 +258,12 @@ function stageOrderWarning(stages, fromState, toKey, lifecycleStates = []) {
|
|
|
223
258
|
return null
|
|
224
259
|
}
|
|
225
260
|
|
|
226
|
-
module.exports = {
|
|
261
|
+
module.exports = {
|
|
262
|
+
ticketsInRange,
|
|
263
|
+
refsInBody,
|
|
264
|
+
onlyIgnoredPaths,
|
|
265
|
+
partitionStageMoves,
|
|
266
|
+
stageOrderWarning,
|
|
267
|
+
IDENTIFIER_RE,
|
|
268
|
+
GITHUB_REF_RE,
|
|
269
|
+
}
|