@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,67 @@
+'use strict'
+
+/**
+ * Compare what the tracker STORED against what we sent, and report lost text.
+ *
+ * Why this is not a pull. One-way sync's rule is about **authority**: the
+ * tracker must never influence repo content. This reads a description back to
+ * *check* it — it merges nothing, writes nothing, and feeds nothing into the
+ * projection or the snapshot. The repo remains the only source of truth; the
+ * only output is a warning for a human. Without it, a parser that silently eats
+ * characters produces a mirror that looks pushed and is wrong, which is exactly
+ * how the nested-table corruption went unnoticed (see the Linear provider's
+ * dialect, where that flattener now lives).
+ *
+ * The engine is offline, so the read itself belongs to the push skill — it
+ * fetches over MCP and hands the result here, the same split
+ * `--workspace-states` already uses.
+ *
+ * Each tracker reserialises text its own way, so the reduction that makes its
+ * benign transforms invisible is the provider's `config.dialect.canonicalForCompare`
+ * (see `src/dialect.js`); with no dialect the identity reduction applies.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ */
+
+const { dialectOf } = require('./dialect.js')
+
+// The word-character stream: everything that carries meaning, with every
+// reformatting artefact (whitespace, bullets, asterisk boundaries, pipes,
+// separators) removed. Comparing these catches dropped characters while
+// ignoring every benign transform the dialect names.
+function stream(text, config) {
+  return dialectOf(config).canonicalForCompare(text).replace(/[^\p{L}\p{N}]/gu, '')
+}
+
+/**
+ * @param {string} sent    what we pushed
+ * @param {string} stored  what the tracker returned
+ * @param {object} [config] the provider config (for its dialect)
+ * @returns {{ok:boolean, at:number|null, lost:number, sentContext:string, storedContext:string}}
+ *   `ok` false means word characters differ — content was lost or altered.
+ *   `at` is the index in the reduced stream where they first diverge, with ~40
+ *   characters of each side around it so the warning names the damage.
+ */
+// BLIND SPOT: a `stored` the caller never fetched is indistinguishable here
+// from a description the tracker really did store empty — both reduce to `''`
+// and read as total loss. The evidence that the read happened lives with the
+// caller, so it must pass only a description it actually read back (`verifyLines`
+// gates on `typeof stored.issue === 'string'` for exactly this reason).
+function compareStored(sent, stored, config) {
+  const a = stream(sent, config)
+  const b = stream(stored, config)
+  if (a === b) return { ok: true, at: null, lost: 0, sentContext: '', storedContext: '' }
+
+  let at = 0
+  while (at < a.length && at < b.length && a[at] === b[at]) at++
+  const window = (s) => s.slice(Math.max(0, at - 10), at + 30)
+  return {
+    ok: false,
+    at,
+    lost: a.length - b.length,
+    sentContext: window(a),
+    storedContext: window(b),
+  }
+}
+
+module.exports = { compareStored, stream }

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

