@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/lib/review-brief.mjs

@@ -0,0 +1,43 @@
+// A short brief for the person who reviews a built issue, computed from the issue so the model does not rewrite it.
+// Implements "The review starts with a short brief" of openspec/specs/review/spec.md.
+
+import { parseIssueBody } from './issue-parse.mjs';
+import { section } from './issue-sections.mjs';
+
+export const MAX_SENTENCES = 2;
+export const MAX_LINE = 160;
+
+const LABELS = {
+  en: { asked: 'Asked', outcome: 'Outcome', first: 'Check first', count: (s, e) => `To check: ${s} scenario(s), ${e} edge case(s)` },
+  es: { asked: 'Se pidió', outcome: 'Resultado', first: 'Revisa primero', count: (s, e) => `Por revisar: ${s} escenario(s), ${e} caso(s) borde` },
+};
+const RISK_RE = /(?:Riskiest area, check it first|Zona más riesgosa, revísala primero):\s*(.+)/;
+
+const clean = (text) => String(text ?? '').replace(/<!--[\s\S]*?-->/g, '').replace(/\s+/g, ' ').trim();
+const cap = (text) => (text.length > MAX_LINE ? `${text.slice(0, MAX_LINE - 1).trimEnd()}…` : text);
+
+/** Up to `max` sentences of a text. */
+export function firstSentences(text, max = MAX_SENTENCES) {
+  const t = clean(text);
+  if (!t) return '';
+  return t.split(/(?<=[.!?])\s+/).slice(0, max).join(' ');
+}
+
+/**
+ * issue  { number, title, body }
+ * built  the text of the `built` comment, when there is one (the risk line is taken from it)
+ * Returns the brief as a string of about five lines.
+ */
+export function reviewBrief({ issue, built = '', language = 'en' }) {
+  const L = LABELS[language === 'es' ? 'es' : 'en'];
+  const parsed = parseIssueBody(issue.body);
+  const lines = [`#${issue.number} ${clean(issue.title)}`];
+  const asked = firstSentences(section(issue.body, 'Summary')?.text);
+  if (asked) lines.push(`${L.asked}: ${asked}`);
+  const outcome = clean(section(issue.body, 'Outcome')?.text);
+  if (outcome) lines.push(`${L.outcome}: ${firstSentences(outcome, 1)}`);
+  const risk = String(built).match(RISK_RE)?.[1];
+  if (risk) lines.push(`${L.first}: ${clean(risk)}`);
+  lines.push(L.count(parsed.scenarios, parsed.edgeCases));
+  return lines.map(cap).join('\n');
+}

package/scripts/lib/review-events.mjs

@@ -0,0 +1,56 @@
+// Keeps the lifecycle label in step with pull request reviews. Implements "Review events update the label"
+// of openspec/specs/issue-lifecycle/spec.md. Pure: data in, decision out.
+//
+// event  { kind: 'review', state: 'changes_requested' | 'approved' | 'commented' | ..., reviewer, body, url }
+//        { kind: 'push' }
+// pr     { number, url, author }
+// issue  { number, labels: [names] }
+
+import { resolveLabelNames, transition } from './labels.mjs';
+
+const SUMMARY_LENGTH = 300;
+
+function summarise(body, es) {
+  const text = String(body ?? '').trim().replace(/\s+/g, ' ');
+  if (!text) return es ? 'Revisa los comentarios en el pull request.' : 'See the comments on the pull request.';
+  return text.length > SUMMARY_LENGTH ? `${text.slice(0, SUMMARY_LENGTH)}…` : text;
+}
+
+/** Returns { action, labels: { add, remove }, comment } or null when the event changes nothing. */
+export function planReviewEvent({ config, event, pr, issue }) {
+  if (config.review.mode === 'none') return null;
+  const names = resolveLabelNames(config.labels);
+  const has = (key) => issue.labels.includes(names[key]);
+  const es = String(config.language ?? 'en').startsWith('es');
+
+  if (event.kind === 'push') {
+    if (!has('changes-requested')) return null;
+    return { action: 'back-to-pr-open', labels: transition(issue.labels, 'pr-open', config.labels), comment: null };
+  }
+
+  if (event.kind !== 'review' || event.reviewer === pr.author) return null;
+
+  if (event.state === 'changes_requested') {
+    if (!has('pr-open') && !has('changes-requested')) return null;
+    return {
+      action: 'changes-requested',
+      labels: transition(issue.labels, 'changes-requested', config.labels),
+      comment: {
+        kind: 'changes_requested',
+        data: { author: pr.author, issue: issue.number, reviewer: event.reviewer, summary: summarise(event.body, es), pr: event.url ?? pr.url },
+      },
+    };
+  }
+
+  if (event.state === 'approved') {
+    if (!has('pr-open')) return null;
+    // Who runs `ship`: the approver with merger "approver", the author with merger "author".
+    const recipient = config.review.merger === 'author' ? pr.author : event.reviewer;
+    return {
+      action: 'approved',
+      labels: { add: [], remove: [] },
+      comment: { kind: 'approved', data: { recipient, issue: issue.number, reviewer: event.reviewer, pr: pr.url } },
+    };
+  }
+  return null;
+}

