@verevoir/review 0.2.0 → 0.3.1

package/src/tier.ts

@@ -0,0 +1,207 @@
+// 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]. The mirror: a [smell]
+// finding that quotes one of the lens's own `_Reject:_` lines (not `_Expect:_`) is promoted to
+// [blocking], because the bar says a Reject blocks anywhere. The lens's outcome is then
+// 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.
+//
+// PRACTICE IDS DO NOT COUNT AS QUOTING. Lens signal lines cross-reference other practices by id
+// (a Reject line may say "see complexity-matches-the-problem"), so a finding that merely NAMES
+// that id would otherwise match 24+ characters without quoting anything. Before matching, every
+// practice id of the corpus (and any backticked kebab-case token) is replaced, in BOTH the
+// signal line and the finding, by a break mark. A run of 24 characters can then never span or
+// consist of an id, and a signal line that is only ids has nothing left to quote. Chosen over
+// "the run must contain a non-id word": stripping is one rule applied to both sides, and it
+// cannot be satisfied by an id plus one filler word.
+//
+// WORD BOUNDARIES. After normalising, every run of characters that are not letters or digits
+// becomes one space, and both sides are padded with a space at each end. So the start or end of
+// a text, and punctuation beside a word, all read as the same single space: a phrase at the
+// start of a finding, after "(", or before ":" matches as it would after a space. The
+// 24-character bar is unchanged; "unpinned/unremarked" is still not "unpinned and unremarked".
+
+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)';
+
+/** Appended to the summary of a smell that was promoted. */
+export const PROMOTE_NOTE = ' (promoted: quotes a Reject signal)';
+
+export function normaliseForQuote(text: string): string {
+  return text
+    .replace(/[*_`]/g, '')
+    .replace(/["'‘’“”«»]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+/** Stands where an id was; survives normalisation and cannot occur in prose. */
+const ID_MARK = '\u0001';
+const BACKTICKED_ID = /`[a-z0-9]+(?:-[a-z0-9]+)+`/g;
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function idPattern(ids: readonly string[]): RegExp | undefined {
+  const sorted = [...new Set(ids.map((id) => id.toLowerCase()).filter((id) => id !== ''))].sort(
+    (a, b) => b.length - a.length,
+  );
+  if (sorted.length === 0) return undefined;
+  return new RegExp(`(?<![a-z0-9-])(?:${sorted.map(escapeRegExp).join('|')})(?![a-z0-9-])`, 'g');
+}
+
+function markIds(text: string, pattern: RegExp | undefined): string {
+  const marked = text.toLowerCase().replace(BACKTICKED_ID, ID_MARK);
+  return pattern === undefined ? marked : marked.replace(pattern, ID_MARK);
+}
+
+/** Normalised, punctuation read as a space, padded with a space each end; '' when nothing is left. */
+function boundaryForm(text: string): string {
+  const spaced = normaliseForQuote(text)
+    .replace(/[^\p{L}\p{N}\u0001]+/gu, ' ')
+    .trim();
+  return spaced === '' ? '' : ` ${spaced} `;
+}
+
+/** A 24-character run of `needle` in `haystack`; a needle of 24 or fewer only whole, if allowed. */
+function quotesRun(haystack: string, needle: string, wholeIfShort: boolean): boolean {
+  if (needle === '') return false;
+  if (needle.length <= MIN_QUOTE) return wholeIfShort && haystack.includes(needle);
+  for (let i = 0; i + MIN_QUOTE <= needle.length; i++) {
+    if (haystack.includes(needle.slice(i, i + MIN_QUOTE))) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether `text` contains a verbatim quote (per the rule above) of any of `signals`.
+ * `practiceIds` are the corpus's practice ids, which are ignored on both sides.
+ */
+export function quotesSignal(
+  text: string,
+  signals: readonly string[],
+  practiceIds: readonly string[] = [],
+): boolean {
+  const pattern = idPattern(practiceIds);
+  const haystack = boundaryForm(markIds(text, pattern));
+  for (const signal of signals) {
+    const marked = markIds(signal, pattern);
+    if (marked.includes(ID_MARK)) {
+      // Each stretch between ids is quoted (or not) on its own; a short one never counts.
+      for (const stretch of marked.split(ID_MARK)) {
+        if (quotesRun(haystack, boundaryForm(stretch), false)) return true;
+      }
+    } else if (quotesRun(haystack, boundaryForm(marked), true)) {
+      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 TierContext {
+  /** Per lens id: just the `_Reject:_` lines. A lens with an entry can have smells promoted. */
+  readonly rejects?: Readonly<Record<string, readonly string[]>>;
+  /** Every practice id in the corpus, ignored when matching. */
+  readonly practiceIds?: readonly string[];
+}
+
+export interface TierResult {
+  readonly verdict: Verdict;
+  /** How many findings were downgraded. */
+  readonly downgraded: number;
+  /** How many smells were promoted to [blocking]. */
+  readonly promoted: number;
+}
+
+/**
+ * Downgrade unquoted [blocking] findings of every lens that has an entry in `signals`, promote
+ * smells that quote one of the lens's own Reject lines (`context.rejects`), then re-aggregate.
+ * A lens that was `rejected` and is left with no [blocking] finding counts as `approved`; one
+ * that was `approved` and gained a promoted finding counts as `rejected`; either is marked
+ * `tierAdjusted`. Lenses without an entry (bundled lenses) are untouched. With nothing changed
+ * the verdict is returned as it was.
+ */
+export function enforceTier(
+  verdict: Verdict,
+  signals: Readonly<Record<string, readonly string[]>>,
+  context: TierContext = {},
+): TierResult {
+  const ids = context.practiceIds ?? [];
+  let downgraded = 0;
+  let promoted = 0;
+  const results = verdict.results.map((result): LensResult => {
+    if (!Object.prototype.hasOwnProperty.call(signals, result.lens)) return result;
+    const own = signals[result.lens] ?? [];
+    const rejectLines =
+      context.rejects !== undefined &&
+      Object.prototype.hasOwnProperty.call(context.rejects, result.lens)
+        ? (context.rejects[result.lens] ?? [])
+        : undefined;
+    let changed = false;
+    let lensPromoted = 0;
+    const findings = result.findings.map((finding): Finding => {
+      if (isNone(finding)) return finding;
+      const text = `${finding.summary}\n${finding.detail ?? ''}`;
+      if (finding.blocking) {
+        if (quotesSignal(text, own, ids)) return finding;
+        changed = true;
+        downgraded++;
+        return { ...finding, blocking: false, summary: `${finding.summary}${DOWNGRADE_NOTE}` };
+      }
+      if (rejectLines === undefined || !quotesSignal(text, rejectLines, ids)) return finding;
+      changed = true;
+      promoted++;
+      lensPromoted++;
+      return { ...finding, blocking: true, summary: `${finding.summary}${PROMOTE_NOTE}` };
+    });
+    if (!changed) return result;
+    const outcome =
+      result.outcome === 'rejected' && !hasBlocking(findings)
+        ? ('approved' as const)
+        : result.outcome === 'approved' && lensPromoted > 0
+          ? ('rejected' as const)
+          : result.outcome;
+    // The lens's own reason text is not regenerated, so a changed word must say who changed it.
+    return {
+      ...result,
+      outcome,
+      findings,
+      ...(outcome === result.outcome ? {} : { tierAdjusted: true }),
+    };
+  });
+  if (downgraded === 0 && promoted === 0) return { verdict, downgraded, promoted };
+  // 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,
+    promoted,
+  };
+}

package/src/verdict.ts

@@ -90,6 +90,9 @@ export interface LensResult {
   /** Why this lens could not run, or why it found nothing in scope.
    * Meaningless on `approved` and `rejected`. */
   readonly reason?: string;
+  /** True when tier enforcement (tier.ts) changed this lens's outcome after the model gave it,
+   * so the model's own `reason` text no longer matches. Absent otherwise. */
+  readonly tierAdjusted?: boolean;
   /**
    * This lens's own rulings on whichever prior blocking findings were
    * attributed to it (`Subject.priorFindings`, filtered by lens). Present

package/src/warm-first.ts

@@ -0,0 +1,27 @@
+// Cache warm-up for the fan. runPanel dispatches every lens at once, so with a
+// provider prompt cache each lens writes the same shared prefix and none reads
+// it. `warmFirst` wraps a Reviewer so the FIRST call made runs alone, and every
+// later call waits for it to settle (success or failure) before starting: the
+// rest then read the prefix the first one wrote.
+//
+// The seam is the Reviewer itself, so runPanel is untouched. The first caller
+// is whichever lens runPanel invokes first (the first lens in the set); the
+// check-and-set below runs synchronously within that first call, before any
+// await, so no later call can also believe it is first.
+
+import type { Reviewer } from './panel.js';
+
+export function warmFirst(reviewer: Reviewer): Reviewer {
+  let first: Promise<void> | undefined;
+  return (lensId, prompt) => {
+    if (first === undefined) {
+      const call = reviewer(lensId, prompt);
+      first = call.then(
+        () => undefined,
+        () => undefined,
+      );
+      return call;
+    }
+    return first.then(() => reviewer(lensId, prompt));
+  };
+}