@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,63 @@
+'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 rate-limited response: `Retry-After`
+// (seconds) first, then `X-RateLimit-Reset` (an epoch second — GitHub's
+// primary limit names the moment it lifts rather than a duration), then
+// exponential backoff. A reset already in the past falls through to backoff
+// rather than waiting zero and hammering.
+function retryDelay(res, attempt, maxBackoffMs = MAX_BACKOFF_MS, now = Date.now) {
+  const get = res.headers && typeof res.headers.get === 'function' ? (h) => res.headers.get(h) : () => null
+  const header = get('retry-after')
+  const seconds = header != null ? Number(header) : NaN
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, maxBackoffMs)
+  const reset = Number(get('x-ratelimit-reset'))
+  if (Number.isFinite(reset) && reset > 0) {
+    const wait = reset * 1000 - now()
+    if (wait > 0) return Math.min(wait, maxBackoffMs)
+  }
+  return Math.min(1000 * 2 ** attempt, maxBackoffMs)
+}
+
+// The default answer to "is this response a rate limit?": a 429. A provider
+// whose tracker also signals limits another way (GitHub: a 403 carrying
+// `Retry-After` or a zero `X-RateLimit-Remaining`) passes its own `isLimited`.
+const isTooManyRequests = (res) => res.status === 429
+
+/**
+ * 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 rate-limited, 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, isLimited = isTooManyRequests, now } = {},
+) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
+  for (let n = 0; ; n++) {
+    const response = await attempt()
+    const limited = isLimited(response)
+    if (limited && n < maxRetries) {
+      await wait(retryDelay(response, n, maxBackoffMs, now))
+      continue
+    }
+    return { response, exhausted: limited }
+  }
+}
+
+module.exports = { withRateLimitRetry, retryDelay, isTooManyRequests, 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/list-assignee.js

@@ -0,0 +1,71 @@
+'use strict'
+
+/**
+ * `spec-sync list --mine | --by <user>` — whose tickets to list.
+ *
+ * Linear defined the contract (`linear/src/cli-sync.js`, decision 9 of
+ * `feat-linear-assignment`); this is the same contract for every provider that
+ * lists over the API, so the two sentences below mean the same thing anywhere:
+ *
+ *   - `--mine` with an UNKNOWN identity lists nothing and exits 0. Identity is
+ *     an ordinary unknown (a bot token, an offline machine). What must never
+ *     happen is dropping the filter and printing everyone's work under a
+ *     heading that promised yours.
+ *   - `--by` that matches nobody, or more than one person, exits 1. The
+ *     argument is wrong and only the caller can fix it — the same shape as an
+ *     unknown `--state` — and a fallback to everyone would be the same lie.
+ *
+ * Returns `{ assignee: { id, name } | null }` to carry on with, or
+ * `{ code, lines }` to print and stop.
+ */
+async function resolveListAssignee({ flags, config, env, adapter, resolveIdentity, displayNameOf, tracker, prog }) {
+  if (flags.mine && flags.by) {
+    return {
+      code: 1,
+      lines: [
+        `${prog} list: --mine and --by both filter by assignee, so they cannot be combined`,
+        '  use --mine for your own, or --by <user> for someone else.',
+      ],
+    }
+  }
+  if (flags.mine) {
+    const who = await resolveIdentity(config, env, { adapter })
+    if (!who || !who.ok) {
+      return {
+        code: 0,
+        lines: [
+          `${prog} list: --mine needs to know who you are, and it does not (${(who && who.reason) || 'no identity'})`,
+          '  run `spec-sync whoami --set <id>` to say so, or use --by <user>.',
+        ],
+      }
+    }
+    return { assignee: { id: who.id, name: who.name || who.id } }
+  }
+  if (flags.by) {
+    const term = String(flags.by)
+    let found
+    try {
+      found = await adapter.searchUsers(term, { limit: 50 })
+    } catch (error) {
+      return { code: 1, lines: [`${prog} list: could not search users (${error.message})`] }
+    }
+    const users = (found && found.users) || []
+    if (!users.length) {
+      return {
+        code: 1,
+        lines: [`${prog} list: no ${tracker} user matches ${JSON.stringify(term)}`, '  `spec-sync users <term>` lists who there is.'],
+      }
+    }
+    if (users.length > 1) {
+      const lines = [`${prog} list: ${users.length} users match ${JSON.stringify(term)}`]
+      for (const u of users.slice(0, 10)) lines.push(`  ${displayNameOf(u) || '(unnamed)'}${u.email ? `  ${u.email}` : ''}`)
+      if (users.length > 10) lines.push(`  … and ${users.length - 10} more`)
+      lines.push('  narrow it — an email address matches exactly one person.')
+      return { code: 1, lines }
+    }
+    return { assignee: { id: users[0].id, name: displayNameOf(users[0]) || users[0].id } }
+  }
+  return { assignee: null }
+}
+
+module.exports = { resolveListAssignee }