package/scripts/lib/review-state.mjs

@@ -0,0 +1,157 @@
+// State of one on-device review, and the rule that decides whether a pull request may be opened.
+// Implements "Pull request only after verification" of openspec/specs/review/spec.md.
+
+export const STATUSES = ['pending', 'ok', 'fail'];
+
+const same = (a, b) => a.class === b.class && a.excerpt === b.excerpt;
+
+export const AUTOPILOT_MODES = ['off', 'precheck', 'verify'];
+
+export function newState(items, { autopilot = 'off' } = {}) {
+  if (!AUTOPILOT_MODES.includes(autopilot)) throw new Error(`autopilot must be one of ${AUTOPILOT_MODES.join(', ')}`);
+  return {
+    autopilot,
+    envConfirmed: false,
+    items: items.map((i) => ({ id: i.id, title: i.title, status: 'pending', note: null, precheck: null, auto: null })),
+    captures: [],
+    audit: null,
+    waivers: [],
+    agreed: false,
+  };
+}
+
+/**
+ * Waive the n-th finding of the audit (numbered from 1, as the audit prints them) with a written reason.
+ * Only the person calls this; an inconclusive audit and an empty reason are refused.
+ * Returns the state with the verdict recomputed.
+ */
+export function waiveFinding(state, number, reason) {
+  const why = String(reason ?? '').trim();
+  if (!state.audit) throw new Error('the log audit has not run: there is nothing to waive');
+  if (state.audit.verdict === 'REVIEW INCONCLUSIVE') throw new Error('an inconclusive audit cannot be waived: restart the app and repeat the steps');
+  if (!why) throw new Error('a waiver needs a written reason: waive <number> <reason>');
+  const finding = state.audit.findings[Number(number) - 1];
+  if (!finding) throw new Error(`there is no finding ${number} in the audit (it has ${state.audit.findings.length})`);
+  state.waivers ??= [];
+  if (!state.waivers.some((w) => same(w, finding))) state.waivers.push({ class: finding.class, excerpt: finding.excerpt, reason: why });
+  return applyWaivers(state);
+}
+
+/** Mark the findings that match a waiver and recompute the verdict: all waived is "REVIEW PASSED (with waivers)". */
+export function applyWaivers(state) {
+  const audit = state.audit;
+  if (!audit || audit.verdict === 'REVIEW INCONCLUSIVE') return state;
+  audit.findings.forEach((f) => {
+    const w = (state.waivers ?? []).find((x) => same(x, f));
+    if (w) {
+      f.waived = true;
+      f.reason = w.reason;
+    } else {
+      delete f.waived;
+      delete f.reason;
+    }
+  });
+  if (audit.findings.length > 0) audit.verdict = audit.findings.every((f) => f.waived) ? 'REVIEW PASSED (with waivers)' : 'REVIEW REJECTED';
+  return state;
+}
+
+/** The markdown section of the pull request body and the report for the waived findings; empty when there are none. */
+export function waivedSection(state) {
+  const waived = (state.audit?.findings ?? []).filter((f) => f.waived);
+  if (waived.length === 0) return '';
+  return ['## Waived findings', '', ...waived.map((f) => `- **${f.class}**: \`${f.excerpt.replace(/`/g, "'")}\` — waived by the reviewer: ${f.reason}`), ''].join('\n');
+}
+
+/**
+ * Reconcile the checklist after a fix changed the specification and the code.
+ * Lines that were confirmed stay confirmed; lines that failed go back to pending so they are tested again;
+ * new scenarios are added as pending. The log audit and the person's agreement no longer apply to the new code.
+ */
+export function syncState(state, items) {
+  const before = new Map(state.items.map((i) => [i.title, i]));
+  state.items = items.map((i) => {
+    const old = before.get(i.title);
+    // A line confirmed by the person stays; one the agent verified automatically does not: the code under it changed.
+    const keep = old && old.status === 'ok' && !old.auto;
+    return { id: i.id, title: i.title, status: keep ? 'ok' : 'pending', note: null, precheck: null, auto: null };
+  });
+  state.audit = null;
+  state.waivers = [];
+  state.agreed = false;
+  return state;
+}
+
+export function setItem(state, id, status, note = null) {
+  if (!STATUSES.includes(status)) throw new Error(`status must be one of ${STATUSES.join(', ')}`);
+  const item = state.items.find((i) => i.id === id);
+  if (!item) throw new Error(`there is no checklist item ${id}`);
+  item.status = status;
+  item.note = note;
+  // What the person decides replaces what the agent recorded: a confirmation is theirs, a failure or a retest starts again.
+  item.auto = null;
+  if (status !== 'ok') item.precheck = null;
+  return state;
+}
+
+const driving = (state) => {
+  const mode = state.autopilot ?? 'off';
+  if (mode === 'off') throw new Error('the agent does not drive the review: review.autopilot is "off"');
+  if (!state.envConfirmed) throw new Error('the person has not confirmed in writing that the app points to non-production data: run "confirm-env" after they do');
+  return mode;
+};
+
+/** The person confirmed that the app under review does not point to production data. */
+export function confirmEnv(state) {
+  state.envConfirmed = true;
+  return state;
+}
+
+/** The agent's own result for a line, apart from the person's confirmation. Modes precheck and verify only. */
+export function precheckItem(state, id, result, note = null) {
+  driving(state);
+  if (!['ok', 'fail'].includes(result)) throw new Error('a pre-check result is ok or fail');
+  const item = state.items.find((i) => i.id === id);
+  if (!item) throw new Error(`there is no checklist item ${id}`);
+  item.precheck = result;
+  if (note) item.note = note;
+  return state;
+}
+
+/** The agent marks a line as verified automatically, saying how. Mode verify only; the line becomes ok but stays labelled. */
+export function autoItem(state, id, how) {
+  const mode = driving(state);
+  if (mode !== 'verify') throw new Error(`a line can be verified automatically only when review.autopilot is "verify" (it is "${mode}")`);
+  const why = String(how ?? '').trim();
+  if (!why) throw new Error('say how the line was verified: auto <number> <the assertion, finder or log that proved it>');
+  const item = state.items.find((i) => i.id === id);
+  if (!item) throw new Error(`there is no checklist item ${id}`);
+  item.status = 'ok';
+  item.precheck = 'ok';
+  item.auto = why;
+  return state;
+}
+
+/** The "Verified automatically" section of the pull request body; empty when no line was. */
+export function autoSection(state) {
+  const lines = state.items.filter((i) => i.auto);
+  if (lines.length === 0) return '';
+  return ['## Verified automatically', '', ...lines.map((i) => `- ${i.id}. ${i.title}: ${i.auto}`), ''].join('\n');
+}
+
+/**
+ * May the pull request be opened? Only when the log audit passed, every checklist line is confirmed
+ * working by the person, and the person agrees. Returns { open, reasons }.
+ */
+export function decidePr(state) {
+  const reasons = [];
+  if (!state.audit) reasons.push('the log audit has not run');
+  else if (state.audit.verdict === 'REVIEW INCONCLUSIVE') reasons.push('the log audit was inconclusive: it had no log of the app to judge, so it proves nothing');
+  else if (!['REVIEW PASSED', 'REVIEW PASSED (with waivers)'].includes(state.audit.verdict)) reasons.push('the log audit found problems');
+  state.items.forEach((i) => {
+    if (i.status === 'pending') reasons.push(`checklist item ${i.id} ("${i.title}") is not confirmed yet`);
+    if (i.status === 'fail') reasons.push(`checklist item ${i.id} ("${i.title}") failed${i.note ? `: ${i.note}` : ''}`);
+  });
+  if (state.items.length === 0) reasons.push('there are no scenarios to verify');
+  if (!state.agreed) reasons.push('the person has not agreed to open the pull request');
+  return { open: reasons.length === 0, reasons };
+}

