@verevoir/review 0.2.0 → 0.3.0

package/src/references.ts

@@ -0,0 +1,381 @@
+// Deterministic resolution of references in a diff's ADDED lines, so a lens can see whether
+// an `ADR 009` citation points at the right ADR, or a cited file path exists, instead of
+// guessing. No model call. Runs only when there is a context root.
+//
+// Scanned: ADR references (`ADR 009`, `ADR-009`, `ADR 9`) and repo-relative file paths with
+// common extensions, optionally with `:line`. Only lines the change ADDS are scanned.
+//
+// SAFETY: same rules as context-files.ts. A cited path with a `..` segment, an absolute path
+// or a NUL is refused without being touched; a path or ADR file that resolves (through a
+// symlink) outside the context root is refused. The ADR search lists directories to a depth of
+// 4 and skips node_modules, .git and dist.
+
+import { diffPaths, unsafePathReason } from './context-files.js';
+import type { ContextFs } from './context-files.js';
+
+/** At most this many distinct references are resolved; the rest are counted, not resolved. */
+export const MAX_REFERENCES = 40;
+
+/** Directory levels below the root that the ADR search lists. */
+export const ADR_SEARCH_DEPTH = 4;
+
+/** The basename search visits at most this many entries before it stops and says so. */
+export const MAX_SEARCH_FILES = 5000;
+
+/** Directory levels below the root that the basename search descends. */
+export const BASENAME_SEARCH_DEPTH = 8;
+
+export interface ReferenceOptions {
+  /** Overrides MAX_SEARCH_FILES (tests). */
+  readonly maxSearchFiles?: number;
+}
+
+const SKIPPED_DIRS = new Set(['node_modules', '.git', 'dist']);
+const ADR_DIRS = new Set(['adrs', 'adr']);
+
+export interface DirEntry {
+  readonly name: string;
+  readonly isDir: boolean;
+}
+
+export interface ReferenceFs extends ContextFs {
+  /** List a directory's entries. Absent where the host cannot list directories. */
+  readonly listDir?: (path: string) => Promise<DirEntry[]>;
+}
+
+export interface AddedLine {
+  readonly file: string;
+  readonly line: number;
+  readonly text: string;
+}
+
+/** Lines the diff adds, with the file and new-side line number of each. */
+export function addedLines(diff: string): AddedLine[] {
+  const out: AddedLine[] = [];
+  let file = '';
+  let inHunk = false;
+  let next = 0;
+  for (const line of diff.split(/\r?\n/)) {
+    if (line.startsWith('diff --git ')) {
+      inHunk = false;
+      continue;
+    }
+    if (!inHunk && line.startsWith('+++ ')) {
+      const raw = line.slice(4).split('\t')[0]?.trim() ?? '';
+      file = raw === '/dev/null' ? '' : raw.replace(/^b\//, '');
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hunk !== null) {
+      inHunk = true;
+      next = Number(hunk[1]);
+      continue;
+    }
+    if (!inHunk) continue;
+    if (line.startsWith('+')) {
+      out.push({ file, line: next, text: line.slice(1) });
+      next++;
+    } else if (line.startsWith(' ')) {
+      next++;
+    }
+  }
+  return out;
+}
+
+export interface Reference {
+  readonly kind: 'adr' | 'path';
+  /** ADR number (adr) or the cited path (path). */
+  readonly target: string;
+  /** The text as written, e.g. `ADR 9`. */
+  readonly display: string;
+  /** Where it was cited, `file:line`. */
+  readonly where: string;
+}
+
+const ADR_RE = /\bADR[ -]?0*(\d{1,4})\b/gi;
+const PATH_RE =
+  /(?<![\w./-])((?:[\w.-]+\/)*[\w.-]+\.(?:md|ts|tsx|js|mjs|cjs|json|yml|yaml|sh))(?::(\d+))?(?![\w-])/g;
+
+/** Distinct references in the added lines, in order of first appearance. */
+export function findReferences(diff: string): Reference[] {
+  const seen = new Set<string>();
+  const out: Reference[] = [];
+  for (const added of addedLines(diff)) {
+    const where = `${added.file === '' ? '(unknown file)' : added.file}:${String(added.line)}`;
+    for (const m of added.text.matchAll(ADR_RE)) {
+      const target = String(Number(m[1]));
+      const key = `adr:${target}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ kind: 'adr', target, display: m[0], where });
+    }
+    for (const m of added.text.matchAll(PATH_RE)) {
+      const target = m[1] ?? '';
+      const key = `path:${target}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ kind: 'path', target, display: m[0], where });
+    }
+  }
+  return out;
+}
+
+function isAbsent(cause: unknown): boolean {
+  const code = (cause as { code?: unknown }).code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
+function describe(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+interface Root {
+  readonly real: string;
+  readonly prefix: string;
+}
+
+function inside(root: Root, real: string): boolean {
+  return real === root.real || real.startsWith(root.prefix);
+}
+
+/** Relative paths of every file directly inside an `adrs` / `adr` directory, depth-limited. */
+async function adrFiles(root: Root, fs: ReferenceFs): Promise<string[] | undefined> {
+  const list = fs.listDir;
+  if (list === undefined) return undefined;
+  const found: string[] = [];
+  const queue: { rel: string; depth: number }[] = [{ rel: '', depth: 0 }];
+  while (queue.length > 0) {
+    const { rel, depth } = queue.shift() ?? { rel: '', depth: 0 };
+    let entries: DirEntry[];
+    try {
+      entries = await list(rel === '' ? root.real : `${root.prefix}${rel}`);
+    } catch {
+      continue;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+      if (entry.isDir) {
+        if (SKIPPED_DIRS.has(entry.name)) continue;
+        if (ADR_DIRS.has(entry.name.toLowerCase())) {
+          try {
+            for (const inner of await list(`${root.prefix}${childRel}`)) {
+              if (!inner.isDir) found.push(`${childRel}/${inner.name}`);
+            }
+          } catch {
+            // an unreadable ADR directory simply contributes nothing
+          }
+        }
+        if (depth + 1 < ADR_SEARCH_DEPTH) queue.push({ rel: childRel, depth: depth + 1 });
+      }
+    }
+  }
+  return found;
+}
+
+function firstHeading(text: string): string | undefined {
+  const match = /^# (.+?)[ \t]*$/m.exec(text);
+  return match?.[1]?.trim();
+}
+
+async function resolveAdr(
+  ref: Reference,
+  root: Root,
+  files: string[] | undefined,
+  fs: ReferenceFs,
+): Promise<string> {
+  if (files === undefined) return 'could not be searched (this host cannot list directories)';
+  const pattern = new RegExp(`^0*${ref.target}-`);
+  const hits = files.filter((rel) => pattern.test(rel.slice(rel.lastIndexOf('/') + 1)));
+  if (hits.length === 0) return 'not found in this repository';
+  const parts: string[] = [];
+  for (const rel of hits) {
+    try {
+      const real = await fs.realpath(`${root.prefix}${rel}`);
+      if (!inside(root, real)) {
+        parts.push(`${rel} (refused: resolves outside the context root)`);
+        continue;
+      }
+      const title = firstHeading(await fs.readFile(real));
+      parts.push(title === undefined ? `${rel} (no title)` : `${rel}: '${title}'`);
+    } catch (cause) {
+      parts.push(`${rel} (could not be read: ${describe(cause)})`);
+    }
+  }
+  return parts.join('; ');
+}
+
+interface BasenameSearch {
+  readonly matches: string[];
+  readonly capped: boolean;
+  readonly searchable: boolean;
+}
+
+/** Breadth-first search for files named `name`, bounded by depth and entries visited. */
+async function findByBasename(
+  root: Root,
+  fs: ReferenceFs,
+  name: string,
+  maxVisited: number,
+): Promise<BasenameSearch> {
+  const list = fs.listDir;
+  if (list === undefined) return { matches: [], capped: false, searchable: false };
+  const matches: string[] = [];
+  const queue: { rel: string; depth: number }[] = [{ rel: '', depth: 0 }];
+  let visited = 0;
+  while (queue.length > 0) {
+    const { rel, depth } = queue.shift() ?? { rel: '', depth: 0 };
+    let entries: DirEntry[];
+    try {
+      entries = await list(rel === '' ? root.real : `${root.prefix}${rel}`);
+    } catch {
+      continue;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      visited++;
+      if (visited > maxVisited) return { matches, capped: true, searchable: true };
+      const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+      if (entry.isDir) {
+        if (SKIPPED_DIRS.has(entry.name)) continue;
+        if (depth + 1 < BASENAME_SEARCH_DEPTH) queue.push({ rel: childRel, depth: depth + 1 });
+      } else if (entry.name === name) {
+        matches.push(childRel);
+      }
+    }
+  }
+  return { matches, capped: false, searchable: true };
+}
+
+function basenameOf(path: string): string {
+  return path.slice(path.lastIndexOf('/') + 1);
+}
+
+async function isRootDir(root: Root, fs: ReferenceFs, name: string): Promise<boolean> {
+  try {
+    const real = await fs.realpath(`${root.prefix}${name}`);
+    return inside(root, real);
+  } catch {
+    return false;
+  }
+}
+
+const OWNER_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
+async function resolvePath(
+  ref: Reference,
+  root: Root,
+  fs: ReferenceFs,
+  deleted: readonly string[],
+  maxVisited: number,
+): Promise<string> {
+  const unsafe = unsafePathReason(ref.target);
+  if (unsafe !== undefined) return `refused (${unsafe})`;
+  const segments = ref.target.split('/');
+  const bare = segments.length === 1;
+
+  // A real repo-relative path always wins.
+  try {
+    const real = await fs.realpath(`${root.prefix}${ref.target}`);
+    if (!inside(root, real)) return 'refused (resolves outside the context root)';
+    const stat = await fs.statFile(real);
+    return stat.isFile ? 'exists' : 'exists but is not a regular file';
+  } catch (cause) {
+    if (!isAbsent(cause)) return `could not be checked (${describe(cause)})`;
+  }
+
+  // An exact repo-relative path the diff deletes.
+  if (!bare && deleted.includes(ref.target)) return 'deleted by this change';
+
+  if (bare) {
+    // Surviving files win; a deleted copy only matters when none survives.
+    const deletedCopies = deleted.filter((d) => basenameOf(d) === ref.target);
+    const found = await findByBasename(root, fs, ref.target, maxVisited);
+    if (!found.searchable) {
+      return deletedCopies.length > 0
+        ? `deleted by this change (${deletedCopies.join(', ')})`
+        : 'not found at the context root (cannot search elsewhere: this host cannot list ' +
+            'directories)';
+    }
+    const capNote = found.capped ? ' (search capped)' : '';
+    const deletedNote =
+      deletedCopies.length > 0
+        ? `; a copy at ${deletedCopies.join(', ')} was deleted by this change`
+        : '';
+    if (found.matches.length === 1) return `${found.matches[0] ?? ''}${capNote}${deletedNote}`;
+    if (found.matches.length > 1) {
+      return (
+        `ambiguous: ${String(found.matches.length)} matches, e.g. ` +
+        `${found.matches.slice(0, 2).join(', ')}${capNote}${deletedNote}`
+      );
+    }
+    if (deletedCopies.length > 0) return `deleted by this change (${deletedCopies.join(', ')})`;
+    return found.capped
+      ? 'not found in the part of this repository searched (search capped)'
+      : 'not found anywhere in this repository';
+  }
+
+  // owner/repo/... where neither first segment is a real directory here: another repository.
+  const [owner = '', repo = ''] = segments;
+  if (
+    segments.length >= 3 &&
+    OWNER_RE.test(owner) &&
+    !(await isRootDir(root, fs, owner)) &&
+    !(await isRootDir(root, fs, `${owner}/${repo}`))
+  ) {
+    return 'external (another repository), not checked';
+  }
+  return 'not found in this repository';
+}
+
+/**
+ * The body of the "References in added lines" section for `diff`, resolved against `rootPath`.
+ * Throws only when the root itself cannot be resolved.
+ */
+export async function buildReferences(
+  diff: string,
+  rootPath: string,
+  fs: ReferenceFs,
+  options: ReferenceOptions = {},
+): Promise<string> {
+  const maxVisited = options.maxSearchFiles ?? MAX_SEARCH_FILES;
+  const deleted = diffPaths(diff)
+    .filter((p) => p.deleted && p.path !== '')
+    .map((p) => p.path);
+  let real: string;
+  try {
+    real = await fs.realpath(rootPath);
+  } catch (cause) {
+    throw new Error(`--context-root ${rootPath} could not be resolved: ${describe(cause)}`);
+  }
+  const root: Root = { real, prefix: real.endsWith('/') ? real : `${real}/` };
+
+  const all = findReferences(diff);
+  if (all.length === 0) return 'No ADR or file references were found in the added lines.';
+  const refs = all.slice(0, MAX_REFERENCES);
+
+  let adrs: string[] | undefined;
+  let adrsSearched = false;
+  const lines: string[] = [];
+  for (const ref of refs) {
+    let result: string;
+    if (ref.kind === 'adr') {
+      if (!adrsSearched) {
+        adrs = await adrFiles(root, fs);
+        adrsSearched = true;
+      }
+      result = await resolveAdr(ref, root, adrs, fs);
+    } else {
+      result = await resolvePath(ref, root, fs, deleted, maxVisited);
+    }
+    const shown = ref.kind === 'adr' ? ref.display : `\`${ref.display}\``;
+    lines.push(`- ${shown} (${ref.where}) → ${result}`);
+  }
+  if (all.length > refs.length) {
+    lines.push(
+      `- … and ${String(all.length - refs.length)} more reference(s) not resolved ` +
+        `(limit ${String(MAX_REFERENCES)}).`,
+    );
+  }
+  return lines.join('\n');
+}

package/src/report.ts

@@ -20,11 +20,28 @@ const HEADING: Record<Outcome, string> = {
   out_of_scope: 'Nothing in scope',
 };
 
+/** One de-duplicated finding: the group's highest tier, its first member, and who raised it. */
+export interface DedupGroupView {
+  readonly blocking: boolean;
+  readonly finding: Finding;
+  readonly raisedBy: readonly { readonly lens: string; readonly practices: readonly string[] }[];
+}
+
 export interface ReportContext {
   /** Where the lens set was read from, so a reader knows whose bar this was. */
   readonly source: string;
   /** What was reviewed. */
   readonly subject: string;
+  /** De-duplicated findings (replaces the per-lens finding lists), from `total` raised. */
+  readonly dedup?: { readonly groups: readonly DedupGroupView[]; readonly total: number };
+  /** Why de-duplication did not happen, said in one line. */
+  readonly dedupSkipped?: string;
+}
+
+function raisedByText(view: DedupGroupView): string {
+  return view.raisedBy
+    .map((r) => (r.practices.length === 0 ? r.lens : `${r.lens} (${r.practices.join(', ')})`))
+    .join(', ');
 }
 
 /**
@@ -50,6 +67,14 @@ function findingsByLens(findings: readonly Finding[]): Map<string, Finding[]> {
   return grouped;
 }
 
+/** `lens: verdict` plus the lens's own one-line reason when it gave one. */
+function verdictHeading(lens: string, verdict: Verdict): string {
+  const result = verdict.results.find((r) => r.lens === lens);
+  if (result === undefined) return lens;
+  const reason = result.reason === undefined ? '' : result.reason.trim();
+  return reason === '' ? `${lens}: ${result.outcome}` : `${lens}: ${result.outcome}: ${reason}`;
+}
+
 export function renderReport(verdict: Verdict, context: ReportContext): string {
   const lines: string[] = [
     `## Review: ${HEADING[verdict.outcome]}`,
@@ -89,24 +114,67 @@ export function renderReport(verdict: Verdict, context: ReportContext): string {
   const grouped = findingsByLens(verdict.findings);
   const blockingCount = verdict.findings.filter((finding) => finding.blocking).length;
   const smellCount = verdict.findings.length - blockingCount;
-  if (grouped.size > 0) {
+  const dedup =
+    context.dedup !== undefined && context.dedup.groups.length > 0 ? context.dedup : undefined;
+  if (dedup !== undefined) {
+    const blocking = dedup.groups.filter((g) => g.blocking).length;
+    const smells = dedup.groups.length - blocking;
+    lines.push(
+      `### ${dedup.groups.length} finding(s)` +
+        (smells > 0 ? ` (${blocking} blocking, ${smells} non-blocking)` : '') +
+        `, de-duplicated from ${dedup.total} raised`,
+      '',
+    );
+    for (const group of dedup.groups) {
+      lines.push(`- [${group.blocking ? 'blocking' : 'smell'}] ${group.finding.summary}`);
+      const detail = group.finding.detail;
+      if (detail !== undefined && detail !== '') {
+        for (const detailLine of detail.split('\n')) {
+          lines.push(detailLine === '' ? '' : `  ${detailLine}`);
+        }
+      }
+      lines.push(`  raised by: ${raisedByText(group)}`);
+    }
+    lines.push('');
+    // Per-lens verdict lines are unchanged: every lens that reviewed gets its own.
+    lines.push('### Lens verdicts', '');
+    for (const r of verdict.results) {
+      if (r.outcome === 'approved' || r.outcome === 'rejected') {
+        lines.push(`#### ${verdictHeading(r.lens, verdict)}`, '');
+      }
+    }
+  } else if (grouped.size > 0) {
     lines.push(
       `### ${verdict.findings.length} finding(s)` +
         (smellCount > 0 ? ` (${blockingCount} blocking, ${smellCount} non-blocking)` : ''),
       '',
     );
     for (const [lens, findings] of grouped) {
-      lines.push(`#### ${lens}`, '');
+      lines.push(`#### ${verdictHeading(lens, verdict)}`, '');
       for (const finding of findings) {
         lines.push(`- [${finding.blocking ? 'blocking' : 'smell'}] ${finding.summary}`);
         if (finding.detail !== undefined && finding.detail !== '') {
-          lines.push(`  ${finding.detail}`);
+          for (const detailLine of finding.detail.split('\n')) {
+            lines.push(detailLine === '' ? '' : `  ${detailLine}`);
+          }
         }
       }
       lines.push('');
     }
   }
 
+  // Every lens gets a line: the approving ones, with no findings, are not otherwise
+  // visible. Lenses that did not run or had nothing in scope are listed above.
+  const quiet = verdict.results.filter((r) => r.outcome === 'approved' && !grouped.has(r.lens));
+  if (dedup === undefined && quiet.length > 0) {
+    if (grouped.size === 0) lines.push('### Lens verdicts', '');
+    for (const r of quiet) lines.push(`#### ${verdictHeading(r.lens, verdict)}`, '');
+  }
+
+  if (context.dedupSkipped !== undefined) {
+    lines.push(`De-duplication was skipped: ${context.dedupSkipped}.`, '');
+  }
+
   // BL-144: a substantiated rejection now wins the outcome WORD even when
   // lenses remain unrun (see verdict.ts's own header) — but that must never
   // read as "fix the findings above and this becomes approved". It cannot:

package/src/run-review.ts

@@ -40,6 +40,10 @@ import { selectReviewer } from './reviewer-selection.js';
 import type { HttpPost } from './reviewer-anthropic.js';
 import { describeThrown, type RawCall } from './raw-call.js';
 import { normaliseReviewerReply, type Reviewer } from './panel.js';
+import { warmFirst } from './warm-first.js';
+import { enforceTier } from './tier.js';
+import { dedupFindings, numberFindings, toGroupViews } from './dedup.js';
+import type { DedupGroupView } from './report.js';
 
 export type { ReviewAccount } from './review-account.js';
 
@@ -73,6 +77,17 @@ export interface ReviewNodeInput {
    * leaves every existing call site building its Reviewer exactly as
    * before. */
   readonly reviewer?: Reviewer;
+  /** Run the first lens alone, then fan out the rest, so they read the prompt
+   * cache it wrote. Only applies with 2 or more lenses. Off when absent. */
+  readonly warmFirst?: boolean;
+  /** Per lens id: the signal lines its [blocking] findings must quote (see tier.ts). A lens
+   * with no entry is left as it was. Absent: no tier enforcement. */
+  readonly tierSignals?: Readonly<Record<string, readonly string[]>>;
+  /** After the panel (and tier enforcement), make ONE extra call through the same reviewer to
+   * group findings that describe the same defect (see dedup.ts). Off when absent. */
+  readonly dedup?: boolean;
+  /** Per lens id: its practices, so a de-duplicated finding can name them. */
+  readonly practiceNames?: Readonly<Record<string, readonly { id: string; title: string }[]>>;
 }
 
 export interface ReviewNodeResult {
@@ -83,6 +98,8 @@ export interface ReviewNodeResult {
   /** Every prompt as dispatched, keyed by lens id — proof the fan shares
    * one prefix, rather than merely claiming it. */
   readonly prompts: ReadonlyMap<string, Prompt>;
+  /** How many [blocking] findings tier enforcement downgraded to smells (0 when none). */
+  readonly downgraded: number;
 }
 
 // RECORD-NEVER-PREDICT discipline: `onCall` is OPTIONAL so every existing
@@ -160,17 +177,48 @@ export async function runReviewNode(
           }
         };
 
-  const { verdict, prompts } = await runPanel(
-    input.lensSet,
-    input.subject,
-    observedReviewer,
-    input.practices,
-  );
+  // Outside the observer, so each lens's recorded wall time is its own call,
+  // not the time it spent waiting for the warm-up.
+  const dispatched =
+    input.warmFirst === true && input.lensSet.lenses.length >= 2
+      ? warmFirst(observedReviewer)
+      : observedReviewer;
+
+  const panel = await runPanel(input.lensSet, input.subject, dispatched, input.practices);
+  const prompts = panel.prompts;
+
+  // C1 runs before C2: de-duplication sees the tiers as enforced.
+  const tiered =
+    input.tierSignals === undefined
+      ? { verdict: panel.verdict, downgraded: 0 }
+      : enforceTier(panel.verdict, input.tierSignals);
+  const verdict = tiered.verdict;
+
+  let dedup: { groups: DedupGroupView[]; total: number } | undefined;
+  let dedupSkipped: string | undefined;
+  if (input.dedup === true && verdict.findings.length >= 2) {
+    const numbered = numberFindings(verdict.findings);
+    // The observed reviewer, outside warm-first: the extra call is recorded like a lens call.
+    const outcome = await dedupFindings(numbered, observedReviewer);
+    if (outcome.ok) {
+      dedup = { groups: toGroupViews(outcome.groups, input.practiceNames), total: numbered.length };
+    } else {
+      dedupSkipped = outcome.reason;
+    }
+  }
 
   const report = renderReport(verdict, {
     source: input.lensSetSource,
     subject: input.subject.title,
+    ...(dedup === undefined ? {} : { dedup }),
+    ...(dedupSkipped === undefined ? {} : { dedupSkipped }),
   });
 
-  return { verdict, report, exitCode: exitCodeFor(verdict.outcome), prompts };
+  return {
+    verdict,
+    report,
+    exitCode: exitCodeFor(verdict.outcome),
+    prompts,
+    downgraded: tiered.downgraded,
+  };
 }

package/src/tier.ts

@@ -0,0 +1,103 @@
+// Enforces the tier in code. A derived lens is told to tag a finding [blocking] only when it
+// quotes the signal it fails, but a model honours that loosely. After parsing, every [blocking]
+// finding of a derived lens is checked against THAT lens's own practices' `_Reject:_` /
+// `_Expect:_` lines; one that quotes none is downgraded to [smell] and the lens's outcome is
+// recomputed. Deterministic: no model call.
+//
+// MATCHING RULE. Both sides are normalised (lower-cased; markdown emphasis `*` `_` and
+// backticks removed; quote marks removed; runs of whitespace collapsed to one space). A
+// finding (summary + detail) quotes a signal line when it contains a contiguous
+// MIN_QUOTE-character (24) run of the signal's normalised text, or the whole normalised line
+// when the line is shorter than that.
+
+import { aggregate } from './verdict.js';
+import type { Finding, LensResult, Verdict } from './verdict.js';
+
+/** The shortest verbatim run of a signal line that counts as quoting it. */
+export const MIN_QUOTE = 24;
+
+/** Appended to the summary of a finding that was downgraded. */
+export const DOWNGRADE_NOTE = ' (downgraded: no signal quoted)';
+
+export function normaliseForQuote(text: string): string {
+  return text
+    .replace(/[*_`]/g, '')
+    .replace(/["'‘’“”«»]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+/** Whether `text` contains a verbatim quote (per the rule above) of any of `signals`. */
+export function quotesSignal(text: string, signals: readonly string[]): boolean {
+  const haystack = normaliseForQuote(text);
+  for (const signal of signals) {
+    const needle = normaliseForQuote(signal);
+    if (needle === '') continue;
+    if (needle.length <= MIN_QUOTE) {
+      if (haystack.includes(needle)) return true;
+      continue;
+    }
+    for (let i = 0; i + MIN_QUOTE <= needle.length; i++) {
+      if (haystack.includes(needle.slice(i, i + MIN_QUOTE))) return true;
+    }
+  }
+  return false;
+}
+
+// Same test as verdict.ts's: a [blocking] line whose text begins "none" says "nothing found".
+const NONE_SENTINEL = /^none(?:\s*$|\s*[-—]\s)/;
+
+function isNone(finding: Finding): boolean {
+  return NONE_SENTINEL.test(finding.summary.trim());
+}
+
+function hasBlocking(findings: readonly Finding[]): boolean {
+  return findings.some((f) => f.blocking && !isNone(f));
+}
+
+export interface TierResult {
+  readonly verdict: Verdict;
+  /** How many findings were downgraded. */
+  readonly downgraded: number;
+}
+
+/**
+ * Downgrade unquoted [blocking] findings of every lens that has an entry in `signals`, then
+ * re-aggregate. A lens that was `rejected` and is left with no [blocking] finding counts as
+ * `approved`. Lenses without an entry (bundled lenses) are untouched. With nothing to
+ * downgrade the verdict is returned as it was.
+ */
+export function enforceTier(
+  verdict: Verdict,
+  signals: Readonly<Record<string, readonly string[]>>,
+): TierResult {
+  let downgraded = 0;
+  const results = verdict.results.map((result): LensResult => {
+    if (!Object.prototype.hasOwnProperty.call(signals, result.lens)) return result;
+    const own = signals[result.lens] ?? [];
+    let changed = false;
+    const findings = result.findings.map((finding): Finding => {
+      if (!finding.blocking || isNone(finding)) return finding;
+      if (quotesSignal(`${finding.summary}\n${finding.detail ?? ''}`, own)) return finding;
+      changed = true;
+      downgraded++;
+      return { ...finding, blocking: false, summary: `${finding.summary}${DOWNGRADE_NOTE}` };
+    });
+    if (!changed) return result;
+    const outcome =
+      result.outcome === 'rejected' && !hasBlocking(findings)
+        ? ('approved' as const)
+        : result.outcome;
+    return { ...result, outcome, findings };
+  });
+  if (downgraded === 0) return { verdict, downgraded };
+  // Prior-round rulings are carried on each result; the CLI never supplies orphaned ones.
+  return {
+    verdict: aggregate(
+      verdict.results.map((r) => r.lens),
+      results,
+    ),
+    downgraded,
+  };
+}