package/src/vendor/provider-kit/src/list-rows.js

@@ -0,0 +1,35 @@
+'use strict'
+
+/**
+ * Shared pieces of `spec-sync list`: what `--state` means, and how a row's
+ * board state and its spec's own status are put side by side.
+ */
+
+const { remoteStateReading, stateNamesFor, LIFECYCLE_BUCKETS } = require('../../sync-core')
+
+// `--state` takes a lifecycle bucket as well as a tracker state. A bucket
+// expands to every tracker name it has (`stateNamesFor`, aliases included); any
+// other value is a tracker state, matched as it always was.
+function expandStateArgs(args, config) {
+  return (args || []).flatMap((arg) => (LIFECYCLE_BUCKETS.includes(arg) ? stateNamesFor(arg, config) : [arg]))
+}
+
+// The spec's status beside the board's, and whether they disagree. A board
+// state that maps to no bucket never disagrees: it is somewhere push does not
+// manage, which is not a claim about the spec. Nor does a row whose spec is not
+// on this machine — there is nothing to disagree WITH.
+function specColumn(stateName, spec, config) {
+  const specStatus = spec ? spec.bucket : null
+  const seen = stateName == null ? null : remoteStateReading({ state: { name: stateName } }, config)
+  const disagrees = Boolean(specStatus && seen && seen.mapped && seen.bucket !== specStatus)
+  return { specStatus, disagrees }
+}
+
+// The cell itself: `in-progress`, `≠ backlog` when it disagrees, `—` when the
+// spec is not here.
+function specCell({ specStatus, disagrees }) {
+  if (!specStatus) return '—'
+  return disagrees ? `≠ ${specStatus}` : specStatus
+}
+
+module.exports = { expandStateArgs, specColumn, specCell }

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 }

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

@@ -0,0 +1,94 @@
+'use strict'
+
+/**
+ * Flatten markdown tables that sit INSIDE a list item, because both tracker
+ * dialects need it: Linear's renderer corrupts nested-table data cells
+ * (measured on probe SKI-28, 2026-08-28 — every data cell loses its first N
+ * characters, N being the rendered list indent; the auth header
+ * `X-Extraction-Key` was stored as `Extraction-Key`), and ADF's `listItem`
+ * cannot contain a `table` node at all, so a Jira render would drop or mangle
+ * it. The re-emitted shapes are ones proven to survive nesting unchanged:
+ *
+ *   - 2 columns  → a bullet list (`- a — b`), the key/value case
+ *   - otherwise  → a fenced code block wrapping the original rows verbatim
+ *
+ * This shapes the PROJECTION only. Repo files are never rewritten: the source
+ * markdown is valid and renders correctly in GitHub and every editor.
+ */
+
+const { fenceMask } = require('../../sync-core/src/task-block.js')
+
+// A table row: optional indent, then a `|`-delimited line. We only ever act on
+// indented ones — a column-0 table (the `## Phases` index, every Impact map) is
+// rendered correctly by Linear and must project byte-identically.
+const ROW_RE = /^([ \t]+)\|(.*)\|[ \t]*$/
+// The separator under the header — `|---|:--:|`. Its presence is what makes the
+// block a table rather than prose that happens to contain pipes.
+const SEPARATOR_RE = /^[ \t]+\|[\s:|-]+\|[ \t]*$/
+
+// Split a row into cells on pipes that are OUTSIDE an inline-code span, so a
+// documented `` `a | b` `` alternation stays one cell instead of splitting.
+function splitCells(body) {
+  const cells = []
+  let cur = ''
+  let code = false
+  for (const ch of body) {
+    if (ch === '`') code = !code
+    if (ch === '|' && !code) {
+      cells.push(cur.trim())
+      cur = ''
+      continue
+    }
+    cur += ch
+  }
+  cells.push(cur.trim())
+  return cells
+}
+
+/**
+ * Rewrite every indented table in `md`. Returns the text unchanged when there is
+ * nothing nested to flatten.
+ * @param {string} md
+ * @returns {string}
+ */
+function flattenNestedTables(md) {
+  if (md == null) return md
+  const lines = String(md).split('\n')
+  const inFence = fenceMask(lines)
+  const out = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const header = ROW_RE.exec(lines[i])
+    // A table shown as an EXAMPLE inside a ``` block is documentation — often of
+    // this very bug — so it is left exactly as written.
+    if (!header || inFence[i] || !SEPARATOR_RE.test(lines[i + 1] || '')) {
+      out.push(lines[i])
+      continue
+    }
+
+    const indent = header[1]
+    const rows = [splitCells(header[2])]
+    const raw = [lines[i], lines[i + 1]]
+    let j = i + 2
+    for (; j < lines.length && !inFence[j]; j++) {
+      const row = ROW_RE.exec(lines[j])
+      if (!row) break
+      rows.push(splitCells(row[2]))
+      raw.push(lines[j])
+    }
+
+    if (rows[0].length === 2) {
+      // Header first, bolded: dropping it would lose content and inventing a
+      // caption would invent it.
+      out.push(`${indent}- **${rows[0][0]}** — **${rows[0][1]}**`)
+      for (const r of rows.slice(1)) out.push(`${indent}- ${r[0]} — ${r[1]}`)
+    } else {
+      out.push(`${indent}\`\`\``, ...raw, `${indent}\`\`\``)
+    }
+    i = j - 1
+  }
+  return out.join('\n')
+}
+
+
+module.exports = { flattenNestedTables, splitCells }

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