package/scripts/lib/reviewers.mjs

@@ -0,0 +1,39 @@
+// Chooses who reviews a pull request.
+// Implements "Reviewer selection" of openspec/specs/issue-lifecycle/spec.md.
+
+import { resolveLabelNames } from './labels.mjs';
+
+/**
+ * members      team.members
+ * specWriter   team.spec_writer (never reviews)
+ * author       whoever opens the pull request (never reviews their own)
+ * approvers    team.approvers (only used when mode is "roles")
+ * mode         review.mode
+ * openCounts   { login: number of open review requests }
+ * prNumber     breaks ties in rotation
+ * Returns a login, or null when nobody is eligible.
+ */
+export function pickReviewer({ members, specWriter = null, author, approvers = [], mode = 'peer', openCounts = {}, prNumber = 0 }) {
+  const eligible = members.filter((m) => m !== author && m !== specWriter && (mode !== 'roles' || approvers.includes(m)));
+  if (eligible.length === 0) return null;
+  const load = (m) => openCounts[m] ?? 0;
+  const least = Math.min(...eligible.map(load));
+  const ties = eligible.filter((m) => load(m) === least).sort();
+  return ties[prNumber % ties.length];
+}
+
+/**
+ * What to do when nobody is eligible: label the issue `needs-reviewer` next to its state and mention the spec writer.
+ * Returns { labels: { add, remove }, comment } (comment is null when there is no spec writer to mention).
+ */
+export function noReviewerDecision({ config, issue }) {
+  const names = resolveLabelNames(config.labels);
+  const already = issue.labels?.includes(names['needs-reviewer']);
+  const specWriter = config.team.spec_writer;
+  return {
+    labels: { add: already ? [] : [names['needs-reviewer']], remove: [] },
+    comment: specWriter
+      ? { kind: 'needs_reviewer', data: { spec_writer: specWriter, issue: issue.number, title: issue.title, pr: issue.pr } }
+      : null,
+  };
+}

