@cfbender/cesium 0.3.6 → 0.5.0

package/src/render/blocks/validate-block.ts

@@ -0,0 +1,202 @@
+// Deep per-block field validator — walks catalog schemas and checks field shapes.
+// src/render/blocks/validate-block.ts
+
+import { blockCatalog } from "./catalog.ts";
+
+export interface BlockFieldError {
+  path: string;
+  message: string;
+}
+
+// ─── Levenshtein distance (small, iterative) ─────────────────────────────────
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const aLen = a.length;
+  const bLen = b.length;
+  if (aLen === 0) return bLen;
+  if (bLen === 0) return aLen;
+  // Use two rows
+  let prev = Array.from({ length: bLen + 1 }, (_, i) => i);
+  let curr: number[] = Array.from({ length: bLen + 1 }, () => 0);
+  for (let i = 1; i <= aLen; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= bLen; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        (prev[j] ?? 0) + 1,
+        (curr[j - 1] ?? 0) + 1,
+        (prev[j - 1] ?? 0) + cost,
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[bLen] ?? 0;
+}
+
+/**
+ * Given an unknown field name and a list of known field names, returns the
+ * closest known name if the Levenshtein distance is ≤ 2, otherwise checks
+ * common alias patterns, otherwise returns null.
+ */
+function didYouMean(unknown: string, known: string[]): string | null {
+  // Explicit common aliases that wouldn't be caught by Levenshtein alone
+  const ALIASES: Record<string, string> = {
+    label: "k",
+    value: "v",
+    description: "text",
+    title: "label",
+    med: "medium",
+    name: "k",
+    key: "k",
+    val: "v",
+  };
+
+  // Check alias map first
+  const aliased = ALIASES[unknown.toLowerCase()];
+  if (aliased !== undefined && known.includes(aliased)) {
+    return aliased;
+  }
+
+  // Fall back to Levenshtein ≤ 2
+  let best: string | null = null;
+  let bestDist = 3; // threshold: only suggest if distance ≤ 2
+  for (const name of known) {
+    const d = levenshtein(unknown, name);
+    if (d < bestDist) {
+      bestDist = d;
+      best = name;
+    }
+  }
+  return best;
+}
+
+// ─── JSON Schema fragment types ───────────────────────────────────────────────
+
+type SchemaNode =
+  | { type: "string"; enum?: string[] }
+  | { type: "number" }
+  | { type: "boolean" }
+  | { type: "array"; items?: SchemaNode }
+  | { type: "object"; properties?: Record<string, SchemaNode>; required?: string[] }
+  | { const: unknown };
+
+function isSchemaNode(v: unknown): v is SchemaNode {
+  return v !== null && typeof v === "object";
+}
+
+// ─── Deep validator ───────────────────────────────────────────────────────────
+
+/**
+ * Validate a single value against a JSON Schema fragment node.
+ * Appends any findings to `errors`. `path` is the dotted path for error messages.
+ */
+function validateNode(value: unknown, schema: SchemaNode, path: string, errors: BlockFieldError[]): void {
+  // const node
+  if ("const" in schema) {
+    if (value !== schema.const) {
+      errors.push({ path, message: `expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}` });
+    }
+    return;
+  }
+
+  const s = schema as Exclude<SchemaNode, { const: unknown }>;
+
+  switch (s.type) {
+    case "string": {
+      if (typeof value !== "string") {
+        errors.push({ path, message: `expected string, got ${typeof value}` });
+        return;
+      }
+      if (s.enum !== undefined && !s.enum.includes(value)) {
+        errors.push({
+          path,
+          message: `invalid value "${value}"; must be one of: ${s.enum.map((e) => `"${e}"`).join(", ")}`,
+        });
+      }
+      return;
+    }
+    case "number": {
+      if (typeof value !== "number") {
+        errors.push({ path, message: `expected number, got ${typeof value}` });
+      }
+      return;
+    }
+    case "boolean": {
+      if (typeof value !== "boolean") {
+        errors.push({ path, message: `expected boolean, got ${typeof value}` });
+      }
+      return;
+    }
+    case "array": {
+      if (!Array.isArray(value)) {
+        errors.push({ path, message: `expected array, got ${typeof value}` });
+        return;
+      }
+      if (s.items !== undefined) {
+        const arr = value as unknown[];
+        for (let i = 0; i < arr.length; i++) {
+          validateNode(arr[i], s.items, `${path}[${i}]`, errors);
+        }
+      }
+      return;
+    }
+    case "object": {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        errors.push({ path, message: `expected object, got ${Array.isArray(value) ? "array" : typeof value}` });
+        return;
+      }
+      const obj = value as Record<string, unknown>;
+      const props = s.properties ?? {};
+      const required = s.required ?? [];
+      const knownKeys = Object.keys(props).filter((k) => k !== "type");
+
+      // Only validate required/unknown fields when the schema explicitly defines properties.
+      // An empty or missing properties block (e.g. `items: { type: "object" }` for generic
+      // child lists) means "accept any object" — don't report unknown fields.
+      if (Object.keys(props).length > 0) {
+        // Check required fields
+        for (const req of required) {
+          if (req === "type") continue; // type is already validated by dispatch
+          if (!(req in obj)) {
+            errors.push({ path: `${path}.${req}`, message: `required field "${req}" is missing` });
+          }
+        }
+
+        // Check each present field
+        for (const [key, val] of Object.entries(obj)) {
+          if (key === "type") continue; // skip discriminant
+          const propSchema = props[key];
+          if (propSchema === undefined) {
+            // Unknown field — suggest closest known
+            const suggestion = didYouMean(key, knownKeys);
+            const suggestionMsg = suggestion !== null ? `; did you mean "${suggestion}"?` : "";
+            errors.push({ path: `${path}.${key}`, message: `unknown field "${key}"${suggestionMsg}` });
+          } else if (isSchemaNode(propSchema)) {
+            validateNode(val, propSchema, `${path}.${key}`, errors);
+          }
+        }
+      }
+      return;
+    }
+  }
+}
+
+/**
+ * Deeply validates a block's fields against its catalog schema.
+ * Returns an array of field errors (empty = valid).
+ */
+export function deepValidateBlock(block: Record<string, unknown>, path: string): BlockFieldError[] {
+  const errors: BlockFieldError[] = [];
+  const type = block["type"] as string;
+  const catalogEntry = blockCatalog[type as keyof typeof blockCatalog];
+  if (catalogEntry === undefined) {
+    // Unknown type — already caught by outer validateBlock; skip
+    return errors;
+  }
+
+  const schema = catalogEntry.schema as SchemaNode;
+  validateNode(block, schema, path, errors);
+
+  return errors;
+}

