trackfw 7.0.0 → 7.2.0

package/src/ship/runner.js

@@ -8,16 +8,78 @@
  */
 
 const { spawnSync } = require('child_process')
-const fs = require('fs')
-const path = require('path')
 const { load: loadConfig, reset: resetConfig } = require('../config')
 const { resolve: forgeResolve } = require('../forge/resolve')
 const { forgeAdapter } = require('../forge/adapter')
+const validator = require('../validator')
+const { evaluateBranchIntegration, DECISION: BRANCH_PRUNE_DECISION } = require('../branch/prune')
 
 // Git subcommands that modify local or remote state.
 // In --dry-run mode these are printed but not executed.
 const GIT_WRITE_COMMANDS = new Set(['commit', 'push', 'fetch'])
 
+// force-with-lease refusal messages. Named constants so the ML-1B parity gate has a single
+// place to compare byte-for-byte across the 3 CLIs. Byte-identical to Go's
+// forceLease*Msg/Fmt constants (internal/commands/ship.go) and Python's FORCE_LEASE_* below.
+// Never expose "--force" (raw) as a flag — see
+// ADR-2026-08-19-caminho-governado-para-push-forcado-e-tag-de-release.md.
+const FORCE_LEASE_NO_FORGE_CLI_MSG =
+  'trackfw ship --force-with-lease requires a forge CLI (gh, glab, or az) to confirm an open pull/merge request before rewriting remote history. No forge CLI is available for this repository — install and authenticate it, or push without --force-with-lease.'
+
+function forceLeaseNoPROpenMsg(branch) {
+  return `trackfw ship --force-with-lease refuses to run: branch "${branch}" has no open pull/merge request. Open the PR/MR first (trackfw ship without --force-with-lease, or your forge's web UI), then retry.`
+}
+
+function forceLeaseCannotVerifyMsg(branch, cliName, errMessage) {
+  return `trackfw ship --force-with-lease could not verify whether branch "${branch}" has an open pull/merge request (${cliName} CLI error: ${errMessage}). Refusing rather than risking a force push without a verified PR — check your ${cliName} CLI authentication and retry.`
+}
+
+/**
+ * defaultCheckPROpen queries the resolved forge CLI for an open PR/MR whose source branch is
+ * `branch`, using the same list-based query shape for every forge: empty result means "no PR"
+ * (exit 0), any non-zero exit or unparseable output means "cannot verify" (thrown — never
+ * conflated with "no PR"). bitbucket and "manual" never reach here: runShip only calls
+ * checkPROpen when adapter.available is true, and bitbucket's adapter is always available=false.
+ * @param {object} adapter
+ * @param {string} branch
+ * @returns {boolean}
+ */
+function defaultCheckPROpen(adapter, branch) {
+  let args
+  switch (adapter.forge) {
+    case 'github':
+      args = ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number']
+      break
+    case 'gitlab':
+      // glab mr list: --source-branch filters by source branch, --state opened matches
+      // gh's "open" state, -F json requests machine-readable output (glab's own flag,
+      // not an external jq/GNU dependency).
+      args = ['mr', 'list', '--source-branch', branch, '--state', 'opened', '-F', 'json']
+      break
+    case 'azure':
+      // az defaults to --output json; passed explicitly here for clarity, not reliance
+      // on the ambient default.
+      args = ['repos', 'pr', 'list', '--source-branch', branch, '--status', 'active', '--output', 'json']
+      break
+    default:
+      throw new Error(`no PR/MR query defined for forge "${adapter.forge}"`)
+  }
+
+  const result = spawnSync(adapter.cliName, args, { encoding: 'utf8' })
+  if (result.status !== 0) {
+    const msg = (result.stderr || '').trim() || `${adapter.cliName} exited with ${result.status}`
+    throw new Error(msg)
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(result.stdout || '[]')
+  } catch (e) {
+    throw new Error(`could not parse ${adapter.cliName} output: ${e.message}`)
+  }
+  return Array.isArray(parsed) && parsed.length > 0
+}
+
 /**
  * isGitWriteCmd returns true when the first arg is a write-mode git subcommand.
  * @param {string[]} args
@@ -77,66 +139,25 @@ function defaultCheckGovernance() {
 
 /**
  * checkShipGovernance — hard gate (bypasses config/baseline/lenient).
- * Checks:
- *   1. Current branch has a matching roadmap in wip/
- *   2. WIP roadmaps have a linked REQ
+ *
+ * Delegates entirely to the shared validator functions already used by `trackfw validate`,
+ * `trackfw branch new` and `trackfw commit` — never reimplement this logic locally. Byte-
+ * identical to Go's CheckShipGovernance (internal/validator/validator.go), which has the same
+ * no-args shape and the same two checks:
+ *   1. validateBranchHasWIPRoadmap — current branch (feat/fix/refactor only; re-derived
+ *      internally from TRACKFW_BRANCH/git, same as Go) has a matching roadmap in wip/ OR done/
+ *   2. validateWIPHasREQ — every roadmap in wip/ has a linked REQ
+ * Before this ML, this function reimplemented both checks locally with its own wording (no
+ * "nor done/" clause, no done/ directory scan at all) — see
+ * vault/notes/ship-checkgovernance-error-stream-wording-divergence-2026-08-16.md. Duplicating
+ * the check was the actual root cause of the drift, not just the wording.
  * @returns {string[]} violation messages
  */
 function checkShipGovernance() {
-  const violations = []
-
-  // Resolve roadmap dir via config module (single source of truth; default: docs/roadmaps)
-  const roadmapDir = resolveRoadmapDir()
-  const wipDir = path.join(roadmapDir, 'wip')
-
-  // Get branch name
-  const branchResult = defaultExecGit(['symbolic-ref', '--short', 'HEAD'])
-  const branch = branchResult.error ? '' : branchResult.stdout.trim()
-
-  // Check branch has matching roadmap in wip/ — gated types only (feat/fix/refactor); chore/docs
-  // are exempted by the outer runShip Step 2 skip and never reach this function in practice, but
-  // isGatedShipBranch keeps this check correct in isolation too.
-  if (branch && isGatedShipBranch(branch)) {
-    const slug = normalizeBranchSlug(branch.split('/').slice(1).join('/'))
-    let hasMatch = false
-    let wipFiles = []
-
-    if (fs.existsSync(wipDir)) {
-      wipFiles = fs.readdirSync(wipDir).filter(f => f.endsWith('.md'))
-      for (const f of wipFiles) {
-        if (normalizeBranchSlug(f).includes(slug)) {
-          hasMatch = true
-          break
-        }
-      }
-    }
-
-    if (wipFiles.length === 0) {
-      violations.push(
-        `branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ — create governance artifacts first:\n` +
-        '  trackfw req new "<title>"\n' +
-        '  trackfw roadmap new "<title>"\n' +
-        '  trackfw roadmap move <name> wip'
-      )
-    } else if (!hasMatch) {
-      violations.push(
-        `branch "${branch}" has no matching roadmap in wip/ (found: ${wipFiles.join(', ')}) — ` +
-        'include the branch slug in the roadmap filename'
-      )
-    }
-
-    // Check WIP roadmaps have a linked REQ
-    if (hasMatch && fs.existsSync(wipDir)) {
-      for (const f of wipFiles) {
-        const content = fs.readFileSync(path.join(wipDir, f), 'utf8')
-        if (!content.includes('REQ:') && !content.includes('req:')) {
-          violations.push(`roadmap "${f}" is in wip but has no linked REQ`)
-        }
-      }
-    }
-  }
-
-  return violations
+  return [
+    ...validator.validateBranchHasWIPRoadmap(),
+    ...validator.validateWIPHasREQ(),
+  ]
 }
 
 /**
@@ -172,8 +193,17 @@ function normalizeBranchSlug(value) {
 }
 
 /**
- * detectPendingSquashMerges warns about remote branches with non-empty diffs vs origin/main.
- * Non-blocking.
+ * detectPendingSquashMerges warns about remote branches with genuinely pending work vs
+ * origin/main. Non-blocking.
+ *
+ * Reuses evaluateBranchIntegration (branch/prune.js) — the same touched-files heuristic
+ * `trackfw branch prune` uses — instead of a naive bidirectional `git diff origin/main <branch>
+ * --stat`. The naive check false-positives on a branch that was squash-merged and is now merely
+ * stale (main advanced further afterwards): it always shows a non-empty diff even though nothing
+ * from the branch is actually missing from main. Only DECISION.PENDING_WORK — genuine,
+ * unintegrated work — surfaces this warning; every other decision (no_own_work,
+ * content_identical, review_doc_config, no_merge_base, eval_error) stays silent, the same
+ * posture the naive check had on error (skip, no warning).
  * @param {string} currentBranch
  * @param {function} execGit
  * @param {function} writeln
@@ -188,9 +218,8 @@ function detectPendingSquashMerges(currentBranch, execGit, writeln) {
     const shortName = candidate.replace(/^origin\//, '')
     if (shortName === currentBranch) continue
 
-    const { stdout: diff, error: derr } = execGit(['diff', 'origin/main', candidate, '--stat'])
-    if (derr) continue
-    if (diff.trim()) {
+    const evalResult = evaluateBranchIntegration(candidate, execGit)
+    if (evalResult.decision === BRANCH_PRUNE_DECISION.PENDING_WORK) {
       writeln(`Warning: branch "${shortName}" appears to have unmerged changes vs origin/main.`)
     }
   }
@@ -273,10 +302,17 @@ function allDocOnly(files) {
  */
 const COMMIT_MESSAGE_SEP = '\x1e'
 
+// GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX is the fixed prefix `git symbolic-ref
+// refs/remotes/origin/HEAD` always returns before the branch name, because "origin" is the
+// literal ref namespace queried — never derived from the output itself. Stripping this exact
+// prefix (instead of cutting at the last '/') is what makes defaultBaseBranch correct for a
+// default branch that itself contains a slash (e.g. "release/7.2"): lastIndexOf('/') used to
+// cut at "7.2", discarding "release/". Mirrors Go's ship.go gitSymbolicRefOriginHeadPrefix.
+const GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX = 'refs/remotes/origin/'
+
 /**
  * defaultBaseBranch resolves the repository's default branch for `git log <base>..HEAD`.
- * Tries `git symbolic-ref refs/remotes/origin/HEAD` (format "refs/remotes/origin/main" —
- * only the name after the last slash is kept) and falls back to "main" when that fails or
+ * Tries `git symbolic-ref refs/remotes/origin/HEAD` and falls back to "main" when that fails or
  * yields nothing.
  * @param {function} execGit
  * @returns {string}
@@ -285,9 +321,9 @@ function defaultBaseBranch(execGit) {
   const { stdout, error } = execGit(['symbolic-ref', 'refs/remotes/origin/HEAD'])
   if (error) return 'main'
   const out = (stdout || '').trim()
-  const idx = out.lastIndexOf('/')
-  if (idx < 0 || idx + 1 >= out.length) return 'main'
-  return out.slice(idx + 1)
+  if (!out.startsWith(GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX)) return 'main'
+  const name = out.slice(GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX.length)
+  return name === '' ? 'main' : name
 }
 
 /**
@@ -396,6 +432,15 @@ function runShip(opts, deps = {}) {
   const execGit = deps.execGit || defaultExecGit
   const checkGovernanceFn = deps.checkGovernance || defaultCheckGovernance
   const writeln = deps.writeln || ((s) => process.stdout.write(s + '\n'))
+  // writeErr — the terminal error line for every abort path below, written to STDERR with the
+  // "Error: " prefix. Mirrors Go exactly: ship.go returns these same messages as a bare
+  // fmt.Errorf(...), and internal/commands/root.go's Execute() wrapper prints them to stderr as
+  // `fmt.Fprintln(os.Stderr, cmd.ErrPrefix(), err.Error())` — cmd.ErrPrefix() is "Error:", and
+  // Fprintln inserts exactly one space between operands, so the wire format is
+  // "Error: <message>\n". Every multi-line detail printed BEFORE the abort (violation lists,
+  // remediation hints, "Note: ..." blocks) stays on stdout via writeln, same as Go's deps.out —
+  // only this final one-line (or one-block) summary moves to stderr.
+  const writeErr = deps.writeErr || ((s) => process.stderr.write(`Error: ${s}\n`))
 
   // Inner git wrapper: skips write commands in dry-run mode.
   function git(args) {
@@ -416,20 +461,20 @@ function runShip(opts, deps = {}) {
   // ─── Step 1: Branch validation ─────────────────────────────────────────────
   const branchResult = execGit(['symbolic-ref', '--short', 'HEAD'])
   if (branchResult.error) {
-    writeln(`error: could not determine current branch (are you in a git repo?): ${branchResult.error.message}`)
+    writeErr(`could not determine current branch (are you in a git repo?): ${branchResult.error.message}`)
     return 1
   }
   const branch = branchResult.stdout.trim()
 
   // main/master is blocked unconditionally — the doc-only exception never applies here.
   if (branch === 'main' || branch === 'master') {
-    writeln(`error: trackfw ship cannot run on "${branch}" — use a feature branch:\n  git checkout -b feat/<slug>`)
+    writeErr(`trackfw ship cannot run on "${branch}" — use a feature branch:\n  git checkout -b feat/<slug>`)
     return 1
   }
 
   if (!docOnly && !isShipBranch(branch)) {
-    writeln(
-      `error: branch "${branch}" does not match the required pattern feat|fix|refactor|chore|docs/<slug>\n` +
+    writeErr(
+      `branch "${branch}" does not match the required pattern feat|fix|refactor|chore|docs/<slug>\n` +
       'Rename your branch or create a new one:\n  git checkout -b feat/<slug>'
     )
     return 1
@@ -461,13 +506,66 @@ function runShip(opts, deps = {}) {
       writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")
       writeln("passes but 'trackfw ship' aborts here, you likely have lenient mode")
       writeln("configured — ship always requires REQ + roadmap in wip/.")
-      writeln(`\nerror: governance check failed: ${violations.length} violation(s)`)
+      writeErr(`governance check failed: ${violations.length} violation(s)`)
       return 1
     }
 
     writeln('Governance: OK')
   }
 
+  // ─── Step 2.5: force-with-lease gate ───────────────────────────────────────
+  // Runs before any write (commit/push) — a refusal here must never leave a local
+  // commit the caller cannot push. Read-only, so it runs in --dry-run too, same
+  // posture as the read-only calls in Step 0 / Step 7.
+  //
+  // forceLeaseAdapter/forceLeaseResolution are reused by Step 7 below to avoid a
+  // second forge resolution and a duplicate "Forge: ..." line, and because Step 7
+  // must skip PR/MR creation entirely once this gate has confirmed one is already
+  // open — creating a second one would be a spurious failure on every successful
+  // force push.
+  let forceLeaseAdapter = null
+  let forceLeaseResolution = null
+  if (opts.forceWithLease) {
+    const { stdout: gateRemoteURLRaw } = execGit(['remote', 'get-url', 'origin'])
+    const gateRemoteURL = (gateRemoteURLRaw || '').trim()
+
+    let resolution
+    try {
+      resolution = forgeResolve({
+        flagForge: opts.forge || '',
+        configForge: deps.configForge || '',
+        remoteURL: gateRemoteURL,
+        repoDir: deps.repoDir || '',
+      })
+    } catch (resErr) {
+      writeErr(resErr.message)
+      return 1
+    }
+
+    const adapter = forgeAdapter(resolution.forge, deps.availFn || undefined)
+    if (resolution.forge === 'manual' || !adapter.available) {
+      writeErr(FORCE_LEASE_NO_FORGE_CLI_MSG)
+      return 1
+    }
+
+    const checkPROpen = deps.checkPROpen || defaultCheckPROpen
+    let open
+    try {
+      open = checkPROpen(adapter, branch)
+    } catch (prErr) {
+      writeErr(forceLeaseCannotVerifyMsg(branch, adapter.cliName, prErr.message))
+      return 1
+    }
+    if (!open) {
+      writeErr(forceLeaseNoPROpenMsg(branch))
+      return 1
+    }
+
+    writeln(`force-with-lease: open ${adapter.noun} confirmed for "${branch}" (${resolution.forge}).`)
+    forceLeaseAdapter = adapter
+    forceLeaseResolution = resolution
+  }
+
   // ─── Step 3: Squash-merge detection ────────────────────────────────────────
   if (opts.dryRun) {
     writeln('[dry-run] git fetch origin --prune')
@@ -490,9 +588,16 @@ function runShip(opts, deps = {}) {
   writeln('────────────────────────────────────────────────────────\n')
 
   // Reuses stagedFiles read at the top of the function (Step 0) — never re-query git here.
-  if (stagedFiles.length === 0) {
-    writeln(
-      'error: nothing is staged — stage your files explicitly before running ship:\n' +
+  //
+  // --force-with-lease push-only mode: a rebase that resolved conflicts already
+  // committed the result (the index is clean afterwards) — there is nothing left to
+  // stage or commit, only to push. Only --force-with-lease grants this exception;
+  // without it, "nothing staged" still aborts exactly as before (non-regression).
+  const pushOnly = opts.forceWithLease && stagedFiles.length === 0
+
+  if (stagedFiles.length === 0 && !opts.forceWithLease) {
+    writeErr(
+      'nothing is staged — stage your files explicitly before running ship:\n' +
       '  git add <file1> <file2> ...\n' +
       "Never use 'git add .' or 'git add -A'"
     )
@@ -500,29 +605,38 @@ function runShip(opts, deps = {}) {
   }
 
   // ─── Step 5: Commit ────────────────────────────────────────────────────────
-  if (!opts.message) {
-    writeln(
-      'error: commit message is required — use -m:\n' +
-      '  trackfw ship -m "feat(<scope>): <description>"'
-    )
-    return 1
-  }
+  if (pushOnly) {
+    writeln('Nothing staged — --force-with-lease pushes existing commits only, no new commit.')
+  } else {
+    if (!opts.message) {
+      writeErr(
+        'commit message is required — use -m:\n' +
+        '  trackfw ship -m "feat(<scope>): <description>"'
+      )
+      return 1
+    }
 
-  const { error: commitErr } = git(['commit', '-m', opts.message])
-  if (commitErr) {
-    writeln(`error: git commit failed: ${commitErr.message}`)
-    return 1
-  }
+    const { error: commitErr } = git(['commit', '-m', opts.message])
+    if (commitErr) {
+      writeErr(`git commit failed: ${commitErr.message}`)
+      return 1
+    }
 
-  if (!opts.dryRun) {
-    writeln(`Committed: ${opts.message}`)
+    if (!opts.dryRun) {
+      writeln(`Committed: ${opts.message}`)
+    }
   }
 
   // ─── Step 6: Push ──────────────────────────────────────────────────────────
-  const pushArgs = buildPushArgs(branch, execGit)
+  let pushArgs = buildPushArgs(branch, execGit)
+  if (opts.forceWithLease) {
+    // Fixed position: push --force-with-lease [-u] origin <branch> — identical
+    // across the 3 CLIs (ML-1B's parity gate compares this literally).
+    pushArgs = [pushArgs[0], '--force-with-lease', ...pushArgs.slice(1)]
+  }
   const { error: pushErr } = git(pushArgs)
   if (pushErr) {
-    writeln(`error: git push failed: ${pushErr.message}`)
+    writeErr(`git push failed: ${pushErr.message}`)
     return 1
   }
 
@@ -531,6 +645,17 @@ function runShip(opts, deps = {}) {
   }
 
   // ─── Step 7: Open PR/MR ────────────────────────────────────────────────────
+  // --force-with-lease only ever reaches here after Step 2.5 confirmed a PR/MR is
+  // already open on this branch — creating another one would be a spurious failure
+  // on every successful force push. Reuses the adapter/resolution Step 2.5 already
+  // computed instead of resolving the forge a second time.
+  if (opts.forceWithLease) {
+    writeln(`Forge:     ${forceLeaseResolution.forge} (source: ${forceLeaseResolution.source})`)
+    writeln(`${forceLeaseAdapter.noun} already open — skipping creation (--force-with-lease).`)
+    writeln('\nship complete.')
+    return 0
+  }
+
   const { stdout: remoteURLRaw } = execGit(['remote', 'get-url', 'origin'])
   const remoteURL = (remoteURLRaw || '').trim()
 
@@ -638,4 +763,12 @@ module.exports = {
   gitCommitsSince,
   buildPRBody,
   COMMIT_MESSAGE_SEP,
+  detectPendingSquashMerges,
+  defaultCheckPROpen,
+  FORCE_LEASE_NO_FORGE_CLI_MSG,
+  forceLeaseNoPROpenMsg,
+  forceLeaseCannotVerifyMsg,
+  // Exported for reuse by push/runner.js (AC2 of REQ-2026-08-22-trackfw-push).
+  buildPushArgs,
+  defaultExecGit,
 }