@skitterbyte/skitterspec-jira 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,197 @@
+'use strict'
+
+/**
+ * The apply ORCHESTRATION — the ordering, stamping and accounting shared by
+ * every provider's `spec-sync apply`, with the tracker calls themselves left
+ * to provider `ops` (deferred to this shape until two providers existed to
+ * validate it: one folds workflow state into its create/update payloads, the
+ * other must move status by a separate transition call — so state application
+ * lives inside the ops, and the skeleton owns only what is identical).
+ *
+ * What the skeleton owns, in order:
+ *
+ *   1. resolve every workflow state BEFORE the first write, so a bad
+ *      `config.states` value cannot strand the spec mid-apply;
+ *   2. the twin-mint guard: an EXACT-title issue held by no spec is a positive
+ *      signal the issue already exists — refuse to mint a second (a fuzzy
+ *      match must never count: being wrong here blocks a legitimate push);
+ *   3. mint-or-update the spec issue, stamping the identifier the moment the
+ *      create lands — an interrupt after that point must not mint a twin;
+ *   4. sub-issue creates, each STAMPED AS IT LANDS, then updates (keyed by
+ *      ref, never by id — the read-back matches by ref);
+ *   5. read back what the tracker stored and run the same check `verify` runs;
+ *   6. record the snapshot from the now-stamped files, so the next push is
+ *      empty.
+ *
+ * Orphan accounting rides the whole way: `created` is what the tracker holds,
+ * `stamped` what the repo recorded, and the one case a re-run makes WORSE is a
+ * create whose stamp could not be written — the identifiers travel out on the
+ * error so the caller can name them.
+ *
+ * @param {object} ops the provider's tracker calls:
+ *   - `prevalidateStates(buckets)`          throw early on a bad state name
+ *   - `mintIssue({ title, issue })`         → `{ id, identifier, url }`
+ *   - `updateIssue(existing, issue)`        apply `plan.issue` to a live issue
+ *   - `mintSubIssue(parentId, sub)`         → `{ id, identifier }`
+ *   - `updateSubIssue(sub)`                 apply a sub-issue update
+ *   - `remoteEditedLine(identifier)`        the someone-else-edited warning
+ *   - `twinAdvice(twin, title, specName)`   the refusal message for a twin
+ */
+
+const path = require('node:path')
+
+const {
+  readSnapshot,
+  readBase,
+  projectionOf,
+  recordPush,
+  writeFrontmatter,
+  stampSubIssueId,
+  fieldsOf,
+  remoteDescriptionEdited,
+  listPhaseFiles,
+} = require('../../sync-core')
+const { makeSpecHelpers } = require('./specs.js')
+
+/**
+ * The outer accounting wrapper: run the inner apply, and on ANY throw attach
+ * what had been stamped versus created by the time it happened.
+ */
+async function applySpecPlan(args) {
+  const progress = {}
+  try {
+    return await applyInner({ ...args, progress })
+  } catch (error) {
+    const r = progress.result
+    if (error && typeof error === 'object' && error.stamped === undefined) {
+      error.stamped = r ? (r.issue ? 1 : 0) + Object.keys(r.subIssues || {}).length : 0
+      error.created = progress.created || []
+      error.orphans = error.created.slice(error.stamped)
+    }
+    throw error
+  }
+}
+
+async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progress, forceNew = false, program = 'spec-sync' }) {
+  const fields = fieldsOf(config)
+  const helpers = makeSpecHelpers({ program })
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
+  const lines = []
+  const result = { issue: null, subIssues: {} }
+  // Handed out immediately, so a throw from anywhere below still reports what
+  // had been stamped by the time it happened.
+  if (progress) progress.result = result
+
+  // 1. Every state resolved BEFORE the first write.
+  const wanted = new Set()
+  if (plan.issue && plan.issue.state) wanted.add(plan.issue.state)
+  for (const s of (plan.subIssues && plan.subIssues.create) || []) if (s.state) wanted.add(s.state)
+  for (const s of (plan.subIssues && plan.subIssues.update) || []) if (s.state) wanted.add(s.state)
+  ops.prevalidateStates([...wanted])
+
+  let parentId = null
+  if (!identifier) {
+    // 2. REFUSE TO MINT A TWIN. An EXACT match held by no spec is a positive
+    // signal that the issue already exists; a near-match must never count —
+    // being wrong here blocks a legitimate push, and a renamed spec is
+    // answered by adopting the issue, not by fuzz.
+    if (!forceNew && adapter.searchIssues) {
+      const title = String(plan.title || readSnapshot(snapshotDir, config).title || '').trim()
+      if (title) {
+        let found = []
+        try {
+          found = (await ops.searchTwin(title)) || []
+        } catch {
+          // A search we could not run is not evidence of an orphan. Carry on
+          // and mint — the cannot-tell case goes to the harmless branch, which
+          // here is the one that does the work the caller asked for.
+          found = []
+        }
+        const claimed = new Set(helpers.listSpecs(dir, config).map((sp) => sp.identifier).filter(Boolean))
+        const twin = found.find(
+          (i) => i && i.identifier && !claimed.has(i.identifier) && String(i.title || '').trim() === title,
+        )
+        if (twin) throw new Error(ops.twinAdvice(twin, title, path.basename(snapshotDir)))
+      }
+    }
+    // 3. Mint, then stamp IMMEDIATELY: noted before it is stamped, so a stamp
+    // that cannot be written can still name the identifier it strands.
+    const created = await ops.mintIssue({ title: readSnapshot(snapshotDir, config).title, issue: plan.issue })
+    parentId = created.id
+    if (progress) (progress.created = progress.created || []).push(created.identifier)
+    writeFrontmatter(snapshotDir, config, {
+      [fields.identifier]: created.identifier,
+      [fields.url]: created.url,
+    })
+    result.issue = { id: created.id, identifier: created.identifier, url: created.url }
+    lines.push(`  issue created: ${created.identifier}`)
+  } else {
+    const existing = await adapter.readIssue(identifier)
+    if (!existing || !existing.id) throw new Error(ops.missingIssueMessage(identifier))
+    parentId = existing.id
+    result.issue = { id: existing.id, identifier: existing.identifier, url: existing.url }
+
+    // SOMEONE ELSE EDITED THE DESCRIPTION SINCE THE LAST PUSH, and this write
+    // replaces it. A WARNING AND NEVER A REFUSAL: one-way sync means the repo
+    // wins; what was wrong was winning silently.
+    if (remoteDescriptionEdited(readBase(dir, identifier, config), existing, config) === true) {
+      lines.push(ops.remoteEditedLine(identifier))
+    }
+    if (plan.issue) {
+      await ops.updateIssue(existing, plan.issue)
+      lines.push(`  issue updated: ${identifier}`)
+    }
+  }
+
+  // 4. Sub-issue creates — each stamped as it lands, for the same reason.
+  for (const sub of (plan.subIssues && plan.subIssues.create) || []) {
+    const created = await ops.mintSubIssue(parentId, sub)
+    if (progress) (progress.created = progress.created || []).push(created.identifier)
+    const file = resolvePhaseFileIn(snapshotDir, sub.ref)
+    if (!file) throw new Error(`no phase file for ref ${sub.ref}`)
+    stampSubIssueId(snapshotDir, file, created.identifier, config)
+    result.subIssues[sub.ref] = created.identifier
+    lines.push(`  sub-issue created: ${sub.ref} → ${created.identifier}`)
+  }
+
+  // 5. Sub-issue updates — keyed by REF, never by id: the read-back matches
+  // sub-issues to phases by ref, and a plan written before updates carried a
+  // ref still resolves — by id, off the projection.
+  const refById = new Map()
+  for (const s of projectionOf(snapshotDir, config).subIssues || []) {
+    if (s.id != null) refById.set(String(s.id), s.ref)
+  }
+  for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
+    await ops.updateSubIssue(sub)
+    result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
+    lines.push(`  sub-issue updated: ${sub.id}`)
+  }
+
+  // 6. Read back what the tracker stored and run the SAME check verify runs.
+  const stored = { issue: undefined, subIssues: {} }
+  if (result.issue) {
+    const back = await adapter.readIssue(result.issue.id)
+    if (back && typeof back.description === 'string') stored.issue = back.description
+  }
+  for (const [ref, id] of Object.entries(result.subIssues)) {
+    const back = await adapter.readIssue(id)
+    if (back && typeof back.description === 'string') stored.subIssues[ref] = back.description
+  }
+  const verify = helpers.verifyLines(snapshotDir, config, stored, result.issue ? result.issue.identifier : identifier)
+  lines.push(...verify.map((l) => `  ${l}`))
+  const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
+
+  // 7. Record the snapshot from the now-stamped files, so the next push is empty.
+  const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config })
+  lines.push(`  snapshot: ${path.relative(dir, file)}`)
+  return { result, lines, lost }
+}
+
+// The phase file a sub-issue ref names — the ref is the phase-file basename.
+function resolvePhaseFileIn(snapshotDir, ref) {
+  const want = String(ref).replace(/\.md$/, '')
+  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
+}
+
+module.exports = { applySpecPlan }

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