package/scripts/lib/role-skills.mjs

@@ -0,0 +1,112 @@
+// Extra skills per role. Implements the "role-skills" specification: a skill is given to an agent only when it
+// is trustworthy, and the reason a skill was left out is always reported.
+//
+// `git(args) -> stdout` is injected (it throws when the command fails) so the logic is tested without a repository.
+
+import { createHash } from 'node:crypto';
+import { ROLES } from './stack-profile.mjs';
+
+export const SKILL_DIRS = ['.agents/skills', '.claude/skills'];
+export const SIZE_BUDGET_BYTES = 20 * 1024;
+const SCRIPT_EXTENSIONS = ['.sh', '.bash', '.js', '.mjs', '.cjs', '.ts', '.py', '.rb', '.php', '.ps1'];
+const NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** The roles whose lists apply to `role`: `fix` uses those of `dev` and `qa`. */
+export const rolesFor = (role) => (role === 'fix' ? ['dev', 'qa'] : [role]);
+
+/** Does a skill folder hold anything that can run? `files` are paths relative to the folder. */
+export function hasScripts(files) {
+  return files.some((f) => {
+    const parts = f.split('/');
+    return parts.slice(0, -1).includes('scripts') || SCRIPT_EXTENSIONS.some((ext) => parts[parts.length - 1].toLowerCase().endsWith(ext));
+  });
+}
+
+/** Does the frontmatter of a SKILL.md reserve the skill for the person? */
+export function reservedForPerson(skillMd) {
+  const head = String(skillMd ?? '').replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+  return head ? /^disable-model-invocation:\s*true\s*$/m.test(head[1]) : false;
+}
+
+/** Entries of `git ls-tree -r` for a path: [{ mode, path }]. */
+function listTree(git, ref, dir) {
+  let out;
+  try {
+    out = git(['ls-tree', '-r', ref, '--', dir]);
+  } catch {
+    return [];
+  }
+  return String(out).split('\n').filter(Boolean).map((line) => {
+    const [meta, path] = line.split('\t');
+    return { mode: meta.split(' ')[0], path };
+  });
+}
+
+/**
+ * Decide whether one skill can be given to an agent.
+ * Returns { name, path, scripts } when it can, or { name, left_out: true, reason }.
+ */
+export function resolveSkill({ name, git, baseRef, allowScripts = [], dirs = SKILL_DIRS }) {
+  const out = (reason) => ({ name, left_out: true, reason });
+  if (!NAME_RE.test(name)) return out('invalid name');
+
+  let sawLink = false;
+  for (const dir of dirs) {
+    const folder = `${dir}/${name}`;
+    const entries = listTree(git, baseRef, folder);
+    if (entries.length === 0) continue;
+    if (entries.some((e) => e.mode === '120000')) {
+      sawLink = true;
+      continue; // a link is followed only through the folder it points to, which is one of `dirs`
+    }
+    const files = entries.map((e) => e.path.slice(folder.length + 1));
+    const skillMd = `${folder}/SKILL.md`;
+    if (!files.includes('SKILL.md')) return out('no SKILL.md on the base branch');
+    let text;
+    try {
+      text = git(['show', `${baseRef}:${skillMd}`]);
+    } catch {
+      return out('no SKILL.md on the base branch');
+    }
+    if (reservedForPerson(text)) return out('reserved for the person');
+    const scripts = hasScripts(files);
+    if (scripts && !allowScripts.includes(name)) return out('has scripts and is not allowed');
+    return { name, path: skillMd, scripts };
+  }
+  return out(sawLink ? 'is a link to a folder that is not on the base branch' : 'not on the base branch');
+}
+
+/** Resolve the skills of a role (or of `fix`) from a resolved profile. */
+export function resolveRoleSkills({ role, profile, git, baseRef, allowScripts = [], dirs = SKILL_DIRS }) {
+  if (![...ROLES, 'fix'].includes(role)) throw new Error(`unknown role "${role}"; allowed: ${[...ROLES, 'fix'].join(', ')}`);
+  const names = [...new Set(rolesFor(role).flatMap((r) => profile.skills[r] ?? []))];
+  return names.map((name) => resolveSkill({ name, git, baseRef, allowScripts, dirs }));
+}
+
+/** Sum of the sizes (bytes) of the skills handed to one role, and whether it is over the budget. */
+export function skillBudget(sizes) {
+  const bytes = sizes.reduce((a, b) => a + b, 0);
+  return { bytes, over: bytes > SIZE_BUDGET_BYTES };
+}
+
+/**
+ * The hash `skills-lock.json` keeps for a skill folder: SHA-256 over its files, sorted by path without regard to
+ * case, each contributing its relative path and then its content. `files` is [{ path, content }].
+ * (Found by reproducing the `computedHash` of a lock file written by the skills installer.)
+ */
+export function folderHash(files) {
+  const h = createHash('sha256');
+  [...files].sort((a, b) => (a.path.toLowerCase() < b.path.toLowerCase() ? -1 : a.path.toLowerCase() > b.path.toLowerCase() ? 1 : 0)).forEach((f) => {
+    h.update(f.path);
+    h.update(f.content);
+  });
+  return h.digest('hex');
+}
+
+/** Names of the skills whose folder hash differs from the one in the lock file. `hashes` maps name to hash (or null when the folder is absent). */
+export function lockDifferences(lock, hashes) {
+  const skills = lock && typeof lock === 'object' && lock.skills && typeof lock.skills === 'object' ? lock.skills : {};
+  return Object.entries(skills)
+    .filter(([name, entry]) => hashes[name] !== undefined && hashes[name] !== null && entry?.computedHash && hashes[name] !== entry.computedHash)
+    .map(([name]) => name);
+}

