redlinegate 0.0.1

package/scripts/lib/dora.mjs

@@ -0,0 +1,133 @@
+// DORA metrics from data the collector already pulls, and nothing else.
+//
+// Two of the four are derivable from merged pull requests alone. The other two
+// are not, and this file says so rather than approximating them:
+//
+//   lead time for changes ....... first commit to merge, per pull request. Derived.
+//   change failure rate ......... share of merges that attracted a revert or a
+//                                 hotfix within a window. Derived, with its own
+//                                 caveat below.
+//   deployment frequency ........ needs the deployments API. Absent where a
+//                                 repository does not use it — NOT assumed to be
+//                                 "once per merge", which would silently report
+//                                 trunk-based teams and quarterly-release teams
+//                                 as identical.
+//   MTTR ........................ needs an incident feed. Explicitly out of scope
+//                                 in the roadmap, and not approximated here: a
+//                                 wrong MTTR is the number most likely to be
+//                                 quoted at a stakeholder who will act on it.
+//
+// The change-failure caveat, stated because the number will be quoted: a revert
+// or a hotfix is evidence of a failed change, not proof, and a team that fixes
+// forward without the word "hotfix" scores better than one that labels honestly.
+// It is a floor on the true rate, and every consumer is told so.
+
+const DAY = 86400000;
+
+/** Lead time in hours, per pull request, from first commit to merge. */
+export function leadTimes(records) {
+  const hours = [];
+  for (const record of records ?? []) {
+    const merged = Date.parse(record.merged_at ?? '');
+    const first = Date.parse(record.first_commit_at ?? '');
+    if (Number.isNaN(merged) || Number.isNaN(first)) continue;
+    if (merged < first) continue; // a rebase can move the commit date past the merge
+    hours.push((merged - first) / 3600000);
+  }
+  return hours.sort((a, b) => a - b);
+}
+
+/** The median, which is what DORA reports — a mean is dragged by one stale branch. */
+export function median(values) {
+  if (!values.length) return null;
+  const mid = Math.floor(values.length / 2);
+  return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+}
+
+const REVERT = /^revert[\s:"']|^revert\b/i;
+const HOTFIX = /\b(hotfix|hot-fix)\b/i;
+
+/**
+ * Change failure rate: the share of merged pull requests followed by a revert or
+ * a hotfix touching the same repository within `windowDays`.
+ *
+ * Returns null rather than 0 when there is nothing to divide. Zero here would
+ * read as "this estate never breaks anything", which is a claim no data supports.
+ */
+export function changeFailureRate(records, { windowDays = 7 } = {}) {
+  const merged = (records ?? []).filter((r) => r.merged_at);
+  if (merged.length === 0) return { rate: null, failures: 0, total: 0, reason: 'no merged pull requests in the window' };
+
+  const byRepo = new Map();
+  for (const record of merged) {
+    if (!byRepo.has(record.repo)) byRepo.set(record.repo, []);
+    byRepo.get(record.repo).push(record);
+  }
+
+  let failures = 0;
+  for (const [, list] of byRepo) {
+    const sorted = [...list].sort((a, b) => Date.parse(a.merged_at) - Date.parse(b.merged_at));
+    for (let i = 0; i < sorted.length; i += 1) {
+      const at = Date.parse(sorted[i].merged_at);
+      // A pull request "failed" when a later one in the same repository, inside
+      // the window, is a revert or a hotfix. The remediation itself is not
+      // counted as a failure of its own, or every incident would score twice.
+      const remedied = sorted.slice(i + 1).some((later) => {
+        const gap = Date.parse(later.merged_at) - at;
+        if (gap < 0 || gap > windowDays * DAY) return false;
+        const title = later.title ?? '';
+        return REVERT.test(title) || HOTFIX.test(title);
+      });
+      if (remedied && !REVERT.test(sorted[i].title ?? '') && !HOTFIX.test(sorted[i].title ?? '')) {
+        failures += 1;
+      }
+    }
+  }
+
+  return {
+    rate: failures / merged.length,
+    failures,
+    total: merged.length,
+    // Carried with the number, not buried in a doc. It will be quoted.
+    caveat:
+      'A floor, not the true rate: a revert or hotfix is evidence of a failed change rather than proof, ' +
+      'and a team that fixes forward without saying "hotfix" scores better than one that labels honestly.',
+  };
+}
+
+/**
+ * Deployment frequency, from deployment timestamps the caller supplies.
+ *
+ * Absent — not zero, and not "once per merge" — where a repository does not use
+ * the deployments API. Assuming a merge is a deploy reports a trunk-based team
+ * and a quarterly-release team as identical, which is the exact distinction the
+ * metric exists to draw.
+ */
+export function deploymentFrequency(deployments, windowDays) {
+  if (deployments === null || deployments === undefined) {
+    return { perDay: null, reason: 'this repository does not use the deployments API — frequency is unknown, not zero' };
+  }
+  if (windowDays <= 0) return { perDay: null, reason: 'no window to divide by' };
+  return { perDay: deployments.length / windowDays, count: deployments.length };
+}
+
+/** The DORA block, with every unavailable figure carrying its reason. */
+export function dora(records, { windowDays = 90, deployments = null } = {}) {
+  const times = leadTimes(records);
+  const cfr = changeFailureRate(records, { windowDays: 7 });
+  const freq = deploymentFrequency(deployments, windowDays);
+
+  return {
+    leadTimeHours: times.length
+      ? { median: median(times), p90: times[Math.floor(times.length * 0.9)] ?? null, samples: times.length }
+      : { median: null, p90: null, samples: 0, reason: 'no pull request in the window carries a first-commit timestamp' },
+    changeFailureRate: cfr,
+    deploymentFrequency: freq,
+    // Named so a reader can see it was considered and refused, rather than
+    // wondering whether it was forgotten.
+    meanTimeToRestore: {
+      value: null,
+      reason: 'needs an incident feed Redline does not have and should not acquire — out of scope in the roadmap',
+    },
+  };
+}

package/scripts/lib/exemptions.mjs

@@ -0,0 +1,79 @@
+// Reads the structured exemption block out of a pull request body, for telemetry.
+//
+// Deliberately a mirror of cli/exempt/parse.ts rather than an import: the
+// collector is plain .mjs running in the metrics repo with no build step, and it
+// must not depend on dist/. The two are kept honest by scripts/validate.mjs,
+// which fails the build if the heading or the field names diverge — the failure
+// mode this guards against is the gate accepting a block the audit cannot read,
+// so an exemption is enforced and then never reported.
+
+export const EXEMPTION_HEADING = '## Redline exemption';
+
+// See cli/exempt/parse.ts: the template's own guidance comment contains the field
+// names, so a parser that does not strip comments reads the instructions.
+const withoutComments = (text) => text.replace(/<!--[\s\S]*?-->/g, '');
+
+const field = (block, name) => {
+  const match = new RegExp(`^\\s*[-*]?\\s*${name}\\s*:\\s*(.+)$`, 'im').exec(block);
+  return match?.[1]?.trim() ?? null;
+};
+
+/**
+ * @returns {{reason: string, until: string, scope: string[]} | null}
+ */
+export function readExemption(body) {
+  if (!body) return null;
+  const searchable = withoutComments(body);
+  const start = searchable.toLowerCase().indexOf(EXEMPTION_HEADING.toLowerCase());
+  if (start === -1) return null;
+
+  const rest = searchable.slice(start + EXEMPTION_HEADING.length);
+  const next = /^#{1,2}\s/m.exec(rest);
+  const block = next ? rest.slice(0, next.index) : rest;
+
+  const reason = field(block, 'reason');
+  const until = field(block, 'until');
+  if (!reason || !until) return null;
+  // A string compare against today treats an unparseable date as standing
+  // forever, which is the direction that quietly hides a problem.
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(until) || Number.isNaN(Date.parse(until))) return null;
+
+  const scopeField = field(block, 'scope');
+  return {
+    reason,
+    until,
+    scope: scopeField
+      ? scopeField.split(',').map((s) => s.trim()).filter(Boolean)
+      : ['*'],
+  };
+}
+
+/**
+ * Standing exemptions: those still in force, grouped by scope, most-used first.
+ * A team routing around the gate shows up here as the same scope recurring
+ * across pull requests — which is the signal the roadmap's guardrail wants, and
+ * one a per-pull-request view can never show.
+ */
+export function standingExemptions(records, now = new Date()) {
+  const today = now.toISOString().slice(0, 10);
+  const byScope = new Map();
+
+  for (const record of records) {
+    const exemption = record.exemption;
+    if (!exemption) continue;
+    // An expired exemption is history, not a standing one. Counting it would
+    // make a resolved problem look permanent.
+    if (exemption.until < today) continue;
+    for (const scope of exemption.scope) {
+      const entry = byScope.get(scope) ?? { scope, count: 0, repos: new Set(), soonest: exemption.until };
+      entry.count += 1;
+      entry.repos.add(record.repo);
+      if (exemption.until < entry.soonest) entry.soonest = exemption.until;
+      byScope.set(scope, entry);
+    }
+  }
+
+  return [...byScope.values()]
+    .map((e) => ({ scope: e.scope, count: e.count, repos: e.repos.size, soonest: e.soonest }))
+    .sort((a, b) => b.count - a.count || a.scope.localeCompare(b.scope));
+}

