@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.
- package/MIGRATION.md +170 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +59 -48
- package/assets/rules/spec-planning.md +35 -12
- package/assets/rules/spec-reports.md +47 -6
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +32 -9
- package/assets/skills/spec-bug/SKILL.md +6 -4
- 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 +5 -3
- 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 +114 -28
- package/src/env/resolve.js +11 -4
- package/src/env/review.js +126 -2
- package/src/vendor/linear/api.js +30 -1
- package/src/vendor/linear/cli-sync.js +64 -269
- package/src/vendor/linear/config.js +30 -49
- 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 +60 -59
- package/assets/core/ci-stages.md +0 -110
- 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: {
|
|
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({
|
|
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
|
-
//
|
|
183
|
-
//
|
|
184
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
}
|