package/scripts/lib/run-flags.mjs

@@ -0,0 +1,16 @@
+// The limits and the closed tool lists of an unattended run, written once. Implements "The limits of a run are
+// written once" of the go specification: the local run (`go-local.mjs`) uses this function and a test compares its
+// values with the `claude_args` of templates/workflows/relevo-go.yml, which people copy and so keeps literal values.
+
+export const ALLOWED_TOOLS = 'Bash,Read,Write,Edit,Glob,Grep,Task';
+export const DISALLOWED_TOOLS = 'WebFetch,WebSearch,Bash(curl:*),Bash(wget:*)';
+
+/** The `claude -p` arguments that bound a run: turns, cost, and the closed lists of tools. */
+export function runFlags(config) {
+  return [
+    '--max-turns', String(config.limits.run_max_turns),
+    '--max-budget-usd', String(config.limits.run_max_cost),
+    '--allowedTools', ALLOWED_TOOLS,
+    '--disallowedTools', DISALLOWED_TOOLS,
+  ];
+}

package/scripts/lib/run-usage.mjs

@@ -0,0 +1,65 @@
+// What a cloud run used, read from the execution log of the agent runner. Implements "The consumption of a run is
+// visible" of the execution-modes specification.
+//
+// The format of that log is not documented (only its path is an output of the action), so everything here is
+// tolerant: a JSON array, JSON lines or a single object are accepted, the last entry that looks like a result is
+// used, and anything missing is simply left out. Nothing found means nothing is said, never an error.
+
+function entries(text) {
+  const t = String(text ?? '').trim();
+  if (!t) return [];
+  try {
+    const whole = JSON.parse(t);
+    return Array.isArray(whole) ? whole : [whole];
+  } catch {
+    return t.split('\n').map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+  }
+}
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
+/** { turns, cost, tokens, cached } with null for what the log does not say, or null when it says none of them. */
+export function readUsage(text) {
+  const all = entries(text).filter((e) => e && typeof e === 'object');
+  const result = [...all].reverse().find((e) => e.type === 'result') ?? [...all].reverse().find((e) => num(e.num_turns) !== null);
+  if (!result) return null;
+  const input = num(result.usage?.input_tokens);
+  const output = num(result.usage?.output_tokens);
+  const usage = {
+    turns: num(result.num_turns),
+    cost: num(result.total_cost_usd),
+    tokens: input !== null || output !== null ? (input ?? 0) + (output ?? 0) : null,
+    // Tokens read from or written to the prompt cache are reported apart: they are most of a long run and the
+    // plain input/output figure alone looks far smaller than what the run really processed.
+    cached: num(result.usage?.cache_read_input_tokens) !== null || num(result.usage?.cache_creation_input_tokens) !== null
+      ? (num(result.usage?.cache_read_input_tokens) ?? 0) + (num(result.usage?.cache_creation_input_tokens) ?? 0)
+      : null,
+  };
+  return usage.turns === null && usage.cost === null && usage.tokens === null ? null : usage;
+}
+
+/** One line for a comment, or an empty string when there is nothing to say. */
+export function usageLine(usage, { subscription = false } = {}) {
+  if (!usage) return '';
+  const parts = [];
+  if (usage.turns !== null) parts.push(`${usage.turns} turn${usage.turns === 1 ? '' : 's'}`);
+  if (usage.cost !== null) parts.push(`about $${usage.cost.toFixed(2)}${subscription ? ' (notional: a subscription is not billed per run)' : ''}`);
+  if (usage.tokens !== null) parts.push(`${usage.tokens.toLocaleString('en-US')} tokens${usage.cached ? ` (plus ${usage.cached.toLocaleString('en-US')} from the cache)` : ''}`);
+  return parts.length ? `This run used ${parts.join(', ')}.` : '';
+}
+
+// Messages the Claude CLI and the API document for a usage limit, a quota or an empty credit balance. These patterns
+// are not from a failed run seen here (see docs/pilot-findings.md); a wrong guess only changes the wording of a
+// comment on a run that already failed.
+const LIMIT_RE = /usage limit|limit reached|rate[ _-]?limit|credit balance is too low|exceeded your (current )?quota|insufficient[ _]quota/i;
+
+/** Does the log show that a usage limit, a quota or the credit was reached? */
+export function reachedUsageLimit(text) {
+  return LIMIT_RE.test(String(text ?? ''));
+}