@@ -0,0 +1,50 @@
+'use strict'
+
+/**
+ * Terminal input helpers for a credentials CLI — reading a piped secret, and
+ * prompting for one with the echo off.
+ */
+
+// Read stdin to completion (for `--stdin`).
+function readAllStdin(input) {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    input.setEncoding('utf-8')
+    input.on('data', (chunk) => (data += chunk))
+    input.on('end', () => resolve(data))
+    input.on('error', reject)
+  })
+}
+
+// Prompt on a TTY with the input hidden. `_writeToOutput` is readline's own echo
+// hook — filtering it is what keeps the key off the screen (and out of a
+// screen-shared terminal or a recorded session).
+//
+// READLINE OWNS THE PROMPT, deliberately. Writing it ourselves and then starting
+// the interface loses it: readline clears from the cursor to the end of the
+// screen (`ESC[0J`) before its first redraw, so the prompt was wiped the instant
+// it appeared and the user was left staring at a blank line while the process
+// waited for a key — indistinguishable from a hang.
+//
+// The hook is assigned BEFORE `question`, so the very first redraw goes through
+// it. readline hands it `prompt + what has been typed`; re-writing only the
+// prompt is what keeps the key hidden while the prompt survives every redraw.
+function promptHidden(question, input, out) {
+  const readline = require('node:readline')
+  return new Promise((resolve) => {
+    // `out`, never `process.stdout`: they are the same stream in production, and
+    // hardcoding one half meant readline cleared a screen the prompt had not
+    // been written to under test — the split that hid this bug from the suite.
+    const rl = readline.createInterface({ input, output: out, terminal: true })
+    rl._writeToOutput = (s) => {
+      if (s.includes(question)) out.write(question)
+    }
+    rl.question(question, (answer) => {
+      out.write('\n')
+      rl.close()
+      resolve(answer)
+    })
+  })
+}
+
+module.exports = { readAllStdin, promptHidden }

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