@@ -0,0 +1,68 @@
+'use strict'
+
+/**
+ * A table-driven flag parser for a provider CLI, carrying the one discipline
+ * the first provider learned the hard way: an UNKNOWN `--flag` is a refusal,
+ * never a silent positional. (A renamed flag once parsed as a no-op — the
+ * repair invocation ran the wrong command, ignored the flag, and exited 0.)
+ *
+ * The table maps `--flag` → spec:
+ *   - `{ kind: 'boolean' }`            sets `flags[name] = true`
+ *   - `{ kind: 'value' }`              takes the next token verbatim
+ *   - `{ kind: 'string' }`             takes the next token, trimmed ('' kept)
+ *   - `{ kind: 'number' }`             Number(next token)
+ *   - `{ kind: 'path' }`               path.resolve(next token)
+ *   - `{ kind: 'list' }`               repeatable; pushes trimmed tokens
+ *   - `{ kind: 'custom', take, handle }` `handle(flags, value, context)`;
+ *                                      `take: false` consumes no token
+ *   - any spec may set `name` (defaults to the camelCased flag)
+ *
+ * A spec name never starts with `--`, so the refusal cannot swallow a real
+ * argument. `renamed` maps an old flag to advice lines appended to the refusal,
+ * so a rename hands off instead of leaving the caller to guess.
+ */
+
+const path = require('node:path')
+
+const camel = (flag) => flag.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+
+function parseFlags(args, table, { defaults = {}, renamed = {}, context = {} } = {}) {
+  const flags = { ...defaults }
+  const positional = []
+  const unknown = []
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i]
+    const spec = table[token]
+    if (!spec) {
+      if (String(token).startsWith('--')) unknown.push(token)
+      else positional.push(token)
+      continue
+    }
+    const name = spec.name || camel(token)
+    const kind = spec.kind || 'boolean'
+    if (kind === 'boolean') flags[name] = true
+    else if (kind === 'value') flags[name] = args[++i]
+    else if (kind === 'string') flags[name] = String(args[++i] || '').trim()
+    else if (kind === 'number') flags[name] = Number(args[++i])
+    else if (kind === 'path') flags[name] = path.resolve(args[++i])
+    else if (kind === 'list') (flags[name] = flags[name] || []).push(String(args[++i] || '').trim())
+    else if (kind === 'custom') {
+      const value = spec.take === false ? undefined : args[++i]
+      spec.handle(flags, value, context)
+    } else throw new Error(`parseFlags: unknown kind "${kind}" for ${token}`)
+  }
+  return { flags, positional, unknown }
+}
+
+// The refusal, phrased once. Returns the lines to print (the caller owns the
+// stream and the exit code).
+function unknownFlagLines(program, unknown, renamed = {}) {
+  const lines = [`${program}: unknown flag ${unknown.join(', ')}`]
+  for (const flag of unknown) {
+    if (renamed[flag]) for (const advice of [].concat(renamed[flag])) lines.push(`  ${advice}`)
+  }
+  lines.push(`  run \`${program}\` for the full usage.`)
+  return lines
+}
+
+module.exports = { parseFlags, unknownFlagLines }

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

