@verevoir/review 0.2.0 → 0.3.1

package/src/practice-lenses.ts

@@ -0,0 +1,286 @@
+// Derives a review lens set from a practice corpus: one lens per distinct
+// `lens:` front-matter value, its focus being a fixed adversarial framing
+// plus the SENSOR text of the practices in that group.
+//
+// PORTED, NOT IMPORTED, from aigency-runtime-v2 (BL-424 trial):
+//   - parseLensFrontmatter / FRONTMATTER_RE / LENS_LINE_RE
+//       <- src/compose/guardrails-corpus.ts
+//   - extractSensorHalf <- src/compose/practice-guides.ts
+//   - the "## Practices this lens checks" append and the placeholder for a
+//     practice with no sensor text <- src/review/lens-practice-partition.ts
+//     (withPractices)
+//
+// FRONT-MATTER: no YAML library. A practice file opens with a `---` block;
+// the only field read is a top-level `lens: <value>` line (one matching pair
+// of surrounding quotes is stripped), exactly as v2 reads it. Other fields
+// are ignored. This is the subset v2 itself understands.
+//
+// A practice with no usable `lens:` is NOT reviewed (v2 routes its sensor to
+// no lens) and is reported in `untagged`. A tagged practice with no sensor
+// text is reported in `missingSensor`; v2 fails closed on that and so does
+// the CLI when it runs a review.
+//
+// PURE: file names and texts come in, a derivation goes out.
+
+import type { Lens, LensSet } from './lensSet.js';
+
+export interface PracticeFile {
+  /** File name, e.g. `failure-legibility.md`. */
+  readonly name: string;
+  readonly text: string;
+}
+
+export interface LensGroup {
+  readonly lensId: string;
+  readonly practiceIds: readonly string[];
+}
+
+export interface DerivedLenses {
+  readonly lensSet: LensSet;
+  readonly groups: readonly LensGroup[];
+  /** Practice ids with no `lens:` value; reviewed by nothing. */
+  readonly untagged: readonly string[];
+  /** Tagged practice ids whose file has no Sensor / Look for text. */
+  readonly missingSensor: readonly string[];
+  /**
+   * Per lens id: the text of every `_Reject:_` / `_Expect:_` signal line in that lens's
+   * practices' sensors (label stripped). A [blocking] finding must quote one of these.
+   */
+  readonly signals: Readonly<Record<string, readonly string[]>>;
+  /** Per lens id: only the `_Reject:_` lines of `signals`. A smell quoting one is promoted. */
+  readonly rejects: Readonly<Record<string, readonly string[]>>;
+  /** Every practice id in the corpus (tagged or not): ignored when matching a quote. */
+  readonly practiceIds: readonly string[];
+  /** Per lens id: its practices' ids and H1 titles ('' when none), to name them in a report. */
+  readonly practiceNames: Readonly<
+    Record<string, readonly { readonly id: string; readonly title: string }[]>
+  >;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+const LENS_LINE_RE = /^lens:[ \t]*(.+?)[ \t]*$/m;
+
+const GUIDE_HEADING = '**Guide**';
+const SENSOR_HEADING = '**Sensor**';
+const LOOK_FOR_HEADING = '**Look for**';
+
+/** Anchors the tier to a quoted signal, so the same finding does not flip run to run. */
+export const TIER_ANCHOR =
+  "Tag a finding [blocking] only when you quote the signal it fails: a practice's " +
+  '_Reject:_ line anywhere, or its _Expect:_ line for lines this change adds or modifies. ' +
+  'A finding that quotes no signal is a [smell].';
+
+/**
+ * The fixed framing every derived lens opens with. The last paragraph is glue:
+ * it maps the corpus README's provenance rule onto this diff and the reply
+ * tags, and is NOT a copy of the README (the README's grading text reaches the
+ * lens as "The bar").
+ */
+export function framingFor(lensId: string): string {
+  return (
+    `Review this change adversarially for the "${lensId}" dimension: assume it is wrong, ` +
+    'and look for a concrete defect that violates one of the practices below. ' +
+    'Report only what you can point to in the diff.\n\n' +
+    'Provenance sets the bar. Lines this change adds or modifies are generated work, held to ' +
+    'Expect; unchanged context is taken-on work, held to Accept. A Reject signal is ' +
+    '[blocking] anywhere, and so is an Expect gap in added or modified lines; an ' +
+    'Accept-but-not-Expect gap in untouched context is a [smell] recommendation. ' +
+    'An untouched line counts as part of this change only where the change makes it untrue; ' +
+    'name the changed line that does so, otherwise judge it as untouched context. ' +
+    TIER_ANCHOR +
+    ' Name the practice each finding violates. ' +
+    'Before your verdict line, add one line `REASON: <one sentence on what you checked and ' +
+    'why you approve or reject>`.'
+  );
+}
+
+const SIGNALS_HEADING = '## Signals: reject / accept / expect';
+const PROVENANCE_MARKER = '**The two halves are keyed to different tiers.**';
+
+export type BarResult =
+  { readonly ok: true; readonly text: string } | { readonly ok: false; readonly reason: string };
+
+/**
+ * The grading rules from the corpus README (practices/README.md): the whole
+ * "## Signals: reject / accept / expect" section (to the next `## ` heading),
+ * plus the paragraph opening "**The two halves are keyed to different tiers.**"
+ * (which lives under "## Guide and sensor"; only that paragraph, to the next
+ * blank line). Either missing is a failure with a reason, never a fallback.
+ */
+export function extractBar(readme: string): BarResult {
+  const lines = readme.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === SIGNALS_HEADING);
+  if (start === -1) {
+    return { ok: false, reason: `the README has no "${SIGNALS_HEADING}" section` };
+  }
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if ((lines[i] ?? '').startsWith('## ')) {
+      end = i;
+      break;
+    }
+  }
+  const signals = lines.slice(start, end).join('\n').trim();
+  if (signals === SIGNALS_HEADING) {
+    return { ok: false, reason: `the README's "${SIGNALS_HEADING}" section is empty` };
+  }
+  if (signals.includes(PROVENANCE_MARKER)) return { ok: true, text: signals };
+  const at = readme.indexOf(PROVENANCE_MARKER);
+  if (at === -1) {
+    return {
+      ok: false,
+      reason: `the README has no paragraph beginning "${PROVENANCE_MARKER}"`,
+    };
+  }
+  const rest = readme.slice(at);
+  const blank = rest.search(/\r?\n[ \t]*\r?\n/);
+  const paragraph = (blank === -1 ? rest : rest.slice(0, blank)).trim();
+  return { ok: true, text: `${signals}\n\n${paragraph}` };
+}
+
+const H1_RE = /^# (.+?)[ \t]*$/m;
+
+/** The first `# Title` line after any front-matter block, or undefined. */
+export function parseTitle(markdown: string): string | undefined {
+  const body = markdown.replace(FRONTMATTER_RE, '');
+  const match = H1_RE.exec(body);
+  const title = match?.[1]?.trim();
+  return title === undefined || title === '' ? undefined : title;
+}
+
+export function parseLensFrontmatter(markdown: string): string | undefined {
+  const match = FRONTMATTER_RE.exec(markdown);
+  if (!match) return undefined;
+  const lensMatch = LENS_LINE_RE.exec(match[1] ?? '');
+  if (!lensMatch) return undefined;
+  const raw = (lensMatch[1] ?? '').trim();
+  const unquoted =
+    raw.length >= 2 &&
+    ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))
+      ? raw.slice(1, -1)
+      : raw;
+  return unquoted.trim() === '' ? undefined : unquoted.trim();
+}
+
+/** From `**Sensor**` (else `**Look for**`) to the next `**Guide**` or end of file. */
+export function extractSensorHalf(markdown: string): string | undefined {
+  let heading = SENSOR_HEADING;
+  let start = markdown.indexOf(SENSOR_HEADING);
+  if (start === -1) {
+    heading = LOOK_FOR_HEADING;
+    start = markdown.indexOf(LOOK_FOR_HEADING);
+  }
+  if (start === -1) return undefined;
+  const rest = markdown.slice(start);
+  const nextGuide = rest.indexOf(GUIDE_HEADING, heading.length);
+  const slice = nextGuide === -1 ? rest : rest.slice(0, nextGuide);
+  if (slice.slice(heading.length).trim() === '') return undefined;
+  return slice.trim();
+}
+
+const SIGNAL_LINE_RE = /^\s*(?:[-*+]\s+)?[_*]{1,2}(Reject|Expect):[_*]{1,2}\s*(.*)$/i;
+const BLOCK_START_RE = /^\s*(?:[-*+]\s|\d+\.\s|#|\*\*)/;
+
+/**
+ * The text of each `_Reject:_` / `_Expect:_` line in a sensor half, label stripped. Indented
+ * continuation lines (not a new bullet, heading or bold label) are joined onto their line.
+ */
+export function extractSignalLines(sensor: string): string[] {
+  return extractLabelledSignals(sensor).map((s) => s.text);
+}
+
+/** As `extractSignalLines`, keeping which label each line carried. */
+export function extractLabelledSignals(
+  sensor: string,
+): { readonly kind: 'reject' | 'expect'; readonly text: string }[] {
+  const out: { kind: 'reject' | 'expect'; text: string }[] = [];
+  const lines = sensor.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = SIGNAL_LINE_RE.exec(lines[i] ?? '');
+    if (match === null) continue;
+    const kind = (match[1] ?? '').toLowerCase() === 'reject' ? 'reject' : 'expect';
+    let text = (match[2] ?? '').trim();
+    while (i + 1 < lines.length) {
+      const next = lines[i + 1] ?? '';
+      if (next.trim() === '' || !/^\s+\S/.test(next) || BLOCK_START_RE.test(next)) break;
+      text = `${text} ${next.trim()}`;
+      i++;
+    }
+    if (text !== '') out.push({ kind, text });
+  }
+  return out;
+}
+
+/**
+ * Group practice files by their `lens:` value and build one lens per group.
+ * Files are taken in name order, a top-level README.md and non-.md files are
+ * skipped (as v2 does), and lenses are ordered by id, so the result is
+ * deterministic.
+ */
+export function deriveLensSet(files: readonly PracticeFile[]): DerivedLenses {
+  const eligible = files
+    .filter((f) => f.name.endsWith('.md') && f.name.toLowerCase() !== 'readme.md')
+    .slice()
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  const byLens = new Map<
+    string,
+    { id: string; title: string | undefined; sensor: string | undefined }[]
+  >();
+  const signals: Record<string, string[]> = {};
+  const rejects: Record<string, string[]> = {};
+  const practiceIds: string[] = [];
+  const practiceNames: Record<string, { id: string; title: string }[]> = {};
+  const untagged: string[] = [];
+  const missingSensor: string[] = [];
+  for (const file of eligible) {
+    const id = file.name.slice(0, -'.md'.length);
+    practiceIds.push(id);
+    const lensId = parseLensFrontmatter(file.text);
+    if (lensId === undefined) {
+      untagged.push(id);
+      continue;
+    }
+    const sensor = extractSensorHalf(file.text);
+    if (sensor === undefined) missingSensor.push(id);
+    const group = byLens.get(lensId) ?? [];
+    const title = parseTitle(file.text);
+    group.push({ id, title, sensor });
+    byLens.set(lensId, group);
+    const labelled = sensor === undefined ? [] : extractLabelledSignals(sensor);
+    (signals[lensId] ??= []).push(...labelled.map((s) => s.text));
+    (rejects[lensId] ??= []).push(
+      ...labelled.filter((s) => s.kind === 'reject').map((s) => s.text),
+    );
+    (practiceNames[lensId] ??= []).push({ id, title: title ?? '' });
+  }
+
+  const lensIds = [...byLens.keys()].sort();
+  const lenses: Lens[] = [];
+  const groups: LensGroup[] = [];
+  for (const lensId of lensIds) {
+    const members = byLens.get(lensId) ?? [];
+    const body = members
+      .map((m) => {
+        const heading = `### ${m.id}${m.title === undefined ? '' : `: ${m.title}`}`;
+        return `${heading}\n\n${m.sensor ?? `(no sensor text available for ${m.id})`}`;
+      })
+      .join('\n\n');
+    lenses.push({
+      id: lensId,
+      title: lensId,
+      focus: `${framingFor(lensId)}\n\n## Practices this lens checks\n\n${body}`,
+    });
+    groups.push({ lensId, practiceIds: members.map((m) => m.id) });
+  }
+  return {
+    lensSet: { version: 1, lenses },
+    groups,
+    untagged,
+    missingSensor,
+    signals,
+    rejects,
+    practiceIds,
+    practiceNames,
+  };
+}