@@ -0,0 +1,219 @@
+'use strict'
+
+/**
+ * Which tickets a release contains.
+ *
+ * The repo lands specs with `merge --ff-only`, so history is linear and branch
+ * names never reach it. A commit's `Refs:` trailer is therefore the only place
+ * the ticket survives into the range a release scans — see the
+ * `commit-trailers` rule. Nothing here is tracker-specific: the identifier
+ * shape defaults to `KEY-123` (Linear, Jira), and a provider whose refs look
+ * different (GitHub's `#123`) passes its own `refPattern`.
+ *
+ * The parsing half is pure and takes commits as data, so the rules below are
+ * testable without git. Reading the range, and enriching refs with issue titles,
+ * belong to the caller.
+ */
+
+// An issue identifier: uppercase team key, dash, number. The default, used
+// whenever a caller passes no `refPattern`.
+const IDENTIFIER_RE = /\b[A-Z][A-Z0-9]*-\d+\b/g
+// A GitHub issue ref in the same repo: `#123`.
+//
+// WHAT WOULD FOOL IT: `#` is also how a commit says "issue number" in prose and
+// how `owner/repo#123` names ANOTHER repo's issue. Prose is excluded by the
+// trailer anchor (only a `Refs:` line is scanned); the cross-repo form is
+// excluded by the lookbehind, so a ref into some other repo never lands on this
+// one's release.
+const GITHUB_REF_RE = /(?<![\w/.-])#\d+\b/g
+// A `Refs:` trailer line. Anchored, so it is a line of its own — never prose
+// that happens to mention the word.
+const TRAILER_RE = /^Refs:[ \t]*(.+?)[ \t]*$/
+
+/**
+ * The refs a single commit body claims.
+ *
+ * Deliberately blind to three things that LOOK like trailers and are not:
+ *
+ *   - a line inside a ``` fence — a commit explaining the convention quotes it;
+ *   - a quoted line (`> Refs: …`) — same reason, in review replies;
+ *   - an indented line (4+ spaces) — markdown code, e.g. a sample message.
+ *
+ * Counting any of those would make a release claim work it does not contain,
+ * which is worse than missing a ticket: the missing one is noticed when someone
+ * looks for it, the invented one never is.
+ */
+function refsInBody(body, refPattern) {
+  const pattern = asGlobal(refPattern) || IDENTIFIER_RE
+  const found = []
+  let fenced = false
+  for (const raw of String(body || '').split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    if (/^\s*>/.test(line)) continue
+    if (/^ {4,}|\t/.test(line)) continue
+    const m = TRAILER_RE.exec(line.trim() === line ? line : line.trimStart())
+    if (!m) continue
+    for (const id of m[1].match(pattern) || []) found.push(id)
+  }
+  return found
+}
+
+// `String.prototype.match` only returns every hit for a GLOBAL regex; a
+// provider passing `/#\d+/` would otherwise get its first ref and lose the rest
+// in silence. Anything that is not a RegExp is no pattern at all.
+function asGlobal(pattern) {
+  if (!(pattern instanceof RegExp)) return null
+  return pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`)
+}
+
+/**
+ * Whether a commit's changed paths are ENTIRELY bookkeeping.
+ *
+ * The problem it solves: a spec's `chore(spec): complete <name>` commit carries
+ * the same `Refs:` trailer as the code it describes, but lands after the tag
+ * that shipped that code — so the ticket turns up in two consecutive release
+ * ranges, once for its code and once for its paperwork.
+ *
+ * Deliberately a POSITIVE signal: it says yes only when it actually saw paths
+ * and every one of them sits under an ignored prefix. It never reasons from an
+ * absence.
+ *
+ * WHAT WOULD FOOL THE OTHER PHRASING ("no unignored path was found"): git lists
+ * no files at all for a MERGE commit (without `-m`) — verified, not assumed —
+ * nor for a genuinely empty one, and a `git log` that failed outright yields no
+ * paths for anything. Under that phrasing every one of those becomes a release
+ * silently losing its tickets. Under this one they mean "nothing was seen, so
+ * nothing is known", which keeps the pre-filter behaviour: an over-claimed
+ * ticket is noticed when someone looks for it, whereas a ticket that quietly
+ * belongs to no release never is.
+ *
+ * Matching is path-prefix, not glob: `specs` and `specs/` both mean the
+ * directory, and a prefix only matches on a path SEGMENT boundary, so `specs/`
+ * never swallows `specs-archive/`.
+ *
+ * @param {string[]|null|undefined} paths repo-relative paths the commit changed
+ * @param {string[]} ignorePaths repo-relative prefixes that are bookkeeping
+ */
+function onlyIgnoredPaths(paths, ignorePaths) {
+  if (!Array.isArray(paths) || !paths.length) return false
+  const prefixes = (Array.isArray(ignorePaths) ? ignorePaths : [])
+    .filter((p) => typeof p === 'string' && p.trim())
+    .map((p) => p.trim().replace(/^\.\//, '').replace(/\/+$/, ''))
+    .filter(Boolean)
+  if (!prefixes.length) return false
+  return paths.every((raw) => {
+    const file = String(raw == null ? '' : raw)
+      .trim()
+      .replace(/^\.\//, '')
+    // An unreadable entry is an unknown, not an ignored one — it makes the whole
+    // commit count, per the bias above.
+    if (!file) return false
+    return prefixes.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))
+  })
+}
+
+/**
+ * Fold commits into the report a release needs.
+ *
+ * @param {Array<{sha?:string, subject?:string, body?:string, paths?:string[]}>} commits
+ * @param {{ignorePaths?:string[], refPattern?:RegExp, foreignPatterns?:RegExp[]}} [options]
+ *   `ignorePaths` marks bookkeeping — see `onlyIgnoredPaths`. Omitted (or
+ *   empty) means nothing is ignored, so the report is what it was before the
+ *   filter existed. `refPattern` is this provider's ref shape (see
+ *   `refsInBody`). `foreignPatterns` are OTHER trackers' ref shapes this repo
+ *   used before — a repo that moved from Linear to GitHub still has
+ *   `Refs: SKS-29` all through its history, and those commits were referenced,
+ *   just not to this tracker. They are counted as `historical` rather than
+ *   `unreferenced`, which exists to surface a MISSED trailer.
+ * @returns {{tickets: Array<{ref:string, commits:number}>, unreferenced:number, ignored:number, total:number, historical?:number}}
+ *   `historical` is present only when `foreignPatterns` was given, so a
+ *   provider that never moved trackers sees exactly the shape it always did.
+ *   `tickets` is deduped in FIRST-SEEN order: a ticket touched by eight commits
+ *   is listed once, where it first appears, not eight times. `ignored` is
+ *   reported rather than merely subtracted — a filter that removes commits in
+ *   silence reads as "there was nothing there".
+ */
+function ticketsInRange(commits, options = {}) {
+  const ignorePaths = (options && options.ignorePaths) || []
+  const refPattern = options && options.refPattern
+  const foreign = ((options && options.foreignPatterns) || []).map(asGlobal).filter(Boolean)
+  const seen = new Map()
+  let unreferenced = 0
+  let ignored = 0
+  let historical = 0
+  for (const commit of commits || []) {
+    if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
+      // Not counted as unreferenced either: that number exists to surface a
+      // MISSED trailer, and a paperwork commit is not a gap someone should hunt.
+      ignored++
+      continue
+    }
+    const refs = [...new Set(refsInBody(commit && commit.body, refPattern))]
+    if (!refs.length) {
+      // A POSITIVE signal, never an absence: only a trailer that actually
+      // carries an older tracker's ref makes a commit historical. A commit with
+      // no trailer at all is still the gap `unreferenced` is there to name.
+      if (foreign.some((p) => refsInBody(commit && commit.body, p).length)) historical++
+      else unreferenced++
+      continue
+    }
+    for (const ref of refs) seen.set(ref, (seen.get(ref) || 0) + 1)
+  }
+  const report = {
+    tickets: [...seen.entries()].map(([ref, count]) => ({ ref, commits: count })),
+    unreferenced,
+    ignored,
+    total: (commits || []).length,
+  }
+  if (foreign.length) report.historical = historical
+  return report
+}
+
+/**
+ * Name the spec behind each ticket a range contains, so a consumer can act on
+ * a release without a second lookup.
+ *
+ * A ref no spec has stamped keeps `spec: null` and `url: null` — never a guess
+ * from a similar folder name. It may be tracker-only work, or a typo in a
+ * trailer, and a consumer acting on an invented match is worse than one told
+ * there was none.
+ *
+ * Pure: it takes the spec list as data (`listSpecs` rows), so it is testable
+ * without a repo.
+ */
+function nameTickets(tickets, specs) {
+  const byRef = new Map()
+  for (const s of specs || []) {
+    if (s && s.identifier && !byRef.has(s.identifier)) byRef.set(s.identifier, s)
+  }
+  return (tickets || []).map((t) => {
+    const s = byRef.get(t.ref)
+    return { ...t, spec: s ? s.spec : null, url: s ? s.url || null : null }
+  })
+}
+
+// The answer a removed release verb gives (`release`, `stage`). Exit 1, not a
+// quiet 0: a pipeline still calling one must learn it no longer mirrors
+// anything, rather than go on believing it does.
+function refuseRemovedVerb(out, program, verb) {
+  out.write(
+    `${program} ${verb}: removed — skitterspec no longer writes release or deploy state; ` +
+      `\`${program} released <range> --json\` lists the tickets a range contains, for your own tooling to act on\n`,
+  )
+  return 1
+}
+
+module.exports = {
+  ticketsInRange,
+  refuseRemovedVerb,
+  nameTickets,
+  refsInBody,
+  onlyIgnoredPaths,
+  IDENTIFIER_RE,
+  GITHUB_REF_RE,
+}