package/scripts/lib/metrics.mjs

@@ -0,0 +1,172 @@
+// Shared telemetry aggregation. The digest and the dashboard must not disagree about
+// what "acted on" means, so both read their numbers from here.
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Loads telemetry records, optionally filtered to those merged since an ISO timestamp.
+ */
+export function loadRecords(dataDir = 'data', sinceIso = null) {
+  const records = [];
+  const problems = [];
+  if (!existsSync(dataDir)) return { records, problems: ['data directory is missing'] };
+
+  for (const file of readdirSync(dataDir).filter((f) => /^\d{4}-\d{2}\.jsonl$/.test(f))) {
+    const lines = readFileSync(join(dataDir, file), 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      if (!line.trim()) return;
+      try {
+        const record = JSON.parse(line);
+        if (sinceIso && (record.merged_at ?? '') < sinceIso) return;
+        records.push(record);
+      } catch {
+        // One malformed line must not silence the whole report.
+        problems.push(`${file}:${i + 1} is not valid JSON`);
+      }
+    });
+  }
+  records.sort((a, b) => (a.merged_at ?? '').localeCompare(b.merged_at ?? ''));
+  return { records, problems };
+}
+
+const staleOf = (record) =>
+  Object.values(record.outcomes?.stale_by_severity ?? {}).reduce((a, b) => a + b, 0);
+
+export function aggregate(records) {
+  const sum = (fn) => records.reduce((n, r) => n + (fn(r) ?? 0), 0);
+
+  const byRule = new Map();
+  const byRepo = new Map();
+  const reviewers = new Set();
+
+  for (const record of records) {
+    for (const [ruleId, stats] of Object.entries(record.rules ?? {})) {
+      const entry = byRule.get(ruleId) ?? { fired: 0, resolved: 0, stale: 0, repos: new Set(), severity: stats.severity };
+      entry.fired += stats.fired ?? 0;
+      entry.resolved += stats.resolved ?? 0;
+      entry.stale += stats.stale ?? 0;
+      entry.repos.add(record.repo);
+      byRule.set(ruleId, entry);
+    }
+    const repo = byRepo.get(record.repo) ?? { prs: 0, findings: 0, blocker: 0, stale: 0, exempted: 0 };
+    repo.prs += 1;
+    repo.findings += record.findings?.total ?? 0;
+    repo.blocker += record.findings?.blocker ?? 0;
+    repo.stale += staleOf(record);
+    repo.exempted += record.exempted ? 1 : 0;
+    byRepo.set(record.repo, repo);
+    for (const reviewer of record.reviewers ?? []) reviewers.add(reviewer);
+  }
+
+  const findings = sum((r) => r.findings?.total);
+
+  // Ingested scanner findings, aggregated ALONGSIDE Redline's own and never into
+  // them. Every number above this line describes Redline's own catalogue and is
+  // what rule tuning reads; folding another tool's rule ids in would tune
+  // Redline's rules on that tool's noise. Reported separately, they answer a
+  // question neither tool can answer alone: what the estate's whole finding
+  // surface looks like under one severity contract.
+  // Once per repository, not once per pull request. A scanner alert count is a
+  // fact about the repository; every merged PR in that repo carries the same
+  // snapshot, so summing them multiplied the estate's ingested findings by the
+  // number of merges. The most recent record per repo wins — records are sorted
+  // by merge time, so that is the freshest snapshot.
+  const scannerByRepo = new Map();
+  for (const record of records) {
+    if (!record.scanner) continue;
+    scannerByRepo.set(record.repo, record.scanner);
+  }
+
+  const scannerByTool = new Map();
+  const scannerBySeverity = { blocker: 0, high: 0, suggestion: 0 };
+  let scannerTotal = 0;
+  for (const scanner of scannerByRepo.values()) {
+    scannerTotal += scanner.findings ?? 0;
+    for (const [tool, n] of Object.entries(scanner.by_tool ?? {})) {
+      scannerByTool.set(tool, (scannerByTool.get(tool) ?? 0) + n);
+    }
+    for (const [severity, n] of Object.entries(scanner.by_severity ?? {})) {
+      if (severity in scannerBySeverity) scannerBySeverity[severity] += n;
+    }
+  }
+
+  return {
+    scanner: {
+      findings: scannerTotal,
+      bySeverity: scannerBySeverity,
+      byTool: [...scannerByTool.entries()]
+        .map(([tool, findings]) => ({ tool, findings }))
+        .sort((a, b) => b.findings - a.findings),
+      // How many repositories in this window emit anything at all. This is the
+      // number that decides whether Phase 1 was worth doing, and the roadmap's
+      // open question 1 asks for exactly it.
+      repos: [...scannerByRepo.values()].filter((s) => (s.findings ?? 0) > 0).length,
+    },
+    prs: records.length,
+    prsWithFindings: records.filter((r) => (r.findings?.total ?? 0) > 0).length,
+    findings,
+    blocker: sum((r) => r.findings?.blocker),
+    high: sum((r) => r.findings?.high),
+    suggestion: sum((r) => r.findings?.suggestion),
+    resolved: sum((r) => r.outcomes?.resolved),
+    stale: sum(staleOf),
+    untagged: sum((r) => r.untagged_findings),
+    withoutRuleId: sum((r) => r.findings_without_rule_id),
+    unknownRuleIds: sum((r) => r.unknown_rule_ids),
+    exempted: records.filter((r) => r.exempted).length,
+    humanThreads: sum((r) => r.human_review_threads),
+    reviewers: [...reviewers],
+    repos: byRepo.size,
+    byRepo: [...byRepo.entries()]
+      .map(([repo, s]) => ({ repo, ...s }))
+      .sort((a, b) => b.blocker - a.blocker || b.findings - a.findings),
+    byRule: [...byRule.entries()]
+      .map(([id, s]) => ({
+        id,
+        severity: s.severity,
+        fired: s.fired,
+        resolved: s.resolved,
+        stale: s.stale,
+        repos: s.repos.size,
+        // Ignored rate is the noise metric: fired a lot, acted on rarely.
+        ignoredRate: s.fired ? s.stale / s.fired : 0,
+        actedRate: s.fired ? s.resolved / s.fired : 0,
+      }))
+      .sort((a, b) => b.fired - a.fired),
+  };
+}
+
+/** Rules that fire often and are acted on rarely — the tuning queue. */
+export function noisiestRules(agg, { minFired = 5, minIgnoredRate = 0.3, limit = 5 } = {}) {
+  return agg.byRule
+    .filter((r) => r.id !== '(untagged)' && r.fired >= minFired && r.ignoredRate >= minIgnoredRate)
+    .sort((a, b) => b.ignoredRate - a.ignoredRate || b.fired - a.fired)
+    .slice(0, limit);
+}
+
+/** Rules that fire often and are almost always acted on — evidence they earn their place. */
+export function mostValuableRules(agg, { minFired = 5, limit = 5 } = {}) {
+  return agg.byRule
+    .filter((r) => r.id !== '(untagged)' && r.fired >= minFired)
+    .sort((a, b) => b.actedRate - a.actedRate || b.fired - a.fired)
+    .slice(0, limit);
+}
+
+/** Buckets records into calendar weeks for trend lines. */
+export function weekly(records) {
+  const weeks = new Map();
+  for (const record of records) {
+    const date = new Date(record.merged_at ?? Date.now());
+    const monday = new Date(date);
+    monday.setUTCDate(date.getUTCDate() - ((date.getUTCDay() + 6) % 7));
+    const key = monday.toISOString().slice(0, 10);
+    if (!weeks.has(key)) weeks.set(key, []);
+    weeks.get(key).push(record);
+  }
+  return [...weeks.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([week, rows]) => ({ week, ...aggregate(rows) }));
+}
+
+export const pct = (n, d) => (d === 0 ? '—' : `${Math.round((n / d) * 100)}%`);

