@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/review-packet.mjs

@@ -0,0 +1,503 @@
+// Build a bounded, content-free evidence packet for an independent review of a
+// combined release. The packet contains paths and hunk coordinates, never patch
+// lines, so a large release does not consume the reviewer's context before the
+// targeted inspection starts.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const PACKET_VERSION = 2
+export const DEFAULT_MAX_BYTES = 64 * 1024
+
+const RISK_GROUPS = [
+  { id: 'auth', pattern: /(^|\/)(auth|authn|authz|oauth|session|token|identity|iam|policy)(\/|[._-]|$)/i },
+  { id: 'money', pattern: /(^|\/)(billing|money|payment|pricing|price|tax|invoice|refund)(\/|[._-]|$)/i },
+  { id: 'tenancy', pattern: /(^|\/)(tenant|tenancy|organization|organisation|org-scope|workspace)(\/|[._-]|$)/i },
+  { id: 'migration', pattern: /(^|\/)(migrations?|schema|ddl)(\/|[._-]|$)|\.(sql|prisma)$/i },
+]
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+}
+
+function exactSha(rev, cwd) {
+  return git(['rev-parse', '--verify', `${rev}^{commit}`], cwd)
+}
+
+function exactRevisionSha(revision, label, cwd) {
+  try {
+    return exactSha(revision, cwd)
+  } catch {
+    throw new Error(`${label} does not resolve to an exact commit`)
+  }
+}
+
+function exactRefSha(ref, label, cwd) {
+  try {
+    git(['check-ref-format', ref], cwd)
+    return git(['show-ref', '--verify', '--hash', ref], cwd)
+  } catch {
+    throw new Error(`${label} does not resolve as an exact ref`)
+  }
+}
+
+function pinnedSha(value, label, cwd) {
+  if (!/^[0-9a-f]{40}$/.test(value || '')) throw new Error(`${label} must be a full 40-character lowercase commit SHA`)
+  let resolved
+  try {
+    resolved = exactSha(value, cwd)
+  } catch {
+    throw new Error(`${label} ${value} does not resolve to a commit in this repository`)
+  }
+  if (resolved !== value) throw new Error(`${label} ${value} does not resolve exactly`)
+  return resolved
+}
+
+function repositoryIdentity(remoteUrl) {
+  let host
+  let repoPath
+  try {
+    const parsed = new URL(remoteUrl)
+    host = parsed.hostname.toLowerCase()
+    repoPath = parsed.pathname
+  } catch {
+    const scp = /^(?:[^@]+@)?([^:]+):(.+)$/.exec(remoteUrl || '')
+    if (!scp) throw new Error('target remote URL has no recognizable repository identity')
+    host = scp[1].toLowerCase()
+    repoPath = scp[2]
+  }
+  repoPath = repoPath.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')
+  if (!/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+$/.test(repoPath) || repoPath.split('/').includes('..')) {
+    throw new Error('target remote URL has no safe repository path')
+  }
+  return `${host}/${repoPath}`
+}
+
+function authoritativeTarget({ targetRef, targetHeadRev, targetRepository, head, suppliedBase, cwd }) {
+  const match = `${targetRef || ''}`.match(/^refs\/remotes\/([^/]+)\/(.+)$/)
+  if (!match) throw new Error('target ref must be a fully qualified remote-tracking ref (refs/remotes/<remote>/<branch>)')
+  if (match[2] === 'HEAD') throw new Error('target ref must identify an explicit remote branch, not symbolic HEAD')
+  const [, remote] = match
+  let configuredUrl
+  try {
+    configuredUrl = git(['remote', 'get-url', '--', remote], cwd)
+  } catch {
+    throw new Error('target ref remote is not configured in this repository')
+  }
+  if (repositoryIdentity(configuredUrl) !== targetRepository) throw new Error('target repository mismatch for configured target remote')
+
+  const refHead = exactRefSha(targetRef, 'target ref', cwd)
+  const targetHead = pinnedSha(targetHeadRev, 'target head', cwd)
+  if (refHead !== targetHead) throw new Error(`target ref drifted from pinned target head ${targetHead}; resolved ${refHead}`)
+
+  let actualBase
+  try {
+    actualBase = git(['merge-base', targetHead, head], cwd)
+  } catch {
+    throw new Error(`authoritative target and exact head ${head} have no merge-base in this repository`)
+  }
+  if (actualBase !== suppliedBase) {
+    throw new Error(`supplied base ${suppliedBase} does not equal authoritative merge-base ${actualBase} of pinned target and head ${head}`)
+  }
+  return { targetRef, targetHead, targetRepository }
+}
+
+function safeRepoPath(value) {
+  if (typeof value !== 'string' || !value || path.isAbsolute(value)) return false
+  const parts = value.replaceAll('\\', '/').split('/')
+  return !parts.includes('..') && !parts.includes('.') && !parts.includes('') && !value.includes('\0')
+}
+
+function parseNameStatusZ(raw) {
+  const fields = raw.split('\0')
+  if (fields.at(-1) === '') fields.pop()
+  const entries = []
+  for (let i = 0; i < fields.length;) {
+    const status = fields[i++]
+    if (!/^[ACDMRTUXB][0-9]*$/.test(status || '')) throw new Error(`unparseable name-status record ${JSON.stringify(status)}`)
+    if (status.startsWith('R') || status.startsWith('C')) {
+      const oldPath = fields[i++]
+      const newPath = fields[i++]
+      if (!safeRepoPath(oldPath) || !safeRepoPath(newPath)) throw new Error('unsafe changed path in rename/copy record')
+      entries.push({ status, oldPath, newPath })
+    } else {
+      const changedPath = fields[i++]
+      if (!safeRepoPath(changedPath)) throw new Error('unsafe changed path in name-status record')
+      entries.push({ status, path: changedPath })
+    }
+  }
+  return entries
+}
+
+function pathSides(entry) {
+  if (entry.oldPath) return [
+    { path: entry.oldPath, side: 'preimage', status: entry.status },
+    { path: entry.newPath, side: 'postimage', status: entry.status },
+  ]
+  return [{ path: entry.path, side: entry.status.startsWith('D') ? 'preimage' : 'postimage', status: entry.status }]
+}
+
+function riskIds(changedPath) {
+  const ids = RISK_GROUPS.filter((group) => group.pattern.test(changedPath)).map((group) => group.id)
+  return ids.length ? ids : []
+}
+
+function hunkLocators(base, head, changedPath, side, cwd) {
+  const output = git(['diff', '--no-color', '--no-ext-diff', '--no-renames', '--unified=0', `${base}..${head}`, '--', changedPath], cwd)
+  const hunks = []
+  for (const line of output.split(/\r?\n/)) {
+    const match = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line)
+    if (match) {
+      hunks.push({
+        oldStart: Number(match[1]), oldLines: Number(match[2] ?? 1),
+        newStart: Number(match[3]), newLines: Number(match[4] ?? 1),
+      })
+    }
+  }
+  if (hunks.length) return hunks
+  const revision = side === 'preimage' ? base : head
+  try {
+    const lines = git(['show', `${revision}:${changedPath}`], cwd).split(/\r?\n/).length
+    return side === 'preimage'
+      ? [{ oldStart: 1, oldLines: lines, newStart: 0, newLines: 0 }]
+      : [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: lines }]
+  } catch { return [] }
+}
+
+function validateLocator(locator) {
+  if (typeof locator !== 'string' || !locator.trim()) return false
+  const value = locator.trim()
+  if (/^https:\/\/[^\s]+$/.test(value) || /^#\d+$/.test(value) || /^`[^`]+`$/.test(value)) return true
+  if (!/^([^:\s]+\.[A-Za-z][\w-]{0,9})(?::\d+(?:-\d+)?)?$/.test(value)) return false
+  return safeRepoPath(value.split(':')[0])
+}
+
+function readJsonFile(relative, cwd, label) {
+  if (!safeRepoPath(relative)) throw new Error(`${label} path must be a repository-relative file without traversal`)
+  let root
+  let resolved
+  try {
+    root = fs.realpathSync(cwd)
+    resolved = fs.realpathSync(path.resolve(root, relative))
+  } catch {
+    throw new Error(`${label} file is unavailable`)
+  }
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new Error(`${label} path escapes the repository`)
+  try {
+    return JSON.parse(fs.readFileSync(resolved, 'utf8'))
+  } catch {
+    throw new Error(`${label} file must contain valid JSON`)
+  }
+}
+
+function relevantEvidence(input, base, head, cwd) {
+  if (!input || input.headSha !== head || !Array.isArray(input.pullRequests)) {
+    throw new Error(`evidence headSha must match exact head ${head}`)
+  }
+  const output = []
+  for (const pr of input.pullRequests) {
+    if (pr.headSha === base) continue
+    let inRange = false
+    try {
+      inRange = exactSha(pr.headSha, cwd) === pr.headSha
+      git(['merge-base', '--is-ancestor', base, pr.headSha], cwd)
+      git(['merge-base', '--is-ancestor', pr.headSha, head], cwd)
+    } catch {
+      inRange = false
+    }
+    if (!inRange) throw new Error(`PR #${pr.number ?? '?'} evidence headSha is outside the exact range`)
+    if (!Number.isInteger(pr.number) || !/^https:\/\/[^\s]+$/.test(pr.url || '') || !Array.isArray(pr.evidence)) {
+      throw new Error('malformed per-PR evidence record')
+    }
+    for (const item of pr.evidence) {
+      if (!item || typeof item.kind !== 'string' || typeof item.status !== 'string' || !validateLocator(item.locator)) {
+        throw new Error(`unsafe evidence locator for PR #${pr.number}`)
+      }
+    }
+    output.push({
+      number: pr.number,
+      url: pr.url,
+      headSha: pr.headSha,
+    })
+  }
+  return output.sort((a, b) => a.number - b.number)
+}
+
+function validateCi(input, head) {
+  if (!input || input.headSha !== head) throw new Error(`CI headSha does not match exact head ${head}`)
+  if (!Array.isArray(input.jobs)) throw new Error('CI jobs must be an array')
+  if (input.jobs.some((job) => !job || typeof job.name !== 'string' || typeof job.status !== 'string')) throw new Error('each CI job requires string name and status fields')
+  return { headSha: input.headSha, jobs: input.jobs.map((job) => ({ name: job.name, status: job.status, ...(typeof job.url === 'string' && /^https:\/\/[^\s]+$/.test(job.url) ? { url: job.url } : {}) })) }
+}
+
+function packetBytes(packet) {
+  return Buffer.byteLength(`${JSON.stringify(packet, null, 2)}\n`)
+}
+
+function syncOutputBytes(packet) {
+  let previousBytes = -1
+  while (packet.truncation.outputBytes !== previousBytes) {
+    previousBytes = packet.truncation.outputBytes
+    packet.truncation.outputBytes = packetBytes(packet)
+  }
+  return packet.truncation.outputBytes
+}
+
+export function collectPacket({ baseRev, headRev, headRef, targetRef, targetHeadRev, targetRepository, evidence, ci, maxBytes, cwd = process.cwd() }) {
+  const base = pinnedSha(baseRev, 'base', cwd)
+  const head = pinnedSha(headRev, 'head', cwd)
+  const target = authoritativeTarget({ targetRef, targetHeadRev, targetRepository, head, suppliedBase: base, cwd })
+  if (headRef && exactRevisionSha(headRef, 'head ref', cwd) !== head) throw new Error(`head ref drifted from requested head ${head}`)
+
+  const rawNameStatus = execFileSync('git', ['diff', '--name-status', '-z', '-M', '-C', '--find-copies-harder', `${base}..${head}`], {
+    cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+  })
+  const nameStatus = parseNameStatusZ(rawNameStatus)
+  const highRisk = new Map(RISK_GROUPS.map((group) => [group.id, []]))
+  const highRiskEntryIndexes = new Set()
+  nameStatus.forEach((entry, index) => {
+    for (const side of pathSides(entry)) {
+      for (const id of riskIds(side.path)) {
+        highRiskEntryIndexes.add(index)
+        highRisk.get(id).push({ ...side, hunks: hunkLocators(base, head, side.path, side.side, cwd) })
+      }
+    }
+  })
+
+  const packet = {
+    version: PACKET_VERSION,
+    range: {
+      base,
+      head,
+      expression: `${base}..${head}`,
+      targetRef: target.targetRef,
+      targetHead: target.targetHead,
+      targetRepository: target.targetRepository,
+    },
+    diff: {
+      stat: git(['diff', '--shortstat', `${base}..${head}`], cwd),
+      nameStatus: [...nameStatus],
+    },
+    highRiskGroups: [...highRisk.entries()].filter(([, paths]) => paths.length).map(([id, paths]) => ({ id, paths })),
+    pullRequests: relevantEvidence(evidence, base, head, cwd),
+    ci: validateCi(ci, head),
+    reviewInstructions: [
+      'Inspect every high-risk path through the targeted hunk coordinates before sampling ordinary paths.',
+      'Check cross-PR interaction at shared modules, changed-and-consumed contracts, migrations, and ordering boundaries.',
+      'Return one bounded complete verdict covering every high-risk group and every relevant PR; do not request or reproduce a full patch dump.',
+    ],
+    truncation: {
+      maxBytes,
+      totalChangedFiles: nameStatus.length,
+      includedNameStatus: nameStatus.length,
+      omittedNameStatus: 0,
+      omittedHighRiskPaths: 0,
+    },
+  }
+
+  packet.truncation.outputBytes = 0
+  if (syncOutputBytes(packet) > maxBytes) {
+    for (let index = packet.diff.nameStatus.length - 1; index >= 0 && syncOutputBytes(packet) > maxBytes; index--) {
+      if (highRiskEntryIndexes.has(index)) continue
+      packet.diff.nameStatus.splice(index, 1)
+      packet.truncation.omittedNameStatus++
+      packet.truncation.includedNameStatus--
+    }
+  }
+  if (syncOutputBytes(packet) > maxBytes) {
+    throw new Error(`required metadata exceeds byte bound ${maxBytes}; omittedHighRiskPaths=0, omittedNameStatus=${packet.truncation.omittedNameStatus}`)
+  }
+  authoritativeTarget({ ...target, targetHeadRev: target.targetHead, head, suppliedBase: base, cwd })
+  if (headRef && exactRevisionSha(headRef, 'head ref', cwd) !== head) throw new Error(`head ref drifted from requested head ${head}`)
+  return packet
+}
+
+const FULL_SHA = /^[0-9a-f]{40}$/
+const SAFE_HOST = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/
+const SAFE_REPOSITORY_SEGMENT = /^[A-Za-z0-9._-]+$/
+const MAX_PACKET_BYTES = 16 * 1024 * 1024
+
+function displayArgument(value) {
+  return JSON.stringify(`${value}`)
+}
+
+function safeExactRef(value, prefixes) {
+  const prefix = prefixes.find((candidate) => value.startsWith(candidate))
+  if (!prefix) return false
+  const remainder = value.slice(prefix.length)
+  const parts = remainder.split('/')
+  return remainder !== '@'
+    && !value.includes('..')
+    && !value.includes('@{')
+    && !value.endsWith('.')
+    && !/[\x00-\x20\x7f~^:?*\[\\]/.test(value)
+    && parts.every((part) => part && !part.startsWith('.') && !part.endsWith('.lock'))
+}
+
+function typedValue(option, value) {
+  const fail = (contract) => { throw new Error(`--${option.name} must ${contract}`) }
+  if (option.type === 'sha') {
+    if (!FULL_SHA.test(value)) fail('be a full 40-character lowercase commit SHA')
+    return value
+  }
+  if (option.type === 'target-ref') {
+    if (!safeExactRef(value, ['refs/remotes/'])) fail('be a fully-qualified non-symbolic remote-tracking branch ref')
+    const parts = value.slice('refs/remotes/'.length).split('/')
+    if (parts.length < 2 || parts.at(-1) === 'HEAD') fail('be a fully-qualified non-symbolic remote-tracking branch ref')
+    return value
+  }
+  if (option.type === 'head-ref') {
+    if (FULL_SHA.test(value)) return value
+    if (!safeExactRef(value, ['refs/heads/', 'refs/tags/', 'refs/remotes/'])) {
+      fail('be a full lowercase SHA or fully-qualified exact refs/heads, refs/tags, or non-symbolic refs/remotes revision')
+    }
+    if (value.startsWith('refs/remotes/') && value.endsWith('/HEAD')) {
+      fail('be a full lowercase SHA or fully-qualified exact refs/heads, refs/tags, or non-symbolic refs/remotes revision')
+    }
+    return value
+  }
+  if (option.type === 'repository') {
+    const [host, ...repoParts] = value.split('/')
+    if (!SAFE_HOST.test(host) || repoParts.length < 2 || repoParts.some((part) => !SAFE_REPOSITORY_SEGMENT.test(part) || part === '.' || part === '..') || /[\x00-\x20\x7f]/.test(value)) {
+      fail('be a safe lowercase-host/owner/repository identity')
+    }
+    return value
+  }
+  if (option.type === 'repo-path') {
+    if (!safeRepoPath(value) || /^[A-Za-z]:[\\/]/.test(value) || /[\x00-\x1f\x7f]/.test(value)) {
+      fail('be a repository-relative file path without absolute, traversal, dot, empty, or control segments')
+    }
+    return value
+  }
+  if (option.type === 'bytes') {
+    if (!/^[1-9][0-9]*$/.test(value)) fail('be a decimal integer from 1 through 16777216')
+    const parsed = Number(value)
+    if (!Number.isSafeInteger(parsed) || parsed > MAX_PACKET_BYTES) fail('be a decimal integer from 1 through 16777216')
+    return parsed
+  }
+  throw new Error(`internal schema error for --${option.name}`)
+}
+
+const COLLECT_OPTIONS = Object.freeze([
+  { name: 'base', required: true, metavar: 'sha', type: 'sha', note: 'full lowercase exact commit SHA' },
+  { name: 'head', required: true, metavar: 'sha', type: 'sha', note: 'full lowercase exact commit SHA' },
+  { name: 'head-ref', required: false, metavar: 'exact-ref-or-sha', type: 'head-ref', note: 'omitting --head-ref disables named-head drift detection; exact head/target/CI/merge-base checks remain' },
+  { name: 'target-ref', required: true, metavar: 'refs/remotes/remote/branch', type: 'target-ref', note: 'fully-qualified explicit remote-tracking branch' },
+  { name: 'target-head', required: true, metavar: 'sha', type: 'sha', note: 'full lowercase exact commit SHA' },
+  { name: 'target-repository', required: true, metavar: 'host/owner/repo', type: 'repository', note: 'normalized safe repository identity' },
+  { name: 'evidence', required: true, metavar: 'file', type: 'repo-path', dashValueWithEquals: true, note: "--evidence=<file> is required for a value beginning '-'" },
+  { name: 'ci', required: true, metavar: 'file', type: 'repo-path', dashValueWithEquals: true, note: "--ci=<file> is required for a value beginning '-'" },
+  { name: 'max-bytes', required: false, metavar: '1..16777216', type: 'bytes', defaultValue: DEFAULT_MAX_BYTES, note: 'bounded decimal integer' },
+])
+
+const COMMAND_SCHEMA = Object.freeze({
+  collect: Object.freeze({
+    description: 'Emits bounded exact-range JSON metadata for an independent combined-release review.',
+    options: COLLECT_OPTIONS,
+  }),
+})
+
+function usage() {
+  const command = COMMAND_SCHEMA.collect
+  const synopsis = command.options.map((option) => {
+    const token = `--${option.name} <${option.metavar}>`
+    return option.required ? token : `[${token}]`
+  }).join(' ')
+  const rows = command.options.map((option) => {
+    const requirement = option.required ? 'required' : `optional; default ${option.defaultValue ?? 'none'}`
+    return `  --${option.name} <${option.metavar}>  ${requirement}; accepts --${option.name}=<value>; ${option.note}`
+  })
+  return [
+    `review-packet collect ${synopsis}`,
+    '',
+    command.description,
+    ...rows,
+    'When --head-ref is present it must be an exact fully-qualified ref or full lowercase SHA; omitting --head-ref disables named-head drift detection while exact head, target, CI, and merge-base checks remain.',
+    'The packet includes stat/name-status, targeted high-risk hunk coordinates, relevant PR evidence, and exact-head CI. It never emits patch lines.',
+  ].join('\n')
+}
+
+function optionToken(arg) {
+  if (arg === '--') throw new Error('empty option name "--"')
+  if (!arg.startsWith('--')) {
+    if (arg.startsWith('-') || /^[\u2010-\u2015\u2212]/u.test(arg)) throw new Error('malformed option syntax')
+    throw new Error('unexpected positional argument')
+  }
+  const equals = arg.indexOf('=')
+  const name = arg.slice(2, equals === -1 ? undefined : equals)
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('malformed option name')
+  return { name, inline: equals !== -1, value: equals === -1 ? undefined : arg.slice(equals + 1) }
+}
+
+function parseArgs(argv) {
+  const [commandName, ...rest] = argv
+  const command = COMMAND_SCHEMA[commandName]
+  if (!command) throw new Error('unsupported command (expected "collect")')
+  const byName = new Map(command.options.map((option) => [option.name, option]))
+  const raw = new Map()
+
+  for (let index = 0; index < rest.length; index++) {
+    const token = optionToken(rest[index])
+    const option = byName.get(token.name)
+    if (!option) throw new Error(`unknown option for command ${displayArgument(commandName)}`)
+    if (raw.has(option.name)) throw new Error(`--${option.name} may be supplied only once`)
+    let value = token.value
+    if (!token.inline) {
+      value = rest[index + 1]
+      if (typeof value !== 'string' || value === '' || value.startsWith('-')) {
+        if (option.dashValueWithEquals && typeof value === 'string' && value.startsWith('-') && !value.startsWith('--')) {
+          throw new Error(`--${option.name} requires --${option.name}=<value> for a value beginning '-'`)
+        }
+        throw new Error(`--${option.name} requires a value`)
+      }
+      index++
+    } else if (value === '') {
+      throw new Error(`--${option.name} requires a non-empty value`)
+    }
+    raw.set(option.name, value)
+  }
+
+  const options = {}
+  for (const option of command.options) {
+    if (!raw.has(option.name)) {
+      if (option.required) throw new Error(`--${option.name} is required`)
+      if (option.defaultValue !== undefined) options[option.name] = option.defaultValue
+      continue
+    }
+    options[option.name] = typedValue(option, raw.get(option.name))
+  }
+  return { command: commandName, options }
+}
+
+const USAGE = usage()
+
+export function main(argv, cwd = process.cwd()) {
+  try {
+    if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) {
+      console.log(USAGE)
+      return 0
+    }
+    const { command, options } = parseArgs(argv)
+    const packet = collectPacket({
+      baseRev: options.base,
+      headRev: options.head,
+      headRef: options['head-ref'],
+      targetRef: options['target-ref'],
+      targetHeadRev: options['target-head'],
+      targetRepository: options['target-repository'],
+      evidence: readJsonFile(options.evidence, cwd, 'evidence'),
+      ci: readJsonFile(options.ci, cwd, 'CI'),
+      maxBytes: options['max-bytes'],
+      cwd,
+    })
+    console.log(JSON.stringify(packet, null, 2))
+    return 0
+  } catch (error) {
+    console.error(`review-packet: ${error.message}`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exit(main(process.argv.slice(2)))