package/src/prompt.ts

@@ -78,6 +78,23 @@ export interface Subject {
    * change-context assembler is PR 2.
    */
   readonly citedContext?: string;
+  /**
+   * Whole-file context for the files the diff touches (or a one-line note
+   * saying there is none), already rendered. Rendered once, in `shared`,
+   * right after the diff under `FILE_CONTEXT_HEADING`. Absent or blank omits
+   * the section entirely, so every caller before this is byte-identical.
+   */
+  readonly fileContext?: string;
+  /**
+   * Check results (CI) for this change, rendered verbatim once, in `shared`, under
+   * `CHECKS_HEADING` between "## The change" and "## The diff". Absent or blank omits it.
+   */
+  readonly checks?: string;
+  /**
+   * Resolved references found in the diff's added lines, rendered once, in `shared`,
+   * under `REFERENCES_HEADING` after the changed files. Absent or blank omits it.
+   */
+  readonly references?: string;
   /**
    * BL-146: the originating item's own acceptance text, verbatim. This is
    * the one input to a review that the run under review did not write —
@@ -127,6 +144,9 @@ export interface Prompt {
   readonly shared: string;
   /** The only part that varies by lens. Goes last. */
   readonly perLens: string;
+  /** `false` for a call whose `shared` no other call reads (the dedup call): a transport that
+   * marks `shared` cacheable must not, as the cache write would never be read. */
+  readonly cache?: false;
 }
 
 /** The two halves in the one order that preserves the shared prefix. */
