@skitterbyte/skitterspec-linear 7.0.2 → 8.0.1

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

@@ -1,33 +1,30 @@
 'use strict'
 
 /**
- * The three-way compare at the heart of the hybrid sync.
+ * One-sided change detection for one-way sync (repo → Linear).
  *
- * `classify(local, remote, base, config)` compares each configured field across
- * the local snapshot, the remote (remote) projection, and the committed base
- * (the last-synced state). Per field it returns a raw three-way `status`
- * (unchanged / local-only / remote-only / conflict), then collapses it through
- * the field's ownership (`both|pull|push`) into effective `pushable` / `pullable`
- * flags. Ownership is what makes most "both sides differ" cases *not* a real
- * conflict:
- *   - a `pull` field never pushes (remote wins) → conflict collapses to remote-only
- *   - a `push` field never pulls (repo wins)    → conflict collapses to local-only
- *   - only a `both` field where both sides moved off base is a true `conflict`.
+ * 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:
  *
- * Pure and deterministic: field identity is a stable content hash (sorted-key
- * JSON → SHA-1), so `null`, `undefined`, and a missing base all compare equal,
- * and object key order never causes a false diff. No Date.now()/Math.random().
+ *   - 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')
 
-// Deterministic JSON: object keys sorted recursively; array order preserved
-// (order is meaningful for milestones/tasks). undefined normalises to null.
+// 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 (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(',') + '}'
@@ -35,181 +32,93 @@ function stableStringify(value) {
   return JSON.stringify(value)
 }
 
-// Stable content hash of a single field value.
+// Stable content hash of a value.
 function hashField(value) {
   return createHash('sha1').update(stableStringify(value)).digest('hex')
 }
 
-// Raw three-way status from the three hashes.
-function rawStatus(localH, remoteH, baseH) {
-  const localChanged = localH !== baseH
-  const remoteChanged = remoteH !== baseH
-  if (!localChanged && !remoteChanged) return 'unchanged'
-  if (localChanged && !remoteChanged) return 'local-only'
-  if (!localChanged && remoteChanged) return 'remote-only'
-  // both moved off base — but they may have converged on the same value.
-  if (localH === remoteH) return 'unchanged'
-  return 'conflict'
-}
+// --- 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) ---------
 
-// --- keyed collections (per-item three-way) --------------------------------
-
-// Index an array of items by their `idKey` value (stringified). Non-arrays and
-// items missing the id are skipped — they can't participate in a keyed merge.
-function indexById(arr, idKey) {
-  const map = new Map()
-  if (Array.isArray(arr)) {
-    for (const item of arr) {
-      if (item && typeof item === 'object' && item[idKey] != null) {
-        map.set(String(item[idKey]), item)
-      }
-    }
-  }
-  return map
-}
-
-// Signature of an item under a given id: its content hash with the id stripped
-// (so an id-only change / reorder is not a content edit), or 'ABSENT' when the
-// id isn't present on that side. 'ABSENT' never collides with a hex hash.
-function itemSignature(map, id, idKey) {
-  if (!map.has(id)) return 'ABSENT'
-  const { [idKey]: _omit, ...content } = map.get(id)
-  return hashField(content)
-}
-
-// Raw per-item three-way: which side moved off base, and how (added/edited/
-// removed). Mirrors rawStatus but tracks presence so add vs edit vs remove is
-// distinguishable.
-function itemRaw(localSig, remoteSig, baseSig) {
-  const localChanged = localSig !== baseSig
-  const remoteChanged = remoteSig !== baseSig
-  if (!localChanged && !remoteChanged) return { raw: 'unchanged', side: null }
-  const kind = (sig, base) => (base === 'ABSENT' ? 'added' : sig === 'ABSENT' ? 'removed' : 'edited')
-  if (localChanged && !remoteChanged) return { raw: kind(localSig, baseSig), side: 'local' }
-  if (!localChanged && remoteChanged) return { raw: kind(remoteSig, baseSig), side: 'remote' }
-  if (localSig === remoteSig) return { raw: 'unchanged', side: null } // both converged
-  return { raw: 'conflict', side: null }
-}
-
-// Collapse a raw per-item outcome through ownership into an effective status +
-// push/pull flags. Removals are report-only in v1 (surfaced, never auto-applied).
-function collapseItem({ raw, side }, ownership) {
-  const canPush = ownership === 'both' || ownership === 'push'
-  const canPull = ownership === 'both' || ownership === 'pull'
-  if (raw === 'unchanged') return { status: 'unchanged', side: null, pushable: false, pullable: false, report: false }
-  if (raw === 'removed') return { status: 'removed', side, pushable: false, pullable: false, report: true }
-  if (raw === 'conflict') {
-    if (ownership === 'push') return { status: 'edited', side: 'local', pushable: true, pullable: false, report: false }
-    if (ownership === 'pull') return { status: 'edited', side: 'remote', pushable: false, pullable: true, report: false }
-    return { status: 'conflict', side: null, pushable: true, pullable: true, report: false }
-  }
-  // added / edited
-  if (side === 'local') return { status: raw, side, pushable: canPush, pullable: false, report: false }
-  return { status: raw, side, pushable: false, pullable: canPull, report: false }
+// The project 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.
+function projectHash(p) {
+  return hashField({ description: p.description ?? null, status: p.status ?? null })
 }
+const milestoneHash = (m) => hashField({ name: m.name ?? null, goal: m.goal ?? null })
+const issueHash = (t) => hashField({ title: t.title ?? null, description: t.description ?? null, done: !!t.done })
 
 /**
- * Classify a keyed collection field item-by-item. Returns one entry per id seen
- * across local/remote/base, each with its effective status and push/pull flags,
- * plus the local/remote item values so a caller can apply the change.
+ * The snapshot to commit after a successful push: a content hash per object 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 classifyItems(local, remote, base, ownership, idKey) {
-  const lMap = indexById(local, idKey)
-  const rMap = indexById(remote, idKey)
-  const bMap = indexById(base, idKey)
-  const ids = new Set([...lMap.keys(), ...rMap.keys(), ...bMap.keys()])
-  const items = []
-  for (const id of ids) {
-    const raw = itemRaw(
-      itemSignature(lMap, id, idKey),
-      itemSignature(rMap, id, idKey),
-      itemSignature(bMap, id, idKey),
-    )
-    const c = collapseItem(raw, ownership)
-    items.push({
-      id,
-      status: c.status,
-      side: c.side,
-      pushable: c.pushable,
-      pullable: c.pullable,
-      report: c.report,
-      local: lMap.get(id) || null,
-      remote: rMap.get(id) || null,
-    })
+function snapshotOf(projection) {
+  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 {
+    project: projectHash(p),
+    milestones: byId(p.milestones, milestoneHash),
+    issues: byId(p.issues, issueHash),
   }
-  return items
-}
-
-// Collapse the raw status through ownership into an effective status + flags.
-function collapse(raw, ownership) {
-  const canPush = ownership === 'both' || ownership === 'push'
-  const canPull = ownership === 'both' || ownership === 'pull'
-
-  if (raw === 'unchanged') return { status: 'unchanged', pushable: false, pullable: false }
-  if (raw === 'local-only') return { status: 'local-only', pushable: canPush, pullable: false }
-  if (raw === 'remote-only') return { status: 'remote-only', pushable: false, pullable: canPull }
-
-  // conflict: both sides diverged off base.
-  if (ownership === 'push') return { status: 'local-only', pushable: true, pullable: false }
-  if (ownership === 'pull') return { status: 'remote-only', pushable: false, pullable: true }
-  return { status: 'conflict', pushable: true, pullable: true }
 }
 
 /**
- * Classify every field in `config.sync.fieldOwnership`.
- *
- * @param {object} local  normalized local snapshot (normalizeLocal output)
- * @param {object} remote normalized remote projection (normalizeRemote output)
- * @param {object|null} base the committed base (same shape) or null (never synced)
- * @returns {Array<{field, ownership, raw, status, pushable, pullable}>}
- *   one entry per configured field, in config order.
+ * Diff the local projection against the last-pushed snapshot.
+ * @returns {{ project?: object, milestones: {create,update}, issues: {create,update} }}
+ *   create items carry a `ref` (local handle) and no id; update items carry `id`.
  */
