@1aboveio/skills 0.19.3 → 0.20.2

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

@@ -1,415 +0,0 @@
-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)
-    },
-  }
-}