@skitterbyte/skitterspec-linear 9.1.0 → 10.0.0

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

@@ -0,0 +1,90 @@
+'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 — `linear_project_id` → `linear_identifier`,
+ * `linear_milestone_id` → `linear_issue_id`.
+ *
+ * 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')
+
+// Frontmatter keys only the pre-9.0 model ever wrote.
+const LEGACY_OVERVIEW_KEY = 'linear_project_id'
+const LEGACY_PHASE_KEY = 'linear_milestone_id'
+
+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 keys = []
+  const files = []
+
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const overview = frontmatterOf(path.join(snapshotDir, overviewFile))
+  if (overview[LEGACY_OVERVIEW_KEY] != null) {
+    keys.push(LEGACY_OVERVIEW_KEY)
+    files.push(overviewFile)
+  }
+
+  for (const file of listPhaseFiles(snapshotDir)) {
+    if (frontmatterOf(path.join(snapshotDir, file))[LEGACY_PHASE_KEY] != null) {
+      if (!keys.includes(LEGACY_PHASE_KEY)) keys.push(LEGACY_PHASE_KEY)
+      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 }

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

@@ -253,14 +253,53 @@ function phaseTitle(body) {
   return t || null
 }
 
+// The raw ⬜/🔄/✅ on a phase file's h1, or undefined when it carries none.
+// Kept separate from `phaseStateBucket` because the LINT has to tell "absent"
+// apart from "not-started" — the projection deliberately cannot (see below).
+function headingEmoji(body) {
+  const h1 = /^#\s+(.*)$/m.exec(body)
+  return h1 ? (h1[1].match(/[⬜🔄✅]/u) || [])[0] : undefined
+}
+
+// The `> **Status:** …` line's value, or null when the file has none. This is
+// the human mirror of the heading emoji, not a source of truth — `lintPhases`
+// cross-checks it, and nothing else reads it.
+function phaseStatusLine(body) {
+  const m = /^>.*\*\*Status:\*\*\s*(.+?)\s*$/m.exec(body)
+  return m ? m[1] : null
+}
+
+// Read a `> **Status:**` value leniently into the canonical vocabulary: an emoji
+// if it carries one, else a word we recognise. Returns null for anything else —
+// the line is free prose, and warning on an unrecognised phrasing would train
+// the warning away.
+// `pending` is deliberately NOT here: "pending review" matches as not-started
+// but means roughly the opposite, and a false positive is worse than a missed
+// check — it teaches the reader to ignore the warning.
+const STATUS_WORDS = [
+  [/\b(not[\s-]?started|todo|to[\s-]do|planned)\b/i, 'not-started'],
+  [/\b(in[\s-]?progress|started|doing|wip)\b/i, 'in-progress'],
+  [/\b(done|complete[d]?|finished|shipped)\b/i, 'done'],
+]
+function statusLineValue(line) {
+  if (!line) return null
+  const emoji = (line.match(/[⬜🔄✅]/u) || [])[0]
+  if (emoji) return EMOJI_STATUS[emoji]
+  for (const [re, status] of STATUS_WORDS) if (re.test(line)) return status
+  return null
+}
+
 // A phase's status (from its heading emoji ⬜/🔄/✅) mapped to a state bucket the
 // `states` table understands, so a sub-issue lands in the matching Linear issue
 // state. Unknown/absent → backlog.
+//
+// That fallback conflates "author marked it not-started" with "author used a
+// format we don't parse", which is silent corruption: the wrong state pushes
+// cleanly and `record` then commits it as the INTENDED value. The fix is not
+// leniency here — one convention beats two — it is `lintPhases`, which warns.
 const PHASE_STATE_BUCKET = { 'not-started': 'backlog', 'in-progress': 'in-progress', done: 'complete' }
 function phaseStateBucket(body) {
-  const h1 = /^#\s+(.*)$/m.exec(body)
-  const emoji = h1 ? (h1[1].match(/[⬜🔄✅]/u) || [])[0] : undefined
-  return PHASE_STATE_BUCKET[EMOJI_STATUS[emoji]] || 'backlog'
+  return PHASE_STATE_BUCKET[EMOJI_STATUS[headingEmoji(body)]] || 'backlog'
 }
 
 // Parse a task line (already stripped of its leading "- ") into a keyed item:
@@ -303,7 +342,20 @@ function readPhaseFiles(snapshotDir) {
       // and Linear may canonicalize a soft line break away on save. Collapsing
       // both sides keeps a wrapped goal from diffing forever.
       const goal = collapseHyphenAware((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
-      const tasks = findTaskBlocks(body.split('\n')).map((b) => `[${b.mark}] ${b.text}`)
+      // Rendered as markdown checklist lines, ready to drop into a sub-issue
+      // description: indentation kept so nesting survives, each bullet keeping
+      // the marker its author wrote, and any inline `(KEY-123)` stamped on a legacy task
+      // line stripped — those ids were per-task issues we no longer create, and
+      // they read as noise in the mirror.
+      const tasks = findTaskBlocks(body.split('\n')).map((b) => {
+        // `findTaskBlocks` also returns the plain sub-bullets written underneath
+        // a task. They carry no checkbox, so they render as the bullet their
+        // author used — emitting `- [ ]` here would invent a task that does not
+        // exist in the repo.
+        const parsed = parseTaskLine(`[${b.checkbox ? b.mark : ' '}] ${b.text}`)
+        const text = parsed ? parsed.text : b.text
+        return b.checkbox ? `${b.indent}- [${b.mark}] ${text}` : `${b.indent}${b.marker} ${text}`
+      })
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -312,11 +364,85 @@ function readPhaseFiles(snapshotDir) {
         name: phaseTitle(body),
         goal: goal.trim(),
         state: phaseStateBucket(body),
+        // Lint-only signals. `emoji` is undefined when the heading carries none
+        // — the distinction `state` throws away; `statusLine` is the raw
+        // `> **Status:**` value. Neither affects the projection.
+        emoji: headingEmoji(body),
+        statusLine: phaseStatusLine(body),
         tasks,
       }
     })
 }
 
+// --- phase-status lint ------------------------------------------------------
+
+/**
+ * Warn where a phase's status signals are absent or disagree.
+ *
+ * A spec carries the same status in three places — the phase file's h1 emoji,
+ * its `> **Status:**` line, and the `00-overview.md` phase-index row — and only
+ * the h1 is load-bearing. Writing the other two correctly while leaving the h1
+ * bare projects a finished phase as `backlog`, pushes cleanly, and records the
+ * wrong value as intended. Nothing looks wrong anywhere.
+ *
+ * Returns `[{ file, code, message }]`, `code` being `missing-status-emoji` or
+ * `status-disagreement`. Pure aside from reads; callers decide how loud to be
+ * (today: printed, never fatal).
+ */
+function lintPhases(snapshotDir, config) {
+  const phases = readPhaseFiles(snapshotDir)
+  if (!phases.length) return []
+
+  // The overview may be absent (a legacy bare `<name>.md` spec) — that is not
+  // itself a lint failure, it just removes one of the three cross-checks.
+  let indexRows = []
+  try {
+    const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+    const raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
+    const { sections } = parseSections(parseFrontmatter(raw).body)
+    indexRows = parsePhaseIndex(sections.Phases)
+  } catch {
+    indexRows = []
+  }
+
+  const warnings = []
+  phases.forEach((phase, i) => {
+    if (!phase.emoji) {
+      warnings.push({
+        file: phase.file,
+        code: 'missing-status-emoji',
+        message: `no ⬜/🔄/✅ in the heading — projecting as not-started`,
+      })
+      // Without a heading emoji there is nothing to disagree WITH: the other two
+      // signals can't be checked against a value that was never expressed.
+      return
+    }
+
+    const heading = EMOJI_STATUS[phase.emoji]
+
+    const fromLine = statusLineValue(phase.statusLine)
+    if (fromLine && fromLine !== heading) {
+      warnings.push({
+        file: phase.file,
+        code: 'status-disagreement',
+        message: `heading says ${heading} but its Status line says ${fromLine}`,
+      })
+    }
+
+    // Match the index row by phase title, falling back to position — a renamed
+    // phase shouldn't silently drop the check.
+    const row = indexRows.find((r) => r.name === phase.name) || indexRows[i]
+    if (row && row.status !== heading) {
+      warnings.push({
+        file: phase.file,
+        code: 'status-disagreement',
+        message: `heading says ${heading} but the overview phase-index row says ${row.status}`,
+      })
+    }
+  })
+  return warnings
+}
+
 // --- ownership-driven field set ---------------------------------------------
 
 // Reduce an `extracted` map to exactly the configured field keys, defaulting a
@@ -359,6 +485,22 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
   return canonicalizeMarkdown(parts.join('\n\n')) || null
 }
 
