@skitterbyte/skitterspec-jira 0.0.0-stage → 1.0.0

package/src/vendor/provider-kit/src/credentials.js

@@ -0,0 +1,404 @@
+'use strict'
+
+/**
+ * The user-level credentials store, shared by every skitterspec provider —
+ * where an API credential lives when it is not in the environment.
+ *
+ * A repo's committed provider config deliberately holds only the NAME of an
+ * env var, never a credential. This store is the alternative: one file per
+ * machine, outside every repo, at
+ * `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else `~/.config/…`).
+ *
+ * TWO SCHEMAS, one file. v1 — `{ version: 1, teams: { <scopeId>: entry } }` —
+ * predates providers being plural, so every v1 entry belongs to the one
+ * provider that existed then (the factory names it as `legacyV1Owner`). v2
+ * namespaces: `{ version: 2, providers: { <name>: { teams: {…} } } }`. Reads
+ * understand both. Writes by the legacy owner keep a v1 store v1 — older CLIs
+ * still read it, and its tests pin the shape — while the FIRST write by any
+ * other provider migrates the file to v2, folding the v1 entries under the
+ * legacy owner. That is the moment two providers actually share the file, and
+ * before it nothing changes shape underneath anyone.
+ *
+ * An entry's `key` may be a string (a bare API key) or an object (a compound
+ * credential such as email + token) — the store passes it through opaquely.
+ *
+ * Reads never throw: every failure returns a structured reason, and a missing
+ * store is the normal default, not a problem. Nothing here ever returns a key
+ * inside an error, and callers must keep it out of logs, plans, snapshots and
+ * stamped frontmatter.
+ */
+
+const { spawnSync } = require('node:child_process')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const DIR_NAME = 'skitterspec'
+const FILE_NAME = 'credentials.json'
+
+// Modes wider than owner-only. Checked ssh-style: a store other users can read
+// is refused rather than read, because silently using it would hide the leak,
+// and silently chmod'ing someone's file is not ours to do.
+const GROUP_OR_WORLD = 0o077
+
+// 60s: a password manager may prompt for biometric or a master password, and a
+// hang here would look like the CLI itself wedging.
+const COMMAND_TIMEOUT_MS = 60_000
+
+/**
+ * Absolute path of the store. Honours `$XDG_CONFIG_HOME`, else `~/.config`.
+ * `env` and `homedir` are injected so tests never touch a real home directory.
+ */
+function storePath(env = process.env, homedir = os.homedir) {
+  const xdg = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.trim()
+  const base = xdg || path.join(homedir(), '.config')
+  return path.join(base, DIR_NAME, FILE_NAME)
+}
+
+/**
+ * Read the store (schema-agnostic).
+ *
+ * @returns {object} `{ ok: true, store, path }` — parsed and owner-only;
+ *   `{ ok: false, reason, code, path }` otherwise. `code` is one of:
+ *   `absent` (no file — the normal default, not a problem), `permissions`
+ *   (group/world readable), `unreadable`, `malformed`.
+ */
+function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
+  let info
+  try {
+    info = stat(file)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { ok: false, code: 'absent', path: file, reason: `no credentials store at ${file}` }
+    }
+    return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
+  }
+
+  if (info.mode & GROUP_OR_WORLD) {
+    const mode = (info.mode & 0o777).toString(8)
+    return {
+      ok: false,
+      code: 'permissions',
+      path: file,
+      reason:
+        `credentials store ${file} is mode ${mode} — readable by other users.\n` +
+        `  Run: chmod 600 ${file}`,
+    }
+  }
+
+  let raw
+  try {
+    raw = read(file, 'utf-8')
+  } catch (err) {
+    return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
+  }
+
+  let store
+  try {
+    store = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, code: 'malformed', path: file, reason: `invalid JSON in ${file}: ${err.message}` }
+  }
+  if (!store || typeof store !== 'object' || Array.isArray(store)) {
+    return { ok: false, code: 'malformed', path: file, reason: `invalid credentials store in ${file}` }
+  }
+  return { ok: true, store, path: file }
+}
+
+/** The store's permission bits as an octal string, or null when absent. */
+function storeMode(file, deps = {}) {
+  const stat = deps.stat || fs.statSync
+  try {
+    return (stat(file).mode & 0o777).toString(8)
+  } catch {
+    return null
+  }
+}
+
+// Last 4 characters, for reporting that a key exists without revealing it.
+// Compound (object) credentials have no meaningful tail — null, never a dump.
+function fingerprint(key) {
+  if (typeof key !== 'string' || !key) return null
+  return `…${key.slice(-4)}`
+}
+
+// The provider's scope map (`teams`) inside a parsed store, resolving both
+// schemas. Returns `null` when the store holds nothing for this provider —
+// which for a v1 store is every provider except the legacy owner.
+function scopeMapOf(store, provider, legacyV1Owner) {
+  if (!store || typeof store !== 'object') return null
+  if (store.providers && typeof store.providers === 'object') {
+    const entry = store.providers[provider]
+    return entry && typeof entry.teams === 'object' ? entry.teams : null
+  }
+  if (provider !== legacyV1Owner) return null
+  return store.teams && typeof store.teams === 'object' ? store.teams : null
+}
+
+function defaultRunCommand(command, timeout) {
+  const r = spawnSync('sh', ['-c', command], { encoding: 'utf-8', timeout })
+  if (r.error) return { ok: false, error: r.error.message }
+  if (r.status !== 0) {
+    // stderr only — stdout is the secret, and must not reach an error message.
+    const detail = (r.stderr || '').trim().split('\n')[0] || `exit ${r.status}`
+    return { ok: false, error: detail }
+  }
+  return { ok: true, stdout: r.stdout }
+}
+
+/**
+ * A store bound to one provider. `legacyV1Owner` names the provider whose
+ * entries a v1 store holds — the one that predates the namespace; a provider
+ * IS that owner exactly when the names match.
+ */
+function makeCredentialsStore({ provider, legacyV1Owner }) {
+  if (!provider) throw new Error('makeCredentialsStore: provider name required')
+  const ownsV1 = provider === legacyV1Owner
+
+  const mapOf = (store) => scopeMapOf(store, provider, legacyV1Owner)
+
+  function entryFor(store, scopeId) {
+    if (!scopeId) return null
+    const map = mapOf(store)
+    const entry = map ? map[scopeId] : null
+    return entry && typeof entry === 'object' ? entry : null
+  }
+
+  function keyFor(store, scopeId) {
+    const entry = entryFor(store, scopeId)
+    if (!entry) return null
+    const key = entry.key
+    if (typeof key === 'string') return key.trim() || null
+    return null
+  }
+
+  // A compound (object) credential, for providers whose auth is more than one
+  // string. Strings resolve through `keyFor`; this never trims or reshapes.
+  function credentialFor(store, scopeId) {
+    const entry = entryFor(store, scopeId)
+    if (!entry) return null
+    return entry.key && typeof entry.key === 'object' ? entry.key : null
+  }
+
+  function userFor(store, scopeId) {
+    const entry = entryFor(store, scopeId)
+    if (!entry) return null
+    const user = entry.user
+    if (!user || typeof user !== 'object') return null
+    // The id is what an assignment is actually made with, so an entry without
+    // one is not a partial identity — it is no identity at all.
+    const id = typeof user.id === 'string' && user.id.trim() ? user.id.trim() : null
+    if (!id) return null
+    const name = typeof user.name === 'string' && user.name.trim() ? user.name.trim() : null
+    return { id, name }
+  }
+
+  /**
+   * Resolve one scope's key from the store: a stored `key` first, else running
+   * its `keyCommand` and taking stdout.
+   *
+   * `keyCommand` is honoured ONLY from this user-level store — never from a
+   * repo's committed config, which travels with the repo and would let a cloned
+   * repo run arbitrary code. A command that fails, times out or prints nothing
+   * resolves to no key — the ordinary "fall back" state — but its stderr is
+   * carried back so a broken command is diagnosable. Its **stdout is never**
+   * put in an error: that is the key.
+   */
+  function resolveKey(store, scopeId, deps = {}) {
+    const direct = keyFor(store, scopeId)
+    if (direct) return { key: direct, source: 'store' }
+
+    const entry = entryFor(store, scopeId)
+    const command = entry && typeof entry.keyCommand === 'string' ? entry.keyCommand.trim() : ''
+    if (!command) return { key: null, source: null }
+
+    const run = deps.run || defaultRunCommand
+    const result = run(command, deps.timeoutMs || COMMAND_TIMEOUT_MS)
+    if (!result.ok) {
+      return { key: null, source: null, command, reason: `keyCommand failed: ${result.error}` }
+    }
+    const key = (result.stdout || '').trim()
+    if (!key) {
+      return { key: null, source: null, command, reason: 'keyCommand produced no output' }
+    }
+    return { key, source: 'command', command }
+  }
+
+  // Read-modify-write of this provider's scope map, with the schema rules from
+  // the module header. `mutate(entry)` returns the scope's next entry, or the
+  // literal string 'delete' to drop it; `mutate` receives the current entry (or
+  // null). Refuses on an unreadable or over-permissive store, exactly like a
+  // read — silently rewriting a world-readable file would leave the leak.
+  function mutateEntry(file, scopeId, mutate, deps = {}) {
+    const mkdir = deps.mkdir || fs.mkdirSync
+    const write = deps.write || fs.writeFileSync
+    const chmod = deps.chmod || fs.chmodSync
+    const exists = deps.exists || fs.existsSync
+
+    const created = !exists(file)
+    let store = null
+    if (!created) {
+      const current = readStore(file, deps)
+      if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
+      store = current.store
+    }
+
+    // Decide the shape this write leaves behind.
+    const isV2 = !!(store && store.providers && typeof store.providers === 'object')
+    if (!store) {
+      store = ownsV1 ? { version: 1, teams: {} } : { version: 2, providers: {} }
+    } else if (!isV2 && !ownsV1) {
+      // The first write by a second provider: fold the v1 entries under their
+      // owner and namespace the file. This is the one moment the shape changes.
+      const legacyTeams = store.teams && typeof store.teams === 'object' ? store.teams : {}
+      store = { version: 2, providers: { [legacyV1Owner]: { teams: legacyTeams } } }
+    }
+
+    let map
+    if (store.providers && typeof store.providers === 'object') {
+      if (!store.providers[provider] || typeof store.providers[provider] !== 'object') {
+        store.providers[provider] = { teams: {} }
+      }
+      if (!store.providers[provider].teams || typeof store.providers[provider].teams !== 'object') {
+        store.providers[provider].teams = {}
+      }
+      if (!store.version || store.version < 2) store.version = 2
+      map = store.providers[provider].teams
+    } else {
+      if (!store.teams || typeof store.teams !== 'object') store.teams = {}
+      if (!store.version) store.version = 1
+      map = store.teams
+    }
+
+    const current = map[scopeId] && typeof map[scopeId] === 'object' ? map[scopeId] : null
+    const next = mutate(current)
+    if (next === 'delete') {
+      if (!current) return { ok: true, path: file, created: false, removed: false }
+      delete map[scopeId]
+    } else if (next !== undefined) {
+      map[scopeId] = next
+    }
+
+    mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+    write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+    // `mode` on writeFileSync only applies when the file is CREATED, so an
+    // existing file keeps its mode — narrow it explicitly.
+    chmod(file, 0o600)
+    return { ok: true, path: file, created, removed: next === 'delete' }
+  }
+
+  /** Record a credential (string key or compound object) for one scope. */
+  function writeKey(file, scopeId, key, deps = {}) {
+    if (!scopeId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+    const isCompound = key && typeof key === 'object'
+    const value = isCompound ? key : typeof key === 'string' ? key.trim() : ''
+    if (!value || (isCompound && !Object.keys(value).length)) {
+      return { ok: false, reason: 'empty key — nothing stored' }
+    }
+    return mutateEntry(file, scopeId, (entry) => ({ ...(entry || {}), key: value }), deps)
+  }
+
+  /** Record the identity for one scope, preserving its credential. */
+  function writeUser(file, scopeId, user, deps = {}) {
+    if (!scopeId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+    const id = user && typeof user.id === 'string' ? user.id.trim() : ''
+    if (!id) return { ok: false, reason: 'no user id — nothing stored' }
+    const name = user && typeof user.name === 'string' ? user.name.trim() : ''
+    return mutateEntry(
+      file,
+      scopeId,
+      (entry) => ({ ...(entry || {}), user: name ? { id, name } : { id } }),
+      deps,
+    )
+  }
+
+  /**
+   * Record a command for one scope instead of a key. Unlike a key, a command is
+   * not a secret, so this one IS safe to pass as an argument. `literalKeyRe`
+   * (with `literalKeyAdvice`) is the provider's own key shape — a command with
+   * a key written into it is refused at the door, because a command is
+   * displayed by `credentials status` and never treated as a secret.
+   */
+  function writeKeyCommand(file, scopeId, command, deps = {}, { literalKeyRe, literalKeyAdvice } = {}) {
+    if (!scopeId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+    if (typeof command !== 'string' || !command.trim()) {
+      return { ok: false, reason: 'empty command — nothing stored' }
+    }
+    if (literalKeyRe && literalKeyRe.test(command)) {
+      return { ok: false, reason: literalKeyAdvice || 'that command has a key written into it.' }
+    }
+    // A command REPLACES a stored key for that scope — keeping both would mean
+    // the key silently wins and the command never runs.
+    return mutateEntry(file, scopeId, () => ({ keyCommand: command.trim() }), deps)
+  }
+
+  /** Remove one scope's entry entirely. Absent store or entry is a clean no-op. */
+  function removeKey(file, scopeId, deps = {}) {
+    const current = readStore(file, deps)
+    if (!current.ok) {
+      if (current.code === 'absent') return { ok: true, path: file, removed: false }
+      return { ok: false, reason: current.reason, code: current.code }
+    }
+    if (!entryFor(current.store, scopeId)) return { ok: true, path: file, removed: false }
+    const r = mutateEntry(file, scopeId, () => 'delete', deps)
+    return r.ok ? { ok: true, path: file, removed: true } : r
+  }
+
+  /**
+   * Forget the identity recorded for one scope, leaving its KEY in place.
+   * Deliberately not `removeKey`'s shape: that one drops the whole entry, which
+   * is right when the key is being revoked; here it would sign the user out
+   * entirely because they corrected their own name.
+   */
+  function removeUser(file, scopeId, deps = {}) {
+    const current = readStore(file, deps)
+    if (!current.ok) {
+      if (current.code === 'absent') return { ok: true, path: file, removed: false }
+      return { ok: false, reason: current.reason, code: current.code }
+    }
+    const entry = entryFor(current.store, scopeId)
+    if (!entry || !entry.user) return { ok: true, path: file, removed: false }
+    const r = mutateEntry(
+      file,
+      scopeId,
+      (e) => {
+        const next = { ...(e || {}) }
+        delete next.user
+        return next
+      },
+      deps,
+    )
+    return r.ok ? { ok: true, path: file, removed: true } : r
+  }
+
+  return {
+    provider,
+    storePath,
+    readStore,
+    storeMode,
+    fingerprint,
+    entryFor,
+    keyFor,
+    credentialFor,
+    userFor,
+    resolveKey,
+    writeKey,
+    writeUser,
+    writeKeyCommand,
+    removeKey,
+    removeUser,
+  }
+}
+
+module.exports = {
+  makeCredentialsStore,
+  storePath,
+  readStore,
+  storeMode,
+  fingerprint,
+  defaultRunCommand,
+  COMMAND_TIMEOUT_MS,
+  DIR_NAME,
+  FILE_NAME,
+  GROUP_OR_WORLD,
+}

package/src/vendor/provider-kit/src/doctor.js

@@ -0,0 +1,35 @@
+'use strict'
+
+/**
+ * The doctor REPORT FRAMEWORK — the states, the row shape, and the combining
+ * rule every provider's `doctor` shares. The checks themselves are the
+ * provider's: they name its config files, its states, its transports.
+ *
+ * Two distinctions carry the design:
+ *
+ * 1. **`missing` is not `broken`.** `missing` is an opt-in not taken, which is
+ *    fine; `broken` is configured-but-wrong, which is not. `ok` is false only
+ *    for `broken`, so declining an opt-in never reads as a failure.
+ * 2. **Every non-`ok` row names the command that fixes it**, so the output is
+ *    actionable without reading docs.
+ *
+ * `warn` sits between `ok` and `broken`: worth a human's attention, but not a
+ * failure — said out loud, exit code left alone.
+ */
+
+const DOCTOR_STATES = ['ok', 'missing', 'broken', 'skipped', 'warn']
+
+// A row is a check. `fix` is the exact command to run, or null when there is
+// nothing to fix.
+function doctorRow(id, label, state, detail, fix = null) {
+  if (!DOCTOR_STATES.includes(state)) throw new Error(`doctor: unknown check state "${state}" for ${id}`)
+  return { id, label, state, detail, fix }
+}
+
+// `missing` is a declined opt-in, so it must not fail the run. Only a
+// configured-but-wrong layer does.
+function combineDoctorChecks(checks) {
+  return { ok: !checks.some((c) => c.state === 'broken'), checks }
+}
+
+module.exports = { DOCTOR_STATES, doctorRow, combineDoctorChecks }

package/src/vendor/provider-kit/src/http.js

@@ -0,0 +1,44 @@
+'use strict'
+
+/**
+ * Rate-limit-aware HTTP retry — the transport discipline every provider's API
+ * client shares, with none of any tracker's protocol in it.
+ *
+ * A bulk backfill is exactly the workload that gets throttled, and failing the
+ * run would strand a half-mirrored bucket — so a 429 waits and retries rather
+ * than surfacing. The server says how long to wait (`Retry-After`, seconds);
+ * honour that over guessing, and fall back to exponential backoff (from 1s,
+ * capped) when it doesn't.
+ */
+
+const MAX_RETRIES = 5
+const MAX_BACKOFF_MS = 60_000
+
+// How long to wait before retrying a 429.
+function retryDelay(res, attempt, maxBackoffMs = MAX_BACKOFF_MS) {
+  const header = res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null
+  const seconds = header != null ? Number(header) : NaN
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, maxBackoffMs)
+  return Math.min(1000 * 2 ** attempt, maxBackoffMs)
+}
+
+/**
+ * Run `attempt()` (→ a fetch Response) until it is not rate-limited or the
+ * retries run out. Returns `{ response, exhausted }` — `exhausted` true when
+ * the LAST response is still a 429, so the caller phrases its own refusal (and
+ * marks it retryable: rate limiting is the failure where waiting is the whole
+ * answer, and the one a refusal must stay distinguishable from).
+ */
+async function withRateLimitRetry(attempt, { sleep, maxRetries = MAX_RETRIES, maxBackoffMs = MAX_BACKOFF_MS } = {}) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
+  for (let n = 0; ; n++) {
+    const response = await attempt()
+    if (response.status === 429 && n < maxRetries) {
+      await wait(retryDelay(response, n, maxBackoffMs))
+      continue
+    }
+    return { response, exhausted: response.status === 429 }
+  }
+}
+
+module.exports = { withRateLimitRetry, retryDelay, MAX_RETRIES, MAX_BACKOFF_MS }

package/src/vendor/provider-kit/src/identity.js

@@ -0,0 +1,93 @@
+'use strict'
+
+/**
+ * "Who am I in this workspace?" — the resolution shape every provider's
+ * assignment rests on.
+ *
+ * Three tiers, first hit wins:
+ *
+ *   1. the user-level credentials store  (`source: 'store'`)  — no network
+ *   2. the credential itself, via the tracker's "who am I" call
+ *                                        (`source: 'viewer'`)
+ *   3. nothing                           (`source: 'unknown'`)
+ *
+ * **Unknown is a normal state, not a failure.** A shared/bot key answers the
+ * viewer call with the bot; an offline machine answers with nothing; neither is
+ * a broken install. So this returns a structured result the caller branches on,
+ * never an exception — and it NEVER PROMPTS and NEVER WRITES. Prompting belongs
+ * to the skill with a human in front of it, and caching belongs to the command
+ * that decided the answer was worth keeping: a resolver that wrote to disk as a
+ * side effect would cache a bot's identity the first time CI ran.
+ *
+ * Everything tracker-shaped arrives as a hook: how a credential resolves, how
+ * the viewer is fetched, and how a user object yields a display name.
+ */
+
+/**
+ * @param {object} hooks
+ *   - `scopeId`            the credentials-store scope (e.g. a team id) — '' skips tier 1
+ *   - `file`               the store path (carried through on every result)
+ *   - `readStore(file)`    kit credentials read
+ *   - `userFor(store,id)`  the provider store binding's identity read
+ *   - `resolveCredential()`  → `{ ok, error?, envVar?, … }` — the provider's key resolution
+ *   - `readViewer(credential)` → the tracker's current user (may throw)
+ *   - `nameOf(viewer)`     display name of a user object
+ * @returns {Promise<object>} `{ ok: true, id, name, email?, source, path }` or
+ *   `{ ok: false, source: 'unknown', reason, envVar?, path }`.
+ */
+async function resolveIdentity({ scopeId, file, readStore, userFor, resolveCredential, readViewer, nameOf }) {
+  if (scopeId) {
+    const result = readStore(file)
+    if (result.ok) {
+      const cached = userFor(result.store, scopeId)
+      if (cached) return { ok: true, id: cached.id, name: cached.name, source: 'store', path: file }
+    }
+    // A store that is present but unusable (over-permissive, malformed) is NOT
+    // reported as an identity failure — credential resolution hits the same
+    // file and reports it properly. Duplicating it here would print the same
+    // permissions warning twice for one cause.
+  }
+
+  const credential = resolveCredential()
+  if (!credential.ok) {
+    return { ok: false, source: 'unknown', reason: credential.error, envVar: credential.envVar, path: file }
+  }
+
+  let viewer
+  try {
+    viewer = await readViewer(credential)
+  } catch (error) {
+    // Offline, revoked key, tracker down. All are "cannot tell", which routes
+    // to the harmless branch: the caller skips assignment rather than guessing.
+    return { ok: false, source: 'unknown', reason: error.message, path: file }
+  }
+
+  const id = viewer && typeof viewer.id === 'string' ? viewer.id.trim() : ''
+  if (!id) {
+    return { ok: false, source: 'unknown', reason: 'the tracker returned no viewer for this key', path: file }
+  }
+  return {
+    ok: true,
+    id,
+    name: (nameOf || defaultDisplayName)(viewer),
+    email: (viewer && viewer.email) || null,
+    source: 'viewer',
+    path: file,
+  }
+}
+
+/**
+ * The name to show for a tracker user. Falls back through `displayName` and
+ * `email` so a user with an odd profile still reads as a person rather than a
+ * UUID.
+ */
+function defaultDisplayName(user) {
+  if (!user || typeof user !== 'object') return null
+  for (const field of ['name', 'displayName', 'email']) {
+    const value = user[field]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  return null
+}
+
+module.exports = { resolveIdentity, defaultDisplayName }

package/src/vendor/provider-kit/src/md-compare.js

@@ -0,0 +1,39 @@
+'use strict'
+
+/**
+ * The markdown-form reduction both dialects compare through. Every transform
+ * here is a benign difference between two spellings of the same markdown —
+ * a reserialising editor's (Linear rewrites bullets, renumbers lists,
+ * case-folds checkboxes, collapses separator rows on save) or a round-trip
+ * renderer's (the ADF reducer re-emits `-` bullets and `| -- |` separators
+ * whatever the source used). Normalised away BEFORE comparing, so an intact
+ * mirror never reports as data loss; digits stay significant everywhere else —
+ * a port, a version, a key length still count.
+ */
+
+function canonicalForCompare(text) {
+  return String(text == null ? '' : text)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) =>
+      line
+        // Ordered-list markers → a placeholder. Linear renumbers lists, and the
+        // digits it rewrites are alphanumeric, so a naive alphanumeric compare
+        // would flag its own benign reformat as data loss. Normalising the
+        // marker keeps digits significant EVERYWHERE ELSE — a port, a version, a
+        // key length still count.
+        .replace(/^(\s*)\d+\.(\s)/, '$1#.$2')
+        // Unordered markers unify (`-`/`+` come back as `*`).
+        .replace(/^(\s*)[*+-](\s)/, '$1-$2')
+        // Checkbox marks case-fold. Targeted rather than lowercasing the whole
+        // text, so a genuine case corruption in prose is still caught.
+        .replace(/^(\s*-\s*\[)[xX](\])/, '$1x$2')
+        // Table separator rows collapse (`|-------|` → `| -- |`).
+        .replace(/^\s*\|[\s:|-]+\|\s*$/, '|--|')
+        .replace(/[ \t]+$/, ''),
+    )
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+module.exports = { markdownCanonicalForCompare: canonicalForCompare }