@@ -158,6 +178,15 @@ export const NO_REQUIREMENT_NOTICE =
   'from outside the run to check it against. Say so plainly in your ' +
   'reasoning, and judge only whether the change is coherent on its own terms.';
 
+/** Heading of the shared check-results section (`Subject.checks`). */
+export const CHECKS_HEADING = '## Checks on this change';
+
+/** Heading of the shared resolved-references section (`Subject.references`). */
+export const REFERENCES_HEADING = '## References in added lines';
+
+/** Heading of the shared whole-file context section (`Subject.fileContext`). */
+export const FILE_CONTEXT_HEADING = '## Changed files in full';
+
 /** Heading for the round-aware section appended to `perLens` when
  * `Subject.priorFindings` is non-empty. Exported so a test can assert on
  * it directly rather than re-typing the literal string. */
@@ -204,6 +233,21 @@ export function buildPrompt(
       ? ['', '## Cited code', '', subject.citedContext]
       : [];
 
+  const fileContextSection =
+    subject.fileContext !== undefined && subject.fileContext.trim() !== ''
+      ? ['', FILE_CONTEXT_HEADING, '', subject.fileContext]
+      : [];
+
+  const checksSection =
+    subject.checks !== undefined && subject.checks.trim() !== ''
+      ? ['', CHECKS_HEADING, '', subject.checks]
+      : [];
+
+  const referencesSection =
+    subject.references !== undefined && subject.references.trim() !== ''
+      ? ['', REFERENCES_HEADING, '', subject.references]
+      : [];
+
   // BL-146: NEVER omitted, unlike citedSection above -- a requirement's
   // absence is disclosed, not silently skipped. `requirementText` is
   // either the item's own acceptance text, verbatim (never combined with
@@ -287,12 +331,15 @@ export function buildPrompt(
     `Title: ${subject.title}`,
     '',
     subject.description,
+    ...checksSection,
     '',
     '## The diff',
     '',
     '```diff',
     subject.diff,
     '```',
+    ...fileContextSection,
+    ...referencesSection,
     ...citedSection,
     '',
     '## How to answer',