+// A phase sub-issue's description: its `**Goal:**` line, plus the phase's task
+// list as a markdown checklist when `mapping.tasks` is `checklist`.
+//
+// The checklist is a READ-ONLY mirror like everything else here — the repo is
+// the source of truth, so a box ticked in the tracker is overwritten on the next
+// push. Without it a sub-issue is a title and one sentence, which is too thin to
+// act on; with it the phase is legible to someone working in the tracker without
+// tasks becoming individually-synced objects again.
+function subIssueBody(phase, tasksMode) {
+  if (tasksMode !== 'checklist' || !phase.tasks.length) return phase.goal
+  const parts = []
+  if (phase.goal) parts.push(phase.goal, '')
+  parts.push('## Tasks', '', ...phase.tasks)
+  return parts.join('\n')
+}
+
 /**
  * Normalize a local spec snapshot into the configured field set.
  */
@@ -376,6 +518,7 @@ function normalizeLocal(snapshotDir, config) {
   // so strip the `## Phases` index from the description to avoid duplicating it
   // (as prose AND as sub-issues) in the Linear mirror.
   const phasesProjected = !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership)
+  const tasksMode = (config.mapping && config.mapping.tasks) || 'checklist'
   const extracted = {
     description: buildDescription(
       title,
@@ -386,11 +529,12 @@ function normalizeLocal(snapshotDir, config) {
     // Sub-issue projection: one per phase. `ref` is the phase-file basename — the
     // local handle the push skill stamps a newly-created sub-issue id back into.
     // `state` is the phase's status bucket (from its heading emoji), mapped to a
-    // Linear issue state via `config.states` at push time. Tasks are NOT
-    // projected — they live only in the repo phase files.
+    // Linear issue state via `config.states` at push time. Tasks ride along in
+    // the description as a read-only checklist (`mapping.tasks`), never as
+    // individually-synced objects.
     subIssues: phases
       .filter((p) => p.name)
-      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: p.goal, state: p.state })),
+      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: subIssueBody(p, tasksMode), state: p.state })),
     // Status is the spec's lifecycle bucket. The folder is the source of truth;
     // an explicit `spec_status` frontmatter key overrides it if present.
     workflowState:
@@ -524,8 +668,45 @@ function validateStates(config, workspaceStates) {
   return configured.filter((name) => !have.has(name.toLowerCase().trim()))
 }
 
+// Words that identify a workspace state as belonging to a lifecycle bucket.
+// Used only to SUGGEST a replacement for a configured name the workspace does
+// not have — never to pick one silently. The 8→9 case this exists for is
+// `complete`, where the correct value inverts: the project status `Completed`
+// became the issue state `Done`, and no string-distance measure gets you from
+// one to the other.
+const BUCKET_WORDS = {
+  backlog: ['backlog', 'triage', 'todo', 'to do'],
+  'in-progress': ['in progress', 'in-progress', 'doing', 'started', 'in review'],
+  complete: ['done', 'complete', 'completed', 'shipped', 'merged', 'released'],
+  cancelled: ['canceled', 'cancelled', 'abandoned', "won't do", 'wont do', 'duplicate'],
+}
+
+/**
+ * For each configured state name the workspace lacks, what to use instead.
+ *
+ * `validateStates` says a name is wrong; this says what is right, which is the
+ * difference between an error you can act on and one you have to go look up.
+ *
+ * @returns {Array<{bucket:string, configured:string, suggestion:string|null}>}
+ */
+function stateSuggestions(config, workspaceStates) {
+  const names = (workspaceStates || []).map((s) => String(s)).filter(Boolean)
+  const have = new Set(names.map((n) => n.toLowerCase().trim()))
+  const out = []
+  for (const [bucket, configured] of Object.entries((config && config.states) || {})) {
+    if (typeof configured !== 'string') continue
+    if (have.has(configured.toLowerCase().trim())) continue
+    const words = BUCKET_WORDS[bucket] || []
+    const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
+    out.push({ bucket, configured, suggestion })
+  }
+  return out
+}
+
 module.exports = {
+  stateSuggestions,
   normalizeLocal,
+  lintPhases,
   readSnapshot,
   parseFrontmatter,
   parseSections,

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

@@ -18,6 +18,7 @@
 const { normalizeLocal } = require('./normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
 const { readBase, writeBase } = require('./base.js')
+const { detectLegacyMirror } = require('./legacy.js')
 
 // Build the one-way projection from a local snapshot: the spec issue's prose +
 // status, and its phase sub-issues. `status` is the local lifecycle bucket; the
@@ -36,6 +37,12 @@ function push({ dir, snapshotDir, identifier, config }) {
   const projection = projectionOf(snapshotDir, config)
   const snapshot = readBase(dir, identifier, config)
   const plan = planChanges(projection, snapshot)
+  // A spec still linked under the pre-9.0 model reads as unlinked here, so the
+  // plan above is all-creates and would abandon a live mirror. Carry the finding
+  // ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
+  // skill that applies this plan is exactly the consumer that would miss them.
+  const legacy = detectLegacyMirror({ dir, snapshotDir, identifier, config })
+  if (legacy) plan.legacy = legacy
   return { ok: true, empty: isEmptyPlan(plan), plan, projection }
 }
 

package/src/vendor/sync-core/src/task-block.js

@@ -25,6 +25,43 @@ const LIST_MARKER_RE = /^[ \t]*(?:[-*+]|\d+\.)\s/
 // A checkbox bullet — unambiguously a task, so it always starts its own block,
 // at any indent. (A bare list marker is ambiguous; a checkbox never is.)
 const CHECKBOX_RE = /^[ \t]*[-*+]\s*\[[ xX]\]/
+// A bare list bullet — no checkbox — captured with its marker so a sub-bullet
+// is re-rendered as the `-`/`*`/`1.` its author wrote.
+const BULLET_RE = /^([ \t]*)([-*+]|\d+\.)\s+(.*)$/
+
+function indentWidth(line) {
+  return line.length - line.trimStart().length
+}
+
+// Collect the wrapped continuation lines following the bullet opening at
+// `start`, seeded with the opener's own text. Shared by task bullets and plain
+// sub-bullets — both wrap the same way, and both stop at the first line that
+// belongs to something else.
+function collectContinuation(lines, start, hang, inFence, parts) {
+  let j = start + 1
+  for (; j < lines.length; j++) {
+    const l = lines[j]
+    if (!l.trim()) break
+    if (inFence[j]) break // a fence opening ends the bullet, never continues it
+    if (!CONTINUATION_RE.test(l)) break
+    if (BLOCK_BREAK_RE.test(l)) {
+      // Indent alone can't tell a nested child from a wrapped continuation —
+      // both sit at the hanging indent. The *marker* is the reliable signal:
+      //   - a checkbox (- [ ] / - [x]) is unambiguously a task → always break;
+      //   - a bare marker (-/*/+/N.) is wrapped continuation prose ONLY when it
+      //     sits exactly at the hang; shallower or deeper it's a real sub/
+      //     sibling list → break, and the caller's scan claims it as a block of
+      //     its own. (Keeping the at-hang continuation preserves the task's
+      //     stamped id, so the next push updates instead of creating a
+      //     duplicate issue.)
+      //   - headings, quotes, tables and fences always break.
+      if (CHECKBOX_RE.test(l)) break
+      if (!LIST_MARKER_RE.test(l) || indentWidth(l) !== hang) break
+    }
+    parts.push(l.trim())
+  }
+  return { end: j, parts }
+}
 
 // Mark every line that lies inside a fenced code block — the opening fence, its
 // content, and the closing fence all count as `true`. Line scanners that hunt
@@ -107,51 +144,68 @@ function spanMask(body) {
 }
 
 /**
- * Find every task bullet in `lines` as a logical block.
- * @returns {Array<{start:number, end:number, indent:string, mark:string, text:string}>}
+ * Find every task bullet in `lines` as a logical block, plus the non-checkbox
+ * bullets that live inside a task's list subtree.
+ * @returns {Array<{start:number, end:number, indent:string, marker:string,
+ *   checkbox:boolean, mark:string|null, text:string}>}
  *   `end` is exclusive. `text` is the collapsed single-line form, id included.
+ *   `checkbox` is false for a plain sub-bullet; its `mark` is then null and its
+ *   `marker` is the bullet it was written with (`-`, `*`, `1.` …).
  */
 function findTaskBlocks(lines) {
   const blocks = []
   const inFence = fenceMask(lines)
+  // The marker indents of the task bullets whose list subtree is still open,
+  // outermost first. Without this the scan had no model of nesting at all: a
+  // bare bullet that dedented out of a nested checkbox belonged to nothing and
+  // was silently dropped, taking its wrapped continuations with it.
+  const open = []
+
   for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // A blank line alone doesn't close a subtree — a loose list is still a list.
+    // What closes it is a later line at or shallower than the task's own indent.
+    if (!line.trim()) continue
+    const indent = indentWidth(line)
+    while (open.length && indent <= open[open.length - 1]) open.pop()
     if (inFence[i]) continue // an example bullet inside a ``` block is not a task
-    const m = TASK_START_RE.exec(lines[i])
-    if (!m) continue
-    const parts = [m[3]]
-    // The hanging indent: where the bullet's text starts (marker width). A
-    // wrapped continuation aligns exactly AT this column.
-    const hang = lines[i].length - m[3].length
-    let j = i + 1
-    for (; j < lines.length; j++) {
-      const l = lines[j]
-      if (!l.trim()) break
-      if (inFence[j]) break // a fence opening ends the bullet, never continues it
-      if (!CONTINUATION_RE.test(l)) break
-      if (BLOCK_BREAK_RE.test(l)) {
-        // Indent alone can't tell a nested child from a wrapped continuation —
-        // both sit at the hanging indent. The *marker* is the reliable signal:
-        //   - a checkbox (- [ ] / - [x]) is unambiguously a task → always break;
-        //   - a bare marker (-/*/+/N.) is wrapped continuation prose ONLY when it
-        //     sits exactly at the hang; shallower or deeper it's a real sub/
-        //     sibling list → break. (Keeping the at-hang continuation preserves
-        //     the task's stamped id, so the next push updates instead of
-        //     creating a duplicate issue.)
-        //   - headings, quotes, tables and fences always break.
-        if (CHECKBOX_RE.test(l)) break
-        const indent = l.length - l.trimStart().length
-        if (!LIST_MARKER_RE.test(l) || indent !== hang) break
-      }
-      parts.push(l.trim())
+
+    const t = TASK_START_RE.exec(line)
+    if (t) {
+      // The hanging indent: where the bullet's text starts (marker width). A
+      // wrapped continuation aligns exactly AT this column.
+      const { end, parts } = collectContinuation(lines, i, line.length - t[3].length, inFence, [t[3]])
+      blocks.push({
+        start: i,
+        end,
+        indent: t[1],
+        marker: '-',
+        checkbox: true,
+        mark: t[2].toLowerCase() === 'x' ? 'x' : ' ',
+        text: collapseHyphenAware(parts.join('\n')),
+      })
+      open.push(indent)
+      i = end - 1
+      continue
     }
+
+    // A bare bullet is claimed ONLY inside an open task's subtree. Outside one
+    // it is ordinary prose in the phase file: the projection is the task list,
+    // not the whole body, and widening it here would mirror a Notes section.
+    if (!open.length) continue
+    const b = BULLET_RE.exec(line)
+    if (!b) continue
+    const { end, parts } = collectContinuation(lines, i, line.length - b[3].length, inFence, [b[3]])
     blocks.push({
       start: i,
-      end: j,
-      indent: m[1],
-      mark: m[2].toLowerCase() === 'x' ? 'x' : ' ',
+      end,
+      indent: b[1],
+      marker: b[2],
+      checkbox: false,
+      mark: null,
       text: collapseHyphenAware(parts.join('\n')),
     })
-    i = j - 1
+    i = end - 1
   }
   return blocks
 }

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

@@ -128,6 +128,7 @@ function stampIssueId(snapshotDir, text, id) {
     const lines = fs.readFileSync(p, 'utf-8').split('\n')
     const width = inferWidth(lines)
     for (const b of findTaskBlocks(lines)) {
+      if (!b.checkbox) continue // a plain sub-bullet is not a task — never stamp one
       if (INLINE_ID_RE.test(b.text)) continue
       if (b.text !== want) continue
       const rendered = renderTaskBlock({ indent: b.indent, done: b.mark === 'x', text: want, id }, width)