@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/reconcile-contained-unit-prs.mjs

@@ -0,0 +1,415 @@
+import { execFileSync, spawnSync } from 'node:child_process'
+
+const SHA_RE = /^[0-9a-f]{7,64}$/i
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const clone = (value) => structuredClone(value)
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right)
+const refNumber = (value) => {
+  if (Number.isInteger(value) && value > 0) return value
+  const match = String(value ?? '').match(/(?:^|#)(\d+)$/)
+  return match ? Number(match[1]) : null
+}
+
+const COMPONENT_OUTCOMES = new Set([
+  'component-merged',
+  'component-unreadable',
+  'component-not-merged',
+  'component-merge-sha-mismatch',
+])
+const UNIT_OUTCOMES = new Set([
+  'closed-superseded',
+  'already-closed',
+  'already-merged',
+  'head-drift',
+  'not-contained',
+  'unit-unreadable',
+  'ancestry-unreadable',
+  'preclose-unreadable',
+  'preclose-head-drift',
+  'preclose-not-open',
+  'close-failed',
+  'blocked-component',
+])
+const TERMINAL_UNIT_OUTCOMES = new Set(['closed-superseded', 'already-closed', 'already-merged'])
+const FAILED_UNIT_OUTCOMES = new Set([
+  'head-drift',
+  'not-contained',
+  'unit-unreadable',
+  'ancestry-unreadable',
+  'preclose-unreadable',
+  'preclose-head-drift',
+  'preclose-not-open',
+  'close-failed',
+  'blocked-component',
+])
+
+function normalizedPr(kind, requestedNumber, live) {
+  if (!isObject(live)) throw new Error(`${kind} #${requestedNumber} returned no structured observation`)
+  if (!Number.isInteger(live.number) || live.number <= 0) throw new Error(`${kind} #${requestedNumber} returned missing or malformed numeric identity`)
+  if (live.number !== requestedNumber) throw new Error(`${kind} #${requestedNumber} returned identity ${live.number}`)
+  if (!nonEmpty(live.state)) throw new Error(`${kind} #${requestedNumber} returned no state`)
+  return { ...clone(live), number: requestedNumber }
+}
+
+function candidateUnitEvidence(component, generation) {
+  const candidate = component?.candidate
+  if (!isObject(candidate) || candidate.generation !== generation || candidate.frozen?.generation !== generation) {
+    throw new Error(`component ${component?.id ?? '(unknown)'} has no frozen candidate evidence for delivered generation ${generation}`)
+  }
+  if (!Array.isArray(candidate.frozen.unitEvidence)) {
+    throw new Error(`component ${component.id} frozen unitEvidence is missing`)
+  }
+  return candidate.frozen.unitEvidence
+}
+
+function reconciliationTargets(manifest) {
+  if (manifest?.finalization !== undefined) throw new Error('contained unit PR reconciliation is pre-finalization only')
+  if (!nonEmpty(manifest?.repository)) throw new Error('repository is required for contained unit PR reconciliation')
+  if (!nonEmpty(manifest?.targetBranch)) throw new Error('targetBranch is required for contained unit PR reconciliation')
+  const units = Array.isArray(manifest?.units) ? manifest.units : []
+  const byId = new Map(units.map((unit) => [unit?.id, unit]))
+  const targets = []
+
+  for (const component of Array.isArray(manifest?.components) ? manifest.components : []) {
+    const delivery = component?.delivery
+    if (!isObject(delivery) || delivery.outcome !== 'merged') continue
+    const componentPr = refNumber(delivery.pr)
+    const publishedPr = refNumber(component.pr)
+    if (componentPr == null || publishedPr !== componentPr) {
+      throw new Error(`component ${component?.id ?? '(unknown)'} has no unambiguous published combined PR`)
+    }
+    if (!Number.isSafeInteger(delivery.generation) || delivery.generation < 1 || !SHA_RE.test(delivery.mergedSha ?? '')) {
+      throw new Error(`component ${component.id} has malformed delivered generation or merge SHA`)
+    }
+    const evidence = candidateUnitEvidence(component, delivery.generation)
+    const evidenceById = new Map(evidence.map((entry) => [entry?.unitId, entry]))
+    const linkedUnits = []
+    for (const unitId of Array.isArray(component.units) ? component.units : []) {
+      const unit = byId.get(unitId)
+      if (!unit || !same(unit.deliveryRef, { componentId: component.id, generation: delivery.generation })) continue
+      const unitPr = refNumber(unit.pr)
+      if (unitPr == null || unitPr === componentPr) continue
+      const reviewed = evidenceById.get(unitId)
+      if (!isObject(reviewed) || refNumber(reviewed.pr) !== unitPr) continue
+      if (!SHA_RE.test(reviewed.headSha ?? '') || reviewed.preliminaryReview?.verdict !== 'PASS'
+          || reviewed.preliminaryReview?.headSha !== reviewed.headSha) {
+        throw new Error(`component ${component.id} unit ${unitId} has no exact reviewed unit head in publication evidence`)
+      }
+      linkedUnits.push({ unitId, pr: unitPr, reviewedHeadSha: reviewed.headSha })
+    }
+    if (linkedUnits.length) targets.push({ component, delivery, componentPr, linkedUnits })
+  }
+  return targets
+}
+
+function supersessionComment({ componentPr, reviewedHeadSha, targetRef, mergedSha }) {
+  return `Closing this unit PR as superseded by combined PR #${componentPr}. The exact reviewed unit head ${reviewedHeadSha} is contained in freshly fetched ${targetRef}; the combined component merged as ${mergedSha}.`
+}
+
+function componentRecord(target, fetchedTarget, at) {
+  return {
+    at,
+    target: {
+      branch: fetchedTarget.branch,
+      ref: fetchedTarget.ref,
+      headSha: fetchedTarget.headSha,
+      ...(nonEmpty(fetchedTarget.fetchedAt) ? { fetchedAt: fetchedTarget.fetchedAt } : {}),
+    },
+    componentPr: target.componentPr,
+    generation: target.delivery.generation,
+    mergedSha: target.delivery.mergedSha,
+    component: null,
+    outcome: null,
+    units: target.linkedUnits.map((unit) => ({
+      ...unit,
+      live: null,
+      headMatches: null,
+      ancestry: null,
+      outcome: 'blocked-component',
+    })),
+  }
+}
+
+export async function reconcileContainedUnitPrs(manifest, boundary) {
+  const out = clone(manifest)
+  const targets = reconciliationTargets(out)
+  let fetchedTarget
+  try {
+    fetchedTarget = await boundary.fetchTarget(out.targetBranch)
+  } catch (error) {
+    return { ok: false, errors: [`fresh target fetch failed: ${error.message ?? error}`], manifest: out, target: null, reconciliations: [] }
+  }
+  if (!isObject(fetchedTarget) || fetchedTarget.branch !== out.targetBranch || !nonEmpty(fetchedTarget.ref) || !nonEmpty(fetchedTarget.headSha)) {
+    return { ok: false, errors: ['fresh target fetch returned no matching branch/ref/head SHA'], manifest: out, target: fetchedTarget ?? null, reconciliations: [] }
+  }
+
+  const at = boundary.now()
+  const records = targets.map((target) => componentRecord(target, fetchedTarget, at))
+  const errors = []
+
+  // Phase one observes every component and unit head before any outward mutation.
+  for (let index = 0; index < targets.length; index++) {
+    const target = targets[index]
+    const record = records[index]
+    try {
+      record.component = normalizedPr('component PR', target.componentPr, await boundary.readPr(target.componentPr, out.repository))
+    } catch (error) {
+      record.outcome = 'component-unreadable'
+      errors.push(`component ${target.component.id} PR #${target.componentPr} could not be verified live: ${error.message ?? error}`)
+      continue
+    }
+    if (record.component.state !== 'MERGED' || record.component.merged !== true) {
+      record.outcome = 'component-not-merged'
+      errors.push(`component ${target.component.id} PR #${target.componentPr} is not live-verified merged`)
+      continue
+    }
+    if (record.component.mergeCommitSha !== target.delivery.mergedSha) {
+      record.outcome = 'component-merge-sha-mismatch'
+      errors.push(`component ${target.component.id} PR #${target.componentPr} merge SHA is ${record.component.mergeCommitSha ?? 'missing'}, expected ${target.delivery.mergedSha}`)
+      continue
+    }
+    record.outcome = 'component-merged'
+
+    for (const unit of record.units) {
+      try {
+        unit.live = normalizedPr('unit PR', unit.pr, await boundary.readPr(unit.pr, out.repository))
+      } catch (error) {
+        unit.outcome = 'unit-unreadable'
+        unit.error = error.message ?? String(error)
+        errors.push(`unit ${unit.unitId} PR #${unit.pr} could not be verified live: ${unit.error}`)
+        continue
+      }
+      unit.headMatches = unit.live.headSha === unit.reviewedHeadSha
+      if (unit.live.state === 'MERGED' || unit.live.merged === true) {
+        unit.outcome = 'already-merged'
+        continue
+      }
+      if (unit.live.state === 'CLOSED') {
+        unit.outcome = 'already-closed'
+        continue
+      }
+      if (unit.live.state !== 'OPEN') {
+        unit.outcome = 'unit-unreadable'
+        unit.error = `unsupported live state ${unit.live.state}`
+        errors.push(`unit ${unit.unitId} PR #${unit.pr} returned ${unit.error}`)
+        continue
+      }
+      if (!unit.headMatches) {
+        unit.outcome = 'head-drift'
+        errors.push(`unit ${unit.unitId} PR #${unit.pr} head ${unit.live.headSha ?? 'missing'} does not equal reviewed head ${unit.reviewedHeadSha}`)
+        continue
+      }
+      let contained
+      try {
+        contained = await boundary.isAncestor(unit.reviewedHeadSha, fetchedTarget.ref)
+      } catch (error) {
+        unit.outcome = 'ancestry-unreadable'
+        unit.error = error.message ?? String(error)
+        errors.push(`unit ${unit.unitId} ancestry could not be verified: ${unit.error}`)
+        continue
+      }
+      unit.ancestry = { targetRef: fetchedTarget.ref, contained: contained === true }
+      if (contained !== true) {
+        unit.outcome = 'not-contained'
+        errors.push(`unit ${unit.unitId} reviewed head ${unit.reviewedHeadSha} is not an ancestor of freshly fetched ${fetchedTarget.ref}`)
+        continue
+      }
+      unit.outcome = 'pending-close'
+    }
+  }
+
+  // Phase two re-reads each eligible head immediately before the close mutation.
+  for (let index = 0; index < targets.length; index++) {
+    const target = targets[index]
+    const record = records[index]
+    if (record.outcome !== 'component-merged') continue
+    for (const unit of record.units.filter((entry) => entry.outcome === 'pending-close')) {
+      let preclose
+      try {
+        preclose = normalizedPr('unit PR', unit.pr, await boundary.readPr(unit.pr, out.repository))
+      } catch (error) {
+        unit.outcome = 'preclose-unreadable'
+        unit.error = error.message ?? String(error)
+        errors.push(`unit ${unit.unitId} PR #${unit.pr} pre-close read failed: ${unit.error}`)
+        continue
+      }
+      if (preclose.headSha !== unit.reviewedHeadSha) {
+        unit.outcome = 'preclose-head-drift'
+        unit.live = preclose
+        unit.headMatches = false
+        errors.push(`unit ${unit.unitId} PR #${unit.pr} moved to ${preclose.headSha ?? 'missing'} before close`)
+        continue
+      }
+      if (preclose.state !== 'OPEN' || preclose.merged === true) {
+        unit.outcome = preclose.state === 'MERGED' || preclose.merged === true ? 'already-merged' : preclose.state === 'CLOSED' ? 'already-closed' : 'preclose-not-open'
+        unit.live = preclose
+        if (unit.outcome === 'preclose-not-open') errors.push(`unit ${unit.unitId} PR #${unit.pr} is ${preclose.state}, not OPEN, before close`)
+        continue
+      }
+      unit.comment = supersessionComment({
+        componentPr: target.componentPr,
+        reviewedHeadSha: unit.reviewedHeadSha,
+        targetRef: fetchedTarget.ref,
+        mergedSha: target.delivery.mergedSha,
+      })
+      try {
+        const closed = normalizedPr('closed unit PR', unit.pr, await boundary.closePr(unit.pr, out.repository, unit.comment))
+        if (!['CLOSED', 'MERGED'].includes(closed.state)) throw new Error(`close returned state ${closed.state}`)
+        unit.live = closed
+        unit.outcome = closed.state === 'MERGED' || closed.merged === true ? 'already-merged' : 'closed-superseded'
+      } catch (error) {
+        unit.outcome = 'close-failed'
+        unit.error = error.message ?? String(error)
+        errors.push(`unit ${unit.unitId} PR #${unit.pr} close failed: ${unit.error}`)
+      }
+    }
+  }
+
+  for (let index = 0; index < targets.length; index++) {
+    const delivery = targets[index].component.delivery
+    delivery.reconciliations = [...(Array.isArray(delivery.reconciliations) ? delivery.reconciliations : []), records[index]]
+  }
+  const recordErrors = reconciliationErrors(out)
+  if (recordErrors.length) throw new Error(`invalid reconciliation result: ${recordErrors[0]}`)
+  return {
+    ok: errors.length === 0 && records.every((record) => record.outcome === 'component-merged'
+      && record.units.every((unit) => !FAILED_UNIT_OUTCOMES.has(unit.outcome))),
+    errors,
+    manifest: out,
+    target: fetchedTarget,
+    reconciliations: records,
+  }
+}
+
+export function unitPrReconciliationStatus(manifest) {
+  let targets
+  try {
+    targets = reconciliationTargets(manifest)
+  } catch (error) {
+    return { state: 'invalid', required: true, complete: false, reason: error.message ?? String(error), components: [] }
+  }
+  if (!targets.length) return { state: 'not-required', required: false, complete: true, reason: 'no delivered combined component has explicitly published, distinct unit PRs', components: [] }
+  const components = targets.map((target) => {
+    const latest = Array.isArray(target.delivery.reconciliations) ? target.delivery.reconciliations.at(-1) : null
+    const observed = new Map((Array.isArray(latest?.units) ? latest.units : []).map((unit) => [unit?.unitId, unit]))
+    const pendingUnits = target.linkedUnits
+      .filter((unit) => !TERMINAL_UNIT_OUTCOMES.has(observed.get(unit.unitId)?.outcome))
+      .map((unit) => unit.unitId)
+    return { componentId: target.component.id, componentPr: target.componentPr, pendingUnits, complete: pendingUnits.length === 0 }
+  })
+  const complete = components.every((component) => component.complete)
+  return {
+    state: complete ? 'complete' : 'required',
+    required: true,
+    complete,
+    reason: complete ? 'all linked unit PRs have terminal live observations' : 'delivered combined components still have unreconciled unit PRs',
+    components,
+  }
+}
+
+export function reconciliationErrors(manifest) {
+  const errors = []
+  const units = new Map((Array.isArray(manifest?.units) ? manifest.units : []).map((unit) => [unit?.id, unit]))
+  for (const [componentIndex, component] of (Array.isArray(manifest?.components) ? manifest.components : []).entries()) {
+    const reconciliations = component?.delivery?.reconciliations
+    if (reconciliations === undefined) continue
+    const label = `components[${componentIndex}] (${component?.id ?? 'unknown'}).delivery.reconciliations`
+    if (!Array.isArray(reconciliations)) { errors.push(`${label} must be an array`); continue }
+    for (const [recordIndex, record] of reconciliations.entries()) {
+      const at = `${label}[${recordIndex}]`
+      if (!isObject(record)) { errors.push(`${at} must be an object`); continue }
+      const unknown = Object.keys(record).filter((key) => !['at', 'target', 'componentPr', 'generation', 'mergedSha', 'component', 'outcome', 'units'].includes(key))
+      if (unknown.length) errors.push(`${at} has unknown property ${unknown[0]}`)
+      if (!nonEmpty(record.at) || !nonEmpty(record.target?.ref) || !SHA_RE.test(record.target?.headSha ?? '')) errors.push(`${at} requires timestamp and fresh target ref/head`)
+      if (record.target?.branch !== manifest.targetBranch || record.target?.ref !== `origin/${manifest.targetBranch}`) errors.push(`${at}.target must equal the freshly fetched origin targetBranch`)
+      if (record.componentPr !== refNumber(component.delivery?.pr) || record.generation !== component.delivery?.generation || record.mergedSha !== component.delivery?.mergedSha) {
+        errors.push(`${at} must bind the canonical component delivery PR, generation, and merge SHA`)
+      }
+      if (!COMPONENT_OUTCOMES.has(record.outcome)) errors.push(`${at}.outcome is invalid`)
+      if (record.component != null && record.component.number !== record.componentPr) errors.push(`${at}.component identity is stale`)
+      if (record.outcome === 'component-merged'
+          && (record.component?.state !== 'MERGED' || record.component?.merged !== true || record.component?.mergeCommitSha !== record.mergedSha)) {
+        errors.push(`${at}.component does not prove the recorded merged outcome at the canonical merge SHA`)
+      }
+      if (!Array.isArray(record.units)) { errors.push(`${at}.units must be an array`); continue }
+      const publishedEvidence = new Map((Array.isArray(component.candidate?.frozen?.unitEvidence) ? component.candidate.frozen.unitEvidence : [])
+        .map((entry) => [entry?.unitId, entry]))
+      const seen = new Set()
+      for (const [unitIndex, row] of record.units.entries()) {
+        const unitAt = `${at}.units[${unitIndex}]`
+        if (!isObject(row)) { errors.push(`${unitAt} must be an object`); continue }
+        const unknownUnit = Object.keys(row).filter((key) => !['unitId', 'pr', 'reviewedHeadSha', 'live', 'headMatches', 'ancestry', 'outcome', 'comment', 'error'].includes(key))
+        if (unknownUnit.length) errors.push(`${unitAt} has unknown property ${unknownUnit[0]}`)
+        if (!nonEmpty(row.unitId) || seen.has(row.unitId)) errors.push(`${unitAt}.unitId must be non-empty and unique`)
+        seen.add(row.unitId)
+        if (!UNIT_OUTCOMES.has(row.outcome)) errors.push(`${unitAt}.outcome is invalid`)
+        if (!SHA_RE.test(row.reviewedHeadSha ?? '') || refNumber(row.pr) == null) errors.push(`${unitAt} requires unit PR and reviewed head`)
+        const unit = units.get(row.unitId)
+        if (!unit || !same(unit.deliveryRef, { componentId: component.id, generation: record.generation })) errors.push(`${unitAt} is not linked to this delivered component generation`)
+        const published = publishedEvidence.get(row.unitId)
+        if (!published || refNumber(published.pr) !== row.pr || published.headSha !== row.reviewedHeadSha
+            || published.preliminaryReview?.verdict !== 'PASS' || published.preliminaryReview?.headSha !== row.reviewedHeadSha) {
+          errors.push(`${unitAt} does not match the component's exact published reviewed-unit evidence`)
+        }
+        if (row.live != null && row.live.number !== row.pr) errors.push(`${unitAt}.live identity is stale`)
+        if (row.ancestry != null && (row.ancestry.targetRef !== record.target?.ref || typeof row.ancestry.contained !== 'boolean')) errors.push(`${unitAt}.ancestry is stale`)
+        if (row.outcome === 'closed-superseded'
+            && (row.live?.state !== 'CLOSED' || row.headMatches !== true || row.ancestry?.contained !== true)) {
+          errors.push(`${unitAt} closed-superseded outcome lacks exact-head, ancestry, or terminal-state proof`)
+        }
+        if (row.outcome === 'already-closed' && row.live?.state !== 'CLOSED') errors.push(`${unitAt} already-closed outcome lacks CLOSED state`)
+        if (row.outcome === 'already-merged' && row.live?.state !== 'MERGED' && row.live?.merged !== true) errors.push(`${unitAt} already-merged outcome lacks MERGED state`)
+        if (row.outcome === 'head-drift' && row.headMatches !== false) errors.push(`${unitAt} head-drift outcome lacks a mismatched live head`)
+        if (row.outcome === 'not-contained' && row.ancestry?.contained !== false) errors.push(`${unitAt} not-contained outcome lacks negative fresh-target ancestry`)
+        if (row.outcome === 'closed-superseded') {
+          for (const expected of [`#${record.componentPr}`, row.reviewedHeadSha, record.target.ref, record.mergedSha]) {
+            if (!nonEmpty(row.comment) || !row.comment.includes(expected)) errors.push(`${unitAt}.comment must name combined PR, reviewed head, target ref, and merge SHA`)
+          }
+        }
+      }
+    }
+  }
+  return errors
+}
+
+function runJson(command, args, cwd) {
+  return JSON.parse(execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }))
+}
+
+export function createLiveReconciliationBoundary({ cwd = process.cwd(), now = () => new Date().toISOString() } = {}) {
+  const readPr = async (id, repository) => {
+    if (!Number.isInteger(id) || !nonEmpty(repository)) throw new Error('PR number and repository are required')
+    const view = runJson('gh', ['pr', 'view', String(id), '--repo', repository, '--json', 'number,state,mergedAt,mergeCommit,url,headRefOid'], cwd)
+    return {
+      number: view.number,
+      state: view.state,
+      merged: view.state === 'MERGED' || nonEmpty(view.mergedAt),
+      mergedAt: view.mergedAt ?? null,
+      mergeCommitSha: view.mergeCommit?.oid ?? null,
+      headSha: view.headRefOid ?? null,
+      url: view.url,
+    }
+  }
+  return {
+    now,
+    fetchTarget: async (branch) => {
+      if (!nonEmpty(branch)) throw new Error('targetBranch is not recorded')
+      execFileSync('git', ['fetch', 'origin', branch], { cwd, stdio: ['ignore', 'ignore', 'pipe'] })
+      const ref = `origin/${branch}`
+      const headSha = execFileSync('git', ['rev-parse', ref], { cwd, encoding: 'utf8' }).trim()
+      return { remote: 'origin', branch, ref, headSha, fetchedAt: now() }
+    },
+    isAncestor: async (headSha, ref) => {
+      const result = spawnSync('git', ['merge-base', '--is-ancestor', headSha, ref], { cwd, encoding: 'utf8' })
+      if (result.status === 0) return true
+      if (result.status === 1) return false
+      throw new Error(result.stderr?.trim() || `git merge-base --is-ancestor exited ${result.status ?? 'without status'}`)
+    },
+    readPr,
+    closePr: async (id, repository, comment) => {
+      execFileSync('gh', ['pr', 'close', String(id), '--repo', repository, '--comment', comment], { cwd, stdio: ['ignore', 'ignore', 'pipe'] })
+      return readPr(id, repository)
+    },
+  }
+}