package/src/render/critique.ts

@@ -1,8 +1,9 @@
-// Pure HTML body analyzer — walks parse5 AST and returns structured findings + 0-100 score.
+// Pure body analyzer — mode-aware: html or blocks.
 // Deterministic and pure: same input always yields the same output.
 
 import { parseFragment, defaultTreeAdapter as ta } from "parse5";
 import type { DefaultTreeAdapterMap, DefaultTreeAdapterTypes, ParserOptions } from "parse5";
+import type { Block } from "./blocks/types.ts";
 
 type ChildNode = DefaultTreeAdapterTypes.ChildNode;
 type Element = DefaultTreeAdapterTypes.Element;
@@ -21,6 +22,8 @@ export interface CritiqueFinding {
   message: string;
   /** Populated when the rule represents an aggregate count. */
   count?: number;
+  /** Path in the block tree (blocks mode only), e.g. "blocks[2].children[1]". */
+  path?: string;
 }
 
 export interface CritiqueResult {
@@ -30,6 +33,8 @@ export interface CritiqueResult {
   findings: CritiqueFinding[];
   /** Sum of all text node values in the body (visible text content length). */
   textLength: number;
+  /** Which input mode was detected. */
+  mode: "html" | "blocks";
 }
 
 // ---------------------------------------------------------------------------
@@ -60,7 +65,7 @@ const SEVERITY_ORDER: Record<CritiqueSeverity, number> = {
 };
 
 // ---------------------------------------------------------------------------
-// Tree-walking helpers
+// Tree-walking helpers (HTML mode)
 // ---------------------------------------------------------------------------
 
 function walkNodes(nodes: readonly ChildNode[], visitor: (node: ChildNode) => void): void {
@@ -115,12 +120,12 @@ function hasHighlightDescendant(el: Element): boolean {
 // Scoring + ordering
 // ---------------------------------------------------------------------------
 
-function computeScore(findings: readonly CritiqueFinding[]): number {
-  let score = 100;
+function computeScore(findings: readonly CritiqueFinding[], baseline = 100): number {
+  let score = baseline;
   for (const f of findings) {
     score -= SEVERITY_DEDUCTION[f.severity];
   }
-  return Math.max(0, score);
+  return Math.min(100, Math.max(0, score));
 }
 
 function sortFindings(findings: CritiqueFinding[]): CritiqueFinding[] {
@@ -132,10 +137,10 @@ function sortFindings(findings: CritiqueFinding[]): CritiqueFinding[] {
 }
 
 // ---------------------------------------------------------------------------
-// Main analyzer — pure, deterministic
+// HTML mode — preserves all existing rules + adds prefer-blocks
 // ---------------------------------------------------------------------------
 
-export function critique(htmlBody: string): CritiqueResult {
+export function critiqueHtml(htmlBody: string): CritiqueResult {
   const fragment = parseFragment(htmlBody);
   const children = ta.getChildNodes(fragment) as ChildNode[];
   const findings: CritiqueFinding[] = [];
@@ -155,6 +160,9 @@ export function critique(htmlBody: string): CritiqueResult {
   const unknownCesiumClasses = new Set<string>();
   let codeBlocksWithoutHighlights = 0;
 
+  // prefer-blocks heuristic counters
+  let structuralElementCount = 0;
+
   walkNodes(children, (node) => {
     if (!ta.isElementNode(node)) return;
     const el = node as Element;
@@ -184,12 +192,16 @@ export function critique(htmlBody: string): CritiqueResult {
 
     // --- Class-based counts ---
     if (cls.has("h-display")) hDisplayCount++;
-    if (cls.has("h-section")) hSectionCount++;
+    if (cls.has("h-section")) {
+      hSectionCount++;
+      structuralElementCount++;
+    }
     if (cls.has("tldr")) tldrCount++;
     if (cls.has("eyebrow")) eyebrowCount++;
 
     // Callout without a severity modifier
     if (cls.has("callout")) {
+      structuralElementCount++;
       let hasModifier = false;
       for (const mod of CALLOUT_MODIFIERS) {
         if (cls.has(mod)) {
@@ -200,6 +212,9 @@ export function critique(htmlBody: string): CritiqueResult {
       if (!hasModifier) calloutNoModifierCount++;
     }
 
+    // compare-table counts as structural
+    if (cls.has("compare-table")) structuralElementCount++;
+
     // Unknown cesium-* class names
     for (const c of cls) {
       if (c.startsWith("cesium-") && !KNOWN_CESIUM_CLASSES.has(c)) {
@@ -318,6 +333,16 @@ export function critique(htmlBody: string): CritiqueResult {
     });
   }
 
+  // prefer-blocks: suggest when ≥3 structural elements could be expressed as blocks
+  if (structuralElementCount >= 3) {
+    findings.push({
+      severity: "suggest",
+      code: "prefer-blocks",
+      message: `This document has ${structuralElementCount} structural elements that could be expressed as blocks. Consider using cesium_publish({ blocks: [...] }).`,
+      count: structuralElementCount,
+    });
+  }
+
   // ---------------------------------------------------------------------------
   // Emit info-level findings
   // ---------------------------------------------------------------------------
@@ -354,7 +379,382 @@ export function critique(htmlBody: string): CritiqueResult {
   // ---------------------------------------------------------------------------
 
   const sorted = sortFindings(findings);
-  const score = computeScore(sorted);
+  const score = computeScore(sorted, 100);
+
+  return { score, findings: sorted, textLength, mode: "html" };
+}
 
-  return { score, findings: sorted, textLength };
+// ---------------------------------------------------------------------------
+// Blocks mode — quality-focused rules
+// ---------------------------------------------------------------------------
+
+/** Collect all raw_html blocks from a block tree, with their path. */
+function collectRawHtmlBlocks(
+  blocks: readonly Block[],
+  basePath: string,
+): Array<{ block: Extract<Block, { type: "raw_html" }>; path: string }> {
+  const results: Array<{ block: Extract<Block, { type: "raw_html" }>; path: string }> = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b === undefined) continue;
+    const path = `${basePath}[${i}]`;
+    if (b.type === "raw_html") {
+      results.push({ block: b, path });
+    }
+    if (b.type === "section") {
+      const nested = collectRawHtmlBlocks(b.children, `${path}.children`);
+      for (const n of nested) results.push(n);
+    }
+  }
+  return results;
+}
+
+/** Sum text content characters across all prose/tldr/callout/list/code/kv/timeline/table blocks. */
+function collectTextChars(blocks: readonly Block[]): number {
+  let total = 0;
+  for (const b of blocks) {
+    if (b === undefined) continue;
+    switch (b.type) {
+      case "prose":
+        total += b.markdown.length;
+        break;
+      case "tldr":
+        total += b.markdown.length;
+        break;
+      case "callout":
+        total += b.markdown.length;
+        break;
+      case "list":
+        for (const item of b.items) total += item.length;
+        break;
+      case "code":
+        total += b.code.length;
+        break;
+      case "kv":
+        for (const row of b.rows) total += row.k.length + row.v.length;
+        break;
+      case "timeline":
+        for (const item of b.items) total += item.label.length + item.text.length;
+        break;
+      case "compare_table":
+        for (const row of b.rows) for (const cell of row) total += cell.length;
+        for (const h of b.headers) total += h.length;
+        break;
+      case "risk_table":
+        for (const row of b.rows) total += row.risk.length + row.mitigation.length;
+        break;
+      case "hero":
+        total += b.title.length;
+        if (b.subtitle !== undefined) total += b.subtitle.length;
+        break;
+      case "section":
+        total += b.title.length;
+        total += collectTextChars(b.children);
+        break;
+      case "raw_html":
+        total += b.html.length;
+        break;
+      case "diagram":
+        total += (b.svg ?? b.html ?? "").length;
+        break;
+      case "divider":
+      case "pill_row":
+        break;
+    }
+  }
+  return total;
+}
+
+/** Count top-level section blocks. */
+function countTopLevelSections(blocks: readonly Block[]): number {
+  let count = 0;
+  for (const b of blocks) {
+    if (b !== undefined && b.type === "section") count++;
+  }
+  return count;
+}
+
+/** Count consecutive prose blocks at the same nesting level. Returns max run found + path. */
+function findProseWalls(
+  blocks: readonly Block[],
+  basePath: string,
+): Array<{ start: number; end: number; path: string }> {
+  const walls: Array<{ start: number; end: number; path: string }> = [];
+  let runStart = -1;
+  let runLen = 0;
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b === undefined) continue;
+    if (b.type === "prose") {
+      if (runStart === -1) runStart = i;
+      runLen++;
+    } else {
+      if (runLen > 8) {
+        walls.push({ start: runStart, end: i - 1, path: basePath });
+      }
+      runStart = -1;
+      runLen = 0;
+    }
+    if (b.type === "section") {
+      const nested = findProseWalls(b.children, `${basePath}[${i}].children`);
+      for (const n of nested) walls.push(n);
+    }
+  }
+  // Check trailing run
+  if (runLen > 8 && runStart !== -1) {
+    walls.push({ start: runStart, end: blocks.length - 1, path: basePath });
+  }
+  return walls;
+}
+
+/** Collect all code blocks with their path. */
+function collectCodeBlocks(
+  blocks: readonly Block[],
+  basePath: string,
+): Array<{ block: Extract<Block, { type: "code" }>; path: string }> {
+  const results: Array<{ block: Extract<Block, { type: "code" }>; path: string }> = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b === undefined) continue;
+    const path = `${basePath}[${i}]`;
+    if (b.type === "code") {
+      results.push({ block: b, path });
+    }
+    if (b.type === "section") {
+      const nested = collectCodeBlocks(b.children, `${path}.children`);
+      for (const n of nested) results.push(n);
+    }
+  }
+  return results;
+}
+
+/** Check compare_table for row/header count mismatch. */
+function checkTableShape(
+  blocks: readonly Block[],
+  basePath: string,
+): Array<{ path: string; message: string }> {
+  const issues: Array<{ path: string; message: string }> = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b === undefined) continue;
+    const path = `${basePath}[${i}]`;
+    if (b.type === "compare_table") {
+      const hLen = b.headers.length;
+      for (let ri = 0; ri < b.rows.length; ri++) {
+        const row = b.rows[ri];
+        if (row !== undefined && row.length !== hLen) {
+          issues.push({
+            path: `${path}.rows[${ri}]`,
+            message: `compare_table row has ${row.length} cells but headers has ${hLen}`,
+          });
+        }
+      }
+    }
+    if (b.type === "section") {
+      const nested = checkTableShape(b.children, `${path}.children`);
+      for (const n of nested) issues.push(n);
+    }
+  }
+  return issues;
+}
+
+/** Check for sections nested deeper than 3. */
+function checkNestingDepth(
+  blocks: readonly Block[],
+  basePath: string,
+  currentDepth: number,
+): Array<{ path: string }> {
+  const issues: Array<{ path: string }> = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b === undefined) continue;
+    const path = `${basePath}[${i}]`;
+    if (b.type === "section") {
+      if (currentDepth > 3) {
+        issues.push({ path });
+      } else {
+        const nested = checkNestingDepth(b.children, `${path}.children`, currentDepth + 1);
+        for (const n of nested) issues.push(n);
+      }
+    }
+  }
+  return issues;
+}
+
+/** Heuristic: detect framework markup inside raw_html that has a known block equivalent. */
+const REDUNDANT_PATTERNS: Array<{ pattern: RegExp; suggestion: string }> = [
+  { pattern: /<table\s[^>]*class="compare-table"/, suggestion: "compare_table" },
+  { pattern: /<div\s[^>]*class="card"/, suggestion: "section or callout" },
+  { pattern: /<aside\s[^>]*class="callout/, suggestion: "callout" },
+  { pattern: /<aside\s[^>]*class="tldr"/, suggestion: "tldr" },
+  { pattern: /<ul\s[^>]*class="timeline"/, suggestion: "timeline" },
+  { pattern: /<table\s[^>]*class="risk-table"/, suggestion: "risk_table" },
+  { pattern: /<dl\s[^>]*class="kv"/, suggestion: "kv" },
+];
+
+function detectRedundantRawHtml(html: string): string | null {
+  for (const { pattern, suggestion } of REDUNDANT_PATTERNS) {
+    if (pattern.test(html)) {
+      return suggestion;
+    }
+  }
+  return null;
+}
+
+/** Find the first hero block index (if any). */
+function findHeroIndex(blocks: readonly Block[]): number {
+  for (let i = 0; i < blocks.length; i++) {
+    if (blocks[i]?.type === "hero") return i;
+  }
+  return -1;
+}
+
+/** Check whether a tldr block exists anywhere in the tree. */
+function hasTldr(blocks: readonly Block[]): boolean {
+  for (const b of blocks) {
+    if (b === undefined) continue;
+    if (b.type === "tldr") return true;
+    if (b.type === "section" && hasTldr(b.children)) return true;
+  }
+  return false;
+}
+
+export function critiqueBlocks(blocks: Block[]): CritiqueResult {
+  const findings: CritiqueFinding[] = [];
+
+  // Total text content for ratio checks
+  const totalChars = collectTextChars(blocks);
+
+  // --- raw-html-overuse (warn) ---
+  const rawHtmlBlocks = collectRawHtmlBlocks(blocks, "blocks");
+  const rawHtmlCharTotal = rawHtmlBlocks.reduce((sum, { block }) => sum + block.html.length, 0);
+  const rawHtmlRatio = totalChars > 0 ? rawHtmlCharTotal / totalChars : 0;
+
+  if (rawHtmlBlocks.length > 2 || rawHtmlRatio > 0.3) {
+    const reason =
+      rawHtmlBlocks.length > 2
+        ? `${rawHtmlBlocks.length} raw_html blocks (max 2 before critique warns)`
+        : `raw_html payload is ${Math.round(rawHtmlRatio * 100)}% of body characters (>30%)`;
+    findings.push({
+      severity: "warn",
+      code: "raw-html-overuse",
+      message: `raw_html overuse: ${reason}. Consider expressing more content as typed blocks.`,
+      count: rawHtmlBlocks.length,
+    });
+  }
+
+  // --- missing-tldr (suggest) ---
+  const topLevelSections = countTopLevelSections(blocks);
+  if (topLevelSections > 5 && !hasTldr(blocks)) {
+    findings.push({
+      severity: "suggest",
+      code: "missing-tldr",
+      message: `Document has ${topLevelSections} sections but no tldr block. Add one near the top to orient readers.`,
+    });
+  }
+
+  // --- prose-wall (suggest) ---
+  const proseWalls = findProseWalls(blocks, "blocks");
+  for (const wall of proseWalls) {
+    findings.push({
+      severity: "suggest",
+      code: "prose-wall",
+      message: `More than 8 consecutive prose blocks at ${wall.path}[${wall.start}..${wall.end}]. Break the run with a list, callout, or section.`,
+      path: `${wall.path}[${wall.start}..${wall.end}]`,
+    });
+  }
+
+  // --- code-without-meaningful-lang (info) ---
+  const codeBlocks = collectCodeBlocks(blocks, "blocks");
+  for (const { block, path } of codeBlocks) {
+    if (block.lang === "text") {
+      findings.push({
+        severity: "info",
+        code: "code-without-meaningful-lang",
+        message: `Code block at ${path} uses lang "text". Specify a real language (e.g. "typescript", "json", "bash") for better rendering.`,
+        path,
+      });
+    }
+  }
+
+  // --- table-shape (warn) --- defensive check
+  const tableIssues = checkTableShape(blocks, "blocks");
+  for (const issue of tableIssues) {
+    findings.push({
+      severity: "warn",
+      code: "table-shape",
+      message: issue.message,
+      path: issue.path,
+    });
+  }
+
+  // --- nesting-depth (warn) --- defensive check
+  const depthIssues = checkNestingDepth(blocks, "blocks", 1);
+  for (const issue of depthIssues) {
+    findings.push({
+      severity: "warn",
+      code: "nesting-depth",
+      message: `Section at ${issue.path} exceeds maximum nesting depth of 3.`,
+      path: issue.path,
+    });
+  }
+
+  // --- redundant-raw-html (suggest) ---
+  for (const { block, path } of rawHtmlBlocks) {
+    const suggestion = detectRedundantRawHtml(block.html);
+    if (suggestion !== null) {
+      findings.push({
+        severity: "suggest",
+        code: "redundant-raw-html",
+        message: `raw_html block at ${path} contains framework markup that could be expressed as a \`${suggestion}\` block.`,
+        path,
+      });
+    }
+  }
+
+  // --- tldr-too-long (suggest) ---
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i];
+    if (b === undefined) continue;
+    if (b.type === "tldr" && b.markdown.length > 400) {
+      const path = `blocks[${i}]`;
+      findings.push({
+        severity: "suggest",
+        code: "tldr-too-long",
+        message: `tldr at ${path} is ${b.markdown.length} characters (>400). Keep tldrs punchy — aim for 1-3 sentences.`,
+        path,
+      });
+    }
+  }
+
+  // --- hero-not-first (warn) --- defensive: validate already enforces this
+  const heroIdx = findHeroIndex(blocks);
+  if (heroIdx > 0) {
+    findings.push({
+      severity: "warn",
+      code: "hero-not-first",
+      message: `Hero block found at blocks[${heroIdx}] but must be the first block.`,
+      path: `blocks[${heroIdx}]`,
+    });
+  }
+
+  // Sort, score with +5 baseline bonus, return
+  const sorted = sortFindings(findings);
+  // blocks mode starts at 105, capped at 100 — gives a +5 bonus for well-formed docs
+  const score = computeScore(sorted, 105);
+
+  return { score, findings: sorted, textLength: totalChars, mode: "blocks" };
+}
+
+// ---------------------------------------------------------------------------
+// Backwards-compat wrapper — accepts an HTML body string (html mode)
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated Use critiqueHtml() or critiqueBlocks() directly.
+ * Kept for backwards compatibility with existing call sites.
+ */
+export function critique(htmlBody: string): CritiqueResult {
+  return critiqueHtml(htmlBody);
 }