@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/vendor/sync-core/src/compare.js

@@ -0,0 +1,338 @@
+'use strict'
+
+/**
+ * One-sided change detection for one-way sync (repo → tracker).
+ *
+ * The repo is the source of truth; Linear is a generated mirror. We never read
+ * remote content. Instead we record a **last-pushed snapshot** — a content hash
+ * per object — and diff the current local projection against it:
+ *
+ *   - an item with no id            → CREATE (never pushed)
+ *   - an item whose hash changed    → UPDATE (edited since last push)
+ *   - an item whose hash matches    → skip (unchanged)
+ *
+ * `planChanges(projection, snapshot)` returns the create/update plan the push
+ * skill applies over MCP; `snapshotOf(projection)` is what we record afterwards.
+ *
+ * Pure and deterministic: hashes are a sorted-key JSON → SHA-1, so key order and
+ * null/undefined never cause a false diff. No Date.now()/Math.random().
+ */
+
+const { createHash } = require('node:crypto')
+// The tolerant reduction `verify.js` already uses to tell the tracker's own
+// reserialisation apart from a real edit. Imported rather than reimplemented:
+// two reductions that disagree would be two different answers to one question.
+// Dialect-parameterised: the provider's `config.dialect` names the transforms.
+const { stream } = require('./verify.js')
+
+// Deterministic JSON: object keys sorted recursively; array order preserved.
+// undefined normalises to null.
+function stableStringify(value) {
+  if (value === undefined || value === null) return 'null'
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']'
+  if (typeof value === 'object') {
+    const keys = Object.keys(value).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value)
+}
+
+// Stable content hash of a value.
+function hashField(value) {
+  return createHash('sha1').update(stableStringify(value)).digest('hex')
+}
+
+// --- content hashes (id / local handles excluded, so they never affect the
+//     diff — an id stamped in after a create must not read as an edit) ---------
+
+// The spec ISSUE fields the repo owns and pushes: prose + workflow state.
+// Priority, labels, cycles and comments are Linear-native triage — one-way sync
+// neither pushes nor reads them, so a PM's triage is never clobbered.
+//
+// The COMBINED hash, retained for snapshots written before the fields were split
+// (and read by any older CLI still pointed at this repo). New pushes diff
+// `issueFields` below; this stays so neither direction breaks on the other.
+function specIssueHash(p) {
+  return hashField({ description: p.description ?? null, state: p.status ?? null })
+}
+
+// Per-field hashes of the same two values.
+//
+// They are hashed SEPARATELY because skitterspec tells the tracker about its
+// own transitions and nothing else. The description is resent whenever it
+// changes; the state only when the spec itself moves. Welding the two meant any
+// prose edit re-emitted the state and dragged back an issue someone had moved
+// on the tracker — which is theirs to do. Diffing them apart is what lets a
+// push touch the description without re-asserting a state.
+function specIssueFieldHashes(p, config) {
+  const hashes = {
+    description: hashField(p.description ?? null),
+    state: hashField(p.status ?? null),
+  }
+  // ONLY WHEN THE FIELD IS IN PLAY. A repo that has not opted `assignee` into
+  // `sync.fieldOwnership` must not accumulate assignee hashes in its snapshots —
+  // "the feature is inert" has to include the files it writes, or opting in later
+  // would find a history of hashes it never agreed to.
+  if (p.assignee !== undefined) hashes.assignee = hashField(p.assignee ?? null)
+
+  // A SECOND HASH OF THE SAME TEXT, answering a different question.
+  //
+  // `description` above decides what to PUSH: it is exact, because any
+  // difference between the repo and what the repo last sent is a difference the
+  // repo should send again. This one decides whether SOMEBODY ELSE has been
+  // here, and for that exactness is precisely wrong — the tracker reserialises
+  // markdown on save (bullets rewritten, ordered lists renumbered, table
+  // separators collapsed), so comparing the exact hash against a read-back would
+  // report a human edit on every intact mirror in the workspace.
+  //
+  // So it hashes the `stream` reduction instead: word characters only, which is
+  // what `compareStored` already compares and what makes every benign transform
+  // invisible. The cost is the mirror image — an edit consisting ONLY of
+  // punctuation or formatting is invisible here too — and that is the right way
+  // round: the unknown case goes to the branch that says nothing rather than the
+  // one that accuses (`.claude/rules/negative-checks.md` rule 4).
+  //
+  // It is recorded and never planned on. `issueChanges` reads `description`,
+  // `state` and `assignee` by name and never iterates this object, so adding a
+  // key here cannot make a push pending — there is a test for exactly that.
+  hashes.descriptionStream = hashField(stream(p.description ?? '', config))
+  return hashes
+}
+
+/**
+ * Has the tracker's copy of the description been edited by someone other than
+ * this repo, since the last push?
+ *
+ * THREE ANSWERS, and the third is the point: `true`, `false`, and `null` for
+ * cannot-tell. Only `true` may be reported to a user, because only `true` is
+ * evidence. The three cannot-tells, each an absence that proves nothing:
+ *
+ *   - no `issueFields.descriptionStream` in the snapshot. EVERY snapshot written
+ *     before this function existed lacks it, so reading that absence as evidence
+ *     would accuse every spec in every repo on the first run after an upgrade.
+ *     This is the blind spot that matters most here.
+ *   - no `description` key on the remote object. The caller did not ask the
+ *     tracker for it, or could not.
+ *   - a `description` that is not a string. The same blind spot `compareStored`
+ *     documents: a value the caller never fetched is indistinguishable from one
+ *     the tracker really holds empty.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ *
+ * @param {object|null} snapshot  the committed last-pushed snapshot
+ * @param {object|null} remote    what the tracker currently holds for the issue
+ * @returns {boolean|null}
+ */
+function remoteDescriptionEdited(snapshot, remote, config) {
+  const fields = snapshot && snapshot.issueFields
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return null
+  const recorded = fields.descriptionStream
+  if (typeof recorded !== 'string' || !recorded) return null
+
+  if (!remote || typeof remote !== 'object') return null
+  // A provider whose remote shape differs supplies `config.remote.description`.
+  const hook = config && config.remote && config.remote.description
+  const text = typeof hook === 'function' ? hook(remote) : 'description' in remote ? remote.description : undefined
+  if (typeof text !== 'string') return null
+
+  return hashField(stream(text, config)) !== recorded
+}
+
+/**
+ * The same question for one phase SUB-ISSUE: has its body been edited on the
+ * tracker since the last push? It matters most where the tracker renders a
+ * phase's task list as clickable boxes — GitHub does — because ticking one
+ * there is an edit the next push replaces.
+ *
+ * The same three answers and the same cannot-tells as above, plus one of its
+ * own: no `subIssueStreams` in the snapshot, or none for this id. Every
+ * snapshot written before this existed lacks it, and a phase whose body was
+ * never sent (no goal) has nothing recorded.
+ *
+ * @param {object|null} snapshot  the committed last-pushed snapshot
+ * @param {string} id             the sub-issue's id as the snapshot keys it
+ * @param {object|null} remote    what the tracker currently holds for it
+ * @returns {boolean|null}
+ */
+function remoteSubIssueEdited(snapshot, id, remote, config) {
+  const streams = snapshot && snapshot.subIssueStreams
+  if (!streams || typeof streams !== 'object' || Array.isArray(streams)) return null
+  const recorded = streams[String(id)]
+  if (typeof recorded !== 'string' || !recorded) return null
+  return remoteDescriptionEdited({ issueFields: { descriptionStream: recorded } }, remote, config)
+}
+// A phase SUB-ISSUE: its name, goal and state (all repo-owned).
+const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
+
+/**
+ * The snapshot to commit after a successful push: the spec-issue hash plus a
+ * content hash per sub-issue that currently has an id. Create items (id == null)
+ * aren't recorded until the skill stamps their returned id and the next
+ * projection includes it.
+ */
+function snapshotOf(projection, config) {
+  const p = projection || {}
+  const byId = (arr, hash) => {
+    const out = {}
+    for (const item of arr || []) if (item && item.id != null) out[String(item.id)] = hash(item)
+    return out
+  }
+  return {
+    // Both shapes are written: `issueFields` is what a current push diffs, and
+    // `issue` keeps a snapshot readable by anything still expecting the combined
+    // hash. Cheap insurance — two SHA-1s of text already in hand.
+    issue: specIssueHash(p),
+    issueFields: specIssueFieldHashes(p, config),
+    subIssues: byId(p.subIssues, subIssueHash),
+    // Recorded and never planned on, like `descriptionStream`: `planChanges`
+    // reads `subIssues` by name, so this key cannot make a push pending. Only a
+    // phase whose body is actually sent (a string goal) gets one.
+    subIssueStreams: byId(
+      (p.subIssues || []).filter((s) => s && typeof s.goal === 'string'),
+      (s) => hashField(stream(s.goal, config)),
+    ),
+  }
+}
+
+/**
+ * Diff the local projection against the last-pushed snapshot.
+ * @returns {{ issue?: object, subIssues: {create,update} }}
+ *   `unstamped` (when present) lists phases whose stamp is missing while the
+ *   snapshot still remembers an unminted-for id — ambiguous, so neither created
+ *   nor updated. create items carry a `ref` (local handle) and no id; update items carry both
+ *   — the `ref` because the read-back check matches sub-issues to phases BY ref,
+ *   and an update with only an id makes every one of them look unmatched.
+ *   `plan.issue` (when present) is the spec issue's description + state; the push
+ *   skill applies its provider's project/grouping choice on top of it.
+ */
+function planChanges(projection, snapshot) {
+  const p = projection || {}
+  const snap = snapshot || {}
+  const snapS = snap.subIssues || {}
+
+  // Ids the last push minted that no phase claims any more. A phase file's stamp
+  // is the only link back to its sub-issue, and it lives in frontmatter — so a
+  // whole-file rewrite, a hand edit or a bad merge drops it while the sub-issue
+  // carries on existing. This snapshot is the only memory that it was ever
+  // minted, and nothing else in the push path re-reads the tracker.
+  const claimed = new Set()
+  for (const s of p.subIssues || []) if (s.id != null) claimed.add(String(s.id))
+  const unclaimed = Object.keys(snapS).filter((id) => !claimed.has(id))
+
+  const subIssues = { create: [], update: [] }
+  const unstamped = []
+  for (const s of p.subIssues || []) {
+    if (s.id == null) {
+      // THREE STATES, NOT TWO. "No stamp" means "new phase" only when every id
+      // the snapshot remembers is still claimed. With an unclaimed id sitting
+      // beside an unstamped phase the two readings — a new phase, and a phase
+      // whose stamp was lost — are indistinguishable from here, so this routes to
+      // the harmless branch and mints nothing. Being wrong this way costs a
+      // re-stamp; the other way cost a duplicate sub-issue and a manual cancel.
+      if (unclaimed.length) {
+        unstamped.push({ ref: s.ref, name: s.name, candidates: unclaimed.slice() })
+      } else {
+        subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
+      }
+    } else if (snapS[String(s.id)] !== subIssueHash(s)) {
+      subIssues.update.push({ ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state })
+    }
+  }
+
+  const plan = { subIssues }
+  if (unstamped.length) plan.unstamped = unstamped
+  const issue = issueChanges(p, snap)
+  if (issue) plan.issue = issue
+  return plan
+}
+
+/**
+ * What changed about the spec issue itself — `{description}`, `{state}`, or
+ * both, or null when neither did.
+ *
+ * Three states, not two: a snapshot may carry the split hashes, only the old
+ * combined one, or nothing at all. Only the first can say which field moved.
+ *
+ * The other two are UNKNOWN, and route to the harmless branch — today's welded
+ * behaviour, sending both fields. Sending a state that did not change is
+ * redundant; withholding one that did would leave the mirror silently stale, and
+ * that is the failure worth avoiding. The push rewrites the snapshot in the new
+ * shape, so a spec passes through `unknown` exactly once.
+ */
+function issueChanges(projection, snapshot) {
+  const p = projection || {}
+  const snap = snapshot || {}
+  const both = () => {
+    const out = { description: p.description ?? null, state: p.status ?? null }
+    // ASSERT, NEVER CLEAR, on this path. There are no split hashes here, so
+    // whether an assignee was ever pushed is unknown — and the harmless reading
+    // of "unknown" is to send one we have and stay silent about one we don't.
+    if (p.assignee != null) out.assignee = p.assignee
+    return out
+  }
+
+  const fields = snap.issueFields
+  if (fields === null || typeof fields !== 'object' || Array.isArray(fields)) {
+    // No split hashes recorded: an old snapshot, or no snapshot at all (a
+    // create, which needs both fields anyway).
+    if (snap.issue !== specIssueHash(p)) return both()
+    // Description and state are unchanged — but the COMBINED HASH SAYS NOTHING
+    // ABOUT THE ASSIGNEE, which was never one of its inputs. Absence of evidence
+    // again, and the two directions are not equally safe: asserting an assignee
+    // the repo actually recorded costs one redundant write, while staying quiet
+    // would strand it until some unrelated prose edit happened to push. Clearing
+    // is still never guessed at. The push rewrites the snapshot in the split
+    // shape, so a spec passes through here exactly once.
+    return p.assignee != null ? { assignee: p.assignee } : null
+  }
+
+  const want = specIssueFieldHashes(p)
+  const changed = {}
+  if (fields.description !== want.description) changed.description = p.description ?? null
+  if (fields.state !== want.state) changed.state = p.status ?? null
+
+  // ASSIGNEE — AN ABSENT SNAPSHOT KEY MEANS "NEVER PUSHED", NOT "WAS NULL".
+  //
+  // What would fool this check: every spec linked before assignee existed has a
+  // snapshot with no `assignee` key, and so does every spec in a repo that never
+  // opted the field in. Read that absence as `null` and the first push after
+  // upgrade computes null → null → "unchanged"… except where a PM had assigned
+  // the issue in Linear, which the repo would then silently clear. The bill for
+  // getting this wrong is somebody else's triage, workspace-wide, in one command.
+  //
+  // So absence is routed to the harmless branch: assert an assignee we actually
+  // have, and never send a clear at something we never set.
+  // (`.claude/rules/negative-checks.md` — prefer a positive signal to an absence,
+  // and bias the unknown case toward inaction.)
+  if (want.assignee !== undefined) {
+    if (fields.assignee === undefined) {
+      if (p.assignee != null) changed.assignee = p.assignee
+    } else if (fields.assignee !== want.assignee) {
+      // A recorded hash IS a positive signal that the repo pushed this field
+      // before, so a change to null here is a retraction of our own assignment
+      // rather than a guess at someone else's.
+      changed.assignee = p.assignee ?? null
+    }
+  }
+
+  return Object.keys(changed).length ? changed : null
+}
+
+// True when a plan would push nothing.
+function isEmptyPlan(plan) {
+  return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length
+}
+
+module.exports = {
+  planChanges,
+  remoteDescriptionEdited,
+  remoteSubIssueEdited,
+  issueChanges,
+  specIssueFieldHashes,
+  snapshotOf,
+  isEmptyPlan,
+  hashField,
+  stableStringify,
+  specIssueHash,
+  subIssueHash,
+}

