@hone-ai/cli 1.39.0 → 1.41.0

package/lib/required-checks.js

@@ -0,0 +1,354 @@
+'use strict';
+/**
+ * HC-GF-348 — the status checks `hone setup` requires are READ from the repository's own workflows.
+ *
+ * Setup used to require `ai-code-review` on every repository. No workflow Hone serves reports a check
+ * by that name (the served reviewer job is `ai-review`, with no `name:`), and since HC-GF-337g that job
+ * runs only on `--ai-reviewer`. A required check that never reports leaves every PR waiting, and
+ * `enforce_admins: true` stops admins merging around it. So the name is now taken from the installed
+ * workflow, and required only when that workflow will run the job.
+ *
+ * GitHub names an Actions check after the job: its job-level `name:` if it has one, else its key.
+ * The parser below reads exactly that and nothing else. Two near-misses it must reject:
+ *   - the workflow's top-level `name:` (column 0) — that names the workflow, not a check;
+ *   - a step's `- name:` (deeper, behind a dash) — that names a step.
+ * A `name:` built from an expression (`${{ matrix.x }}`) is returned as written. GitHub reports the
+ * evaluated value, and a job with a `strategy:` reports one check per matrix leg (`ai-review (x)`),
+ * never its bare name. Neither can be REQUIRED (it would never report — the failure this module
+ * exists to prevent), so requiredChecksForSetup requires nothing for such a reviewer job. For the
+ * prune they are harmless: such a name never equals the legacy one.
+ *
+ * No YAML library: the CLI bundles none, and reviewer-optin.js reads this same file with a regex.
+ *
+ * Exports
+ *   workflowCheckNames(text)        → string[]  the check names a workflow's jobs report
+ *   reviewerCheckName(text)         → string|null  the name the `ai-review` job reports
+ *   requiredChecksForSetup({...})   → string[]  what setup requires: the reviewer check only when it runs
+ *   reportedChecksInDir(dir)        → string[]|null  every name reported under dir; null = could not tell
+ */
+
+const REVIEWER_JOB_KEY = 'ai-review';
+const SECURITY_SCAN_JOB_KEY = 'security-scan';
+
+function unquote(v) {
+  let s = String(v).replace(/\s+#.*$/, '').trim();
+  if (s.length >= 2 && ((s[0] === '"' && s.endsWith('"')) || (s[0] === "'" && s.endsWith("'")))) {
+    s = s.slice(1, -1);
+  }
+  return s;
+}
+
+/** [{ key, name, matrix }] for each job in the workflow's top-level `jobs:` block; name is null without one. */
+function workflowJobs(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^jobs:\s*(#.*)?$/.test(l));
+  if (start < 0) return [];
+  const jobs = [];
+  let jobIndent = null;   // the column job keys sit at
+  let propIndent = null;  // the column the current job's own properties sit at
+  let current = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent === 0) break;                       // the next top-level key ends `jobs:`
+    if (jobIndent == null) jobIndent = indent;
+    if (indent <= jobIndent) {
+      const m = /^ *([A-Za-z0-9_-]+):\s*(#.*)?$/.exec(line);
+      current = m && indent === jobIndent ? { key: m[1], name: null, matrix: false, reusable: false } : null;
+      if (current) jobs.push(current);
+      propIndent = null;
+      continue;
+    }
+    if (!current) continue;
+    if (propIndent == null) propIndent = indent;
+    // Only the job's own properties count; anything deeper (steps, with:, env:) is not its name.
+    if (indent !== propIndent) continue;
+    if (/^ *strategy:/.test(line)) current.matrix = true;
+    // A job that calls a reusable workflow reports as `caller / callee`, never its own name.
+    if (/^ *uses:/.test(line)) current.reusable = true;
+    const n = current.name == null && /^ *name:\s*(.+)$/.exec(line);
+    if (n) current.name = unquote(n[1]) || null;
+  }
+  return jobs;
+}
+
+function workflowCheckNames(text) {
+  return workflowJobs(text).map((j) => j.name || j.key);
+}
+
+function reviewerCheckName(text) {
+  const job = workflowJobs(text).find((j) => j.key === REVIEWER_JOB_KEY);
+  return job ? (job.name || job.key) : null;
+}
+
+// ── on: — does a workflow run on pull requests to a branch? (HC-GF-354) ────────────────────────────
+
+const PR_EVENTS = new Set(['pull_request', 'pull_request_target']);
+
+/** `[a, b]` or a bare scalar → list of unquoted items; null when it is neither (an anchor, a placeholder). */
+function flowList(v) {
+  const t = String(v).replace(/\s+#.*$/, '').trim();
+  if (!t) return null;
+  if (t.startsWith('[')) {
+    if (!t.endsWith(']')) return null;
+    const inner = t.slice(1, -1).trim();
+    return inner ? inner.split(',').map((x) => unquote(x)).filter(Boolean) : [];
+  }
+  if (/^[&*{|>]/.test(t)) return null;
+  return [unquote(t)];
+}
+
+/**
+ * The pull-request triggers of a workflow: [{ event, branches, branchesIgnore, types, unreadable }], each
+ * filter null when absent and 'unreadable' when present but not a list this parser can read
+ * (`{{BRANCHES}}` before setup substitutes it, an anchor, a nested mapping). `unreadable: true` marks a
+ * trigger with anything else that can skip a PR (`paths`, `paths-ignore`, an inline mapping). Reads
+ * `on: x`, `on: [x, y]` and the block form.
+ */
+function workflowPullRequestTriggers(text) {
+  if (typeof text !== 'string' || !text) return [];
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^["']?on["']?:/.test(l));
+  if (start < 0) return [];
+  const inline = lines[start].replace(/^["']?on["']?:/, '').replace(/\s+#.*$/, '').trim();
+  if (inline) {
+    const events = flowList(inline) || [];
+    return events.filter((e) => PR_EVENTS.has(e)).map((event) => ({ event, branches: null, branchesIgnore: null, types: null, unreadable: false }));
+  }
+  const out = [];
+  let eventIndent = null;
+  let current = null;   // the PR trigger being read
+  let pending = null;   // { key, indent } of a `branches:` whose list is on the lines below
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent === 0) break;
+    if (eventIndent == null) eventIndent = indent;
+    if (pending && indent >= pending.indent && /^ *- /.test(line)) {
+      const item = unquote(line.replace(/^ *- /, ''));
+      if (current[pending.key] === 'unreadable') continue;
+      if (!item || /^[&*{]/.test(item)) current[pending.key] = 'unreadable';
+      else current[pending.key].push(item);
+      continue;
+    }
+    if (pending && current[pending.key] && current[pending.key].length === 0) current[pending.key] = 'unreadable';
+    pending = null;
+    if (indent === eventIndent) {
+      const m = /^ *([A-Za-z_]+):\s*(.*)$/.exec(line);
+      current = m && PR_EVENTS.has(m[1]) ? { event: m[1], branches: null, branchesIgnore: null, types: null, unreadable: false } : null;
+      if (current) {
+        // `pull_request: { branches: [x] }`, an alias, any inline value: a filter not read here.
+        const v = m[2].replace(/\s+#.*$/, '').trim();
+        if (v && v !== 'null' && v !== '~') current.unreadable = true;
+        out.push(current);
+      }
+      continue;
+    }
+    if (!current) continue;
+    // A path filter skips some pull requests to the branch, so a check from it is not sure to report.
+    if (/^ *(paths|paths-ignore):/.test(line)) { current.unreadable = true; continue; }
+    const f = /^ *(branches|branches-ignore|types):\s*(.*)$/.exec(line);
+    if (!f) continue;
+    const key = { branches: 'branches', 'branches-ignore': 'branchesIgnore', types: 'types' }[f[1]];
+    const rest = f[2].replace(/\s+#.*$/, '').trim();
+    if (!rest) { current[key] = []; pending = { key, indent }; continue; }
+    current[key] = flowList(rest) || 'unreadable';
+  }
+  if (pending && current && current[pending.key] && current[pending.key].length === 0) current[pending.key] = 'unreadable';
+  return out;
+}
+
+/** GitHub's branch glob, as far as it is read here: `**` anything, `*` anything but `/`. 'unreadable' otherwise. */
+function branchMatchesPattern(pattern, branch) {
+  if (typeof pattern !== 'string' || !pattern || /[!?[\]+]/.test(pattern) || pattern.startsWith('/') || pattern.includes('{{')) {
+    return 'unreadable';
+  }
+  const re = pattern.replace(/[.^$()|\\{}]/g, '\\$&').replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*');
+  return new RegExp(`^${re}$`).test(branch);
+}
+
+function filterMatches(patterns, branch) {
+  const r = patterns.map((p) => branchMatchesPattern(p, branch));
+  if (r.includes('unreadable')) return 'unreadable';
+  return r.includes(true);
+}
+
+/**
+ * True only when the workflow is SURE to run on a pull request to `branch`. Anything it cannot read
+ * answers false: requiring nothing is safe, requiring a check that never reports holds every PR.
+ */
+function workflowTriggersPullRequestTo(text, branch) {
+  if (typeof branch !== 'string' || !branch) return false;
+  return workflowPullRequestTriggers(text).some((t) => {
+    if (t.unreadable || t.branches === 'unreadable' || t.branchesIgnore === 'unreadable' || t.types === 'unreadable') return false;
+    // Only a trigger that fires when a PR is opened AND when it is pushed to reports on every PR.
+    if (Array.isArray(t.types) && !(t.types.includes('opened') && t.types.includes('synchronize'))) return false;
+    if (t.branches && t.branchesIgnore) return false;   // GitHub rejects a workflow that sets both
+    if (t.branches) return filterMatches(t.branches, branch) === true;
+    if (t.branchesIgnore) return filterMatches(t.branchesIgnore, branch) === false;
+    return true;
+  });
+}
+
+// ── ci.required_checks in .pipeline-config.yml (HC-GF-352) ───────────────────────────────────────
+
+/** The names listed under `ci: required_checks:`, flow or block form; [] when absent. */
+function configuredRequiredChecks(configText) {
+  if (typeof configText !== 'string' || !configText) return [];
+  const lines = configText.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^ci:\s*(#.*)?$/.test(l));
+  if (start < 0) return [];
+  let keyIndent = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent === 0) break;
+    if (keyIndent == null) keyIndent = indent;
+    if (indent !== keyIndent) continue;
+    const m = /^ *required_checks:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const rest = m[1].replace(/\s+#.*$/, '').trim();
+    if (rest) return flowList(rest) || [];
+    const items = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (!l.trim() || /^\s*#/.test(l)) continue;
+      if (!/^ *- /.test(l) || l.match(/^ */)[0].length < keyIndent) break;
+      const v = unquote(l.replace(/^ *- /, ''));
+      if (v) items.push(v);
+    }
+    return items;
+  }
+  return [];
+}
+
+// ── what setup requires ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * [{ key, name }] for the jobs that report under ONE fixed name. Not a matrix job (one check per leg,
+ * `test (18)`), not a reusable-workflow call (`caller / callee`), not a name built from an expression.
+ * Requiring nothing is always safe; requiring a name that never reports holds every PR.
+ */
+function fixedJobs(text) {
+  return workflowJobs(text)
+    .filter((j) => !j.matrix && !j.reusable && !(j.name || j.key).includes('${{'))
+    .map((j) => ({ key: j.key, name: j.name || j.key }));
+}
+
+/** The fixed check name a served job reports, or null. */
+function fixedJobCheck(text, key) {
+  const job = fixedJobs(text).find((j) => j.key === key);
+  return job ? job.name : null;
+}
+
+/**
+ * What `hone setup` requires on the protected branch, and every candidate it left out with the reason.
+ *
+ * Candidates: the served reviewer check (only when the installed workflow runs that job — HC-GF-348),
+ * the served `security-scan` check (always — HC-GF-354), and the names in `ci.required_checks`
+ * (HC-GF-352). Each is required only if a workflow reports it under a fixed name and is sure to run on
+ * pull requests to `branch`. `branch` null (not known yet): no trigger test, nothing dropped for it.
+ *
+ * @returns {{ required: string[], dropped: Array<{ name: string, reason: string }> }}
+ */
+function requiredChecksPlan({
+  reviewerState, reviewerWorkflowText, workflowsDir, configText, branch = null,
+  fsImpl = require('fs'), pathImpl = require('path'),
+} = {}) {
+  const required = [];
+  const dropped = [];
+  const notOnBranch = `its workflow does not run on pull requests to \`${branch}\``;
+  const served = (name) => {
+    if (!name || required.includes(name)) return;
+    if (branch != null && !workflowTriggersPullRequestTo(reviewerWorkflowText, branch)) dropped.push({ name, reason: notOnBranch });
+    else required.push(name);
+  };
+  if (reviewerState === 'on' || reviewerState === 'legacy') served(fixedJobCheck(reviewerWorkflowText, REVIEWER_JOB_KEY));
+  served(fixedJobCheck(reviewerWorkflowText, SECURITY_SCAN_JOB_KEY));
+
+  const configured = configuredRequiredChecks(configText)
+    .filter((n) => !required.includes(n) && !dropped.some((d) => d.name === n));
+  if (configured.length) {
+    const files = reportedChecksByFileInDir(workflowsDir, { fsImpl, pathImpl });
+    for (const name of configured) {
+      if (files == null) { dropped.push({ name, reason: "the repository's workflows could not all be read" }); continue; }
+      const reporting = files.filter((f) => f.names.includes(name));
+      if (!reporting.length) { dropped.push({ name, reason: 'not reported by any workflow' }); continue; }
+      const fixed = reporting.filter((f) => fixedJobs(f.text).some((j) => j.name === name));
+      if (!fixed.length) {
+        dropped.push({ name, reason: 'its job reports per matrix leg or as a reusable-workflow call, never under this name' });
+        continue;
+      }
+      if (branch != null && !fixed.some((f) => workflowTriggersPullRequestTo(f.text, branch))) {
+        dropped.push({ name, reason: notOnBranch });
+        continue;
+      }
+      required.push(name);
+    }
+  }
+  return { required, dropped };
+}
+
+/**
+ * @param {{ reviewerState: 'on'|'off'|'legacy'|'absent', reviewerWorkflowText: string|null }} args
+ *   reviewerState is workflowReviewerState() (cli/lib/reviewer-optin.js) of the installed ai-review.yml.
+ */
+function requiredChecksForSetup(args = {}) {
+  return requiredChecksPlan(args).required;
+}
+
+/**
+ * [{ file, text, names }] for each workflow in `dir`. `[]` when there is no such directory. `null` when a
+ * workflow file exists but could not be read.
+ */
+function reportedChecksByFileInDir(dir, { fsImpl = require('fs'), pathImpl = require('path') } = {}) {
+  if (typeof dir !== 'string' || !dir) return [];
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(dir);
+  } catch (e) {
+    return e && (e.code === 'ENOENT' || e.code === 'ENOTDIR') ? [] : null;
+  }
+  const out = [];
+  for (const f of entries) {
+    if (!/\.ya?ml$/i.test(f)) continue;
+    let text;
+    try {
+      text = fsImpl.readFileSync(pathImpl.join(dir, f), 'utf8');
+    } catch {
+      return null;
+    }
+    out.push({ file: f, text, names: workflowCheckNames(text) });
+  }
+  return out;
+}
+
+/**
+ * Every check name the workflows in `dir` report. `[]` when there is no such directory (nothing reports
+ * anything). `null` when a workflow file exists but could not be read: the caller cannot tell what is
+ * reported, so it must not remove a required check on the strength of this answer.
+ */
+function reportedChecksInDir(dir, opts = {}) {
+  const files = reportedChecksByFileInDir(dir, opts);
+  if (files == null) return null;
+  return [...new Set(files.flatMap((f) => f.names))];
+}
+
+module.exports = {
+  workflowCheckNames,
+  reviewerCheckName,
+  requiredChecksForSetup,
+  requiredChecksPlan,
+  reportedChecksInDir,
+  reportedChecksByFileInDir,
+  workflowPullRequestTriggers,
+  workflowTriggersPullRequestTo,
+  branchMatchesPattern,
+  configuredRequiredChecks,
+  REVIEWER_JOB_KEY,
+  SECURITY_SCAN_JOB_KEY,
+};

package/lib/review-diff.js

@@ -0,0 +1,188 @@
+'use strict';
+/**
+ * review-diff.js — HC-GF-390: the base diff a reviewer needs beside a whole emitted file.
+ *
+ * In editor mode step_4's artifact carries every changed file whole (tree-artifact.js), while the
+ * reviewers (step_5, 5d, 5e) see the ORIGINAL only through the bundle, which windows a file longer
+ * than BUNDLE_MAX_PER_FILE_CHARS. A change outside those windows was compared with nothing. This
+ * computes, for step_4 only, `git diff HEAD` of each file the render emitted whole whose HEAD version
+ * is over that cap. It is sent beside the artifact as `reviewDiff` and stored apart from it: the
+ * artifact itself is never touched.
+ *
+ * It never fails a submit. Every git call has a timeout; anything it cannot do becomes a one-line
+ * note, and a note means "unverified", exactly as an absent diff did before.
+ *
+ * Exit modes of what it consumes (HC-GF-117):
+ *   rendered.files            HANDLED: the only candidates. A created, deleted, renamed, binary-at-render
+ *                             or over-1 MB file is never in it, so it is never diffed.
+ *   git rev-parse fails       HANDLED: no HEAD → null, nothing sent.
+ *   git diff --name-status    HANDLED: a throw → one note, nothing diffed.
+ *   per-file git calls        HANDLED: a throw (timeout, ENOBUFS, spawn, non-zero) → a note, next file.
+ *   "Binary files … differ"   HANDLED: a note (a text file .gitattributes marks binary).
+ *   empty diff                HANDLED: a note (the file no longer differs from HEAD).
+ *   post-image ≠ rendered     HANDLED: a note. The diff must describe the bytes the reviewer was sent.
+ */
+
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { gitEnv } = require('./git-env');
+const { BUNDLE_MAX_PER_FILE_CHARS } = require('./bundle-limits');
+const { isSecretPath } = require('./bundle-context');
+const { FILE_BLOCK_RE } = require('./block-grammar');
+
+const REVIEW_DIFF_MAX_CHARS = 60_000;      // diff text, summed over the files included
+const PER_CALL_MS = 15_000;
+const DEADLINE_MS = 60_000;                // every per-file call gets min(PER_CALL_MS, what is left)
+const MAX_NOTES = 100;
+const MAX_NOTE_CHARS = 300;
+// Kept equal to server/src/services/review-diff.js REVIEW_DIFF_MAX_BYTES (pinned by the HC-GF-390 tests).
+const REVIEW_DIFF_MAX_BYTES = 256 * 1024;
+
+const SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+
+/** The bundle windows a file whose text is longer than the cap (bundle-paths.js `text.length <= limit` is whole). */
+const overCap = (length) => length > BUNDLE_MAX_PER_FILE_CHARS;
+
+/**
+ * The pinned diff. Every option a user's git config could change is given on the command line, as a
+ * flag the `diff` subcommand takes (not a leading `-c`, so a caller can still recognise the call).
+ */
+function diffArgs(headSha, rel) {
+  return ['diff', '--no-color', '--no-ext-diff', '--no-textconv', '--no-renames', '--full-index',
+    '--diff-algorithm=myers', '--no-relative', '--inter-hunk-context=0', '-U3',
+    '--src-prefix=a/', '--dst-prefix=b/', headSha, '--', rel];
+}
+
+function defaultRunGit(repoRoot) {
+  return (args, timeoutMs) => execFileSync('git', args, {
+    cwd: repoRoot, env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    timeout: Math.max(1, Math.floor(timeoutMs)), stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * The contents of the first `file:` block for `rel` in a rendered artifact, as the server's
+ * carry-forward `blocksOf` reads it (same grammar, same scope, same one-newline strip), or null.
+ */
+function blockContents(text, rel) {
+  const t = String(text || '');
+  const sec = t.search(/^##\s+Changed Files/im);
+  const scope = t.slice(sec === -1 ? 0 : sec);
+  for (const m of scope.matchAll(FILE_BLOCK_RE)) {
+    if (m[2].trim() === rel) return m[3].replace(/\r?\n$/, '');
+  }
+  return null;
+}
+
+/** git's object id of a blob holding `str` as UTF-8, computed in memory (never `hash-object -w`). */
+function gitBlobId(str, algo = 'sha1') {
+  const bytes = Buffer.from(String(str), 'utf8');
+  return crypto.createHash(algo).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+}
+
+/** One line, no control characters, at most `max` chars. */
+function oneLine(s, max) {
+  const flat = String(s == null ? '' : s).replace(/[\x00-\x1f\x7f]+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/**
+ * @param {object}   opts
+ * @param {string}   opts.repoRoot
+ * @param {{text: string, files: string[]}} opts.rendered  renderFromTree()'s result
+ * @param {(args: string[], timeoutMs: number) => string} [opts.runGit]
+ * @param {() => number} [opts.now]
+ * @param {(line: string) => void} [opts.warn]  why nothing is sent when that is not "no candidate"
+ * @returns {null | { headSha: string, diff: string, notes: string[], stats: object }}
+ *   null when there is nothing to send: no HEAD, no candidate, or a payload over its byte cap.
+ */
+function computeReviewDiff({ repoRoot, rendered, runGit, now = Date.now, warn = () => {} } = {}) {
+  try {
+    const git = runGit || defaultRunGit(repoRoot);
+    const emitted = new Set(rendered && Array.isArray(rendered.files) ? rendered.files : []);
+    if (!emitted.size) return null;
+
+    const deadline = now() + DEADLINE_MS;
+    let headSha;
+    try { headSha = String(git(['rev-parse', '--verify', 'HEAD^{commit}'], PER_CALL_MS)).trim(); } catch { return null; }
+    if (!SHA_RE.test(headSha)) return null;
+    const algo = headSha.length === 64 ? 'sha256' : 'sha1';
+
+    const notes = [];
+    const sections = [];
+    let used = 0;
+    const note = (rel, reason) => notes.push(oneLine(`${JSON.stringify(rel)}: ${reason}`, MAX_NOTE_CHARS));
+
+    let candidates = [];
+    try {
+      const tokens = String(git(['diff', '--name-status', '-z', '--no-renames', headSha], PER_CALL_MS)).split('\0');
+      for (let i = 0; i + 1 < tokens.length; i += 2) {
+        const status = tokens[i]; const rel = tokens[i + 1];
+        if ((status === 'M' || status === 'T') && emitted.has(rel)) candidates.push(rel);
+      }
+      candidates = [...new Set(candidates)].sort();
+    } catch (e) {
+      notes.push(oneLine(`(all files): git failed listing changes against HEAD: ${e && e.message}`, MAX_NOTE_CHARS));
+    }
+
+    for (let i = 0; i < candidates.length; i++) {
+      const rel = candidates[i];
+      const left = () => Math.min(PER_CALL_MS, deadline - now());
+      let t = left();
+      if (t <= 0) { notes.push(`deadline reached; ${candidates.length - i} file(s) not diffed`); break; }
+      try {
+        // The size first: it reads no content, and a file at or under the cap was bundled whole.
+        // UTF-8 bytes >= UTF-16 length, so a size at or under the cap cannot be a length over it.
+        const size = Number(String(git(['cat-file', '-s', `${headSha}:${rel}`], t)).trim());
+        if (!Number.isFinite(size) || !overCap(size)) continue;
+        if (isSecretPath(rel)) { note(rel, 'secret path; not diffed'); continue; }
+        t = left();
+        if (t <= 0) { notes.push(`deadline reached; ${candidates.length - i} file(s) not diffed`); break; }
+        const head = String(git(['cat-file', 'blob', `${headSha}:${rel}`], t));
+        if (!overCap(head.length)) continue;
+        t = left();
+        if (t <= 0) { notes.push(`deadline reached; ${candidates.length - i} file(s) not diffed`); break; }
+        const out = String(git(diffArgs(headSha, rel), t));
+        if (!out.trim()) { note(rel, 'no longer differs from HEAD; not diffed'); continue; }
+        if (/^Binary files .* differ$/m.test(out) || /^GIT binary patch$/m.test(out)) { note(rel, 'binary to git; not diffed'); continue; }
+        if ((out.match(/^diff --git /gm) || []).length !== 1) { note(rel, 'unexpected diff shape; not included'); continue; }
+        const post = /^index [0-9a-f]+\.\.([0-9a-f]+)(?: [0-7]+)?$/m.exec(out);
+        const contents = blockContents(rendered.text, rel);
+        if (!post || contents === null || post[1] !== gitBlobId(`${contents}\n`, algo)) {
+          note(rel, 'post-image differs from the rendered bytes (an eol or clean filter, no final newline, '
+            + 'non-UTF-8 content, or a change after render); not included');
+          continue;
+        }
+        const section = out.endsWith('\n') ? out : `${out}\n`;
+        if (used + section.length > REVIEW_DIFF_MAX_CHARS) {
+          note(rel, `over the ${REVIEW_DIFF_MAX_CHARS.toLocaleString('en-US')}-char review-diff budget; not included`);
+          continue;
+        }
+        sections.push(section);
+        used += section.length;
+      } catch (e) {
+        note(rel, `git failed: ${oneLine(String((e && e.message) || e).split('\n')[0], 120)}`);
+      }
+    }
+
+    const kept = notes.length > MAX_NOTES
+      ? [...notes.slice(0, MAX_NOTES - 1), `${notes.length - (MAX_NOTES - 1)} more note(s) omitted`]
+      : notes;
+    if (!sections.length && !kept.length) return null;
+    const payload = { headSha, diff: sections.join(''), notes: kept };
+    const bytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
+    if (bytes > REVIEW_DIFF_MAX_BYTES) { warn(`review diff not sent: ${bytes} bytes is over the ${REVIEW_DIFF_MAX_BYTES}-byte limit`); return null; }
+    return { ...payload, stats: { candidates: candidates.length, files: sections.length, chars: used } };
+  } catch (e) {
+    warn(`review diff not sent: ${oneLine((e && e.message) || e, 200)}`);
+    return null;
+  }
+}
+
+/** Exactly what `hone submit-step` posts as `reviewDiff`: the stats stay CLI-side. One mapper, so a test can post what the CLI posts. */
+function toWire(r) { return { headSha: r.headSha, diff: r.diff, notes: r.notes }; }
+
+module.exports = {
+  computeReviewDiff, blockContents, gitBlobId, toWire,
+  _internal: { overCap, diffArgs, REVIEW_DIFF_MAX_CHARS, PER_CALL_MS, DEADLINE_MS, MAX_NOTES, MAX_NOTE_CHARS, REVIEW_DIFF_MAX_BYTES },
+};

package/lib/reviewer-optin.js

@@ -0,0 +1,115 @@
+'use strict';
+/**
+ * HC-GF-337g — the AI code reviewer is OPT-IN.
+ *
+ * `hone setup` used to install it in every adopter repository, where it runs in the adopter's CI
+ * on the adopter's own ANTHROPIC_API_KEY — so a repository that never chose it, and never set the
+ * key, got a red check on every PR. Now its scripts install only on `--ai-reviewer`, and the
+ * ai-review job runs only then. .github/workflows/ai-review.yml itself installs either way: its other
+ * gates (secret scan, tracker, metrics check, E2E healer) are not the reviewer's to take with it.
+ *
+ * Commander keeps the default `undefined` only because `--ai-reviewer` is declared BEFORE
+ * `--no-ai-reviewer` ("If you define --foo first, adding --no-foo does not change the default
+ * value"). Declared the other way round the default becomes `true`, and the always-install comes
+ * back with nothing in the diff to show it — which is why the decision is `=== true` here, and why
+ * tests/regression/hc-gf-337g-reviewer-optin-default.test.js runs the real CLI with no flag.
+ *
+ * Pure: no I/O, so it is unit-testable without the CLI.
+ */
+
+/** True only for an explicit `--ai-reviewer`. No flag, `--no-ai-reviewer`, or no opts at all: false. */
+function shouldInstallReviewer(opts) {
+  return Boolean(opts) && opts.aiReviewer === true;
+}
+
+/**
+ * What an installed .github/workflows/ai-review.yml says about the reviewer job (HC-GF-337g):
+ * 'on' / 'off' (setup's AI_REVIEWER stamp), 'legacy' (written before the stamp existed — it runs the
+ * reviewer on every PR, red without a key) or 'absent' (no file; pass null).
+ */
+function workflowReviewerState(text) {
+  if (text == null) return 'absent';
+  const m = /AI_REVIEWER: "([^"]*)"/.exec(text);
+  if (!m) return 'legacy';
+  return m[1] === 'true' ? 'on' : 'off';
+}
+
+/**
+ * What the operator is told once the setup script has run.
+ *
+ * @param {boolean} installed        the reviewer script is now in the repository (with dryRun: would be)
+ * @param {{ requested?: boolean, alreadyPresent?: boolean, dryRun?: boolean, workflow?: string }} [ctx]
+ *   requested:      `--ai-reviewer` was passed (so `installed: false` means the download failed)
+ *   alreadyPresent: the repository already has .github/workflows/ai-review.yml from an earlier setup
+ *   dryRun:         `--dry-run` — nothing was written, so nothing may be reported as installed
+ *   workflow:       workflowReviewerState() of the repository's ai-review.yml after the script ran (before,
+ *                   on a dry run). An existing workflow is never regenerated, so an install is claimed only
+ *                   when the workflow actually runs the job.
+ * @returns {string} one or more lines, no trailing newline
+ */
+function reviewerNotice(installed, { requested = false, alreadyPresent = false, dryRun = false, workflow } = {}) {
+  const LEGACY = [
+    '    .github/workflows/ai-review.yml predates the opt-in and was kept: it runs the reviewer on every PR,',
+    '    red without ANTHROPIC_API_KEY. Delete it and re-run `hone setup --ai-reviewer` to get the version that',
+    '    skips without a key.',
+  ];
+  // Unknown workflow state (a caller that did not read it): the reviewer side assumes the job is on.
+  const wf = workflow || 'on';
+  if (installed && dryRun) {
+    if (wf === 'legacy') {
+      return ['  DRY-RUN: would install the AI reviewer scripts, but not the job that skips without a key:', ...LEGACY].join('\n');
+    }
+    return [
+      '  DRY-RUN: would install the AI code reviewer (the ai-review job of .github/workflows/ai-review.yml).',
+      '    It runs in your CI on YOUR OWN key: add ANTHROPIC_API_KEY as a repository secret.',
+    ].join('\n');
+  }
+  if (installed && wf === 'legacy') {
+    return ['  ⚠ AI reviewer scripts installed, but not the job that skips without a key:', ...LEGACY].join('\n');
+  }
+  if (installed && wf !== 'on') {
+    return [
+      `  ⚠ AI reviewer scripts installed, but .github/workflows/ai-review.yml ${wf === 'off' ? 'has the reviewer stamped off' : 'is missing'},`,
+      '    so the ai-review job will not run. Delete .github/workflows/ai-review.yml (if present) and re-run',
+      '    `hone setup --ai-reviewer`.',
+    ].join('\n');
+  }
+  if (installed) {
+    return [
+      '  ✓ AI code reviewer installed (the ai-review job of .github/workflows/ai-review.yml).',
+      '    It runs in your CI on YOUR OWN key: add ANTHROPIC_API_KEY as a repository secret.',
+      '    Without it the job is skipped (grey, never blocks a merge). The H-019 learnings gate runs inside it.',
+    ].join('\n');
+  }
+  const lines = requested
+    ? ['  ⚠ AI code reviewer requested (--ai-reviewer) but NOT installed — its download failed or setup did not write it. Re-run setup to retry.']
+    : ['  ℹ AI code reviewer not installed (opt-in: hone setup --ai-reviewer).'];
+  // What is said about the workflow's OTHER gates is read from the workflow too (re-review step_5): it is
+  // never claimed for a workflow that did not arrive, predates the opt-in, or still has the job on.
+  if (workflow === 'absent') {
+    lines.push(
+      '  ⚠ .github/workflows/ai-review.yml is not installed either (its download failed), so its secret scan,',
+      '    tracker and metrics check are missing too. Re-run setup to retry.',
+    );
+  } else if (workflow === 'legacy') {
+    lines.push('    .github/workflows/ai-review.yml predates the opt-in and was kept: delete it and re-run setup to get the version whose ai-review job runs only when chosen.');
+  } else if (workflow === 'on') {
+    lines.push('    .github/workflows/ai-review.yml was kept with the ai-review job switched on by an earlier setup; setup never switches it off.');
+  } else {
+    lines.push('    .github/workflows/ai-review.yml is installed either way: its secret scan, tracker and metrics check run; its ai-review job is skipped.');
+  }
+  lines.push(
+    '    It needs your own ANTHROPIC_API_KEY repository secret, and it carries the H-019 learnings gate:',
+    '    without the reviewer, the learnings gate is not installed either.',
+  );
+  if (alreadyPresent) {
+    lines.push(
+      '  ⚠ .github/scripts/ai-reviewer.js is still here from an earlier setup and was left in place, and an',
+      '    existing .github/workflows/ai-review.yml is never regenerated. To opt out, delete both files and re-run',
+      '    setup; to keep the reviewer, re-run with --ai-reviewer.',
+    );
+  }
+  return lines.join('\n');
+}
+
+module.exports = { shouldInstallReviewer, reviewerNotice, workflowReviewerState };