@skitterbyte/skitterspec-linear 18.3.1 → 19.1.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.
Files changed (36) hide show
  1. package/MIGRATION.md +170 -1
  2. package/README.md +9 -7
  3. package/assets/core/SETUP.md +4 -4
  4. package/assets/core/env.config.md +1 -1
  5. package/assets/core/linear.config.json.example +2 -1
  6. package/assets/core/linear.config.md +59 -48
  7. package/assets/rules/spec-planning.md +35 -12
  8. package/assets/rules/spec-reports.md +47 -6
  9. package/assets/skills/no-spec/SKILL.md +2 -2
  10. package/assets/skills/spec/SKILL.md +32 -9
  11. package/assets/skills/spec-bug/SKILL.md +6 -4
  12. package/assets/skills/spec-hotfix/SKILL.md +4 -2
  13. package/assets/skills/spec-linear-setup/SKILL.md +9 -35
  14. package/assets/skills/spec-list/SKILL.md +13 -1
  15. package/assets/skills/spec-next/SKILL.md +5 -3
  16. package/assets/skills/spec-push/SKILL.md +1 -1
  17. package/assets/skills/spec-status/SKILL.md +30 -26
  18. package/assets/skills/spec-sync/SKILL.md +6 -5
  19. package/package.json +1 -1
  20. package/src/cli.js +114 -28
  21. package/src/env/resolve.js +11 -4
  22. package/src/env/review.js +126 -2
  23. package/src/vendor/linear/api.js +30 -1
  24. package/src/vendor/linear/cli-sync.js +64 -269
  25. package/src/vendor/linear/config.js +30 -49
  26. package/src/vendor/linear/doctor.js +4 -66
  27. package/src/vendor/provider-kit/src/config.js +101 -48
  28. package/src/vendor/provider-kit/src/list-assignee.js +71 -0
  29. package/src/vendor/provider-kit/src/list-rows.js +35 -0
  30. package/src/vendor/provider-kit/src/released.js +27 -77
  31. package/src/vendor/provider-kit/src/specs.js +89 -7
  32. package/src/vendor/sync-core/index.js +3 -4
  33. package/src/vendor/sync-core/src/compare.js +6 -6
  34. package/src/vendor/sync-core/src/normalize.js +60 -59
  35. package/assets/core/ci-stages.md +0 -110
  36. package/src/vendor/provider-kit/src/releases.js +0 -380
@@ -20,7 +20,7 @@
20
20
  * intake: { label, bugLabels, hotfixLabels, preserveOriginal },
21
21
  * mapping: { specFolder, phases, tasks },
22
22
  * states: { backlog, "in-progress", complete, cancelled },
23
- * release: { stages: [{ key, state }] },
23
+ * release: { ignorePaths },
24
24
  * snapshot: { overviewFile },
25
25
  * branch: { pattern },
