@skitterbyte/skitterspec-linear 18.0.1 → 18.1.1
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 +81 -0
- package/assets/core/env.config.md +36 -9
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/rules/spec-planning.md +4 -2
- package/assets/skills/spec-complete/SKILL.md +67 -25
- package/assets/skills/spec-hotfix/SKILL.md +21 -11
- package/assets/skills/spec-sync/SKILL.md +10 -1
- package/package.json +1 -1
- package/src/cli.js +289 -34
- package/src/env/config.js +14 -2
- package/src/env/hotfix.js +288 -16
- package/src/env/hotfixland.js +302 -0
- package/src/env/resolve.js +22 -8
- package/src/init.js +36 -4
- package/src/vendor/linear/api.js +43 -56
- package/src/vendor/linear/cli-sanitise.js +2 -2
- package/src/vendor/linear/cli-sync.js +87 -390
- package/src/vendor/linear/config.js +46 -171
- package/src/vendor/linear/credentials.js +40 -370
- package/src/vendor/linear/dialect.js +177 -0
- package/src/vendor/linear/doctor.js +7 -15
- package/src/vendor/linear/identity.js +20 -70
- package/src/vendor/linear/released.js +4 -222
- package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
- package/src/vendor/provider-kit/index.js +41 -0
- package/src/vendor/provider-kit/src/adapter.js +23 -0
- package/src/vendor/provider-kit/src/apply.js +197 -0
- package/src/vendor/provider-kit/src/args.js +68 -0
- package/src/vendor/provider-kit/src/config.js +198 -0
- package/src/vendor/provider-kit/src/credentials.js +404 -0
- package/src/vendor/provider-kit/src/doctor.js +35 -0
- package/src/vendor/provider-kit/src/http.js +44 -0
- package/src/vendor/provider-kit/src/identity.js +93 -0
- package/src/vendor/provider-kit/src/md-compare.js +39 -0
- package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
- package/src/vendor/provider-kit/src/prompt.js +50 -0
- package/src/vendor/provider-kit/src/released.js +226 -0
- package/src/vendor/provider-kit/src/specs.js +166 -0
- package/src/vendor/provider-kit/src/transport.js +22 -0
- package/src/vendor/sync-core/index.js +22 -5
- package/src/vendor/sync-core/src/compare.js +14 -12
- package/src/vendor/sync-core/src/dialect.js +51 -0
- package/src/vendor/sync-core/src/fields.js +36 -0
- package/src/vendor/sync-core/src/legacy.js +19 -9
- package/src/vendor/sync-core/src/normalize.js +30 -158
- package/src/vendor/sync-core/src/push.js +1 -1
- package/src/vendor/sync-core/src/retarget.js +21 -17
- package/src/vendor/sync-core/src/verify.js +24 -45
- package/src/vendor/sync-core/src/write.js +7 -5
|
@@ -34,6 +34,9 @@
|
|
|
34
34
|
const { readFileSync } = require('node:fs')
|
|
35
35
|
const { join } = require('node:path')
|
|
36
36
|
|
|
37
|
+
const { dialect } = require('./dialect.js')
|
|
38
|
+
const kitConfig = require('../provider-kit/src/config.js')
|
|
39
|
+
|
|
37
40
|
const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
|
|
38
41
|
|
|
39
42
|
// `none` is how a repo DECLINES a field the defaults own. It has to be a
|
|
@@ -161,6 +164,21 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
161
164
|
cancelled: 'Canceled',
|
|
162
165
|
}),
|
|
163
166
|
snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
|
|
167
|
+
// The frontmatter FIELD VOCABULARY this provider stamps into spec files. The
|
|
168
|
+
// engine reads and writes stamps by these names and hardcodes none of them
|
|
169
|
+
// (sync-core `src/fields.js`); the two `legacy*` keys are what the pre-9.0
|
|
170
|
+
// model wrote, and exist so `detectLegacyMirror` can still recognise a
|
|
171
|
+
// stranded mirror. Not user-configurable: the names are this provider's
|
|
172
|
+
// contract with every spec it ever stamped.
|
|
173
|
+
fields: Object.freeze({
|
|
174
|
+
identifier: 'linear_identifier',
|
|
175
|
+
url: 'linear_url',
|
|
176
|
+
issueId: 'linear_issue_id',
|
|
177
|
+
assigneeId: 'linear_assignee_id',
|
|
178
|
+
assigneeName: 'linear_assignee_name',
|
|
179
|
+
legacyIdentifier: 'linear_project_id',
|
|
180
|
+
legacyIssueId: 'linear_milestone_id',
|
|
181
|
+
}),
|
|
164
182
|
// See DEFAULT_RELEASE_STAGES above. `stages` is ordered: the order is recorded
|
|
165
183
|
// for reporting and doctor's ladder check, and deliberately NOT enforced — a
|
|
166
184
|
// rollback from test and a hotfix going straight to prod are both legitimate.
|
|
@@ -259,10 +277,6 @@ const ENV_CONFIG_DEFAULTS = Object.freeze({
|
|
|
259
277
|
// so they cannot drift apart.
|
|
260
278
|
const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
|
|
261
279
|
|
|
262
|
-
function isObject(value) {
|
|
263
|
-
return value !== null && typeof value === 'object' && !Array.isArray(value)
|
|
264
|
-
}
|
|
265
|
-
|
|
266
280
|
// A fresh, deeply-mutable copy of the defaults to merge onto.
|
|
267
281
|
function defaults() {
|
|
268
282
|
return {
|
|
@@ -276,6 +290,7 @@ function defaults() {
|
|
|
276
290
|
mapping: { ...DEFAULT_CONFIG.mapping },
|
|
277
291
|
states: { ...DEFAULT_CONFIG.states },
|
|
278
292
|
snapshot: { ...DEFAULT_CONFIG.snapshot },
|
|
293
|
+
fields: { ...DEFAULT_CONFIG.fields },
|
|
279
294
|
release: {
|
|
280
295
|
stages: DEFAULT_CONFIG.release.stages.map((s) => ({ ...s })),
|
|
281
296
|
ignorePaths: [...DEFAULT_CONFIG.release.ignorePaths],
|
|
@@ -293,172 +308,17 @@ function defaults() {
|
|
|
293
308
|
}
|
|
294
309
|
}
|
|
295
310
|
|
|
296
|
-
//
|
|
297
|
-
//
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
}
|
|
307
|
-
}
|
|
308
|
-
|
|
309
|
-
// Normalise an array config value to trimmed, non-empty strings.
|
|
310
|
-
function stringList(value) {
|
|
311
|
-
return value.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
// Merge (and validate) sync.fieldOwnership. Any key the caller lists joins the
|
|
315
|
-
// compared field set; the value MUST be one of both|pull|push.
|
|
316
|
-
function mergeFieldOwnership(base, parsed) {
|
|
317
|
-
if (!isObject(parsed)) return
|
|
318
|
-
for (const [field, dir] of Object.entries(parsed)) {
|
|
319
|
-
if (!OWNERSHIP.includes(dir)) {
|
|
320
|
-
throw new Error(
|
|
321
|
-
`Invalid ${CONFIG_FILE}: sync.fieldOwnership.${field} = ${JSON.stringify(dir)} ` +
|
|
322
|
-
`(expected one of ${OWNERSHIP.join('|')})`,
|
|
323
|
-
)
|
|
324
|
-
}
|
|
325
|
-
base[field] = dir
|
|
326
|
-
}
|
|
327
|
-
}
|
|
328
|
-
|
|
329
|
-
// Merge (and validate) `mapping.phases` in either of its two forms: a scalar
|
|
330
|
-
// mode for the whole repo, or a map of lifecycle bucket → mode. Loud on a bad
|
|
331
|
-
// key or value, like fieldOwnership and mapping.tasks — a misspelt bucket would
|
|
332
|
-
// otherwise read as a deliberate default and go on minting the sub-issues the
|
|
333
|
-
// config was written to stop.
|
|
334
|
-
function mergePhaseMapping(base, parsed) {
|
|
335
|
-
const value = parsed.phases
|
|
336
|
-
if (typeof value === 'string') {
|
|
337
|
-
if (value.trim()) base.phases = value.trim()
|
|
338
|
-
} else if (isObject(value)) {
|
|
339
|
-
const byBucket = {}
|
|
340
|
-
for (const [bucket, mode] of Object.entries(value)) {
|
|
341
|
-
if (!LIFECYCLE_BUCKETS.includes(bucket)) {
|
|
342
|
-
throw new Error(
|
|
343
|
-
`Invalid ${CONFIG_FILE}: mapping.phases.${bucket} is not a lifecycle bucket ` +
|
|
344
|
-
`(expected one of ${LIFECYCLE_BUCKETS.join('|')})`,
|
|
345
|
-
)
|
|
346
|
-
}
|
|
347
|
-
if (!PHASE_MAPPINGS.includes(mode)) {
|
|
348
|
-
throw new Error(
|
|
349
|
-
`Invalid ${CONFIG_FILE}: mapping.phases.${bucket} = ${JSON.stringify(mode)} ` +
|
|
350
|
-
`(expected one of ${PHASE_MAPPINGS.join('|')})`,
|
|
351
|
-
)
|
|
352
|
-
}
|
|
353
|
-
byBucket[bucket] = mode
|
|
354
|
-
}
|
|
355
|
-
base.phases = byBucket
|
|
356
|
-
} else if (value !== undefined) {
|
|
357
|
-
throw new Error(
|
|
358
|
-
`Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(value)} ` +
|
|
359
|
-
`(expected one of ${PHASE_MAPPINGS.join('|')}, or a map of lifecycle bucket to mode)`,
|
|
360
|
-
)
|
|
361
|
-
}
|
|
362
|
-
if (typeof base.phases === 'string' && !PHASE_MAPPINGS.includes(base.phases)) {
|
|
363
|
-
throw new Error(
|
|
364
|
-
`Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(base.phases)} ` +
|
|
365
|
-
`(expected one of ${PHASE_MAPPINGS.join('|')}, or a map of lifecycle bucket to mode)`,
|
|
366
|
-
)
|
|
367
|
-
}
|
|
368
|
-
}
|
|
369
|
-
|
|
370
|
-
// Merge (and validate) `release.stages` — the project's deployment ladder.
|
|
371
|
-
//
|
|
372
|
-
// Loud on a malformed entry, like fieldOwnership and mapping.phases above: this
|
|
373
|
-
// list names Linear states, and Linear SILENTLY IGNORES an unknown state. A
|
|
374
|
-
// half-typed ladder would push clean and move nothing, which is exactly the
|
|
375
|
-
// failure `validateStates` exists to stop — so a bad shape fails here, at load,
|
|
376
|
-
// rather than at the first deploy nobody is watching.
|
|
377
|
-
//
|
|
378
|
-
// An ABSENT `release` block is not an error: it is the opt-out, and the whole
|
|
379
|
-
// feature is unused without it.
|
|
380
|
-
function mergeReleaseStages(base, parsed) {
|
|
381
|
-
const value = parsed.stages
|
|
382
|
-
if (value === undefined) return
|
|
383
|
-
if (!Array.isArray(value)) {
|
|
384
|
-
throw new Error(
|
|
385
|
-
`Invalid ${CONFIG_FILE}: release.stages = ${JSON.stringify(value)} ` +
|
|
386
|
-
'(expected an array of { key, state })',
|
|
387
|
-
)
|
|
388
|
-
}
|
|
389
|
-
const stages = []
|
|
390
|
-
const seen = new Set()
|
|
391
|
-
value.forEach((entry, i) => {
|
|
392
|
-
if (!isObject(entry)) {
|
|
393
|
-
throw new Error(
|
|
394
|
-
`Invalid ${CONFIG_FILE}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
|
|
395
|
-
'(expected { key, state })',
|
|
396
|
-
)
|
|
397
|
-
}
|
|
398
|
-
for (const field of ['key', 'state']) {
|
|
399
|
-
if (typeof entry[field] !== 'string' || !entry[field].trim()) {
|
|
400
|
-
throw new Error(
|
|
401
|
-
`Invalid ${CONFIG_FILE}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
|
|
402
|
-
'(expected a non-empty string)',
|
|
403
|
-
)
|
|
404
|
-
}
|
|
405
|
-
}
|
|
406
|
-
const key = entry.key.trim()
|
|
407
|
-
if (seen.has(key)) {
|
|
408
|
-
throw new Error(
|
|
409
|
-
`Invalid ${CONFIG_FILE}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
|
|
410
|
-
'(a stage key is how CI names the rung, so it must be unique)',
|
|
411
|
-
)
|
|
412
|
-
}
|
|
413
|
-
seen.add(key)
|
|
414
|
-
stages.push({ key, state: entry.state.trim() })
|
|
415
|
-
})
|
|
416
|
-
base.stages = stages
|
|
417
|
-
}
|
|
418
|
-
|
|
419
|
-
// Merge (and validate) release.ignorePaths — the path prefixes whose commits are
|
|
420
|
-
// bookkeeping. Loud on anything but an array of non-empty strings, like
|
|
421
|
-
// release.stages above: a bad value that quietly fell back to the default would
|
|
422
|
-
// let a project believe it had opted out and go on double-counting tickets.
|
|
423
|
-
//
|
|
424
|
-
// A BLANK entry is rejected rather than dropped. `""` is a prefix of every path,
|
|
425
|
-
// so a stray empty string would silently ignore every commit in the range and
|
|
426
|
-
// report a release as containing nothing — the loudest possible wrong answer,
|
|
427
|
-
// arriving as silence.
|
|
428
|
-
function mergeReleaseIgnorePaths(base, parsed) {
|
|
429
|
-
const value = parsed.ignorePaths
|
|
430
|
-
if (value === undefined) return
|
|
431
|
-
if (!Array.isArray(value)) {
|
|
432
|
-
throw new Error(
|
|
433
|
-
`Invalid ${CONFIG_FILE}: release.ignorePaths = ${JSON.stringify(value)} ` +
|
|
434
|
-
'(expected an array of repo-relative path prefixes)',
|
|
435
|
-
)
|
|
436
|
-
}
|
|
437
|
-
value.forEach((entry, i) => {
|
|
438
|
-
if (typeof entry !== 'string' || !entry.trim()) {
|
|
439
|
-
throw new Error(
|
|
440
|
-
`Invalid ${CONFIG_FILE}: release.ignorePaths[${i}] = ${JSON.stringify(entry)} ` +
|
|
441
|
-
'(expected a non-empty repo-relative path prefix, e.g. "specs/")',
|
|
442
|
-
)
|
|
443
|
-
}
|
|
311
|
+
// The merge machinery is the kit's, bound to this provider's file name and
|
|
312
|
+
// vocabularies; `mergeConfig` below is the part that is Linear's — which keys
|
|
313
|
+
// exist and how they nest.
|
|
314
|
+
const { isObject, stringList, assign } = kitConfig
|
|
315
|
+
const { mergeFieldOwnership, mergePhaseMapping, mergeReleaseStages, mergeReleaseIgnorePaths, mergeKeyedFields } =
|
|
316
|
+
kitConfig.makeMergeHelpers({
|
|
317
|
+
configFile: CONFIG_FILE,
|
|
318
|
+
ownership: OWNERSHIP,
|
|
319
|
+
lifecycleBuckets: LIFECYCLE_BUCKETS,
|
|
320
|
+
phaseMappings: PHASE_MAPPINGS,
|
|
444
321
|
})
|
|
445
|
-
base.ignorePaths = stringList(value)
|
|
446
|
-
}
|
|
447
|
-
|
|
448
|
-
// Merge (and validate) sync.keyedFields. Each value is the item's id property
|
|
449
|
-
// name (a non-empty string); a field listed here is compared per item.
|
|
450
|
-
function mergeKeyedFields(base, parsed) {
|
|
451
|
-
if (!isObject(parsed)) return
|
|
452
|
-
for (const [field, idKey] of Object.entries(parsed)) {
|
|
453
|
-
if (typeof idKey !== 'string' || !idKey.trim()) {
|
|
454
|
-
throw new Error(
|
|
455
|
-
`Invalid ${CONFIG_FILE}: sync.keyedFields.${field} = ${JSON.stringify(idKey)} ` +
|
|
456
|
-
'(expected the item id property name, a non-empty string)',
|
|
457
|
-
)
|
|
458
|
-
}
|
|
459
|
-
base[field] = idKey.trim()
|
|
460
|
-
}
|
|
461
|
-
}
|
|
462
322
|
|
|
463
323
|
/**
|
|
464
324
|
* Merge a parsed config over the defaults. Only known keys are copied (unknown
|
|
@@ -557,6 +417,21 @@ function mergeConfig(base, parsed) {
|
|
|
557
417
|
* Malformed JSON, a bad `fieldOwnership` enum, or a malformed `release.stages`
|
|
558
418
|
* entry → throws a clear Error.
|
|
559
419
|
*/
|
|
420
|
+
// Attach the parts of the provider contract that are code, not JSON: the
|
|
421
|
+
// markdown dialect (sync-core calls its hooks wherever it used to hardcode
|
|
422
|
+
// Linear's quirks) and the `provider` block retarget reads (which config file
|
|
423
|
+
// records the team key, and under which JSON field). Runs on BOTH loader paths
|
|
424
|
+
// so an absent config still carries them.
|
|
425
|
+
function withRuntime(config) {
|
|
426
|
+
config.dialect = dialect
|
|
427
|
+
config.provider = {
|
|
428
|
+
teamKey: (config.linear && config.linear.teamKey) || '',
|
|
429
|
+
configFile: CONFIG_FILE,
|
|
430
|
+
teamKeyJsonField: 'teamKey',
|
|
431
|
+
}
|
|
432
|
+
return config
|
|
433
|
+
}
|
|
434
|
+
|
|
560
435
|
function loadLinearConfig(dir = process.cwd()) {
|
|
561
436
|
const base = defaults()
|
|
562
437
|
const file = join(dir, CONFIG_FILE)
|
|
@@ -565,7 +440,7 @@ function loadLinearConfig(dir = process.cwd()) {
|
|
|
565
440
|
try {
|
|
566
441
|
raw = readFileSync(file, 'utf-8')
|
|
567
442
|
} catch (error) {
|
|
568
|
-
if (error.code === 'ENOENT') return { config: base, present: false }
|
|
443
|
+
if (error.code === 'ENOENT') return { config: withRuntime(base), present: false }
|
|
569
444
|
throw error
|
|
570
445
|
}
|
|
571
446
|
|
|
@@ -576,7 +451,7 @@ function loadLinearConfig(dir = process.cwd()) {
|
|
|
576
451
|
throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
|
|
577
452
|
}
|
|
578
453
|
|
|
579
|
-
return { config: mergeConfig(base, parsed), present: true }
|
|
454
|
+
return { config: withRuntime(mergeConfig(base, parsed)), present: true }
|
|
580
455
|
}
|
|
581
456
|
|
|
582
457
|
/**
|