package/src/vendor/sync-core/src/dialect.js

@@ -0,0 +1,51 @@
+'use strict'
+
+/**
+ * The tracker's markdown DIALECT — how a provider shapes outbound text and
+ * reduces read-backs for comparison. The engine is provider-neutral, but every
+ * tracker reserialises text its own way (one rewrites bullets and mangles
+ * emphasis, another stores a different format entirely), so the transforms live
+ * with the provider and arrive here on `config.dialect`.
+ *
+ * Three hooks, each `string → string` and pure:
+ *
+ *   - `canonicalize(text)`       — canonicalise a projected description so
+ *                                  semantically-equal content hashes equal
+ *                                  across the boundary.
+ *   - `flattenTables(text)`      — rewrite constructs the tracker's renderer is
+ *                                  known to corrupt (applied to every projected
+ *                                  body).
+ *   - `canonicalForCompare(text)`— reduce a read-back so the tracker's own
+ *                                  benign reserialisation does not read as data
+ *                                  loss (see `verify.js`).
+ *
+ * The identity dialect is the default: no provider transforms, plus the one
+ * reduction that is universal (line endings, trailing whitespace, blank-run
+ * collapse) so `canonicalForCompare` is never a bare string equality.
+ */
+
+function baseCanonicalForCompare(text) {
+  return String(text == null ? '' : text)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(/[ \t]+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+const identityDialect = Object.freeze({
+  canonicalize: (text) => text,
+  flattenTables: (text) => text,
+  canonicalForCompare: baseCanonicalForCompare,
+})
+
+// The dialect in play for a config: the provider's hooks over the identity
+// defaults, so a provider may supply any subset.
+function dialectOf(config) {
+  const d = config && config.dialect
+  if (!d || typeof d !== 'object') return identityDialect
+  return { ...identityDialect, ...d }
+}
+
+module.exports = { identityDialect, dialectOf, baseCanonicalForCompare }

package/src/vendor/sync-core/src/fields.js

@@ -0,0 +1,36 @@
+'use strict'
+
+/**
+ * The frontmatter FIELD VOCABULARY — which keys a provider stamps into spec
+ * files. The engine reads and writes stamps by these names and hardcodes none
+ * of them: each provider's config loader supplies its own set (the Linear
+ * provider defaults to `linear_identifier` / `linear_issue_id` / …), so a
+ * second provider stamps its own keys without touching the engine.
+ *
+ * Required keys: `identifier`, `url`, `issueId`, `assigneeId`.
+ * Optional: `assigneeName`, and `legacyIdentifier` / `legacyIssueId` — the keys
+ * a pre-9.0 mirror stamped. A provider with no legacy era simply omits them,
+ * and legacy detection then reports nothing (`legacy.js`).
+ *
+ * A missing `config.fields` THROWS rather than defaulting: a silent default
+ * would let the engine read stamps under names the provider never wrote, and
+ * the failure that produces is an all-creates plan that duplicates a live
+ * mirror — far worse than a loud error at the first call.
+ */
+
+function fieldsOf(config) {
+  const f = config && config.fields
+  if (!f || typeof f !== 'object' || Array.isArray(f)) {
+    throw new Error(
+      'config.fields missing — the provider config must name its frontmatter fields (identifier, url, issueId, assigneeId)',
+    )
+  }
+  for (const key of ['identifier', 'url', 'issueId', 'assigneeId']) {
+    if (typeof f[key] !== 'string' || !f[key]) {
+      throw new Error(`config.fields.${key} missing — the provider config must name this frontmatter field`)
+    }
+  }
+  return f
+}
+
+module.exports = { fieldsOf }

package/src/vendor/sync-core/src/legacy.js

@@ -0,0 +1,100 @@
+'use strict'
+
+/**
+ * Detect a spec whose mirror was created under the **pre-9.0 model**.
+ *
+ * v9 remapped the mirror: a spec is an issue (was a Project), a phase is a
+ * sub-issue (was a Milestone), and tasks are no longer objects at all. The
+ * frontmatter keys moved with it (in the Linear provider's vocabulary,
+ * `linear_project_id` -> `linear_identifier`, `linear_milestone_id` ->
+ * `linear_issue_id` — see `config.fields`).
+ *
+ * The failure this guards is silent and destructive: v9 looks for the new keys,
+ * finds nothing, and produces a perfectly ordinary **all-creates** plan. Applying
+ * it mints a fresh mirror and abandons the old one — in the field that would have
+ * been 17 new objects against 2 projects, 15 milestones and 145 task issues left
+ * orphaned, with nothing on screen suggesting a prior mirror existed. It was
+ * caught only because an all-creates plan looked wrong for specs synced an hour
+ * earlier.
+ *
+ * Pure reads; returns `null` for anything that is not demonstrably pre-9.0, so a
+ * never-pushed spec is never mistaken for a stranded one.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { parseFrontmatter } = require('./normalize.js')
+const { readBase } = require('./base.js')
+const { listPhaseFiles } = require('./write.js')
+
+// The pre-9.0 keys come from the provider's field vocabulary
+// (`config.fields.legacyIdentifier` / `.legacyIssueId`). A provider with no
+// pre-9.0 era omits them, and detection then reports nothing: there is no old
+// model its repos could be stranded on, so an absence is not evidence.
+
+function frontmatterOf(file) {
+  try {
+    return parseFrontmatter(fs.readFileSync(file, 'utf-8')).data || {}
+  } catch {
+    return {}
+  }
+}
+
+// A pre-9.0 snapshot recorded `{project, milestones, issues}`; v9 records
+// `{issue, subIssues}`. Counting what it holds turns the warning from "this
+// looks old" into "this many live objects would be abandoned".
+function countOrphans(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return null
+  const size = (v) => (Array.isArray(v) ? v.length : v && typeof v === 'object' ? Object.keys(v).length : 0)
+  const projects = snapshot.project ? 1 : 0
+  const milestones = size(snapshot.milestones)
+  const issues = size(snapshot.issues)
+  if (!projects && !milestones && !issues) return null
+  return { projects, milestones, issues, total: projects + milestones + issues }
+}
+
+/**
+ * @returns {null|{keys:string[], files:string[], orphans:object|null, orphanCount:number}}
+ */
+function detectLegacyMirror({ dir, snapshotDir, identifier, config }) {
+  const fields = (config && config.fields) || {}
+  const legacyOverviewKey = fields.legacyIdentifier
+  const legacyPhaseKey = fields.legacyIssueId
+  // No legacy vocabulary declared -> this provider has no pre-9.0 era, so there
+  // is no old model its repos could be stranded on, and an absence of the keys
+  // proves nothing (`.claude/rules/negative-checks.md`).
+  if (!legacyOverviewKey && !legacyPhaseKey) return null
+
+  const keys = []
+  const files = []
+
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const overview = frontmatterOf(path.join(snapshotDir, overviewFile))
+  if (legacyOverviewKey && overview[legacyOverviewKey] != null) {
+    keys.push(legacyOverviewKey)
+    files.push(overviewFile)
+  }
+
+  for (const file of listPhaseFiles(snapshotDir)) {
+    if (legacyPhaseKey && frontmatterOf(path.join(snapshotDir, file))[legacyPhaseKey] != null) {
+      if (!keys.includes(legacyPhaseKey)) keys.push(legacyPhaseKey)
+      files.push(file)
+    }
+  }
+
+  let orphans = null
+  try {
+    orphans = countOrphans(readBase(dir, identifier, config))
+  } catch {
+    /* an unreadable snapshot is not evidence either way */
+  }
+
+  // A legacy snapshot alone is enough: the spec may have had its frontmatter
+  // hand-cleaned while the mirror it names is still live.
+  if (!keys.length && !orphans) return null
+
+  return { keys, files, orphans, orphanCount: orphans ? orphans.total : 0 }
+}
+
+module.exports = { detectLegacyMirror }