26
26
  * sync: {
@@ -89,19 +89,6 @@ const TRANSPORTS = Object.freeze(['api', 'mcp'])
89
89
  // nothing secret is ever written to the repo.
90
90
  const DEFAULT_KEY_ENV = 'LINEAR_API_KEY'
91
91
 
92
- // The project's OWN deployment ladder: where a ticket goes AFTER its spec is
93
- // complete — deployed to test, approved for demo, live in prod. Deliberately an
94
- // open, ORDERED list in the project's vocabulary rather than a fixed set: one
95
- // team's `On Test`/`Ready for Demo` is another's `staging`, and most projects
96
- // have none at all. Empty (the default) means the project declared no ladder,
97
- // and every stage-aware path is simply unused.
98
- //
99
- // It is NOT keyed by lifecycle bucket, unlike `states` and `mapping.phases`.
100
- // A deployment stage is a fact about an ENVIRONMENT, and no folder under
101
- // `specs/` can ever derive one — which is why it must not join
102
- // LIFECYCLE_BUCKETS.
103
- const DEFAULT_RELEASE_STAGES = Object.freeze([])
104
-
105
92
  // Repo-relative path prefixes whose commits are BOOKKEEPING, not shipped work.
106
93
  //
107
94
  // A spec's `chore(spec): complete <name>` commit carries the same `Refs:`
@@ -126,7 +113,17 @@ const DEFAULT_CONFIG = Object.freeze({
126
113
  // call only and never stored in the spec or the snapshot, so a PM re-homing the
127
114
  // issue in Linear is invisible to sync. (The old `initiativeId` grouped
128
115
  // Projects, which no longer exist.)
129
- linear: Object.freeze({ teamKey: '', teamId: '', projectId: '' }),
116
+ linear: Object.freeze({
117
+ teamKey: '',
118
+ teamId: '',
119
+ projectId: '',
120
+ // One label per SPEC KIND (`feature`/`bug`/`hotfix`/`chore`, from the spec
121
+ // folder's prefix), applied at mint when set — `{ "chore": "Chore" }`
122
+ // keeps tooling work filterable out of release views. The label must
123
+ // already exist on the team; a missing one is a one-line note, never a
124
+ // failed push. Empty means no kind label, as before.
125
+ labelsByKind: Object.freeze({}),
126
+ }),
130
127
  // Issue intake (`/spec <ISSUE-REF>`, `/spec --from-issue`). `label` is the
131
128
  // inbox filter — issues carrying it are what the web app files; `bugLabels`
132
129
  // route an issue to `/spec-bug` instead of `/spec`, and `hotfixLabels` route it
@@ -179,12 +176,9 @@ const DEFAULT_CONFIG = Object.freeze({
179
176
  legacyIdentifier: 'linear_project_id',
180
177
  legacyIssueId: 'linear_milestone_id',
181
178
  }),
182
- // See DEFAULT_RELEASE_STAGES above. `stages` is ordered: the order is recorded
183
- // for reporting and doctor's ladder check, and deliberately NOT enforced — a
184
- // rollback from test and a hotfix going straight to prod are both legitimate.
185
- // `ignorePaths` (see DEFAULT_RELEASE_IGNORE_PATHS) is what `released`/`stage`
186
- // treat as bookkeeping rather than shipped work.
187
- release: Object.freeze({ stages: DEFAULT_RELEASE_STAGES, ignorePaths: DEFAULT_RELEASE_IGNORE_PATHS }),
179
+ // `ignorePaths` (see DEFAULT_RELEASE_IGNORE_PATHS) is what `released` treats
180
+ // as bookkeeping rather than shipped work.
181
+ release: Object.freeze({ ignorePaths: DEFAULT_RELEASE_IGNORE_PATHS }),
188
182
  branch: Object.freeze({ pattern: '{type}/{slug}' }),
189
183
  // `keyEnv` names the env var holding the personal API key. It is a NAME, not a
190
184
  // key: putting the secret itself here would commit it.
@@ -280,7 +274,7 @@ const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
280
274
  // A fresh, deeply-mutable copy of the defaults to merge onto.
281
275
  function defaults() {
282
276
  return {
283
- linear: { ...DEFAULT_CONFIG.linear },
277
+ linear: { ...DEFAULT_CONFIG.linear, labelsByKind: { ...DEFAULT_CONFIG.linear.labelsByKind } },
284
278
  intake: {
285
279
  label: DEFAULT_CONFIG.intake.label,
286
280
  bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
@@ -289,10 +283,10 @@ function defaults() {
289
283
  },
290
284
  mapping: { ...DEFAULT_CONFIG.mapping },
291
285
  states: { ...DEFAULT_CONFIG.states },
286
+ stateAliases: {},
292
287
  snapshot: { ...DEFAULT_CONFIG.snapshot },
293
288
  fields: { ...DEFAULT_CONFIG.fields },
294
289
  release: {
295
- stages: DEFAULT_CONFIG.release.stages.map((s) => ({ ...s })),
296
290
  ignorePaths: [...DEFAULT_CONFIG.release.ignorePaths],
297
291
  },
298
292
  branch: { ...DEFAULT_CONFIG.branch },
@@ -312,7 +306,7 @@ function defaults() {
312
306
  // vocabularies; `mergeConfig` below is the part that is Linear's — which keys
313
307
  // exist and how they nest.
314
308
  const { isObject, stringList, assign } = kitConfig
315
- const { mergeFieldOwnership, mergePhaseMapping, mergeReleaseStages, mergeReleaseIgnorePaths, mergeKeyedFields } =
309
+ const { mergeStates, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
316
310
  kitConfig.makeMergeHelpers({
317
311
  configFile: CONFIG_FILE,
318
312
  ownership: OWNERSHIP,
@@ -331,6 +325,16 @@ function mergeConfig(base, parsed) {
331
325
  assign(base.linear, parsed.linear, 'teamKey', 'string?')
332
326
  assign(base.linear, parsed.linear, 'teamId', 'string?')
333
327
  assign(base.linear, parsed.linear, 'projectId', 'string?')
328
+ if (isObject(parsed.linear.labelsByKind)) {
329
+ // Only the kinds a spec folder can actually be — an unknown key is
330
+ // dropped, matching the other providers' by-kind validation.
331
+ const byKind = {}
332
+ for (const kind of ['feature', 'bug', 'hotfix', 'chore']) {
333
+ const value = parsed.linear.labelsByKind[kind]
334
+ if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
335
+ }
336
+ base.linear.labelsByKind = byKind
337
+ }
334
338
  }
335
339
 
336
340
  if (isObject(parsed.intake)) {
@@ -361,18 +365,13 @@ function mergeConfig(base, parsed) {
361
365
  mergePhaseMapping(base.mapping, parsed.mapping)
362
366
  }
363
367
 
364
- if (isObject(parsed.states)) {
365
- for (const key of Object.keys(base.states)) {
366
- assign(base.states, parsed.states, key, 'string')
367
- }
368
- }
368
+ mergeStates(base, parsed)
369
369
 
370
370
  if (isObject(parsed.snapshot)) {
371
371
  assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
372
372
  }
373
373
 
374
374
  if (isObject(parsed.release)) {
375
- mergeReleaseStages(base.release, parsed.release)
376
375
  mergeReleaseIgnorePaths(base.release, parsed.release)
377
376
  }
378
377
 
@@ -414,8 +413,7 @@ function mergeConfig(base, parsed) {
414
413
  * Returns `{ config, present }`:
415
414
  * - missing file → `{ config: defaults, present: false }` (opt-out; never throws)
416
415
  * - present → `{ config: merged, present: true }`
417
- * Malformed JSON, a bad `fieldOwnership` enum, or a malformed `release.stages`
418
- * entry → throws a clear Error.
416
+ * Malformed JSON or a bad `fieldOwnership` enum → throws a clear Error.
419
417
  */
420
418
  // Attach the parts of the provider contract that are code, not JSON: the
421
419
  // markdown dialect (sync-core calls its hooks wherever it used to hardcode
@@ -454,21 +452,6 @@ function loadLinearConfig(dir = process.cwd()) {
454
452
  return { config: withRuntime(mergeConfig(base, parsed)), present: true }
455
453
  }
456
454
 
457
- /**
458
- * The project's declared deployment ladder, always an array (empty = none
459
- * declared). Callers read this rather than reaching into the config, so an
460
- * older config object without a `release` block cannot throw.
461
- */
462
- function releaseStages(config) {
463
- const stages = config && config.release && config.release.stages
464
- return Array.isArray(stages) ? stages : []
465
- }
466
-
467
- /** The ladder rung with this key, or null. */
468
- function stageFor(config, key) {
469
- return releaseStages(config).find((s) => s.key === key) || null
470
- }
471
-
472
455
  /**
473
456
  * The path prefixes whose commits are bookkeeping, always an array.
474
457
  *
@@ -484,9 +467,7 @@ function releaseIgnorePaths(config) {
484
467
 
485
468
  module.exports = {
486
469
  loadLinearConfig,
487
- releaseStages,
488
470
  releaseIgnorePaths,
489
- stageFor,
490
471
  mergeConfig,
491
472
  defaults,
492
473
  DEFAULT_CONFIG,
@@ -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. A ladder whose
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
- module.exports = { isObject, stringList, assign, makeMergeHelpers }
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 — the GitHub twin of `partitionStageMoves`' foreign team key.
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
- * Split a release's tickets into the ones a stage move may touch and the ones it
179
- * must not, with a reason for every exclusion.
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
- * Three reasons to leave a ticket alone, and each is a case where acting would
182
- * be worse than not acting:
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
- * - **foreign** — the ref is not this repo's team. A range can carry another
185
- * team's ref (a shared dependency, a quoted ticket), and writing to a team
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 partitionStageMoves({ tickets, teamKey, specs, cededBucket = 'complete' }) {
198
- const bucketOf = new Map()
199
- for (const spec of specs || []) {
200
- if (spec && spec.identifier) bucketOf.set(spec.identifier, spec.bucket)
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 { movable, foreign, unlinked, unfinished }
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
- * Whether moving from `fromState` to the rung `toKey` runs against the declared
225
- * order — and if so, how to say it.
226
- *
227
- * WARNS, never refuses. A rollback from test and a hotfix going straight to prod
228
- * are both legitimate, and a check that blocked either would be wrong on healthy
229
- * input. An issue that is on no rung yet is entering the ladder, which is the
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
- if (lifecycle.has(want)) return null
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
  }