package/scripts/lib/scan.mjs

@@ -0,0 +1,73 @@
+// Scans for temporary markers and credentials.
+// Used before every commit, push and merge, and when validating relevo.yml.
+// Findings never include the secret itself, only what kind of secret it looks like.
+
+const MARKER_RE = /(\/\/|#|<!--|\/\*)\s*(NOCOMMIT|TEMP|DO NOT COMMIT)\b/;
+
+const CREDENTIAL_PATTERNS = [
+  { name: 'anthropic-key', re: /sk-ant-[A-Za-z0-9_-]{10,}/ },
+  { name: 'github-token', re: /\bgh[pousr]_[A-Za-z0-9]{20,}/ },
+  { name: 'github-fine-grained-token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/ },
+  { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { name: 'private-key', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+  {
+    name: 'assigned-secret',
+    re: /\b(api[_-]?key|secret|token|password|passwd)\b["']?\s*[:=]\s*["']?[A-Za-z0-9_\-/+=]{16,}/i,
+  },
+];
+
+// A long unbroken token is only suspicious in a configuration value, not in code.
+const OPAQUE_TOKEN_RE = /^[A-Za-z0-9+/_-]{40,}$/;
+
+/** Returns [{ name }] for every credential-looking pattern in `text`. */
+export function findCredentials(text, { strict = false } = {}) {
+  const found = CREDENTIAL_PATTERNS.filter(({ re }) => re.test(text)).map(({ name }) => ({ name }));
+  if (strict && OPAQUE_TOKEN_RE.test(text.trim())) found.push({ name: 'opaque-token' });
+  return found;
+}
+
+/** Returns the marker found in a line of text, or null. */
+export function findMarker(text) {
+  const m = text.match(MARKER_RE);
+  return m ? m[2] : null;
+}
+
+/**
+ * Scan a unified diff (for example `git diff --cached`). Only added lines are checked.
+ * Returns [{ file, line, kind: 'marker' | 'credential', detail }].
+ */
+export function scanDiff(diffText) {
+  const findings = [];
+  let file = null;
+  let line = 0;
+  String(diffText).split('\n').forEach((raw) => {
+    if (raw.startsWith('+++ ')) {
+      const target = raw.slice(4).trim();
+      file = target === '/dev/null' ? null : target.replace(/^b\//, '');
+      return;
+    }
+    if (raw.startsWith('--- ') || raw.startsWith('diff --git') || raw.startsWith('index ')) return;
+    const hunk = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunk) {
+      line = Number.parseInt(hunk[1], 10);
+      return;
+    }
+    if (raw.startsWith('+')) {
+      const added = raw.slice(1);
+      const marker = findMarker(added);
+      if (marker) findings.push({ file, line, kind: 'marker', detail: marker });
+      findCredentials(added).forEach(({ name }) => findings.push({ file, line, kind: 'credential', detail: name }));
+      line += 1;
+    } else if (raw.startsWith(' ')) {
+      line += 1;
+    }
+  });
+  return findings;
+}
+
+export function formatFindings(findings) {
+  return findings
+    .map((f) => `${f.file ?? '(unknown file)'}:${f.line}  ${f.kind === 'marker' ? 'temporary marker' : 'possible credential'} (${f.detail})`)
+    .join('\n');
+}