@verevoir/review 0.2.0 → 0.3.0

package/dist/practice-lenses.d.ts

@@ -0,0 +1,69 @@
+import type { 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: 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;
+    }[]>>;
+}
+/** Anchors the tier to a quoted signal, so the same finding does not flip run to run. */
+export declare const TIER_ANCHOR: string;
+/**
+ * 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 declare function framingFor(lensId: string): string;
+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 declare function extractBar(readme: string): BarResult;
+/** The first `# Title` line after any front-matter block, or undefined. */
+export declare function parseTitle(markdown: string): string | undefined;
+export declare function parseLensFrontmatter(markdown: string): string | undefined;
+/** From `**Sensor**` (else `**Look for**`) to the next `**Guide**` or end of file. */
+export declare function extractSensorHalf(markdown: string): string | undefined;
+/**
+ * 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 declare function extractSignalLines(sensor: string): string[];
+/**
+ * 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 declare function deriveLensSet(files: readonly PracticeFile[]): DerivedLenses;

package/dist/practice-lenses.js

@@ -0,0 +1,218 @@
+// 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.
+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) {
+    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.**';
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    const out = [];
+    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;
+        let text = (match[1] ?? '').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(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) {
+    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();
+    const signals = {};
+    const practiceNames = {};
+    const untagged = [];
+    const missingSensor = [];
+    for (const file of eligible) {
+        const id = file.name.slice(0, -'.md'.length);
+        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);
+        (signals[lensId] ??= []).push(...(sensor === undefined ? [] : extractSignalLines(sensor)));
+        (practiceNames[lensId] ??= []).push({ id, title: title ?? '' });
+    }
+    const lensIds = [...byLens.keys()].sort();
+    const lenses = [];
+    const groups = [];
+    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,
+        practiceNames,
+    };
+}

package/dist/prompt.d.ts

@@ -29,6 +29,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 —
@@ -96,6 +113,12 @@ export declare const NO_PRACTICES_NOTICE = "No practices were supplied for this
  * disclosed, not silently unnoticed.
  */
 export declare const NO_REQUIREMENT_NOTICE: string;
+/** Heading of the shared check-results section (`Subject.checks`). */
+export declare const CHECKS_HEADING = "## Checks on this change";
+/** Heading of the shared resolved-references section (`Subject.references`). */
+export declare const REFERENCES_HEADING = "## References in added lines";
+/** Heading of the shared whole-file context section (`Subject.fileContext`). */
+export declare 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. */

package/dist/prompt.js

@@ -63,6 +63,12 @@ export const NO_REQUIREMENT_NOTICE = 'No requirement text was supplied for this
     "context -- is this run's own account of its own work; there is nothing " +
     '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. */
@@ -98,6 +104,15 @@ export function buildPrompt(lens, subject, practices, placement = 'shared') {
     const citedSection = subject.citedContext !== undefined && subject.citedContext.trim() !== ''
         ? ['', '## 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
@@ -171,12 +186,15 @@ export function buildPrompt(lens, subject, practices, placement = 'shared') {
         `Title: ${subject.title}`,
         '',
         subject.description,
+        ...checksSection,
         '',
         '## The diff',
         '',
         '```diff',
         subject.diff,
         '```',
+        ...fileContextSection,
+        ...referencesSection,
         ...citedSection,
         '',
         '## How to answer',

package/dist/references.d.ts

@@ -0,0 +1,44 @@
+import type { ContextFs } from './context-files.js';
+/** At most this many distinct references are resolved; the rest are counted, not resolved. */
+export declare const MAX_REFERENCES = 40;
+/** Directory levels below the root that the ADR search lists. */
+export declare const ADR_SEARCH_DEPTH = 4;
+/** The basename search visits at most this many entries before it stops and says so. */
+export declare const MAX_SEARCH_FILES = 5000;
+/** Directory levels below the root that the basename search descends. */
+export declare const BASENAME_SEARCH_DEPTH = 8;
+export interface ReferenceOptions {
+    /** Overrides MAX_SEARCH_FILES (tests). */
+    readonly maxSearchFiles?: number;
+}
+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 declare function addedLines(diff: string): AddedLine[];
+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;
+}
+/** Distinct references in the added lines, in order of first appearance. */
+export declare function findReferences(diff: string): Reference[];
+/**
+ * The body of the "References in added lines" section for `diff`, resolved against `rootPath`.
+ * Throws only when the root itself cannot be resolved.
+ */
+export declare function buildReferences(diff: string, rootPath: string, fs: ReferenceFs, options?: ReferenceOptions): Promise<string>;