@@ -0,0 +1,191 @@
+'use strict'
+
+/**
+ * Push-side writeback: after `push` creates the spec issue + phase sub-issues in
+ * Linear, the skill stamps each returned id back into the repo so the next push
+ * updates rather than recreates. Everything here edits the repo in place:
+ *
+ *   - `stampSubIssueId(dir, file, id, config)` — add/update the provider's
+ *     phase-stamp field (`config.fields.issueId`) in a phase
+ *     file's frontmatter (locate the file with `findPhaseFileByTitle`).
+ *   - `writeFrontmatter(dir, config, patch)` — patch `00-overview.md` frontmatter
+ *     (e.g. the spec issue's `spec_identifier`, `last_synced_at`).
+ *   - `stampIssueId(dir, text, id)` — legacy: append `(ID)` to a task line
+ *     (tasks are no longer synced; kept for the sanitise/util paths).
+ *
+ * No remote read, no pull writeback — the repo is the source of truth.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { findTaskBlocks, renderTaskBlock, collapse, inferWidth } = require('./task-block.js')
+const { fieldsOf } = require('./fields.js')
+
+// Serialize a JS value as a YAML-ish frontmatter scalar.
+function serialize(value) {
+  if (Array.isArray(value)) return JSON.stringify(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  return JSON.stringify(String(value)) // quoted string
+}
+
+// Split `---\n…\n---\n` frontmatter off the top. Returns { fmLines, body, had }.
+function splitFrontmatter(raw) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw)
+  if (!m) return { fmLines: [], body: raw, had: false }
+  return { fmLines: m[1].split('\n'), body: raw.slice(m[0].length), had: true }
+}
+
+// Apply a key→value patch onto frontmatter lines, preserving order.
+function patchFrontmatterLines(lines, patch) {
+  const keys = new Set(Object.keys(patch))
+  const out = []
+  const seen = new Set()
+  for (const line of lines) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (kv && keys.has(kv[1])) {
+      out.push(`${kv[1]}: ${serialize(patch[kv[1]])}`)
+      seen.add(kv[1])
+    } else {
+      out.push(line)
+    }
+  }
+  for (const key of Object.keys(patch)) {
+    if (!seen.has(key)) out.push(`${key}: ${serialize(patch[key])}`)
+  }
+  return out
+}
+
+/**
+ * Update `00-overview.md` frontmatter under `snapshotDir` with `patch`
+ * (key → value; nullish values are skipped). Returns the list of keys written.
+ */
+function writeFrontmatter(snapshotDir, config, patch) {
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const file = path.join(snapshotDir, overviewFile)
+  const raw = fs.readFileSync(file, 'utf-8')
+
+  const clean = {}
+  for (const [k, v] of Object.entries(patch)) {
+    if (v !== null && v !== undefined) clean[k] = v
+  }
+  if (!Object.keys(clean).length) return []
+
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  const patched = patchFrontmatterLines(fmLines, clean)
+  const frontmatter = `---\n${patched.join('\n')}\n---\n`
+  const next = had ? frontmatter + body : frontmatter + '\n' + raw
+
+  fs.writeFileSync(file, next, 'utf-8')
+  return Object.keys(clean)
+}
+
+/**
+ * Remove keys from `00-overview.md` frontmatter. Returns the keys actually
+ * removed (absent ones are a clean no-op, not an error).
+ *
+ * A separate function because `writeFrontmatter` SKIPS nullish values by
+ * design — that is what lets a caller pass a sparse patch without clearing the
+ * fields it left out, and it means "remove this key" is inexpressible there. A
+ * released assignment has to actually leave the file: setting it empty would
+ * leave a spec claiming to be assigned to nobody in particular, and the
+ * projection reads presence, not emptiness.
+ */
+function deleteFrontmatter(snapshotDir, config, keys) {
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const file = path.join(snapshotDir, overviewFile)
+  const raw = fs.readFileSync(file, 'utf-8')
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  if (!had) return []
+
+  const drop = new Set(keys)
+  const removed = []
+  const kept = fmLines.filter((line) => {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (kv && drop.has(kv[1])) {
+      removed.push(kv[1])
+      return false
+    }
+    return true
+  })
+  if (!removed.length) return []
+
+  // An emptied block is dropped entirely rather than left as `---\n---`, which
+  // some markdown renderers show as a horizontal rule.
+  const next = kept.length ? `---\n${kept.join('\n')}\n---\n${body}` : body
+  fs.writeFileSync(file, next, 'utf-8')
+  return removed
+}
+
+// Phase files in a snapshot dir (01-*.md …), execution order.
+function listPhaseFiles(snapshotDir) {
+  try {
+    return fs
+      .readdirSync(snapshotDir)
+      .filter((f) => /^\d\d-.*\.md$/.test(f) && !f.startsWith('00-'))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+// Find the phase file whose h1 title matches `name` (used to stamp a freshly
+// created sub-issue's id back into the phase it came from).
+function findPhaseFileByTitle(snapshotDir, name) {
+  const want = String(name).trim()
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+    const h1 = /^#\s+(.*)$/m.exec(splitFrontmatter(raw).body)
+    if (!h1) continue
+    const title = h1[1]
+      .replace(/\s*[⬜🔄✅]\s*$/u, '')
+      .replace(/^Phase\s+\d+\s*[—–-]\s*/i, '')
+      .trim()
+    if (title === want) return file
+  }
+  return null
+}
+
+// Add/update the provider's phase-stamp field (`config.fields.issueId`) in a
+// phase file's frontmatter (in place) — the sub-issue id for that phase.
+function stampSubIssueId(snapshotDir, file, id, config) {
+  const p = path.join(snapshotDir, file)
+  const raw = fs.readFileSync(p, 'utf-8')
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  const patched = patchFrontmatterLines(fmLines, { [fieldsOf(config).issueId]: String(id) })
+  const fm = `---\n${patched.join('\n')}\n---\n`
+  fs.writeFileSync(p, had ? fm + body : fm + '\n' + raw, 'utf-8')
+}
+
+const INLINE_ID_RE = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/
+
+// Stamp an inline id onto the (idless) task line whose text matches — used after
+// the skill creates an issue for a new local task.
+function stampIssueId(snapshotDir, text, id) {
+  const want = collapse(text)
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const p = path.join(snapshotDir, file)
+    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)
+      lines.splice(b.start, b.end - b.start, ...rendered)
+      fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+      return file
+    }
+  }
+  return null
+}
+
+module.exports = {
+  writeFrontmatter,
+  deleteFrontmatter,
+  splitFrontmatter,
+  serialize,
+  listPhaseFiles,
+  findPhaseFileByTitle,
+  stampSubIssueId,
+  stampIssueId,
+}