@skitterbyte/skitterspec-linear 19.5.0 → 19.6.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/src/env/trust.js CHANGED
@@ -41,8 +41,11 @@ function writeSettings(file, settings) {
41
41
  * - `added` — the root was merged into an existing file
42
42
  * - `present` — the root was already listed (no write)
43
43
  * - `malformed` — the file exists but isn't parseable JSON (left untouched)
44
+ *
45
+ * `{ dryRun: true }` answers the same question and writes nothing — `changed`
46
+ * then means "would change", which is what `spec-env up --plan` reports.
44
47
  */
45
- function ensureWorktreeDirTrusted(dir, rootAbs) {
48
+ function ensureWorktreeDirTrusted(dir, rootAbs, { dryRun = false } = {}) {
46
49
  const file = settingsPath(dir)
47
50
 
48
51
  let raw
@@ -50,7 +53,7 @@ function ensureWorktreeDirTrusted(dir, rootAbs) {
50
53
  raw = fs.readFileSync(file, 'utf-8')
51
54
  } catch (error) {
52
55
  if (error.code === 'ENOENT') {
53
- writeSettings(file, { permissions: { additionalDirectories: [rootAbs] } })
56
+ if (!dryRun) writeSettings(file, { permissions: { additionalDirectories: [rootAbs] } })
54
57
  return { changed: true, reason: 'created' }
55
58
  }
56
59
  throw error
@@ -70,6 +73,7 @@ function ensureWorktreeDirTrusted(dir, rootAbs) {
70
73
  : []
71
74
 
72
75
  if (dirs.includes(rootAbs)) return { changed: false, reason: 'present' }
76
+ if (dryRun) return { changed: true, reason: 'added' }
73
77
 
74
78
  writeSettings(file, {
75
79
  ...parsed,
@@ -314,6 +314,26 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
314
314
  throw error
315
315
  }
316
316
  },
317
+ /**
318
+ * Make `ref` a child of `parentRef` — an epic member under its epic (spec
319
+ * feat-epics). Both are read by identifier or uuid. Idempotent: an issue
320
+ * already under that parent is left alone; one under another is moved,
321
+ * since Linear has one parent per issue. Read back, and refused when Linear
322
+ * holds anything else, so a link that did not land is never reported set.
323
+ */
324
+ async setParent(ref, parentRef) {
325
+ const issue = await this.readIssue(ref)
326
+ if (!issue) throw new Error(`no Linear issue ${ref} to put under ${parentRef}`)
327
+ const parent = await this.readIssue(parentRef)
328
+ if (!parent) throw new Error(`no Linear issue ${parentRef} to put ${issue.identifier} under`)
329
+ if (issue.parent && issue.parent.id === parent.id) return { changed: false }
330
+ await this.updateIssue(issue.id, { parentId: parent.id })
331
+ const back = await this.readIssue(issue.id)
332
+ if (!back || !back.parent || back.parent.id !== parent.id) {
333
+ throw new Error(`${issue.identifier} was put under ${parent.identifier} but Linear reads it back elsewhere`)
334
+ }
335
+ return { changed: true, moved: !!issue.parent }
336
+ },
317
337
  // A phase sub-issue is an ordinary issue carrying `parentId`. Same mutation,
318
338
  // so there is no separate sub-issue surface to keep in step.
319
339
  async createSubIssue(parentId, subIssue) {
@@ -2018,11 +2018,40 @@ async function specSyncList(dir, config, flags, out) {
2018
2018
  // An assignee filter cannot be applied to a spec with no Linear assignee, so
2019
2019
  // the section is withheld under one — counted, never silently dropped.
2020
2020
  const localHidden = assignee ? unlinked.length : null
2021
+ // AN EPIC'S MEMBERS ARE SUB-ISSUES, so the parentless query above cannot
2022
+ // return them (spec feat-epics). For each listed issue linked to an `epic-`
2023
+ // spec here, its children — every one a member, since an epic has no phases —
2024
+ // are read and listed under it, under the same state and assignee filters.
2025
+ // One extra call per epic row, none for any other. Board order (`--next`) is
2026
+ // left alone. A failed read is said once, never a failed listing.
2027
+ const memberFailures = []
2028
+ let listed = ordered
2029
+ if (next === null) {
2030
+ listed = []
2031
+ for (const issue of ordered) {
2032
+ listed.push(issue)
2033
+ const local = byIdentifier.get(issue.identifier)
2034
+ if (!local || !/^epic-/.test(local.spec)) continue
2035
+ let children
2036
+ try {
2037
+ children = (await adapter.listSubIssues(issue.id)) || []
2038
+ } catch {
2039
+ memberFailures.push(issue.identifier)
2040
+ continue
2041
+ }
2042
+ for (const child of children) {
2043
+ if (!child) continue
2044
+ if (stateIds && stateIds.length && !(child.state && stateIds.includes(child.state.id))) continue
2045
+ if (assignee && !(child.assignee && child.assignee.id === assignee.id)) continue
2046
+ listed.push({ ...child, epic: issue.identifier })
2047
+ }
2048
+ }
2049
+ }
2021
2050
  // Identifier → Linear uuid, for the phase lookup below. Kept beside the rows
2022
2051
  // rather than on them, so the --json shape stays exactly what it prints.
2023
- const uuidOf = new Map(ordered.map((i) => [i.identifier, i.id]))
2052
+ const uuidOf = new Map(listed.map((i) => [i.identifier, i.id]))
2024
2053
 
2025
- const rows = ordered.map((issue) => {
2054
+ const rows = listed.map((issue) => {
2026
2055
  const local = byIdentifier.get(issue.identifier) || null
2027
2056
  const column = specColumn((issue.state && issue.state.name) || null, local, config)
2028
2057
  return {
@@ -2043,6 +2072,7 @@ async function specSyncList(dir, config, flags, out) {
2043
2072
  // never looked up, so the shape does not vary by state.
2044
2073
  phase: null,
2045
2074
  url: issue.url || null,
2075
+ ...(issue.epic ? { epic: issue.epic } : {}),
2046
2076
  }
2047
2077
  })
2048
2078
 
@@ -2157,6 +2187,9 @@ async function specSyncList(dir, config, flags, out) {
2157
2187
  if (page.pageInfo && page.pageInfo.hasNextPage) {
2158
2188
  lines.push(' ! Linear reported further pages it did not return — this listing may be short')
2159
2189
  }
2190
+ if (memberFailures.length) {
2191
+ lines.push(` ! could not read the members of ${memberFailures.join(', ')} — they are not listed`)
2192
+ }
2160
2193
  if (phaseFailures.length) {
2161
2194
  lines.push(
2162
2195
  ` ! could not read the phases of ${phaseFailures.join(', ')} — those rows show no phase`,
@@ -2183,11 +2216,13 @@ async function specSyncList(dir, config, flags, out) {
2183
2216
  // on most rows, and padding for a column that is usually blank buys
2184
2217
  // nothing but width.
2185
2218
  const held = [row.assignee, phaseLabel(row.phase)].filter(Boolean).join(' · ')
2219
+ // An epic's member sits indented under its epic's row.
2220
+ const lead = row.epic ? ' ' : ' '
2186
2221
  lines.push(
2187
- ` ${row.identifier.padEnd(idW)} ${row.state.padEnd(stW)} ${cell(row).padEnd(bkW)} ` +
2222
+ `${lead}${row.identifier.padEnd(idW)} ${row.state.padEnd(stW)} ${cell(row).padEnd(bkW)} ` +
2188
2223
  (held ? `${(row.spec || UNLINKED).padEnd(specW)} ${held}` : row.spec || UNLINKED),
2189
2224
  )
2190
- if (row.title) lines.push(` ${pad}${row.title}`)
2225
+ if (row.title) lines.push(`${lead}${pad}${row.title}`)
2191
2226
  }
2192
2227
  }
2193
2228
  if (localHidden === null && unlinked.length) {
@@ -2270,6 +2305,7 @@ function specKindOf(snapshotDir) {
2270
2305
  if (name.startsWith('chore-')) return 'chore'
2271
2306
  if (name.startsWith('issue-')) return 'issue'
2272
2307
  if (name.startsWith('incident-')) return 'incident'
2308
+ if (name.startsWith('epic-')) return 'epic'
2273
2309
  return 'feature'
2274
2310
  }
2275
2311
 
@@ -2326,6 +2362,11 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2326
2362
  prevalidateStates: (buckets) => {
2327
2363
  for (const bucket of buckets) stateId(bucket)
2328
2364
  },
2365
+ // Only where the adapter can — the MCP transport's says nothing, and the
2366
+ // push then names that rather than guessing (provider-kit apply).
2367
+ ...(typeof adapter.setParent === 'function'
2368
+ ? { setParent: (issue, parentIdentifier) => adapter.setParent(issue.id, parentIdentifier) }
2369
+ : {}),
2329
2370
  searchTwin: (title) => adapter.searchIssues({ query: title, teamId }),
2330
2371
  twinAdvice: (twin, wanted, specName) =>
2331
2372
  `${twin.identifier} is already titled "${wanted}" and no spec claims it — ` +
@@ -336,7 +336,7 @@ function mergeConfig(base, parsed) {
336
336
  // Only the kinds a spec folder can actually be — an unknown key is
337
337
  // dropped, matching the other providers' by-kind validation.
338
338
  const byKind = {}
339
- for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident']) {
339
+ for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident', 'epic']) {
340
340
  const value = parsed.linear.labelsByKind[kind]
341
341
  if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
342
342
  }
@@ -37,6 +37,10 @@
37
37
  * - `remoteEditedLine(identifier)` the someone-else-edited warning
38
38
  * - `twinAdvice(twin, title, specName)` the refusal message for a twin
39
39
  * - `afterIssue(issue)` optional; → a report line or null
40
+ * - `setParent(issue, parentIdentifier)` optional; make the spec issue a
41
+ * child of its epic's → `{ changed }`.
42
+ * Absent means this tracker cannot
43
+ * express it, and the push says so.
40
44
  */
41
45
 
42
46
  const path = require('node:path')
@@ -54,6 +58,7 @@ const {
54
58
  listPhaseFiles,
55
59
  descriptionMode,
56
60
  spliceBlock,
61
+ linkedEpic,
57
62
  } = require('../../sync-core')
58
63
  const { makeSpecHelpers } = require('./specs.js')
59
64
 
@@ -163,6 +168,25 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
163
168
  }
164
169
  }
165
170
 
171
+ // An epic member's issue is a child of its epic's (spec feat-epics,
172
+ // Decision 6). Never fatal and never a mint: an epic not linked yet is named
173
+ // and skipped, and a tracker with no way to say "parent" says so.
174
+ const epic = result.issue ? linkedEpic(snapshotDir, config) : null
175
+ if (epic) {
176
+ if (!epic.identifier) {
177
+ lines.push(` !! epic ${epic.name} is not linked yet — parent skipped (push the epic first)`)
178
+ } else if (typeof ops.setParent !== 'function') {
179
+ lines.push(` epic ${epic.identifier}: this tracker cannot express a parent here — skipped`)
180
+ } else {
181
+ try {
182
+ const r = await ops.setParent(result.issue, epic.identifier)
183
+ if (r && r.changed) lines.push(` parent set: ${result.issue.identifier} under epic ${epic.identifier}`)
184
+ } catch (error) {
185
+ lines.push(` ?? parent ${epic.identifier}: ${String((error && error.message) || error).split('\n')[0]}`)
186
+ }
187
+ }
188
+ }
189
+
166
190
  // 4. Sub-issue creates — each stamped as it lands, for the same reason.
167
191
  for (const sub of (plan.subIssues && plan.subIssues.create) || []) {
168
192
  const created = await ops.mintSubIssue(parentId, sub)
@@ -0,0 +1,44 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Epic members in a tracker listing (spec feat-epics). A listing keeps only
5
+ * top-level issues because a sub-issue is normally a phase — but an epic's
6
+ * member is a spec that is ALSO a sub-issue, of its epic's issue. These keep
7
+ * such a member and group it under its epic, on a positive signal only: its
8
+ * parent is linked to an `epic-` spec in this checkout.
9
+ *
10
+ * BLIND SPOT: an epic this checkout has no linked copy of reads as an unknown
11
+ * parent, so its members stay filtered out exactly as they were before epics
12
+ * existed — a missing row, never a phase shown as a spec.
13
+ */
14
+
15
+ /** The identifiers of the `epic-` specs in a `listSpecs`-shaped array. */
16
+ function epicIdentifiers(specs) {
17
+ return new Set((specs || []).filter((s) => s && s.identifier && /^epic-/.test(s.spec)).map((s) => s.identifier))
18
+ }
19
+
20
+ /**
21
+ * The epic an issue is a member of, or null. `parentOf(issue)` gives the
22
+ * parent's identifier in the provider's own spelling.
23
+ */
24
+ function epicOf(issue, epics, parentOf) {
25
+ const parent = issue && issue.parent ? parentOf(issue) : null
26
+ return parent && epics.has(parent) ? parent : null
27
+ }
28
+
29
+ /** Top-level issues, plus the members of a linked epic. */
30
+ function keepSpecIssues(issues, epics, parentOf) {
31
+ return (issues || []).filter((i) => !i.parent || epicOf(i, epics, parentOf))
32
+ }
33
+
34
+ /**
35
+ * Rows reordered so each member follows its epic's row. A member whose epic's
36
+ * row is not in the listing keeps its place. Rows carry `epic` when a member.
37
+ */
38
+ function groupUnderEpics(rows) {
39
+ const listed = new Set(rows.map((r) => r.identifier))
40
+ const under = (id) => rows.filter((r) => r.epic === id)
41
+ return rows.filter((r) => !r.epic || !listed.has(r.epic)).flatMap((r) => [r, ...under(r.identifier)])
42
+ }
43
+
44
+ module.exports = { epicIdentifiers, epicOf, keepSpecIssues, groupUnderEpics }
@@ -13,7 +13,7 @@
13
13
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
14
14
  */
15
15
 
16
- const { ownsField, ownershipOf, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, effectiveStates, specHeaders, linkedIncident, phaseModeFor } = require('./src/normalize.js')
16
+ const { ownsField, ownershipOf, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, effectiveStates, specHeaders, parseWaitsOn, linkedIncident, linkedEpic, phaseModeFor } = require('./src/normalize.js')
17
17
  const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
18
18
  const { readBase, writeBase } = require('./src/base.js')
19
19
  const { push, recordPush, projectionOf } = require('./src/push.js')
@@ -50,7 +50,9 @@ module.exports = {
50
50
  stateSuggestions,
51
51
  effectiveStates,
52
52
  specHeaders,
53
+ parseWaitsOn,
53
54
  linkedIncident,
55
+ linkedEpic,
54
56
  hashField,
55
57
  stableStringify,
56
58
  readBase,
@@ -435,24 +435,68 @@ function readSnapshot(snapshotDir, config) {
435
435
  return { frontmatter: data, title, sections, phases, body }
436
436
  }
437
437
 
438
- // The spec's own `> **Severity:**` and `> **Incident:**` headers, off the
439
- // overview's blockquote block. They are PUSH-TIME EXTRAS, deliberately not
440
- // keys on `normalizeLocal`'s field set: severity lands in a provider-specific
441
- // home (a field, a label) and the incident link as a typed relation, so
442
- // neither belongs in the synced-field hashes a stored base compares.
438
+ // The spec's own `> **Severity:**`, `> **Incident:**`, `> **Epic:**`,
439
+ // `> **Waits on:**` and `> **Lanes:**` headers, off the overview's blockquote
440
+ // block. They are PUSH-TIME EXTRAS, deliberately not keys on `normalizeLocal`'s
441
+ // field set: severity lands in a provider-specific home (a field, a label),
442
+ // the incident and epic links as typed relations, and the waits and lanes are
443
+ // read by `epic status` — none belongs in the synced-field hashes a stored base
444
+ // compares.
443
445
  function specHeaders(snapshotDir, config) {
444
446
  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
445
447
  let raw
446
448
  try {
447
449
  raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
448
450
  } catch {
449
- return { severity: null, incident: null }
451
+ return { severity: null, incident: null, epic: null, waitsOn: [], lanes: null }
450
452
  }
451
453
  const read = (name) => {
452
454
  const m = new RegExp(`^>\\s*\\*\\*${name}:\\*\\*\\s*(.+)$`, 'm').exec(raw)
453
455
  return m ? m[1].trim() : null
454
456
  }
455
- return { severity: read('Severity'), incident: read('Incident') }
457
+ return {
458
+ severity: read('Severity'),
459
+ incident: read('Incident'),
460
+ epic: unquote(read('Epic')) || null,
461
+ waitsOn: parseWaitsOn(read('Waits on')),
462
+ lanes: parseLanes(read('Lanes')),
463
+ }
464
+ }
465
+
466
+ // A header value a hand may have wrapped in backticks, as a spec name usually is.
467
+ function unquote(value) {
468
+ return value == null ? value : value.replace(/^`(.*)`$/, '$1').trim()
469
+ }
470
+
471
+ // `> **Waits on:** <spec>[ phase N], …` → `[{ spec, phase }]`, `phase` null for
472
+ // a whole-spec wait. `none` (or the `—` placeholder) is an empty list.
473
+ //
474
+ // A MALFORMED ENTRY IS KEPT, never dropped: `{ spec: null, phase: null, raw }`.
475
+ // Dropping it would make a wait nobody can read look like no wait at all, and
476
+ // `epic status` would then call the member ready — the accusation running the
477
+ // wrong way. Kept, it reports as cannot-tell (`.claude/rules/negative-checks.md`).
478
+ function parseWaitsOn(value) {
479
+ if (!value) return []
480
+ const trimmed = value.trim()
481
+ if (/^(none|—|-)$/i.test(trimmed)) return []
482
+ return trimmed
483
+ .split(',')
484
+ .map((part) => part.trim())
485
+ .filter(Boolean)
486
+ .map((part) => {
487
+ const m = /^`?([a-z0-9][a-z0-9._-]*)`?(?:\s+phase\s+(\d+))?$/i.exec(part)
488
+ if (!m) return { spec: null, phase: null, raw: part }
489
+ return { spec: m[1], phase: m[2] ? Number(m[2]) : null, raw: part }
490
+ })
491
+ }
492
+
493
+ // `> **Lanes:** N` — a positive whole number, else null. An unreadable cap is
494
+ // no cap, which `epic status` reports as uncapped rather than guessing one.
495
+ function parseLanes(value) {
496
+ if (!value) return null
497
+ const m = /^(\d+)$/.exec(value.trim())
498
+ const n = m ? Number(m[1]) : 0
499
+ return n > 0 ? n : null
456
500
  }
457
501
 
458
502
  // Resolve a fix spec's `> **Incident:**` header to the incident spec it names:
@@ -479,6 +523,39 @@ function linkedIncident(snapshotDir, config) {
479
523
  return { name: incident, identifier: null, found: false }
480
524
  }
481
525
 
526
+ // A member spec's `> **Epic:**` resolved the way `linkedIncident` resolves its
527
+ // header: the epic's folder in any bucket and its stamped identifier, or
528
+ // `identifier: null` when the epic is not linked yet (report and carry on —
529
+ // never mint the other). No header returns null.
530
+ //
531
+ // A FOLDER NOT ON DISK IS NOT PROOF THE EPIC DOES NOT EXIST, for the reason
532
+ // `linkedIncident` gives: buckets are branch-local truth.
533
+ function linkedEpic(snapshotDir, config) {
534
+ const { epic } = specHeaders(snapshotDir, config)
535
+ if (!epic) return null
536
+ const root = path.resolve(snapshotDir, '..', '..', '..')
537
+ const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
538
+ for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
539
+ const file = path.join(root, 'specs', bucket, epic, overviewFile)
540
+ if (!fs.existsSync(file)) continue
541
+ const { data } = parseFrontmatter(fs.readFileSync(file, 'utf-8'))
542
+ const idField = config && config.fields && config.fields.identifier
543
+ const identifier = idField && data[idField] != null ? String(data[idField]) : null
544
+ return { name: epic, identifier, found: true }
545
+ }
546
+ return { name: epic, identifier: null, found: false }
547
+ }
548
+
549
+ // The member's one-line pointer to its epic. Part of the PROJECTION, like the
550
+ // related-incident line, so the stored base, the plan and the tracker hash the
551
+ // same bytes — and so a spec that only GAINS an `Epic:` header still has a
552
+ // change to push, which is what gives the parent link a push to ride on.
553
+ function epicLine(snapshotDir, config) {
554
+ const epic = linkedEpic(snapshotDir, config)
555
+ if (!epic) return ''
556
+ return `\n\nEpic: ${epic.identifier || epic.name}`
557
+ }
558
+
482
559
  // The one-line cross-reference a fix spec's body carries to its incident. Part
483
560
  // of the PROJECTION (not appended at send time), so the stored base, the plan
484
561
  // and what the tracker holds all hash the same bytes — and on GitHub the
@@ -815,7 +892,8 @@ function normalizeLocal(snapshotDir, config) {
815
892
  description: summaryMode
816
893
  ? wrapBlock(
817
894
  dialect.flattenTables(dialect.canonicalize(specBlockInner({ snapshotDir, sections, body, phases }))) +
818
- relatedIncidentLine(snapshotDir, config),
895
+ relatedIncidentLine(snapshotDir, config) +
896
+ epicLine(snapshotDir, config),
819
897
  config,
820
898
  )
821
899
  : withInlinePhases(
@@ -834,7 +912,9 @@ function normalizeLocal(snapshotDir, config) {
834
912
  tasksMode,
835
913
  config.sync.localOnlySections,
836
914
  dialect,
837
- ) + relatedIncidentLine(snapshotDir, config),
915
+ ) +
916
+ relatedIncidentLine(snapshotDir, config) +
917
+ epicLine(snapshotDir, config),
838
918
  // Sub-issue projection: one per phase. `ref` is the phase-file basename — the
839
919
  // local handle the push skill stamps a newly-created sub-issue id back into.
840
920
  // `state` is the phase's status bucket (from its heading emoji), mapped to a
@@ -1131,5 +1211,7 @@ module.exports = {
1131
1211
  remoteStateReading,
1132
1212
  stateNamesFor,
1133
1213
  specHeaders,
1214
+ parseWaitsOn,
1134
1215
  linkedIncident,
1216
+ linkedEpic,
1135
1217
  }