package/scripts/lib/rules.mjs

@@ -0,0 +1,107 @@
+// Shared rule catalogue and finding parser.
+//
+// Every consumer of review output — telemetry, seed scoring, the digest, the dashboard —
+// must agree on what a rule id is and how a finding is parsed. Keeping that in one place
+// is the difference between "our numbers disagree" and a working feedback loop.
+
+import { readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export const SEVERITIES = ['BLOCKER', 'HIGH', 'SUGGESTION'];
+export const RANK = { SUGGESTION: 1, HIGH: 2, BLOCKER: 3 };
+
+// Reserved ids that are not bullets in the standards.
+export const RESERVED_RULE_IDS = new Set(['core/uncatalogued']);
+
+export const RULE_ID = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+const RULE_LINE = /^-\s+`([a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*)`\s+—\s+(.*)$/;
+const RULE_HEADING = /^#{2,3}\s+(BLOCKER|HIGH|SUGGESTION|Security|Type safety|Error handling|General correctness|Scope discipline)\b/i;
+const ANY_HEADING = /^#{1,6}\s/;
+
+// A finding's first line, e.g. "Redline/BLOCKER [react/key-is-index]: ...".
+// The id group is optional so pre-2.1 repos still parse, reported as untagged.
+const FINDING = /(?:^|\n)\s*(?:[*_`>-]*\s*)?Redline\/(BLOCKER|HIGH|SUGGESTION)\b\s*(?:\[\s*`?([a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*)`?\s*\])?/i;
+const BARE_SEVERITY = /\b(BLOCKER|HIGH|SUGGESTION)\b/;
+
+// Logins that count as automated review. Substring match, case-insensitive.
+export const REVIEW_BOTS = ['copilot', 'claude', 'codex', 'cursor', 'devin', 'jules', 'redline'];
+export const isReviewBot = (login = '') =>
+  REVIEW_BOTS.some((bot) => login.toLowerCase().includes(bot));
+
+/**
+ * Reads every rule out of the standards sources.
+ * @returns {Map<string, {id, stack, severity, text, source, line}>}
+ */
+export function loadRules(root = ROOT) {
+  const manifest = JSON.parse(readFileSync(join(root, 'standards/manifest.json'), 'utf8'));
+  const sources = [
+    ['core', manifest.core.source],
+    ...Object.entries(manifest.stacks).map(([id, s]) => [id, s.source]),
+  ];
+
+  const rules = new Map();
+  for (const [stack, relPath] of sources) {
+    const lines = readFileSync(join(root, relPath), 'utf8').split('\n');
+    let severity = null;
+    let inFence = false;
+
+    lines.forEach((line, i) => {
+      if (/^```/.test(line.trim())) inFence = !inFence;
+      if (inFence) return;
+
+      if (ANY_HEADING.test(line)) {
+        const heading = RULE_HEADING.exec(line);
+        if (!heading) {
+          severity = null;
+          return;
+        }
+        const word = heading[1].toUpperCase();
+        // Core groups rules by topic, not severity; each section states its own default.
+        severity = SEVERITIES.includes(word) ? word : /BLOCKER/i.test(line) ? 'BLOCKER' : 'HIGH';
+        return;
+      }
+      if (!severity) return;
+
+      const rule = RULE_LINE.exec(line);
+      if (!rule) return;
+      rules.set(rule[1], {
+        id: rule[1],
+        stack,
+        severity,
+        text: rule[2].replace(/\*\*/g, '').trim(),
+        source: relPath,
+        line: i + 1,
+      });
+    });
+  }
+  return rules;
+}
+
+/**
+ * Parses a review comment body into a finding.
+ * @returns {{severity, ruleId: string|null, tagged: boolean, hasRuleId: boolean}}
+ */
+export function parseFinding(body = '') {
+  const match = FINDING.exec(body);
+  if (match) {
+    return {
+      severity: match[1].toUpperCase(),
+      ruleId: match[2] ? match[2].toLowerCase() : null,
+      tagged: true,
+      hasRuleId: Boolean(match[2]),
+    };
+  }
+  const bare = BARE_SEVERITY.exec(body);
+  return {
+    severity: (bare?.[1] ?? 'SUGGESTION').toUpperCase(),
+    ruleId: null,
+    tagged: false,
+    hasRuleId: false,
+  };
+}
+
+export const emptyBySeverity = () =>
+  Object.fromEntries(SEVERITIES.map((s) => [s.toLowerCase(), 0]));