-function classify(local, remote, base, config) {
-  const ownership = config.sync.fieldOwnership
-  const keyed = (config.sync && config.sync.keyedFields) || {}
-  const baseObj = base || {}
-  return Object.keys(ownership).map((field) => {
-    const own = ownership[field]
-    const idKey = keyed[field]
+function planChanges(projection, snapshot) {
+  const p = projection || {}
+  const snap = snapshot || {}
+  const snapM = snap.milestones || {}
+  const snapI = snap.issues || {}
+
+  const milestones = { create: [], update: [] }
+  for (const m of p.milestones || []) {
+    if (m.id == null) milestones.create.push({ ref: m.ref, name: m.name, goal: m.goal })
+    else if (snapM[String(m.id)] !== milestoneHash(m)) milestones.update.push({ id: m.id, name: m.name, goal: m.goal })
+  }
 
-    // Keyed collection: per-item three-way. Field-level flags aggregate the
-    // items so existing summary code still sees "does this field have work?".
-    if (idKey) {
-      const items = classifyItems(
-        local ? local[field] : null,
-        remote ? remote[field] : null,
-        field in baseObj ? baseObj[field] : null,
-        own,
-        idKey,
-      )
-      const active = items.filter((i) => i.status !== 'unchanged')
-      return {
-        field,
-        ownership: own,
-        keyed: true,
-        idKey,
-        items,
-        status: active.length ? 'items-changed' : 'unchanged',
-        pushable: items.some((i) => i.pushable),
-        pullable: items.some((i) => i.pullable),
-      }
+  const issues = { create: [], update: [] }
+  for (const t of p.issues || []) {
+    if (t.id == null) {
+      issues.create.push({ ref: t.ref, title: t.title, description: t.description, done: !!t.done, milestoneRef: t.milestoneRef })
+    } else if (snapI[String(t.id)] !== issueHash(t)) {
+      issues.update.push({ id: t.id, title: t.title, description: t.description, done: !!t.done })
     }
+  }
+
+  const plan = { milestones, issues }
+  if (snap.project !== projectHash(p)) {
+    plan.project = { description: p.description ?? null, status: p.status ?? null }
+  }
+  return plan
+}
 
-    // Scalar / whole-field (behaviour unchanged).
-    const localH = hashField(local ? local[field] : null)
-    const remoteH = hashField(remote ? remote[field] : null)
-    const baseH = hashField(field in baseObj ? baseObj[field] : null)
-    const raw = rawStatus(localH, remoteH, baseH)
-    const { status, pushable, pullable } = collapse(raw, own)
-    return { field, ownership: own, raw, status, pushable, pullable }
-  })
+// True when a plan would push nothing.
+function isEmptyPlan(plan) {
+  return (
+    !plan.project &&
+    !plan.milestones.create.length &&
+    !plan.milestones.update.length &&
+    !plan.issues.create.length &&
+    !plan.issues.update.length
+  )
 }
 
 module.exports = {
-  classify,
-  classifyItems,
+  planChanges,
+  snapshotOf,
+  isEmptyPlan,
   hashField,
   stableStringify,
-  rawStatus,
-  collapse,
+  projectHash,
+  milestoneHash,
+  issueHash,
 }

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

@@ -16,7 +16,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
-const { findTaskBlocks, collapse } = require('./task-block.js')
+const { findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
 
 // --- markdown / frontmatter parsing -----------------------------------------
 
@@ -126,8 +126,14 @@ function joinOpenSpans(text) {
     const c = text[i]
     if (c === '\n') {
       if (!code && (bold || italic || link)) {
-        out.push(' ')
-        while (i + 1 < text.length && (text[i + 1] === ' ' || text[i + 1] === '\t')) i++
+        // Skip the continuation's indentation, then join. A word wrapped at a
+        // hyphen (`state-entry-with-`⏎`assignment`) is one compound — join TIGHT
+        // (no space) so we don't corrupt it; otherwise a single space.
+        let j = i + 1
+        while (j < text.length && (text[j] === ' ' || text[j] === '\t')) j++
+        const softHyphen = text[i - 1] === '-' && /\w/.test(text[i - 2] || '') && /\w/.test(text[j] || '')
+        if (!softHyphen) out.push(' ')
+        i = j - 1
       } else {
         out.push('\n')
       }
@@ -200,6 +206,11 @@ function canonicalizeMarkdown(text) {
     .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
     .join('\n')
   return joinEmphasisAcrossBreaks(marked)
+    // A word wrapped at a hyphen within a paragraph (`state-entry-with-`⏎
+    // `assignment`) rejoins TIGHT — otherwise Linear (CommonMark) renders the
+    // soft line break as a space and corrupts the compound. Single newline only,
+    // so paragraph breaks are preserved.
+    .replace(/(\w-)[ \t]*\n[ \t]*(?=\w)/g, '$1')
     .replace(/\n{3,}/g, '\n\n')
     .trim()
 }
@@ -275,7 +286,7 @@ function readPhaseFiles(snapshotDir) {
       // Collapsed, not just captured: the goal becomes a milestone description,
       // and Linear may canonicalize a soft line break away on save. Collapsing
       // both sides keeps a wrapped goal from diffing forever.
-      const goal = collapse((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
+      const goal = collapseHyphenAware((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
       const tasks = findTaskBlocks(body.split('\n')).map((b) => `[${b.mark}] ${b.text}`)
       return {
         phase: file.replace(/\.md$/, ''),
@@ -335,24 +346,39 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
  */
 function normalizeLocal(snapshotDir, config) {
   const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
-  const milestonesKeyed = !!(config.sync.keyedFields && config.sync.keyedFields.milestones)
+  // Phases sync as first-class Milestones whenever `milestones` is in the pushed
+  // projection, so strip the `## Phases` index from the description to avoid
+  // duplicating it (as prose AND as milestones) in the Linear mirror.
+  const milestonesProjected = !!(config.sync.fieldOwnership && 'milestones' in config.sync.fieldOwnership)
   const extracted = {
     description: buildDescription(
       title,
       sections,
       config.sync.localOnlySections,
-      milestonesKeyed ? ['Phases'] : [],
+      milestonesProjected ? ['Phases'] : [],
     ),
-    // Keyed milestone items: a phase's linked milestone id (or null when
-    // unlinked), its title and goal. Unlinked phases carry id:null and are
-    // skipped by the keyed compare until they're linked.
+    // Milestone projection items. `ref` is the phase-file basename — the local
+    // handle the push skill stamps a newly-created milestone id back into.
     milestones: phases
       .filter((p) => p.name)
-      .map((p) => ({ id: p.id, name: p.name, goal: p.goal })),
-    // Keyed task items across all phases: inline issue id (or null), text, done.
-    // Deliberately just {id,text,done} so it hashes equal to a remote issue — the
-    // owning phase is recovered at push time by locating the task line.
-    tasks: phases.flatMap((p) => p.tasks.map(parseTaskLine).filter(Boolean)),
+      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: p.goal })),
+    // Issue projection items across all phases. `title` is the first-sentence
+    // Linear title; `description` is the full task text (the mirror keeps both).
+    // `ref` = the collapsed text the push skill matches to stamp a new id in;
+    // `milestoneRef` links the issue to its milestone (id if linked, else phase).
+    tasks: phases.flatMap((p) =>
+      p.tasks
+        .map(parseTaskLine)
+        .filter(Boolean)
+        .map((t) => ({
+          id: t.id,
+          ref: t.text,
+          title: titleFromText(t.text),
+          description: t.text,
+          done: t.done,
+          milestoneRef: p.id || p.phase,
+        })),
+    ),
     phaseBodies: phases.map((p) => ({ phase: p.phase, goal: p.goal })),
     acceptanceCriteria: sections['Acceptance criteria'] || null,
     taskBreakdown: phases.map((p) => ({ phase: p.phase, tasks: p.tasks })),
@@ -399,87 +425,65 @@ function remoteStateName(project) {
   return st
 }
 
-// Real Linear priority is an object `{ value, name }`; accept a bare number too.
-function remotePriority(priority) {
-  if (priority == null) return null
-  if (typeof priority === 'object') return priority.value != null ? priority.value : null
-  return priority
-}
-
-// Real Linear labels are `[{ id, name }]`; accept bare strings too.
-function remoteLabels(labels) {
-  if (!Array.isArray(labels)) return []
-  return labels
-    .map((l) => (typeof l === 'string' ? l : l && l.name != null ? l.name : null))
-    .filter((n) => n != null)
+// The ONE thing one-way sync reads back: the mirror's current workflow state,
+// mapped to the local lifecycle bucket, so `/spec-status` can report a drift
+// ("Linear says Done, your spec says In Progress"). Read-only — it never writes.
+function remoteWorkflowState(project, config) {
+  const name = remoteStateName(project || {})
+  return name != null ? bucketForState(name, config) : null
 }
 
-// Whether a remote Linear issue is complete. The real MCP shape is a flat
-// `statusType` ("completed") — accept the legacy `state.type` and `completedAt`
-// / bare `done` too (fixtures, older shapes).
-function remoteIssueDone(iss) {
-  if (iss.done === true) return true
-  const type = iss.statusType != null ? iss.statusType : iss.state && iss.state.type
-  if (type != null) return String(type).toLowerCase() === 'completed'
-  return iss.completedAt != null
+// Derive a short Linear issue title from a task's full text: the first sentence,
+// falling back to the first `max` chars at a word boundary. A paragraph-length
+// task keeps its full text as the issue *description* (see the projection); this
+// is only the title, so it must read as a one-liner. Guards decimals/versions
+// (`7.0.2`) and common abbreviations (`e.g.`, `i.e.`, `etc.`) so it doesn't cut
+// mid-number or mid-abbreviation.
+function titleFromText(text, max = 100) {
+  const s = collapse(text)
+  if (!s) return s
+  let title = s
+  const re = /[.!?]/g
+  let m
+  while ((m = re.exec(s)) !== null) {
+    const i = m.index
+    const after = s[i + 1]
+    if (after !== undefined && !/\s/.test(after)) continue // not a sentence end
+    if (/\d/.test(s[i - 1] || '') && /\d/.test(after || '')) continue // 7.0.2, 3.14
+    if (/(^|\s)(e\.g|i\.e|etc|vs|no|fig|cf)$/i.test(s.slice(0, i))) continue // abbrev
+    title = s.slice(0, i) // drop the terminator
+    break
+  }
+  title = title.trim()
+  if (title.length > max) {
+    const cut = title.slice(0, max)
+    const sp = cut.lastIndexOf(' ')
+    title = (sp > 40 ? cut.slice(0, sp) : cut).trim()
+  }
+  return title
 }
 
-/**
- * Normalize a remote Project projection (from the MCP adapter, or a fixture)
- * into the same field set as `normalizeLocal`.
- */
-function normalizeRemote(project, config) {
-  const p = project || {}
-  const milestones = Array.isArray(p.milestones) ? p.milestones : []
-  const stateName = remoteStateName(p)
-  const extracted = {
-    description: p.description != null ? canonicalizeMarkdown(p.description) : null,
-    // Keyed milestone items mirroring normalizeLocal: id, title, goal (the Linear
-    // milestone's description). Progress is Linear-derived and not synced.
-    milestones: milestones.map((m) => ({
-      id: m.id != null ? String(m.id) : null,
-      name: m.name,
-      // A milestone's description mirrors the phase's `**Goal:**` line; strip the
-      // label so it hashes equal to the local goal (which readPhaseFiles already
-      // captures without it).
-      goal: (m.description != null ? m.description : '')
-        .replace(/^\s*\*\*Goal:\*\*\s*/, '')
-        .trim(),
-    })),
-    phaseBodies: milestones.map((m) => ({
-      phase: m.name,
-      goal: (m.description != null ? m.description : '').trim(),
-    })),
-    acceptanceCriteria: p.acceptanceCriteria != null ? p.acceptanceCriteria : null,
-    // Keyed task items from the project's issues: keyed by the human identifier
-    // (SKI-123, what the inline task-line id carries — the Linear MCP returns it as
-    // the issue's `id`), text ← title, done ← a completed-type workflow state.
-    tasks: (Array.isArray(p.issues) ? p.issues : []).map((iss) => ({
-      id: iss.identifier != null ? String(iss.identifier) : iss.id != null ? String(iss.id) : null,
-      text: iss.title != null ? iss.title : '',
-      done: remoteIssueDone(iss),
-    })),
-    taskBreakdown: milestones.map((m) => ({
-      phase: m.name,
-      tasks: Array.isArray(m.tasks) ? m.tasks : [],
-    })),
-    workflowState: stateName != null ? bucketForState(stateName, config) : null,
-    priority: remotePriority(p.priority),
-    labels: remoteLabels(p.labels),
-  }
-  return toFieldSet(extracted, config)
+// Which configured state NAMES are absent from the live workspace. The skill
+// fetches the workspace's project-status names over MCP and passes them here;
+// a non-empty result means a typo/rename that Linear would silently no-op.
+function validateStates(config, workspaceStates) {
+  const configured = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
+  const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
+  return configured.filter((name) => !have.has(name.toLowerCase().trim()))
 }
 
 module.exports = {
   normalizeLocal,
-  normalizeRemote,
   readSnapshot,
   parseFrontmatter,
   parseSections,
   parsePhaseIndex,
   parseTaskLine,
+  titleFromText,
+  validateStates,
   canonicalRemoteStatus,
   canonicalizeMarkdown,
   joinEmphasisAcrossBreaks,
   bucketForState,
+  remoteWorkflowState,
 }