bmad-plus 0.19.0 → 0.21.0

package/tools/cli/commands/review.js

@@ -4,8 +4,10 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const review = require('../lib/review');
+const reviewRules = require('../lib/review-rules');
 
 const ID = /^[a-z0-9][a-z0-9.-]{0,80}$/;
+const ACTIONS = ['scope', 'anchor', 'gate', 'continue', 'compare', 'rules'];
 
 function fail(message) {
   throw new Error(message);
@@ -22,14 +24,177 @@ function readJson(file, what) {
   }
 }
 
+function writeJson(file, value) {
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** A reader of the file sees the previous version or the new one, never half of it. */
+function writeAtomically(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, text, { flag: 'wx' });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+const inside = (dir, file) => {
+  const relative = path.relative(dir, file);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+};
+
+/**
+ * Where `--emit-check` writes: a JSON file, resolved against the project, never the evidence
+ * itself. A working-tree scope selects untracked files, so its check stays in the review
+ * folder or out of the project: anywhere else it would enter the change it reports on.
+ */
+function checkTarget(projectDir, value, paths, scope) {
+  const file = path.resolve(projectDir, value);
+  if (!/\.json$/i.test(file)) fail('--emit-check writes a .json file');
+  const evidence = Object.entries(paths).filter(([key]) => key !== 'root');
+  if (evidence.some(([, taken]) => path.relative(taken, file) === ''))
+    fail('--emit-check must not overwrite the review evidence');
+  if (
+    scope.identity.workspace &&
+    inside(projectDir, file) &&
+    !inside(path.dirname(paths.root), file)
+  )
+    fail(
+      `--emit-check: a working-tree review writes its check in ${path.relative(projectDir, path.dirname(paths.root)) || '.'} or outside the project, where it cannot enter the reviewed change`
+    );
+  if (fs.existsSync(file) && !fs.statSync(file).isFile())
+    fail(`--emit-check: ${file} is not a file`);
+  return file;
+}
+
 function print(json, payload, lines) {
   if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
   else for (const line of lines) console.log(line);
 }
 
+function requireId(value, what = 'a review id') {
+  if (!value || !ID.test(value))
+    fail(`${what} is required: lowercase letters, digits, dots and dashes`);
+  return value;
+}
+
+function loadReview(projectDir, dir, id) {
+  const paths = review.layout(projectDir, dir, id);
+  const scope = readJson(paths.scope, `${id}/scope.json`);
+  if (!scope) fail(`no scope at ${paths.scope} — run "bmad-plus review scope ${id}" first`);
+  return { paths, scope };
+}
+
+/** One line of observed usage: what the host reported, nothing estimated. */
+function describeUsage(stop, usage) {
+  const parts = [
+    `stopped: ${stop || 'unstated'}`,
+    `${usage.passes ?? '?'}/${usage.plannedPasses ?? '?'} pass(es)`,
+    `${usage.unitsAttempted}/${usage.units} unit(s) attempted in ${usage.attempts} attempt(s), ${usage.failedAttempts} failed`,
+  ];
+  if (usage.tokens !== undefined) parts.push(`${usage.tokens} tokens`);
+  if (usage.durationMs !== undefined) parts.push(`${Math.round(usage.durationMs / 1000)} s`);
+  return parts.join(', ');
+}
+
+/**
+ * `review continue <id>`: what an interrupted review still owes, against the same sealed
+ * scope. Refused when the code or the rules moved — a new scope and a compare answer that.
+ */
+function continueAction(projectDir, dir, id, paths, scope, json) {
+  const drift = review.scopeDrift(projectDir, scope, {
+    ruleset: reviewRules.loadRuleset(projectDir),
+    outputDir: dir,
+  });
+  if (drift.length) {
+    const next = [
+      `bmad-plus review scope <new-id> (same options as ${id})`,
+      `bmad-plus review compare <new-id> --since ${id}`,
+    ];
+    print(json, { action: 'continue', id, status: 'moved', drift, next }, [
+      `${id} cannot continue: the sealed scope no longer describes the code.`,
+      ...drift.map((reason) => `  - ${reason}`),
+      `  Seal a new scope and compare: ${next.join(', then ')}.`,
+    ]);
+    process.exitCode = 3;
+    return undefined;
+  }
+  const coverage = readJson(paths.coverage, 'coverage.json');
+  const coverageErrors = coverage ? review.validateCoverage(coverage, scope) : [];
+  if (coverageErrors.length) {
+    print(json, { action: 'continue', id, status: 'error', errors: coverageErrors }, [
+      `${id}: coverage.json must be valid before the review continues`,
+      ...coverageErrors.map((e) => `  error   ${e}`),
+    ]);
+    process.exitCode = 3;
+    return undefined;
+  }
+  const findings = readJson(paths.findings, 'findings.json');
+  const findingErrors = findings ? review.validateFindings(findings, scope) : [];
+  const anchored =
+    findings && !findingErrors.length ? review.anchorFindings(projectDir, scope, findings) : null;
+  const packet = review.remainingWork({ scope, coverage, anchored, findingErrors });
+  writeJson(paths.continue, packet);
+  const c = packet.counts;
+  const nothing = !c.files && !c.requote && !c.findingErrors && !c.passes;
+  print(json, { action: 'continue', id, status: 'ready', file: paths.continue, counts: c }, [
+    `${paths.continue} — same scope ${scope.sha256.slice(0, 12)}`,
+    `${c.files} file(s) in ${c.units} unit(s) to review, ${c.requote} finding(s) to requote, ${c.passes} pass(es) left`,
+    ...packet.units.map((unit) => `  ${unit.id.padEnd(5)} ${unit.paths.join(', ')}`),
+    ...packet.abandoned.map(
+      (file) => `  abandoned ${file.path} (${file.unit}): three failed attempts; it stays failed`
+    ),
+    ...packet.requote.map((f) => `  requote ${f.id} ${f.path} (${f.status})`),
+    ...packet.findingErrors.map((e) => `  fix     ${e}`),
+    nothing
+      ? `Nothing remains: once coverage.json records the run as completed, run bmad-plus review gate ${id}.`
+      : 'Add to the same coverage.json and findings.json; set run.stop when this session ends.',
+  ]);
+  process.exitCode = 0;
+  return undefined;
+}
+
+/** `review rules [path]`: the effective rule set, or the rules one path would get. */
+function rulesAction(projectDir, target, json) {
+  const ruleset = reviewRules.loadRuleset(projectDir);
+  const file = target ? target.split(path.sep).join('/').replace(/^\.\//, '') : null;
+  const ids = file ? reviewRules.rulesFor(ruleset, file) : ruleset.rules.map((rule) => rule.id);
+  const listed = ruleset.rules.filter((rule) => ids.includes(rule.id));
+  print(
+    json,
+    {
+      action: 'rules',
+      path: file,
+      sha256: ruleset.sha256,
+      projectFile: ruleset.projectFile,
+      disabled: ruleset.disabled,
+      rules: listed.map(({ id, title, group, layer, globs, source }) => ({
+        id,
+        title,
+        group,
+        layer,
+        globs,
+        source,
+      })),
+    },
+    [
+      `rule set ${ruleset.sha256.slice(0, 12)}${ruleset.projectFile ? ` (built-in + ${ruleset.projectFile})` : ' (built-in)'}`,
+      ...(file ? [`${file} gets ${listed.length} rule(s):`] : []),
+      ...listed.map(
+        (rule) =>
+          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
+      ),
+      ...ruleset.disabled.map((id) => `  ${id.padEnd(24)} disabled by the project`),
+    ]
+  );
+}
+
 module.exports = {
   command: 'review <action> [id]',
-  description: 'Code review evidence: scope, anchor, gate',
+  description: 'Code review evidence: scope, anchor, gate, continue, compare, rules',
   options: [
     ['-d, --directory <path>', 'Project directory'],
     ['--dir <path>', 'Review folder inside the project', review.DEFAULT_DIR],
@@ -38,19 +203,25 @@ module.exports = {
     ['--workspace', 'Review the working tree, untracked files included, against the base'],
     ['--include <glob>', 'Only review matching paths (repeatable)', (v, all) => [...all, v], []],
     ['--exclude <glob>', 'Never review matching paths (repeatable)', (v, all) => [...all, v], []],
+    [
+      '--effort <level>',
+      `Review depth: ${Object.keys(review.EFFORTS).join(', ')} (default medium)`,
+    ],
+    ['--since <id>', 'compare: the earlier review to compare against'],
+    ['--emit-check <file>', 'gate: also write the verdict as a JSON check result for CI'],
     ['--json', 'Machine-readable output'],
   ],
   action: (action, id, options = {}) => {
     const projectDir = path.resolve(options.directory || process.cwd());
+    const dir = options.dir || review.DEFAULT_DIR;
     const json = Boolean(options.json);
     try {
-      if (!id || !ID.test(id))
-        fail('a review id is required: lowercase letters, digits, dots and dashes');
-      if (!['scope', 'anchor', 'gate'].includes(action))
-        fail(`unknown action "${action}" (scope, anchor, gate)`);
-      const paths = review.layout(projectDir, options.dir || review.DEFAULT_DIR, id);
+      if (!ACTIONS.includes(action)) fail(`unknown action "${action}" (${ACTIONS.join(', ')})`);
+      if (action === 'rules') return rulesAction(projectDir, id, json);
+      requireId(id);
 
       if (action === 'scope') {
+        const ruleset = reviewRules.loadRuleset(projectDir);
         const scope = review.buildScope(projectDir, {
           id,
           base: options.base,
@@ -58,34 +229,48 @@ module.exports = {
           workspace: Boolean(options.workspace),
           include: options.include,
           exclude: options.exclude,
+          effort: options.effort,
+          outputDir: dir,
+          ruleset,
         });
+        const paths = review.layout(projectDir, dir, id);
         fs.mkdirSync(paths.root, { recursive: true });
-        fs.writeFileSync(paths.scope, `${JSON.stringify(scope, null, 2)}\n`);
+        writeJson(paths.scope, scope);
+        const byPath = Object.fromEntries(scope.selected.map((item) => [item.path, item.rules]));
+        fs.writeFileSync(
+          paths.checklist,
+          reviewRules.checklist(ruleset, byPath, { title: `Review checklist — ${id}` })
+        );
         const reasons = {};
         for (const item of scope.excluded) reasons[item.reason] = (reasons[item.reason] || 0) + 1;
+        const { plan } = scope;
         print(
           json,
           {
             action,
             id,
             file: paths.scope,
+            checklist: paths.checklist,
             totals: scope.totals,
             units: scope.units.length,
             excluded: reasons,
+            plan,
+            rulesSha256: scope.identity.rulesSha256,
             sha256: scope.sha256,
           },
           [
             `${paths.scope}`,
             `${scope.totals.selected} file(s) to review, ${scope.totals.lines} changed lines, ${scope.units.length} unit(s) — scope ${scope.sha256.slice(0, 12)}`,
             ...Object.entries(reasons).map(([reason, n]) => `  excluded ${n} × ${reason}`),
+            `checklist: ${paths.checklist}`,
+            `plan: ${plan.effort} effort, ${plan.passes} pass(es)${plan.refute ? ', refutation pass' : ''}${plan.planFirst ? ', plan before reading' : ''}${plan.parallelUnits ? ', units can be reviewed in parallel' : ''}`,
             'Every selected file must end in coverage.json as completed, failed or waived (with a reason).',
           ]
         );
-        return;
+        return undefined;
       }
 
-      const scope = readJson(paths.scope, 'scope.json');
-      if (!scope) fail(`no scope at ${paths.scope} — run "bmad-plus review scope ${id}" first`);
+      const { paths, scope } = loadReview(projectDir, dir, id);
 
       if (action === 'anchor') {
         const findings = readJson(paths.findings, 'findings.json');
@@ -98,23 +283,30 @@ module.exports = {
             errors.map((e) => `  error   ${e}`)
           );
           process.exitCode = 1;
-          return;
+          return undefined;
         }
         const anchored = review.anchorFindings(projectDir, scope, findings);
-        fs.writeFileSync(
-          paths.anchored,
-          `${JSON.stringify({ schema: review.FINDINGS_SCHEMA, scopeSha256: scope.sha256, ...anchored }, null, 2)}\n`
-        );
+        writeJson(paths.anchored, {
+          schema: review.FINDINGS_SCHEMA,
+          scopeSha256: scope.sha256,
+          ...anchored,
+        });
         const loose = anchored.findings.filter((f) => f.location.status !== 'located');
-        print(json, { action, id, file: paths.anchored, counts: anchored.counts }, [
-          `${paths.anchored} — ${anchored.counts.located} located, ${anchored.counts.ambiguous} ambiguous, ${anchored.counts.unlocated} unlocated`,
+        const { counts } = anchored;
+        print(json, { action, id, file: paths.anchored, counts }, [
+          `${paths.anchored} — ${counts.located} located, ${counts.ambiguous} ambiguous, ${counts.unlocated} unlocated`,
           ...loose.map(
             (f) =>
               `  ${f.location.status.padEnd(9)} ${f.id} ${f.path}: quote a longer, exact excerpt`
           ),
+          ...(counts.redactions
+            ? [
+                `  ${counts.redactions} credential-like value(s) replaced by [REDACTED] in the written record`,
+              ]
+            : []),
         ]);
         process.exitCode = loose.length ? 1 : 0;
-        return;
+        return undefined;
       }
 
       if (action === 'gate') {
@@ -124,22 +316,65 @@ module.exports = {
         if (findings && !review.validateFindings(findings, scope).length)
           anchored = review.anchorFindings(projectDir, scope, findings);
         const verdict = review.reviewGate({ scope, findings, coverage, anchored });
+        let check = null;
+        if (options.emitCheck) {
+          check = checkTarget(projectDir, options.emitCheck, paths, scope);
+          writeAtomically(
+            check,
+            `${JSON.stringify(review.checkResult({ id, scope, verdict, anchored }), null, 2)}\n`
+          );
+        }
         print(
           json,
-          { action, id, ...verdict },
+          { action, id, ...verdict, check },
           [
             `${id}: ${verdict.status} — coverage ${verdict.coverage.completed}/${verdict.coverage.selected} completed (${verdict.coverage.waived} waived), ${verdict.findings.open} open finding(s), ${verdict.findings.refuted} refuted`,
             ...verdict.reasons.map((reason) => `  - ${reason}`),
+            verdict.usage ? `  run: ${describeUsage(verdict.stop, verdict.usage)}` : '',
+            check ? `  check: ${check}` : '',
             verdict.status === 'clean'
               ? '  clean: no open finding within a fully covered scope. It does not prove the code correct.'
               : '',
           ].filter(Boolean)
         );
-        process.exitCode = { clean: 0, findings: 1, incomplete: 2 }[verdict.status];
-        return;
+        process.exitCode = review.GATE_EXIT[verdict.status];
+        return undefined;
       }
 
-      fail(`unknown action "${action}" (scope, anchor, gate)`);
+      if (action === 'continue') return continueAction(projectDir, dir, id, paths, scope, json);
+
+      // compare: this review against an earlier one.
+      const sinceId = requireId(options.since, '--since <earlier review id>');
+      if (sinceId === id) fail('--since must name a different review');
+      const earlier = loadReview(projectDir, dir, sinceId);
+      const load = (entry, label) => {
+        const findings = readJson(entry.paths.findings, `${label}/findings.json`);
+        if (!findings) fail(`no findings at ${entry.paths.findings}`);
+        const errors = review.validateFindings(findings, entry.scope);
+        if (errors.length) fail(`${label}/findings.json is invalid: ${errors[0]}`);
+        return findings;
+      };
+      const result = review.compareReviews(
+        { scope: earlier.scope, findings: load(earlier, sinceId) },
+        {
+          scope,
+          findings: load({ paths, scope }, id),
+          coverage: readJson(paths.coverage, `${id}/coverage.json`),
+        }
+      );
+      writeJson(paths.compare, result);
+      const c = result.counts;
+      print(
+        json,
+        { action, id, since: sinceId, file: paths.compare, counts: c },
+        [
+          `${id} since ${sinceId}: ${c.new} new, ${c.persisting} persisting, ${c.resolved} resolved, ${c.refuted} refuted, ${c.not_reviewed} not reviewed`,
+          c.not_reviewed
+            ? '  not reviewed: earlier findings on files this review did not complete — they are not known to be fixed.'
+            : '',
+        ].filter(Boolean)
+      );
+      return undefined;
     } catch (error) {
       if (json)
         console.log(
@@ -147,6 +382,7 @@ module.exports = {
         );
       else console.error(`review: ${error.message}`);
       process.exitCode = 3;
+      return undefined;
     }
   },
 };

package/tools/cli/commands/uat.js

@@ -145,6 +145,7 @@ function serve(spec, paths, options) {
               return;
             }
           }
+          uat.redactRun(run);
           fs.writeFileSync(file, JSON.stringify(run, null, 2));
           const s = run.summary;
           console.log(
@@ -284,10 +285,22 @@ module.exports = {
         const dir = path.join(paths.results, spec.id);
         fs.mkdirSync(dir, { recursive: true });
         const file = path.join(dir, `${run.runId}.json`);
+        uat.redactRun(run);
         fs.writeFileSync(file, JSON.stringify(run, null, 2));
-        print(json, { action, specId: spec.id, runId: run.runId, file, summary: run.summary }, [
-          `${file} — ${run.summary.passed} passed, ${run.summary.failed} failed, ${run.summary.blocked} blocked, ${run.summary.unanswered} to do`,
-        ]);
+        print(
+          json,
+          {
+            action,
+            specId: spec.id,
+            runId: run.runId,
+            file,
+            summary: run.summary,
+            redactions: run.redactions || 0,
+          },
+          [
+            `${file} — ${run.summary.passed} passed, ${run.summary.failed} failed, ${run.summary.blocked} blocked, ${run.summary.unanswered} to do`,
+          ]
+        );
         return;
       }
 

package/tools/cli/lib/glob.js

@@ -0,0 +1,73 @@
+/**
+ * Path patterns for review scopes and rules. Deliberately small and dependency-free:
+ * `**` spans directories, `*` stays within one segment, `?` is one character, and
+ * `{a,b}` alternates — every group, nested groups included. Paths use `/`.
+ */
+'use strict';
+
+const MAX_EXPANSIONS = 256;
+const cache = new Map();
+
+/** `src/{a,b{c,d}}/*.js` → four patterns. An unbalanced brace is an error, never a literal. */
+function expandBraces(pattern) {
+  const open = pattern.indexOf('{');
+  if (open < 0) {
+    if (pattern.includes('}')) throw new Error(`unbalanced "}" in pattern "${pattern}"`);
+    return [pattern];
+  }
+  let depth = 0;
+  let close = -1;
+  const commas = [];
+  for (let i = open; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) {
+      close = i;
+      break;
+    } else if (c === ',' && depth === 1) commas.push(i);
+  }
+  if (close < 0) throw new Error(`unbalanced "{" in pattern "${pattern}"`);
+  const head = pattern.slice(0, open);
+  const tail = pattern.slice(close + 1);
+  const bounds = [open, ...commas, close];
+  const results = [];
+  for (let i = 0; i < bounds.length - 1; i++) {
+    const option = pattern.slice(bounds[i] + 1, bounds[i + 1]);
+    for (const expanded of expandBraces(head + option + tail)) {
+      results.push(expanded);
+      if (results.length > MAX_EXPANSIONS)
+        throw new Error(`pattern "${pattern}" expands to more than ${MAX_EXPANSIONS} forms`);
+    }
+  }
+  return results;
+}
+
+function toRegExp(glob) {
+  let source = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      const slash = glob[i + 2] === '/';
+      source += slash ? '(?:.*/)?' : '.*';
+      i += slash ? 2 : 1;
+    } else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** Compiled once per pattern: the same patterns are tested against every changed file. */
+function compile(pattern) {
+  let compiled = cache.get(pattern);
+  if (!compiled) {
+    compiled = expandBraces(pattern).map(toRegExp);
+    cache.set(pattern, compiled);
+  }
+  return compiled;
+}
+
+const matches = (file, pattern) => compile(pattern).some((re) => re.test(file));
+const matchesAny = (file, patterns) => patterns.some((pattern) => matches(file, pattern));
+
+module.exports = { expandBraces, compile, matches, matchesAny };

package/tools/cli/lib/packs.js

@@ -191,7 +191,7 @@ const DERIVED = {
   "product": {
     "code": "bmad-plus",
     "displayName": "BMAD+",
-    "version": "0.19.0",
+    "version": "0.21.0",
     "derivedFrom": "BMAD-METHOD v6.6.0"
   },
   "packOrder": [

package/tools/cli/lib/redact.js

@@ -0,0 +1,116 @@
+/**
+ * Redaction floor for free text that BMAD+ writes to disk or prints: reviewer notes,
+ * tester notes, finding descriptions. It removes credentials that commonly end up pasted
+ * into such text; it is a floor, not a scanner, and never a reason to paste secrets.
+ */
+'use strict';
+
+const MARK = '[REDACTED]';
+const MAX_LENGTH = 20000;
+
+/**
+ * A value that names where a secret comes from rather than holding it: an environment or
+ * secret-store reference, a template placeholder, or an UPPER_SNAKE variable name (an
+ * underscore is required, so an all-capitals random key is still masked).
+ */
+const REFERENCE =
+  /^(?:process\.env\b|os\.environ\b|os\.getenv\b|getenv\b|env\.|secrets\.|vars\.|\$|%|<|\{\{|[A-Z][A-Z0-9]*_[A-Z0-9_]*$|\[REDACTED\]$)/;
+
+/** Ordered: whole blocks first, then structured forms, then well-known token shapes. */
+const RULES = [
+  {
+    kind: 'private-key',
+    pattern:
+      /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g,
+    replace: () => `-----${MARK} PRIVATE KEY-----`,
+  },
+  {
+    kind: 'url-credentials',
+    pattern: /\b([a-z][a-z0-9+.-]{1,20}:\/\/)[^\s/?#@:]+:[^\s/?#@]+@/gi,
+    replace: (_, scheme) => `${scheme}${MARK}@`,
+  },
+  {
+    kind: 'authorization',
+    pattern:
+      /\b((?:authorization|proxy-authorization)\s*[:=]\s*)(bearer|basic|token|digest)\s+[A-Za-z0-9._~+/=-]{8,}/gi,
+    replace: (_, lead, scheme) => `${lead}${scheme} ${MARK}`,
+  },
+  {
+    kind: 'bearer',
+    pattern: /\b(bearer\s+)[A-Za-z0-9._~+/=-]{16,}/gi,
+    replace: (_, lead) => `${lead}${MARK}`,
+  },
+  {
+    kind: 'assignment',
+    // name = value where the name says it holds a credential; the name stays readable.
+    pattern:
+      /\b([A-Za-z0-9_.-]*(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?key|credentials?)[A-Za-z0-9_.-]*["']?\s*[:=]\s*)(["']?)([^\s"',;]{6,})\2/gi,
+    replace: (whole, lead, quote, value) =>
+      REFERENCE.test(value) ? whole : `${lead}${quote}${MARK}${quote}`,
+  },
+  {
+    kind: 'known-token',
+    pattern: new RegExp(
+      [
+        'gh[pousr]_[A-Za-z0-9]{30,}',
+        'github_pat_[A-Za-z0-9_]{40,}',
+        'glpat-[A-Za-z0-9_-]{20,}',
+        'npm_[A-Za-z0-9]{30,}',
+        'sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}',
+        'xox[abprs]-[A-Za-z0-9-]{10,}',
+        'AKIA[0-9A-Z]{16}',
+        'AIza[0-9A-Za-z_-]{35}',
+        'eyJ[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}',
+      ]
+        .map((source) => `\\b${source}`)
+        .join('|'),
+      'g'
+    ),
+    replace: () => MARK,
+  },
+];
+
+/** Control characters other than tab, line feed and carriage return are dropped. */
+function stripControl(text) {
+  let out = '';
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127)) out += char;
+  }
+  return out;
+}
+
+/**
+ * Returns the text with credentials replaced by a marker, and what was replaced by kind.
+ * Non-strings pass through untouched so callers can map over mixed records.
+ */
+function redact(value, { maxLength = MAX_LENGTH } = {}) {
+  if (typeof value !== 'string') return { text: value, found: {} };
+  let text = stripControl(value);
+  const found = {};
+  for (const rule of RULES) {
+    text = text.replace(rule.pattern, (...match) => {
+      found[rule.kind] = (found[rule.kind] || 0) + 1;
+      return rule.replace(...match);
+    });
+  }
+  if (text.length > maxLength) {
+    text = `${text.slice(0, maxLength)} […${text.length - maxLength} characters cut]`;
+    found.truncated = 1;
+  }
+  return { text, found };
+}
+
+/** Redacts the listed string fields of a record in place; returns the number of replacements. */
+function redactFields(record, fields, options) {
+  let count = 0;
+  for (const field of fields) {
+    if (typeof record[field] !== 'string') continue;
+    const { text, found } = redact(record[field], options);
+    record[field] = text;
+    count += Object.entries(found).reduce((n, [kind, k]) => (kind === 'truncated' ? n : n + k), 0);
+  }
+  return count;
+}
+
+module.exports = { MARK, redact, redactFields };