@verevoir/review 0.3.2 → 0.3.3

package/src/context-files.ts

@@ -89,6 +89,117 @@ export function diffPaths(diff: string): DiffPath[] {
   return out;
 }
 
+function stripEither(path: string): string {
+  return path.startsWith('a/') || path.startsWith('b/') ? path.slice(2) : path;
+}
+
+/** The `a/X b/X` header of a `diff --git` line, when both halves are the same path. */
+function gitHeaderPath(line: string): string | undefined {
+  const rest = line.slice('diff --git '.length);
+  if (rest.startsWith('"')) return undefined;
+  const mid = (rest.length - 1) / 2;
+  if (!Number.isInteger(mid) || rest[mid] !== ' ') return undefined;
+  const left = rest.slice(0, mid);
+  const right = rest.slice(mid + 1);
+  if (!left.startsWith('a/') || !right.startsWith('b/')) return undefined;
+  return left.slice(2) === right.slice(2) ? left.slice(2) : undefined;
+}
+
+/**
+ * EVERY path a diff changes, for deciding what kind of change it is (not for reading files).
+ * Unlike diffPaths it also sees what git writes WITHOUT `---`/`+++` headers: a pure rename
+ * (`rename from` / `rename to`), a copy, a binary change (`Binary files A and B differ`) and a
+ * mode-only change (the `diff --git` line itself). Both sides of a rename and the old path of a
+ * deletion are included, so moving code into a .md file is not a documentation change. A path
+ * that cannot be determined is reported as '' so the caller treats the diff as not understood.
+ * A diff with no `diff --git` lines (plain unified) falls back to diffPaths.
+ */
+export function changedPaths(diff: string): string[] {
+  const lines = diff.split(/\r?\n/);
+  if (!lines.some((l) => l.startsWith('diff --git '))) {
+    return diffPaths(diff).map((p) => p.path);
+  }
+  const out = new Set<string>();
+  let block: string[] = [];
+  const flush = (): void => {
+    if (block.length === 0) return;
+    const found: string[] = [];
+    let bad = false;
+    const take = (raw: string, strip: boolean): void => {
+      const value = unquote(raw);
+      if (value === undefined || value === '') bad = true;
+      else if (value !== '/dev/null') found.push(strip ? stripEither(value) : value);
+    };
+    for (const line of block.slice(1)) {
+      if (line.startsWith('@@')) break;
+      if (line.startsWith('rename from ')) take(line.slice(12), false);
+      else if (line.startsWith('rename to ')) take(line.slice(10), false);
+      else if (line.startsWith('copy from ')) take(line.slice(10), false);
+      else if (line.startsWith('copy to ')) take(line.slice(8), false);
+      else if (line.startsWith('--- ') || line.startsWith('+++ ')) take(line.slice(4), true);
+      else {
+        const binary = /^Binary files (.+) and (.+) differ$/.exec(line);
+        if (binary !== null) {
+          take(binary[1] ?? '', true);
+          take(binary[2] ?? '', true);
+        }
+      }
+    }
+    if (found.length === 0 && !bad) {
+      const header = gitHeaderPath(block[0] ?? '');
+      if (header === undefined) bad = true;
+      else found.push(header);
+    }
+    if (bad) out.add('');
+    for (const p of found) out.add(p);
+  };
+  for (const line of lines) {
+    if (line.startsWith('diff --git ')) {
+      flush();
+      block = [line];
+    } else if (block.length > 0) {
+      block.push(line);
+    }
+  }
+  flush();
+  return [...out];
+}
+
+/** A documentation file type, at any depth. BACKLOG.md is covered by .md. */
+const DOCUMENTATION_FILE = /\.(?:md|mdx|rst|adoc)$/i;
+
+/** Documentation by FILE TYPE (.md .mdx .rst .adoc, any depth; not .txt, which also names requirements.txt and CMakeLists.txt); a directory name alone is not enough. */
+export function isDocumentationPath(path: string): boolean {
+  return DOCUMENTATION_FILE.test(path);
+}
+
+/**
+ * True when the diff changes at least one file and EVERY changed path is documentation. Drives
+ * the tier (promotion off) and the spec framing. Paths come from changedPaths; one that cannot
+ * be determined makes the diff NOT docs-only, so promotion stays on.
+ */
+export function isDocumentationOnly(diff: string): boolean {
+  return classifyDiff(diff).documentationOnly;
+}
+
+export interface DiffClassification {
+  /** At least one changed file, and every one is documentation. */
+  readonly documentationOnly: boolean;
+  /** At least one changed path could not be determined (so the diff is never docs-only). */
+  readonly undeterminedPath: boolean;
+}
+
+/** The single classification of a diff: callers compute it once and pass the answer down. */
+export function classifyDiff(diff: string): DiffClassification {
+  const paths = changedPaths(diff);
+  const undeterminedPath = paths.includes('');
+  return {
+    documentationOnly:
+      paths.length > 0 && !undeterminedPath && paths.every((p) => isDocumentationPath(p)),
+    undeterminedPath,
+  };
+}
+
 /** Why a diff-supplied path must not be read, or undefined if it is acceptable. */
 export function unsafePathReason(path: string): string | undefined {
   if (path === '') return 'path could not be read from the diff header';

package/src/prompt.ts

@@ -40,6 +40,7 @@
 // equality against it.
 
 import type { Lens } from './lensSet.js';
+import { isDocumentationOnly } from './context-files.js';
 import {
   REPLY_CONTRACT,
   RULING_MARKER,
@@ -125,6 +126,12 @@ export interface Subject {
    * `buildPrompt` below for exactly how that slice is picked out.
    */
   readonly priorFindings?: ReadonlyArray<PriorFinding>;
+  /**
+   * Whether every changed file is documentation (context-files.ts classifyDiff). A caller that
+   * has already classified the diff passes the answer so it is decided once; absent, buildPrompt
+   * classifies `diff` itself. True adds SPEC_FRAMING to the shared prefix.
+   */
+  readonly docsOnly?: boolean;
 }
 
 /**
@@ -178,6 +185,10 @@ 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.';
 
+/** Added to the shared prefix when every changed file is documentation (see below). */
+export const SPEC_FRAMING =
+  "This change is a specification or plan. Block only where its text commits to behaviour a practice rejects. Where it merely doesn't rule out a case, raise a smell.";
+
 /** Heading of the shared check-results section (`Subject.checks`). */
 export const CHECKS_HEADING = '## Checks on this change';
 
@@ -318,9 +329,12 @@ export function buildPrompt(
     ? ['', PRIOR_FINDINGS_HEADING, '', ...rulingSection, '', ...independentReviewSection]
     : [];
 
+  const specification = subject.docsOnly ?? isDocumentationOnly(subject.diff);
+
   const shared = [
     'You are one lens of a review panel. Several reviewers are reading this same change, each along a different dimension, and their verdicts are combined. Review only your own dimension: another lens is covering the rest, and a finding outside your dimension is noise in someone else’s report.',
     '',
+    ...(specification ? [SPEC_FRAMING, ''] : []),
     ...barInShared,
     '## Requirement',
     '',

package/src/run-review.ts

@@ -31,6 +31,7 @@
 //     unchanged from v5, where this was also true.
 
 import type { LensSet } from './lensSet.js';
+import { classifyDiff } from './context-files.js';
 import type { Prompt, Subject } from './prompt.js';
 import { runPanel } from './panel.js';
 import { exitCodeFor, renderReport } from './report.js';
@@ -108,6 +109,12 @@ export interface ReviewNodeResult {
   readonly downgraded: number;
   /** How many smells tier enforcement promoted to [blocking] (0 when none). */
   readonly promoted: number;
+  /** True when Reject promotion was switched off because every changed file is documentation. */
+  readonly promotionOff: boolean;
+  /** True when every changed file is documentation, whether or not a tier applied. */
+  readonly docsOnly: boolean;
+  /** True when a changed path could not be determined, so the diff was not treated as docs-only. */
+  readonly pathUndetermined: boolean;
   /** Stderr lines, one per member of every merged dedup group (empty when none merged). */
   readonly dedupAudit: readonly string[];
 }
@@ -195,14 +202,22 @@ export async function runReviewNode(
       ? warmFirst(observedReviewer)
       : observedReviewer;
 
-  const panel = await runPanel(input.lensSet, input.subject, dispatched, input.practices);
+  // The docs-only decision is made ONCE, here (context-files.ts classifyDiff). It reaches the
+  // prompt through the subject (spec framing, every mode) and the tier below (promotion off).
+  const docs = classifyDiff(input.subject.diff);
+  const subject = { ...input.subject, docsOnly: docs.documentationOnly };
+  const panel = await runPanel(input.lensSet, subject, dispatched, input.practices);
   const prompts = panel.prompts;
 
+  // Promotion is off when every changed file in the parsed diff is documentation
+  // (classified above by context-files.ts); with no tier signals there is no promotion to turn off.
+  const promotionOff = input.tierSignals !== undefined && docs.documentationOnly;
   // C1 runs before C2: de-duplication sees the tiers as enforced.
   const tiered =
     input.tierSignals === undefined
       ? { verdict: panel.verdict, downgraded: 0, promoted: 0 }
       : enforceTier(panel.verdict, input.tierSignals, {
+          ...(promotionOff ? { promote: false } : {}),
           ...(input.tierRejects === undefined ? {} : { rejects: input.tierRejects }),
           ...(input.practiceIds === undefined ? {} : { practiceIds: input.practiceIds }),
         });
@@ -237,6 +252,9 @@ export async function runReviewNode(
     prompts,
     downgraded: tiered.downgraded,
     promoted: tiered.promoted,
+    promotionOff,
+    docsOnly: docs.documentationOnly,
+    pathUndetermined: docs.undeterminedPath,
     dedupAudit,
   };
 }

package/src/tier.ts

@@ -128,6 +128,11 @@ export interface TierContext {
   readonly rejects?: Readonly<Record<string, readonly string[]>>;
   /** Every practice id in the corpus, ignored when matching. */
   readonly practiceIds?: readonly string[];
+  /**
+   * False turns Reject-quote promotion off (every changed file is documentation; see
+   * context-files.ts isDocumentationOnly). The C1 downgrade is unaffected. Default true.
+   */
+  readonly promote?: boolean;
 }
 
 export interface TierResult {
@@ -158,6 +163,7 @@ export function enforceTier(
     if (!Object.prototype.hasOwnProperty.call(signals, result.lens)) return result;
     const own = signals[result.lens] ?? [];
     const rejectLines =
+      context.promote !== false &&
       context.rejects !== undefined &&
       Object.prototype.hasOwnProperty.call(context.rejects, result.lens)
         ? (context.rejects[result.lens] ?? [])