@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.
Files changed (50) hide show
  1. package/MIGRATION.md +81 -0
  2. package/assets/core/env.config.md +36 -9
  3. package/assets/hooks/main-guard.cjs +1 -1
  4. package/assets/hooks/review-gate.cjs +1 -1
  5. package/assets/rules/spec-planning.md +4 -2
  6. package/assets/skills/spec-complete/SKILL.md +67 -25
  7. package/assets/skills/spec-hotfix/SKILL.md +21 -11
  8. package/assets/skills/spec-sync/SKILL.md +10 -1
  9. package/package.json +1 -1
  10. package/src/cli.js +289 -34
  11. package/src/env/config.js +14 -2
  12. package/src/env/hotfix.js +288 -16
  13. package/src/env/hotfixland.js +302 -0
  14. package/src/env/resolve.js +22 -8
  15. package/src/init.js +36 -4
  16. package/src/vendor/linear/api.js +43 -56
  17. package/src/vendor/linear/cli-sanitise.js +2 -2
  18. package/src/vendor/linear/cli-sync.js +87 -390
  19. package/src/vendor/linear/config.js +46 -171
  20. package/src/vendor/linear/credentials.js +40 -370
  21. package/src/vendor/linear/dialect.js +177 -0
  22. package/src/vendor/linear/doctor.js +7 -15
  23. package/src/vendor/linear/identity.js +20 -70
  24. package/src/vendor/linear/released.js +4 -222
  25. package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
  26. package/src/vendor/provider-kit/index.js +41 -0
  27. package/src/vendor/provider-kit/src/adapter.js +23 -0
  28. package/src/vendor/provider-kit/src/apply.js +197 -0
  29. package/src/vendor/provider-kit/src/args.js +68 -0
  30. package/src/vendor/provider-kit/src/config.js +198 -0
  31. package/src/vendor/provider-kit/src/credentials.js +404 -0
  32. package/src/vendor/provider-kit/src/doctor.js +35 -0
  33. package/src/vendor/provider-kit/src/http.js +44 -0
  34. package/src/vendor/provider-kit/src/identity.js +93 -0
  35. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  36. package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
  37. package/src/vendor/provider-kit/src/prompt.js +50 -0
  38. package/src/vendor/provider-kit/src/released.js +226 -0
  39. package/src/vendor/provider-kit/src/specs.js +166 -0
  40. package/src/vendor/provider-kit/src/transport.js +22 -0
  41. package/src/vendor/sync-core/index.js +22 -5
  42. package/src/vendor/sync-core/src/compare.js +14 -12
  43. package/src/vendor/sync-core/src/dialect.js +51 -0
  44. package/src/vendor/sync-core/src/fields.js +36 -0
  45. package/src/vendor/sync-core/src/legacy.js +19 -9
  46. package/src/vendor/sync-core/src/normalize.js +30 -158
  47. package/src/vendor/sync-core/src/push.js +1 -1
  48. package/src/vendor/sync-core/src/retarget.js +21 -17
  49. package/src/vendor/sync-core/src/verify.js +24 -45
  50. 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
- // Copy a typed field from parsed[key] onto base[key] when it matches `type`.
297
- // Strings are trimmed and must be non-empty to override; `string?` may be empty.
298
- function assign(base, parsed, key, type) {
299
- const v = parsed[key]
300
- if (type === 'string') {
301
- if (typeof v === 'string' && v.trim()) base[key] = v.trim()
302
- } else if (type === 'string?') {
303
- if (typeof v === 'string') base[key] = v
304
- } else if (type === 'boolean') {
305
- if (typeof v === 'boolean') base[key] = v
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
  /**