@@ -0,0 +1,198 @@
+'use strict'
+
+/**
+ * Config-merge machinery shared by every provider's loader.
+ *
+ * A provider's config is a committed JSON file merged over its own defaults —
+ * only known keys copied (unknown ignored for forward-compat), typed fields
+ * validated LOUDLY where a typo would otherwise read as a deliberate choice.
+ * The defaults, the file name and the vocabularies are the provider's; the
+ * merge and validation shapes are identical across providers, so they live
+ * here, bound to the provider by `makeMergeHelpers`.
+ *
+ * Every thrown message names the provider's own config file, so a refusal
+ * points at the file the user actually edits.
+ */
+
+function isObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// Normalise an array config value to trimmed, non-empty strings.
+function stringList(value) {
+  return value.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
+}
+
+// Copy a typed field from parsed[key] onto base[key] when it matches `type`.
+// Strings are trimmed and must be non-empty to override; `string?` may be empty.
+function assign(base, parsed, key, type) {
+  const v = parsed[key]
+  if (type === 'string') {
+    if (typeof v === 'string' && v.trim()) base[key] = v.trim()
+  } else if (type === 'string?') {
+    if (typeof v === 'string') base[key] = v
+  } else if (type === 'boolean') {
+    if (typeof v === 'boolean') base[key] = v
+  }
+}
+
+/**
+ * The provider-bound validators. `configFile` is only used in messages;
+ * `ownership` / `lifecycleBuckets` / `phaseMappings` are the provider's own
+ * vocabularies (they rarely differ between providers, but they are the
+ * provider's to declare).
+ */
+function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappings }) {
+  // Merge (and validate) sync.fieldOwnership. Any key the caller lists joins
+  // the compared field set; the value MUST be one of the ownership modes.
+  function mergeFieldOwnership(base, parsed) {
+    if (!isObject(parsed)) return
+    for (const [field, dir] of Object.entries(parsed)) {
+      if (!ownership.includes(dir)) {
+        throw new Error(
+          `Invalid ${configFile}: sync.fieldOwnership.${field} = ${JSON.stringify(dir)} ` +
+            `(expected one of ${ownership.join('|')})`,
+        )
+      }
+      base[field] = dir
+    }
+  }
+
+  // Merge (and validate) `mapping.phases` in either of its two forms: a scalar
+  // mode for the whole repo, or a map of lifecycle bucket → mode. Loud on a bad
+  // key or value — a misspelt bucket would otherwise read as a deliberate
+  // default and go on minting the sub-issues the config was written to stop.
+  function mergePhaseMapping(base, parsed) {
+    const value = parsed.phases
+    if (typeof value === 'string') {
+      if (value.trim()) base.phases = value.trim()
+    } else if (isObject(value)) {
+      const byBucket = {}
+      for (const [bucket, mode] of Object.entries(value)) {
+        if (!lifecycleBuckets.includes(bucket)) {
+          throw new Error(
+            `Invalid ${configFile}: mapping.phases.${bucket} is not a lifecycle bucket ` +
+              `(expected one of ${lifecycleBuckets.join('|')})`,
+          )
+        }
+        if (!phaseMappings.includes(mode)) {
+          throw new Error(
+            `Invalid ${configFile}: mapping.phases.${bucket} = ${JSON.stringify(mode)} ` +
+              `(expected one of ${phaseMappings.join('|')})`,
+          )
+        }
+        byBucket[bucket] = mode
+      }
+      base.phases = byBucket
+    } else if (value !== undefined) {
+      throw new Error(
+        `Invalid ${configFile}: mapping.phases = ${JSON.stringify(value)} ` +
+          `(expected one of ${phaseMappings.join('|')}, or a map of lifecycle bucket to mode)`,
+      )
+    }
+    if (typeof base.phases === 'string' && !phaseMappings.includes(base.phases)) {
+      throw new Error(
+        `Invalid ${configFile}: mapping.phases = ${JSON.stringify(base.phases)} ` +
+          `(expected one of ${phaseMappings.join('|')}, or a map of lifecycle bucket to mode)`,
+      )
+    }
+  }
+
+  // Merge (and validate) `release.stages` — the project's deployment ladder.
+  //
+  // Loud on a malformed entry: this list names tracker states, and a tracker
+  // that silently ignores an unknown state would let a half-typed ladder push
+  // clean and move nothing — so a bad shape fails here, at load, rather than at
+  // the first deploy nobody is watching. An ABSENT `release` block is not an
+  // error: it is the opt-out, and the whole feature is unused without it.
+  function mergeReleaseStages(base, parsed) {
+    const value = parsed.stages
+    if (value === undefined) return
+    if (!Array.isArray(value)) {
+      throw new Error(
+        `Invalid ${configFile}: release.stages = ${JSON.stringify(value)} ` +
+          '(expected an array of { key, state })',
+      )
+    }
+    const stages = []
+    const seen = new Set()
+    value.forEach((entry, i) => {
+      if (!isObject(entry)) {
+        throw new Error(
+          `Invalid ${configFile}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
+            '(expected { key, state })',
+        )
+      }
+      for (const field of ['key', 'state']) {
+        if (typeof entry[field] !== 'string' || !entry[field].trim()) {
+          throw new Error(
+            `Invalid ${configFile}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
+              '(expected a non-empty string)',
+          )
+        }
+      }
+      const key = entry.key.trim()
+      if (seen.has(key)) {
+        throw new Error(
+          `Invalid ${configFile}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
+            '(a stage key is how CI names the rung, so it must be unique)',
+        )
+      }
+      seen.add(key)
+      stages.push({ key, state: entry.state.trim() })
+    })
+    base.stages = stages
+  }
+
+  // Merge (and validate) release.ignorePaths — the path prefixes whose commits
+  // are bookkeeping. Loud on anything but an array of non-empty strings: a bad
+  // value that quietly fell back would let a project believe it had opted out
+  // and go on double-counting tickets. A BLANK entry is rejected rather than
+  // dropped — `""` is a prefix of every path, so a stray empty string would
+  // silently ignore every commit in the range and report a release as
+  // containing nothing: the loudest possible wrong answer, arriving as silence.
+  function mergeReleaseIgnorePaths(base, parsed) {
+    const value = parsed.ignorePaths
+    if (value === undefined) return
+    if (!Array.isArray(value)) {
+      throw new Error(
+        `Invalid ${configFile}: release.ignorePaths = ${JSON.stringify(value)} ` +
+          '(expected an array of repo-relative path prefixes)',
+      )
+    }
+    value.forEach((entry, i) => {
+      if (typeof entry !== 'string' || !entry.trim()) {
+        throw new Error(
+          `Invalid ${configFile}: release.ignorePaths[${i}] = ${JSON.stringify(entry)} ` +
+            '(expected a non-empty repo-relative path prefix, e.g. "specs/")',
+        )
+      }
+    })
+    base.ignorePaths = stringList(value)
+  }
+
+  // Merge (and validate) sync.keyedFields. Each value is the item's id property
+  // name (a non-empty string); a field listed here is compared per item.
+  function mergeKeyedFields(base, parsed) {
+    if (!isObject(parsed)) return
+    for (const [field, idKey] of Object.entries(parsed)) {
+      if (typeof idKey !== 'string' || !idKey.trim()) {
+        throw new Error(
+          `Invalid ${configFile}: sync.keyedFields.${field} = ${JSON.stringify(idKey)} ` +
+            '(expected the item id property name, a non-empty string)',
+        )
+      }
+      base[field] = idKey.trim()
+    }
+  }
+
+  return {
+    mergeFieldOwnership,
+    mergePhaseMapping,
+    mergeReleaseStages,
+    mergeReleaseIgnorePaths,
+    mergeKeyedFields,
+  }
+}
+
+module.exports = { isObject, stringList, assign, makeMergeHelpers }