@skitterbyte/skitterspec-jira 2.4.0 → 2.5.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.
@@ -198,6 +198,49 @@ function snapshotOf(projection, config) {
198
198
  }
199
199
  }
200
200
 
201
+ /**
202
+ * The `stateNames` record for a snapshot: the tracker state name each item was
203
+ * last SENT, `{ issue, subIssues: { <id>: name } }`, or null when there is
204
+ * nothing to record (no provider hook, nothing ever sent).
205
+ *
206
+ * An item this push sent a state for (`sent`) records today's resolution. Any
207
+ * other item keeps the name the previous snapshot had for it, or gets none —
208
+ * the absence `planChanges` reads as cannot-tell. Writing today's name for an
209
+ * item that was not sent would record a claim about the tracker nobody made.
210
+ *
211
+ * @param {object} projection the projection, carrying `stateName`s
212
+ * @param {object|null} previous the snapshot being replaced
213
+ * @param {{ issue?: boolean, subIssues?: Set<string> }|null} sent
214
+ */
215
+ function stateNamesRecord(projection, previous, sent) {
216
+ const p = projection || {}
217
+ const before = (previous && previous.stateNames) || {}
218
+ const beforeSubs = before.subIssues || {}
219
+ const sentSubs = (sent && sent.subIssues) || new Set()
220
+ const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key)
221
+ const out = { subIssues: {} }
222
+ if (sent && sent.issue && p.stateName !== undefined) out.issue = p.stateName
223
+ else if (has(before, 'issue')) out.issue = before.issue
224
+ for (const s of p.subIssues || []) {
225
+ if (!s || s.id == null) continue
226
+ const id = String(s.id)
227
+ if (sentSubs.has(id) && s.stateName !== undefined) out.subIssues[id] = s.stateName
228
+ else if (has(beforeSubs, id)) out.subIssues[id] = beforeSubs[id]
229
+ }
230
+ if (!has(out, 'issue') && !Object.keys(out.subIssues).length) return null
231
+ return out
232
+ }
233
+
234
+ // Has the state an unchanged item maps to moved under it — a state-map edit in
235
+ // the config rather than a move of the spec? Only a RECORDED name can say: an
236
+ // item with none is cannot-tell and plans nothing, so an upgrade or a config
237
+ // change never turns into a workspace-wide resend. A bucket that now sends no
238
+ // state (`null`) has nothing to resend.
239
+ function remapped(recorded, current) {
240
+ if (recorded === undefined || current === undefined || current === null) return false
241
+ return recorded !== current
242
+ }
243
+
201
244
  /**
202
245
  * Diff the local projection against the last-pushed snapshot.
203
246
  * @returns {{ issue?: object, subIssues: {create,update} }}
@@ -213,6 +256,9 @@ function planChanges(projection, snapshot, { linked = false } = {}) {
213
256
  const p = projection || {}
214
257
  const snap = snapshot || {}
215
258
  const snapS = snap.subIssues || {}
259
+ const names = snap.stateNames || {}
260
+ const recordedSub = (id) =>
261
+ names.subIssues && Object.prototype.hasOwnProperty.call(names.subIssues, id) ? names.subIssues[id] : undefined
216
262
 
217
263
  // Ids the last push minted that no phase claims any more. A phase file's stamp
218
264
  // is the only link back to its sub-issue, and it lives in frontmatter — so a
@@ -239,7 +285,15 @@ function planChanges(projection, snapshot, { linked = false } = {}) {
239
285
  subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
240
286
  }
241
287
  } else if (snapS[String(s.id)] !== subIssueHash(s)) {
242
- subIssues.update.push({ ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state })
288
+ const update = { ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state }
289
+ // No hash on record for an id the spec carries: the snapshot was lost or
290
+ // predates it, so this is a resend, not a move the spec made.
291
+ if (snapS[String(s.id)] === undefined) update.stateResend = 'unknown'
292
+ subIssues.update.push(update)
293
+ } else if (remapped(recordedSub(String(s.id)), s.stateName)) {
294
+ // STATE ONLY: the phase itself is unchanged, so its title and body stay
295
+ // as they are on the tracker.
296
+ subIssues.update.push({ ref: s.ref, id: s.id, state: s.state, stateResend: 'remap' })
243
297
  }
244
298
  }
245
299
 
@@ -276,6 +330,9 @@ function issueChanges(projection, snapshot, { linked = false } = {}) {
276
330
  // `linked` is what tells the two apart: an adopted issue has no snapshot
277
331
  // either, and its board status is a person's, not ours.
278
332
  if (!p.statePulled || !linked) out.state = p.status ?? null
333
+ // A linked issue with no split hashes is a resend: nothing says the spec
334
+ // moved, so the apply must not drag the issue out of a later state.
335
+ if (linked && out.state != null) out.stateResend = 'unknown'
279
336
  // ASSERT, NEVER CLEAR, on this path. There are no split hashes here, so
280
337
  // whether an assignee was ever pushed is unknown — and the harmless reading
281
338
  // of "unknown" is to send one we have and stay silent about one we don't.
@@ -302,6 +359,11 @@ function issueChanges(projection, snapshot, { linked = false } = {}) {
302
359
  const changed = {}
303
360
  if (fields.description !== want.description) changed.description = p.description ?? null
304
361
  if (fields.state !== want.state) changed.state = p.status ?? null
362
+ else if (!p.statePulled && remapped(snap.stateNames && snap.stateNames.issue, p.stateName)) {
363
+ // The tracker owns a pulled state, so a remap never re-asserts it there.
364
+ changed.state = p.status ?? null
365
+ changed.stateResend = 'remap'
366
+ }
305
367
 
306
368
  // ASSIGNEE — AN ABSENT SNAPSHOT KEY MEANS "NEVER PUSHED", NOT "WAS NULL".
307
369
  //
@@ -342,6 +404,7 @@ module.exports = {
342
404
  issueChanges,
343
405
  specIssueFieldHashes,
344
406
  snapshotOf,
407
+ stateNamesRecord,
345
408
  isEmptyPlan,
346
409
  hashField,
347
410
  stableStringify,
@@ -18,7 +18,7 @@
18
18
  const { normalizeLocal, phasesWithheld, phaseModeFor, ownershipOf, readSnapshot } = require('./normalize.js')
19
19
  const { descriptionMode } = require('./summary.js')
20
20
  const { fieldsOf } = require('./fields.js')
21
- const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
21
+ const { planChanges, snapshotOf, stateNamesRecord, isEmptyPlan } = require('./compare.js')
22
22
  const { readBase, writeBase } = require('./base.js')
23
23
  const { detectLegacyMirror } = require('./legacy.js')
24
24
 
@@ -55,9 +55,36 @@ function projectionOf(snapshotDir, config) {
55
55
  // a push sends it only as a transition — see `issueChanges`. Set only when
56
56
  // pulled, and read by name, so it can never reach a hash.
57
57
  if (ownershipOf(config, 'workflowState') === 'pull') projection.statePulled = true
58
+ attachStateNames(projection, snapshotDir, config)
58
59
  return projection
59
60
  }
60
61
 
62
+ // The tracker state NAME each bucket resolves to today, from the provider's
63
+ // `config.remote.writtenStateName(bucket, role, snapshotDir)` hook: a string,
64
+ // `null` for "this bucket sends no state", or `undefined` for cannot-tell — no
65
+ // hook, a hook that threw, or no bucket to resolve. Read by name, so it never
66
+ // reaches a hash: recorded beside them as `stateNames`, it is what lets a plan
67
+ // see a state-map change the bucket hashes are blind to.
68
+ function attachStateNames(projection, snapshotDir, config) {
69
+ const hook = config && config.remote && config.remote.writtenStateName
70
+ if (typeof hook !== 'function') return
71
+ const resolve = (bucket, role) => {
72
+ if (!bucket) return undefined
73
+ try {
74
+ const name = hook(bucket, role, snapshotDir)
75
+ return name === null || typeof name === 'string' ? name : undefined
76
+ } catch {
77
+ return undefined
78
+ }
79
+ }
80
+ const name = resolve(projection.status, 'issue')
81
+ if (name !== undefined) projection.stateName = name
82
+ projection.subIssues = projection.subIssues.map((s) => {
83
+ const sub = resolve(s && s.state, 'subIssue')
84
+ return sub === undefined ? s : { ...s, stateName: sub }
85
+ })
86
+ }
87
+
61
88
  // Does the spec carry its issue stamp? NOT `identifier`: callers fall back to the
62
89
  // folder name for an unlinked spec, so a truthy identifier proves nothing. The
63
90
  // stamp is the positive signal — it tells a create (no issue yet, so the spec's
@@ -101,9 +128,18 @@ function push({ dir, snapshotDir, identifier, config }) {
101
128
  * Record the last-pushed snapshot from the CURRENT files — call after the skill
102
129
  * has applied the plan and stamped new ids. Returns the snapshot path.
103
130
  */
104
- function recordPush({ dir, snapshotDir, identifier, config }) {
131
+ // `sent` says which items this push carried a state for — `{ issue, subIssues }`,
132
+ // the latter a set of ids. Only those get today's name recorded; anything else
133
+ // keeps the name it already had, or none. Recording today's name for an item
134
+ // that was NOT sent would claim the tracker holds it, and silence the very remap
135
+ // this record exists to catch. Without `sent` (a hand-applied MCP push) nothing
136
+ // new is recorded and what was there is kept.
137
+ function recordPush({ dir, snapshotDir, identifier, config, sent = null }) {
105
138
  const projection = projectionOf(snapshotDir, config)
106
- return writeBase(dir, identifier, config, snapshotOf(projection, config))
139
+ const snapshot = snapshotOf(projection, config)
140
+ const names = stateNamesRecord(projection, readBase(dir, identifier, config), sent)
141
+ if (names) snapshot.stateNames = names
142
+ return writeBase(dir, identifier, config, snapshot)
107
143
  }
108
144
 
109
145
  module.exports = { push, recordPush, projectionOf }