package/scripts/lib/sarif.mjs

@@ -0,0 +1,108 @@
+// Ingests code-scanning alerts as findings, alongside Redline's own.
+//
+// Mirrors cli/sarif/ for the collector, which runs in the metrics repo with no
+// build step to import dist/ from — the same arrangement as the exemption
+// parser, and guarded the same way by scripts/validate.mjs.
+//
+// The rule this file exists to hold: an ingested finding is ALWAYS distinguishable
+// from a Redline one. Redline's claim in Phase 1 is that it can measure LLM review
+// and static analysis against one severity contract without either distorting the
+// other, and rule tuning reads this stream. A view that cannot tell a CodeQL
+// finding from a Redline one tunes Redline's rules on another tool's noise, which
+// is the single way this piece can make things worse than not doing it.
+
+export const FALLBACK_SEVERITY = 'SUGGESTION';
+
+export const DEFAULT_SEVERITY_MAP = {
+  error: 'BLOCKER',
+  warning: 'HIGH',
+  note: 'SUGGESTION',
+  none: 'SUGGESTION',
+  critical: 'BLOCKER',
+  high: 'BLOCKER',
+  medium: 'HIGH',
+  moderate: 'HIGH',
+  low: 'SUGGESTION',
+  info: 'SUGGESTION',
+  informational: 'SUGGESTION',
+};
+
+export function mapSeverity(native, map = DEFAULT_SEVERITY_MAP) {
+  const word = String(native ?? '').trim();
+  const mapped = map[word.toLowerCase()];
+  return mapped
+    ? { severity: mapped, native: word, matched: true }
+    : { severity: FALLBACK_SEVERITY, native: word, matched: false };
+}
+
+/**
+ * GitHub code-scanning alerts into normalised findings.
+ *
+ * The alerts API is the practical ingestion point: it is what every SARIF upload
+ * on GitHub becomes, it carries the tool name and the rule id already separated,
+ * and it does not require the collector to fetch and parse raw SARIF blobs per
+ * pull request.
+ */
+export function ingestAlerts(alerts, { map = DEFAULT_SEVERITY_MAP, where = 'alerts' } = {}) {
+  const findings = [];
+  const problems = [];
+
+  for (const alert of alerts ?? []) {
+    const ruleId = alert?.rule?.id?.trim?.();
+    if (!ruleId) {
+      problems.push(`${where}: an alert has no rule id — skipped`);
+      continue;
+    }
+    // security_severity_level is present on security rules; severity is the
+    // SARIF level for everything else. Security first: it is the more specific
+    // statement when both exist.
+    const native = alert.rule.security_severity_level ?? alert.rule.severity;
+    const mapped = mapSeverity(native, map);
+    if (!mapped.matched && native) {
+      problems.push(`${where}: severity "${native}" is not in the severity map — ${ruleId} ingested as ${mapped.severity}`);
+    }
+
+    findings.push({
+      source: 'sarif',
+      tool: alert.tool?.name ?? 'unknown',
+      ruleId,
+      severity: mapped.severity,
+      nativeSeverity: mapped.native,
+      state: alert.state ?? 'unknown',
+      file: alert.most_recent_instance?.location?.path ?? null,
+      line: alert.most_recent_instance?.location?.start_line ?? null,
+    });
+  }
+
+  return { findings, problems };
+}
+
+/**
+ * Per-source aggregate. Two catalogues, never merged into one.
+ *
+ * Acted-on is computed within each source, never across them: Redline's is
+ * "review thread resolved", a scanner's is "alert closed", and averaging two
+ * different definitions produces a number that describes neither.
+ */
+export function aggregateBySource(findings) {
+  const bucket = () => ({ total: 0, blocker: 0, high: 0, suggestion: 0, acted: 0, byTool: {}, byRule: {} });
+  const out = { redline: bucket(), sarif: bucket() };
+
+  for (const finding of findings ?? []) {
+    const side = out[finding.source];
+    if (!side) continue;
+    side.total += 1;
+    side[finding.severity.toLowerCase()] += 1;
+    if (finding.acted) side.acted += 1;
+    side.byTool[finding.tool] = (side.byTool[finding.tool] ?? 0) + 1;
+    const rule = side.byRule[finding.ruleId] ?? { fired: 0, acted: 0, severity: finding.severity };
+    rule.fired += 1;
+    if (finding.acted) rule.acted += 1;
+    side.byRule[finding.ruleId] = rule;
+  }
+
+  for (const side of Object.values(out)) {
+    side.actedRate = side.total > 0 ? side.acted / side.total : null;
+  }
+  return out;
+}

