rcf-lite 0.28.4 → 0.30.0

package/src/cli/build.js

@@ -18,6 +18,10 @@
 
 import { writeFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 
 import { formatErrors, isRcfError, rcfError, writeUnexpectedFailure } from '#core/errors';
 import { updateDocument, walkTree } from '#core/store';
@@ -41,6 +45,14 @@ import { firstBaselineDisagreement } from '../design/index.js';
 import { writeBrowserVerificationAck } from '../browser-verify/index.js';
 // Track C+D §5.4 Stage-1 refusal gate.
 import { fbsRefusalForOpenSweep } from '../req-baseline/gate.js';
+// 0.30.0 PR 8 (REQ-177 / TAC-4125): bundle --next freeze gate.
+import { computeDelta } from '../query/delta.js';
+import { computeImpact } from '../query/impact.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import {
+  applyOverrideToFreezeRecord,
+  loadFreezeRecord,
+} from '../define/freeze-record.js';
 
 const OPTION_SPEC = {
   next: { type: 'boolean' },
@@ -60,6 +72,12 @@ const OPTION_SPEC = {
   // browserVerification record.
   'accept-block': { type: 'boolean' },
   reason: { type: 'string' },
+  // 0.30.0 PR 8 (REQ-177, AC-17702-2 / AC-17702-4). Bundle --next with
+  // --override "<reason>" writes freeze.override { reason, by, at } and
+  // proceeds; without --override the verb refuses on an unfrozen tree
+  // (AC-17702-1) and when every actionable FBS is impacted by the
+  // delta (AC-17702-4).
+  override: { type: 'string' },
 };
 
 export const HELP = `Usage: rcf build <verb> [options]
@@ -96,6 +114,11 @@ Options (bundle):
   --strict                  Refuse (exit 4) a bundle for a blocked item;
                             no effect with --next (it never selects
                             blocked items)
+  --override "<reason>"     With --next: proceed on an unfrozen tree or
+                            an all-impacted delta, recording
+                            freeze.override { reason, by, at } (REQ-177,
+                            0.30.0 PR 8). The reason must be a
+                            non-empty string.
 
 Options (queue):
   --format <format>         md (default) | json
@@ -292,7 +315,10 @@ export async function main(argv, deps = {}) {
     return 0;
   }
   if (mode === 'next') {
-    return await emitNext({ tree, format, io });
+    return await emitNext({
+      tree, projectRoot, format, io,
+      overrideReason: typeof flags.override === 'string' ? flags.override : null,
+    });
   }
   return await emitBundle({
     tree, fbsId: positional, format, strict: Boolean(flags.strict), io,
@@ -356,9 +382,186 @@ async function emitBundle({ tree, fbsId, format, strict, io }) {
   return await emitToSink(output, io);
 }
 
-async function emitNext({ tree, format, io }) {
+/**
+ * 0.30.0 PR 9 (TAC-4125; AC-17702-6): resolve the author identity for
+ * `freeze.override.by`. Preference order (first non-empty wins):
+ *
+ *   1. `git config user.email` under `projectRoot` (the identity git
+ *      itself would attribute an override commit to; CI usually sets
+ *      this through its own git config step).
+ *   2. `GITHUB_ACTOR` (set by GitHub Actions on every run so a CI
+ *      override is attributed to the actor who triggered the workflow,
+ *      even when no git identity is configured).
+ *   3. `USER` or `USERNAME` (local shell identity on Unix / Windows).
+ *   4. The literal string `operator` (never-null fallback so the write
+ *      path cannot blow up on a stripped-down container).
+ *
+ * Pure of side effects beyond the one `git config` read; the git call
+ * is bounded to a short argv and never writes. Errors from `git
+ * config` (no `.git`, no git binary, missing key) fall through to the
+ * next arm silently; the resolution's shape is a single string.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<string>}
+ */
+export async function resolveOverrideBy({ projectRoot }) {
+  // 1. git config user.email (bounded; refuses to log on failure).
+  try {
+    const { stdout } = await execFileAsync(
+      'git', ['config', '--get', 'user.email'],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 2000 },
+    );
+    const email = stdout.trim();
+    if (email.length > 0) return email;
+  } catch {
+    // Fall through to the environment arms.
+  }
+  // Env arms are trimmed so a whitespace-only value does not win
+  // over the next arm (codex review 2026-10-03, P2).
+  const envArm = (key) => {
+    const v = process.env[key];
+    if (typeof v !== 'string') return null;
+    const t = v.trim();
+    return t.length > 0 ? t : null;
+  };
+  // 2. GITHUB_ACTOR (GitHub Actions).
+  const actor = envArm('GITHUB_ACTOR');
+  if (actor) return actor;
+  // 3. USER or USERNAME.
+  const user = envArm('USER');
+  if (user) return user;
+  const username = envArm('USERNAME');
+  if (username) return username;
+  // 4. Never-null fallback.
+  return 'operator';
+}
+
+/**
+ * 0.30.0 PR 8 (REQ-177, TAC-4125): freeze gate for `bundle --next`.
+ * Loads the freeze record and the computed delta, writes
+ * freeze.override when --override "<reason>" is given, computes the
+ * set of re-execute FBS impacted by the delta, and returns a refusal
+ * when the tree is unfrozen and no override is given.
+ *
+ * Pure of CLI I/O: it writes freeze.override through the freeze-record
+ * module (which is the normal write path) but prints no output; the
+ * caller surfaces the refusal and the override line.
+ *
+ * @param {object} args
+ * @param {object} args.tree - walker tree.
+ * @param {string} args.projectRoot
+ * @param {string|null} args.overrideReason - the --override flag value, or null when absent.
+ * @returns {Promise<{ ok: true, impactedFbsIds: Set<string>, override: {reason:string, by:string, at:string}|null } | { ok: false, exitCode: 2|4, message: string }>}
+ */
+async function enforceBundleNextFreezeGate({ tree, projectRoot, overrideReason }) {
+  if (overrideReason !== null && (typeof overrideReason !== 'string' || overrideReason.length === 0)) {
+    return {
+      ok: false,
+      exitCode: 2,
+      message: 'build bundle --next: --override requires a non-empty reason (e.g. --override "hotfix")',
+    };
+  }
+  const [freeze, ledgers] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+  ]);
+  const delta = computeDelta(tree, freeze, ledgers);
+  if (!delta.frozen && overrideReason === null) {
+    return {
+      ok: false,
+      exitCode: 4,
+      message:
+        'build bundle --next: refused on an unfrozen tree. Run `rcf define readiness` and close the change with `rcf define freeze`, '
+        + 'or re-run with --override "<reason>" to record `freeze.override { reason, by, at }` and proceed (NV-DL-ADM-01).',
+    };
+  }
+  let appliedOverride = null;
+  if (overrideReason !== null) {
+    const at = new Date().toISOString();
+    const by = await resolveOverrideBy({ projectRoot });
+    const { record } = await applyOverrideToFreezeRecord({
+      projectRoot,
+      reason: overrideReason,
+      by,
+      at,
+      docHashes: delta.currentDocHashes ?? {},
+      treeHash: delta.currentTreeHash,
+      briefStatements: ledgers?.brief?.statements?.length ?? 0,
+    });
+    appliedOverride = record.override;
+  }
+  // Compute impacted FBS set when the tree is frozen (unfrozen trees
+  // have no base to compare against; AC-17702-5 governs that path).
+  // "Impacted" means an FBS that must be re-executed because its own
+  // definition changed OR because it fans out from a changed/added
+  // pivot (REQ, US, AC, TAC, ADR) via expandFbsDependents.
+  const impactedFbsIds = new Set();
+  if (delta.frozen) {
+    const pivotIds = [
+      ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+      ...delta.added.filter((id) => !id.startsWith('ledger:')),
+    ];
+    // A changed/added FBS is itself impacted.
+    for (const id of pivotIds) {
+      if (typeof id === 'string' && id.startsWith('FBS-')) impactedFbsIds.add(id);
+    }
+    const seen = new Set();
+    for (const id of pivotIds) {
+      const impact = computeImpact(tree, { id });
+      if (!impact.found || !Array.isArray(impact.nodes)) continue;
+      for (const node of impact.nodes) {
+        if (seen.has(node.id)) continue;
+        seen.add(node.id);
+        if (node.kind === 'fbs' && node.role !== 'pivot' && node.actionNeeded === 're-execute') {
+          impactedFbsIds.add(node.id);
+        }
+      }
+    }
+  }
+  return { ok: true, impactedFbsIds, override: appliedOverride };
+}
+
+async function emitNext({ tree, projectRoot, format, io, overrideReason = null }) {
+  // 0.30.0 PR 8 (REQ-177 / TAC-4125): refuse without a freeze record,
+  // write freeze.override on --override "<reason>" and proceed, skip
+  // impacted FBS from the next-item selection.
+  const gate = await enforceBundleNextFreezeGate({
+    tree, projectRoot, overrideReason,
+  });
+  if (!gate.ok) {
+    io.stderr.write(`[error] ${gate.message}\n`);
+    return gate.exitCode;
+  }
+  if (gate.override) {
+    const o = gate.override;
+    io.stderr.write(`[info] build bundle --next: freeze.override recorded (reason=${JSON.stringify(o.reason)}, by=${o.by}, at=${o.at}).\n`);
+  }
+  // Skip FBS impacted by a non-empty delta; the next-item compute
+  // walks the queue from the top and the first unimpacted actionable
+  // FBS wins. Every skipped FBS is named on stderr with the reason.
   const queue = computeQueue(tree);
-  const next = selectNext(queue);
+  let next = null;
+  if (gate.impactedFbsIds.size === 0) {
+    next = selectNext(queue);
+  } else {
+    for (const item of queue.items) {
+      if (item.state !== 'actionable') continue;
+      if (gate.impactedFbsIds.has(item.fbsId)) {
+        io.stderr.write(`[info] build bundle --next: skipping ${item.fbsId} (impacted by the delta; re-freeze or re-execute first).\n`);
+        continue;
+      }
+      next = { fbsId: item.fbsId };
+      break;
+    }
+  }
+  if (!next && gate.impactedFbsIds.size > 0 && overrideReason === null) {
+    io.stderr.write(
+      '[error] build bundle --next: refused because every actionable FBS is impacted by the delta. '
+      + 'Re-run with --override "<reason>" to record `freeze.override { reason, by, at }` and proceed (NV-DL-ADM-05).\n',
+    );
+    return 4;
+  }
   if (next) {
     // Track C+D §5.4: Stage-1 (Define) refuses to enter Build for any
     // FBS binding an AC on a US that still has open baseline sweep