@skitterbyte/skitterspec-jira 2.5.1 → 2.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.
@@ -215,6 +215,27 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
215
215
  return { id: String(created.id), identifier: created.key, url: urlOf(created.key) }
216
216
  },
217
217
 
218
+ /**
219
+ * Make `keyOrId` a child of the Epic `parentKey` — an epic member under its
220
+ * epic (spec feat-epics), through the `parent` field every Jira Cloud
221
+ * project now takes for an Epic. Idempotent: an issue already under it is
222
+ * left alone; one under another epic is moved. Read back, and refused when
223
+ * Jira holds anything else. BLIND SPOT: a site still on the legacy
224
+ * "Epic Link" field refuses the write, and the push reports that refusal
225
+ * rather than reaching for a custom field it cannot name.
226
+ */
227
+ async setParent(keyOrId, parentKey) {
228
+ const issue = await this.readIssue(keyOrId)
229
+ if (!issue) throw new Error(`no Jira issue ${keyOrId} to put under ${parentKey}`)
230
+ if (issue.parent && issue.parent.identifier === parentKey) return { changed: false }
231
+ await request('PUT', `/issue/${encodeURIComponent(issue.identifier)}`, { body: { fields: { parent: { key: parentKey } } } })
232
+ const back = await this.readIssue(issue.identifier)
233
+ if (!back || !back.parent || back.parent.identifier !== parentKey) {
234
+ throw new Error(`${issue.identifier} was put under ${parentKey} but Jira reads it back under ${back && back.parent ? back.parent.identifier : 'no parent'}`)
235
+ }
236
+ return { changed: true, moved: !!issue.parent }
237
+ },
238
+
218
239
  async updateIssue(keyOrId, updates) {
219
240
  const fields = issueFields(updates)
220
241
  if (!Object.keys(fields).length) return {}
@@ -37,6 +37,7 @@ const {
37
37
  descriptionMode,
38
38
  } = require('../sync-core')
39
39
  const kit = require('../provider-kit')
40
+ const { epicIdentifiers, epicOf, keepSpecIssues, groupUnderEpics } = require('../provider-kit/src/epic-rows.js')
40
41
  const { BUCKETS, findSpecFolder, currentBranch } = require('../../env/resolve.js')
41
42
 
42
43
  const { loadJiraConfig, mergeConfig, defaults, CONFIG_FILE, LIFECYCLE_BUCKETS, DEFAULT_CONFIG } = require('./config.js')
@@ -138,13 +139,17 @@ function specKindOf(snapshotDir) {
138
139
  if (name.startsWith('chore-')) return 'chore'
139
140
  if (name.startsWith('issue-')) return 'issue'
140
141
  if (name.startsWith('incident-')) return 'incident'
142
+ if (name.startsWith('epic-')) return 'epic'
141
143
  return 'feature'
142
144
  }
143
145
 
144
146
  function applyOps({ adapter, config, kind = 'feature', snapshotDir = null, out = null }) {
145
147
  // The mint type for THIS spec's kind (jira.issueTypeByKind), falling back to
146
148
  // the one configured type — unmapped kinds mint exactly as before.
147
- const mintType = (config.jira.issueTypeByKind && config.jira.issueTypeByKind[kind]) || config.jira.issueType
149
+ // An epic mints as Jira's own Epic type unless the site maps it elsewhere:
150
+ // that is what makes it its members' native parent (spec feat-epics).
151
+ const mintType =
152
+ (config.jira.issueTypeByKind && config.jira.issueTypeByKind[kind]) || (kind === 'epic' ? 'Epic' : config.jira.issueType)
148
153
  // Push-time extras off the spec's own headers: `Severity:` lands in the
149
154
  // site's own field (`jira.severityField`, opt-in — unset, the header stays
150
155
  // repo-only), `Incident:` as a "Relates" issue link. Neither is a synced
@@ -192,6 +197,9 @@ function applyOps({ adapter, config, kind = 'feature', snapshotDir = null, out =
192
197
  statusFor(bucket, config.jira.subtaskType)
193
198
  }
194
199
  },
200
+ ...(typeof adapter.setParent === 'function'
201
+ ? { setParent: (issue, parentIdentifier) => adapter.setParent(issue.identifier || issue.id, parentIdentifier) }
202
+ : {}),
195
203
  searchTwin: (title) => adapter.searchIssues({ query: title, projectKey: config.jira.projectKey }),
196
204
  twinAdvice: (twin, wanted, specName) =>
197
205
  `${twin.identifier} is already titled "${wanted}" and no spec claims it — ` +
@@ -700,14 +708,19 @@ async function specSyncList(dir, config, flags, out) {
700
708
  return 1
701
709
  }
702
710
  const linked = new Map(listSpecs(dir, config).filter((s) => s.identifier).map((s) => [s.identifier, s]))
703
- const rows = issues
704
- .filter((i) => !i.parent)
705
- .map((i) => ({
711
+ // An epic's members are sub-issues of its Epic, kept and grouped under it
712
+ // (provider-kit `epic-rows.js`, which names the blind spot).
713
+ const epics = epicIdentifiers([...linked.values()])
714
+ const parentKey = (i) => i.parent.identifier
715
+ const rows = groupUnderEpics(
716
+ keepSpecIssues(issues, epics, parentKey).map((i) => ({
706
717
  identifier: i.identifier,
707
718
  title: i.title,
708
719
  state: i.state ? i.state.name : null,
709
720
  spec: linked.has(i.identifier) ? linked.get(i.identifier).spec : null,
710
- }))
721
+ ...(epicOf(i, epics, parentKey) ? { epic: epicOf(i, epics, parentKey) } : {}),
722
+ })),
723
+ )
711
724
  if (flags.json) {
712
725
  out.write(JSON.stringify(rows, null, 2) + '\n')
713
726
  return 0
@@ -717,8 +730,11 @@ async function specSyncList(dir, config, flags, out) {
717
730
  return 0
718
731
  }
719
732
  const lines = [`${PROGRAM} list: ${config.jira.projectKey}`]
733
+ const shown = new Set(rows.map((r) => r.identifier))
720
734
  for (const r of rows) {
721
- lines.push(` ${r.identifier}\t${r.state || '—'}\t${r.title || ''}${r.spec ? ` -> ${r.spec}` : ''}`)
735
+ const lead = r.epic && shown.has(r.epic) ? ' ' : ' '
736
+ const tail = r.epic && !shown.has(r.epic) ? ` (epic ${r.epic})` : ''
737
+ lines.push(`${lead}${r.identifier}\t${r.state || '—'}\t${r.title || ''}${r.spec ? ` -> ${r.spec}` : ''}${tail}`)
722
738
  }
723
739
  out.write(lines.join('\n') + '\n')
724
740
  return 0
@@ -163,7 +163,7 @@ function mergeConfig(base, parsed) {
163
163
  // Only the kinds a spec folder can actually be — an unknown key is
164
164
  // dropped, matching the other providers' by-kind validation.
165
165
  const byKind = {}
166
- for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident']) {
166
+ for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident', 'epic']) {
167
167
  const value = parsed.jira.issueTypeByKind[kind]
168
168
  if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
169
169
  }
@@ -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
  }