package/scripts/lib/spend.mjs

@@ -0,0 +1,69 @@
+// AI spend, at whatever grain the vendor's own reporting actually offers.
+//
+// The roadmap's open question 2 asks whether spend is attributable per repository
+// or only org-wide. The honest answer depends on the vendor and cannot be settled
+// in code, so this module carries the grain WITH the number and every consumer
+// reads it. The failure it prevents: an org-level figure divided by repository
+// count, presented as per-repository cost. That number looks precise, is entirely
+// invented, and is the one a stakeholder will act on.
+//
+// Redline cannot read a vendor's billing API for you. It takes the figure you
+// have, records where it came from, and refuses to make it more precise than it is.
+
+export const GRAINS = ['repo', 'org', 'unknown'];
+
+/**
+ * @param {{total: number, currency?: string, grain?: string, source?: string, period?: string}} input
+ */
+export function readSpend(input) {
+  if (!input || typeof input.total !== 'number' || !Number.isFinite(input.total)) {
+    return { available: false, reason: 'no AI spend figure was supplied — read it from the assistant vendor\'s usage reporting' };
+  }
+  if (input.total < 0) {
+    return { available: false, reason: `spend cannot be negative (${input.total})` };
+  }
+  const grain = GRAINS.includes(input.grain) ? input.grain : 'unknown';
+  return {
+    available: true,
+    total: input.total,
+    currency: input.currency ?? 'USD',
+    grain,
+    source: input.source ?? 'supplied by the operator',
+    period: input.period ?? null,
+  };
+}
+
+/**
+ * Cost per BLOCKER caught — the figure nobody else in the toolchain can compute.
+ *
+ * A cost-management tool knows spend and has no findings, so it cannot compute
+ * value. A DORA tool has neither. Redline knows which findings were acted on, and
+ * joining the two is the whole argument.
+ *
+ * It refuses in three cases rather than producing a misleading number:
+ *   - no spend figure at all
+ *   - no BLOCKERs in the window, which would divide by zero
+ *   - a per-repo question asked of an org-level figure
+ */
+export function costPerBlocker(spend, blockersCaught, { scope = 'org' } = {}) {
+  if (!spend?.available) {
+    return { value: null, reason: spend?.reason ?? 'no spend figure' };
+  }
+  if (!Number.isFinite(blockersCaught) || blockersCaught <= 0) {
+    return { value: null, reason: 'no BLOCKER findings were acted on in this window — nothing to divide by' };
+  }
+  if (scope === 'repo' && spend.grain !== 'repo') {
+    return {
+      value: null,
+      reason:
+        `spend is reported at ${spend.grain} grain, so it cannot be attributed per repository. ` +
+        'Publish the org-level figure against org-level value instead of inventing a per-repo number.',
+    };
+  }
+  return {
+    value: spend.total / blockersCaught,
+    currency: spend.currency,
+    grain: spend.grain,
+    blockersCaught,
+  };
+}