@cfbender/cesium 0.6.1 → 0.7.0

package/src/render/validate.ts

@@ -1,14 +1,9 @@
 // Validates cesium_publish and cesium_ask tool input before any write occurs.
 
-import { parseFragment, defaultTreeAdapter as ta } from "parse5";
-import type { DefaultTreeAdapterTypes } from "parse5";
 import type { Block } from "./blocks/types.ts";
 import { blockCatalog } from "./blocks/catalog.ts";
 import { deepValidateBlock } from "./blocks/validate-block.ts";
 
-type ChildNode = DefaultTreeAdapterTypes.ChildNode;
-type Element = DefaultTreeAdapterTypes.Element;
-
 export interface ValidationOk<T> {
   ok: true;
   value: T;
@@ -29,7 +24,8 @@ export type PublishKind =
   | "audit"
   | "rfc"
   | "other"
-  | "ask";
+  | "ask"
+  | "annotate";
 
 export const PUBLISH_KINDS: readonly PublishKind[] = [
   "plan",
@@ -42,10 +38,23 @@ export const PUBLISH_KINDS: readonly PublishKind[] = [
   "rfc",
   "other",
   "ask",
+  "annotate",
 ];
 
 // ─── Interactive artifact types ────────────────────────────────────────────────
 
+export type Comment = {
+  id: string; // server-assigned nanoid, opaque to client
+  anchor: string; // matches /^block-\d+(\.line-\d+)?$/
+  selectedText: string; // captured at submit time, ≤ 4096 chars
+  comment: string; // ≤ 16384 chars, non-empty after trim
+  createdAt: string; // ISO 8601
+};
+
+export type Verdict = "approve" | "request_changes" | "comment";
+
+export type VerdictMode = "approve" | "approve-or-reject" | "full";
+
 export type Option = {
   id: string;
   label: string;
@@ -114,7 +123,8 @@ export type AnswerValue =
   | { type: "slider"; value: number }
   | { type: "react"; decision: string; comment?: string };
 
-export type InteractiveData = {
+export type InteractiveAskData = {
+  kind: "ask";
   status: "open" | "complete" | "expired" | "cancelled";
   requireAll: boolean;
   expiresAt: string;
@@ -123,6 +133,20 @@ export type InteractiveData = {
   completedAt?: string;
 };
 
+export type InteractiveAnnotateData = {
+  kind: "annotate";
+  status: "open" | "complete" | "expired" | "cancelled";
+  expiresAt: string;
+  verdictMode: VerdictMode;
+  requireVerdict: boolean;
+  perLineFor: ("diff" | "code")[];
+  comments: Comment[];
+  verdict: { value: Verdict; decidedAt: string } | null;
+  completedAt?: string;
+};
+
+export type InteractiveData = InteractiveAskData | InteractiveAnnotateData;
+
 // ─── Question validation ───────────────────────────────────────────────────────
 
 function isNonEmptyString(v: unknown): v is string {
@@ -410,27 +434,309 @@ export function validateAskInput(input: unknown): AskValidationResult {
   return { ok: true, value: result };
 }
 
-// ─── PublishInput — supports html XOR blocks ──────────────────────────────────
+// ─── AnnotateInput validation ──────────────────────────────────────────────────
 
-export type PublishInput =
-  | {
-      title: string;
-      kind: PublishKind;
-      html: string;
-      blocks?: never;
-      summary?: string;
-      tags?: string[];
-      supersedes?: string;
+// annotate is blocks-only by design — no html/body escape valve.
+export interface AnnotateInput {
+  title: string;
+  blocks: Block[];
+  verdictMode?: VerdictMode;
+  perLineFor?: ("diff" | "code")[];
+  requireVerdict?: boolean;
+  summary?: string;
+  tags?: string[];
+  expiresAt?: string;
+}
+
+const VERDICT_MODES: readonly VerdictMode[] = ["approve", "approve-or-reject", "full"];
+
+function isVerdictMode(v: unknown): v is VerdictMode {
+  return typeof v === "string" && (VERDICT_MODES as readonly string[]).includes(v);
+}
+
+export function validateAnnotateInput(input: unknown): ValidationResult<AnnotateInput> {
+  if (input === null || typeof input !== "object") {
+    return { ok: false, error: "input must be an object" };
+  }
+  const raw = input as Record<string, unknown>;
+
+  // title — required, non-empty, ≤ 200 chars
+  if (!("title" in raw) || typeof raw["title"] !== "string" || raw["title"].trim() === "") {
+    return { ok: false, error: "title is required and must be a non-empty string" };
+  }
+  if (raw["title"].length > 200) {
+    return { ok: false, error: "title must be 200 characters or fewer" };
+  }
+  const title = raw["title"];
+
+  // annotate is blocks-only — stray `body` is silently ignored, not an error.
+
+  // blocks — required, non-empty array
+  if (!("blocks" in raw) || !Array.isArray(raw["blocks"]) || raw["blocks"].length === 0) {
+    return { ok: false, error: "blocks must be a non-empty array" };
+  }
+  const blocksResult = validateBlocksArray(raw["blocks"]);
+  if (!blocksResult.ok) {
+    const errorMessages = blocksResult.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+    return { ok: false, error: `blocks validation failed — ${errorMessages}` };
+  }
+
+  // verdictMode — optional, must be valid enum value
+  if ("verdictMode" in raw && raw["verdictMode"] !== undefined) {
+    if (!isVerdictMode(raw["verdictMode"])) {
+      return {
+        ok: false,
+        error: `verdictMode must be one of: ${VERDICT_MODES.join(", ")}`,
+      };
     }
-  | {
-      title: string;
-      kind: PublishKind;
-      blocks: Block[];
-      html?: never;
-      summary?: string;
-      tags?: string[];
-      supersedes?: string;
+  }
+
+  // perLineFor — optional array, only "diff" and "code", no duplicates
+  if ("perLineFor" in raw && raw["perLineFor"] !== undefined) {
+    if (!Array.isArray(raw["perLineFor"])) {
+      return { ok: false, error: "perLineFor must be an array" };
+    }
+    const seen = new Set<string>();
+    for (const item of raw["perLineFor"] as unknown[]) {
+      if (item !== "diff" && item !== "code") {
+        return {
+          ok: false,
+          error: `perLineFor items must be "diff" or "code", got "${String(item)}"`,
+        };
+      }
+      if (seen.has(item)) {
+        return {
+          ok: false,
+          error: `perLineFor must not contain duplicates, got duplicate "${item}"`,
+        };
+      }
+      seen.add(item);
+    }
+  }
+
+  // requireVerdict — optional boolean
+  if ("requireVerdict" in raw && raw["requireVerdict"] !== undefined) {
+    if (typeof raw["requireVerdict"] !== "boolean") {
+      return { ok: false, error: "requireVerdict must be a boolean" };
+    }
+  }
+
+  // summary — optional string
+  if ("summary" in raw && raw["summary"] !== undefined) {
+    if (typeof raw["summary"] !== "string") {
+      return { ok: false, error: "summary must be a string" };
+    }
+  }
+
+  // tags — optional array of strings
+  if ("tags" in raw && raw["tags"] !== undefined) {
+    if (!Array.isArray(raw["tags"])) {
+      return { ok: false, error: "tags must be an array of strings" };
+    }
+    for (const tag of raw["tags"]) {
+      if (typeof tag !== "string") {
+        return { ok: false, error: "tags must be an array of strings" };
+      }
+    }
+  }
+
+  // expiresAt — optional, must be valid ISO date string
+  if ("expiresAt" in raw && raw["expiresAt"] !== undefined) {
+    if (typeof raw["expiresAt"] !== "string") {
+      return { ok: false, error: "expiresAt must be a string" };
+    }
+    const d = new Date(raw["expiresAt"]);
+    if (isNaN(d.getTime())) {
+      return { ok: false, error: "expiresAt must be a valid ISO date string" };
+    }
+  }
+
+  const result: AnnotateInput = { title, blocks: blocksResult.blocks };
+  if (isVerdictMode(raw["verdictMode"])) result.verdictMode = raw["verdictMode"];
+  if (Array.isArray(raw["perLineFor"]))
+    result.perLineFor = raw["perLineFor"] as ("diff" | "code")[];
+  if (typeof raw["requireVerdict"] === "boolean") result.requireVerdict = raw["requireVerdict"];
+  if (typeof raw["summary"] === "string") result.summary = raw["summary"];
+  if (Array.isArray(raw["tags"])) result.tags = raw["tags"] as string[];
+  if (typeof raw["expiresAt"] === "string") result.expiresAt = raw["expiresAt"];
+
+  return { ok: true, value: result };
+}
+
+// ─── Comment value validation ──────────────────────────────────────────────────
+
+const ANCHOR_RE = /^block-\d+(\.line-\d+)?$/;
+
+export function validateCommentValue(
+  input: unknown,
+): ValidationResult<{ anchor: string; selectedText: string; comment: string }> {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, error: "input must be an object" };
+  }
+  const raw = input as Record<string, unknown>;
+
+  // anchor
+  if (typeof raw["anchor"] !== "string") {
+    return { ok: false, error: "anchor must be a string" };
+  }
+  if (!ANCHOR_RE.test(raw["anchor"])) {
+    return {
+      ok: false,
+      error: `anchor must match /^block-\\d+(\\.line-\\d+)?$/, got "${raw["anchor"]}"`,
+    };
+  }
+  const anchor = raw["anchor"];
+
+  // selectedText — required, can be empty, ≤ 4096 chars
+  if (typeof raw["selectedText"] !== "string") {
+    return { ok: false, error: "selectedText must be a string" };
+  }
+  if (raw["selectedText"].length > 4096) {
+    return { ok: false, error: "selectedText must be 4096 characters or fewer" };
+  }
+  const selectedText = raw["selectedText"];
+
+  // comment — required, non-empty after trim, ≤ 16384 chars
+  if (typeof raw["comment"] !== "string") {
+    return { ok: false, error: "comment must be a string" };
+  }
+  if (raw["comment"].trim() === "") {
+    return { ok: false, error: "comment must be non-empty" };
+  }
+  if (raw["comment"].length > 16384) {
+    return { ok: false, error: "comment must be 16384 characters or fewer" };
+  }
+  const comment = raw["comment"];
+
+  return { ok: true, value: { anchor, selectedText, comment } };
+}
+
+// ─── Verdict value validation ──────────────────────────────────────────────────
+
+const VERDICTS_BY_MODE: Record<VerdictMode, readonly Verdict[]> = {
+  approve: ["approve"],
+  "approve-or-reject": ["approve", "request_changes"],
+  full: ["approve", "request_changes", "comment"],
+};
+
+export function validateVerdictValue(input: unknown, mode: VerdictMode): ValidationResult<Verdict> {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, error: "input must be an object" };
+  }
+  const raw = input as Record<string, unknown>;
+
+  if (typeof raw["verdict"] !== "string") {
+    return { ok: false, error: "verdict must be a string" };
+  }
+  const v = raw["verdict"];
+  const allowed = VERDICTS_BY_MODE[mode];
+  if (!(allowed as readonly string[]).includes(v)) {
+    return {
+      ok: false,
+      error: `verdict "${v}" is not allowed in "${mode}" mode; allowed: ${allowed.join(", ")}`,
     };
+  }
+
+  return { ok: true, value: v as Verdict };
+}
+
+// ─── coerceInteractiveData ─────────────────────────────────────────────────────
+
+function isValidStatus(v: unknown): v is InteractiveData["status"] {
+  return v === "open" || v === "complete" || v === "expired" || v === "cancelled";
+}
+
+function coerceAsAskData(raw: Record<string, unknown>): InteractiveAskData | null {
+  if (!isValidStatus(raw["status"])) return null;
+  if (!Array.isArray(raw["questions"])) return null;
+  if (typeof raw["requireAll"] !== "boolean") return null;
+  if (typeof raw["expiresAt"] !== "string") return null;
+  const answers =
+    raw["answers"] !== null && typeof raw["answers"] === "object" && !Array.isArray(raw["answers"])
+      ? (raw["answers"] as Record<string, { value: AnswerValue; answeredAt: string }>)
+      : null;
+  if (answers === null) return null;
+
+  const result: InteractiveAskData = {
+    kind: "ask",
+    status: raw["status"],
+    requireAll: raw["requireAll"],
+    expiresAt: raw["expiresAt"],
+    questions: raw["questions"] as Question[],
+    answers,
+  };
+  if (typeof raw["completedAt"] === "string") result.completedAt = raw["completedAt"];
+  return result;
+}
+
+function coerceAsAnnotateData(raw: Record<string, unknown>): InteractiveAnnotateData | null {
+  if (!isValidStatus(raw["status"])) return null;
+  if (typeof raw["expiresAt"] !== "string") return null;
+  if (!isVerdictMode(raw["verdictMode"])) return null;
+  if (typeof raw["requireVerdict"] !== "boolean") return null;
+  if (!Array.isArray(raw["perLineFor"])) return null;
+  if (!Array.isArray(raw["comments"])) return null;
+  // verdict can be null or an object
+  const rawVerdict = raw["verdict"];
+  const verdict =
+    rawVerdict === null
+      ? null
+      : rawVerdict !== null &&
+          typeof rawVerdict === "object" &&
+          !Array.isArray(rawVerdict) &&
+          typeof (rawVerdict as Record<string, unknown>)["value"] === "string" &&
+          typeof (rawVerdict as Record<string, unknown>)["decidedAt"] === "string"
+        ? (rawVerdict as { value: Verdict; decidedAt: string })
+        : undefined;
+  if (verdict === undefined) return null;
+
+  const result: InteractiveAnnotateData = {
+    kind: "annotate",
+    status: raw["status"],
+    expiresAt: raw["expiresAt"],
+    verdictMode: raw["verdictMode"],
+    requireVerdict: raw["requireVerdict"],
+    perLineFor: raw["perLineFor"] as ("diff" | "code")[],
+    comments: raw["comments"] as Comment[],
+    verdict,
+  };
+  if (typeof raw["completedAt"] === "string") result.completedAt = raw["completedAt"];
+  return result;
+}
+
+/**
+ * Tolerant reader for embedded cesium-meta.interactive JSON.
+ *
+ * - Returns null for non-object input or unrecognized shapes.
+ * - Legacy ask artifacts (without a `kind` field) are coerced to InteractiveAskData
+ *   with `kind: "ask"` injected.
+ */
+export function coerceInteractiveData(raw: unknown): InteractiveData | null {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+
+  if (obj["kind"] === "annotate") {
+    return coerceAsAnnotateData(obj);
+  }
+
+  if (obj["kind"] === "ask" || obj["kind"] === undefined || !("kind" in obj)) {
+    return coerceAsAskData(obj);
+  }
+
+  // Unknown kind
+  return null;
+}
+
+// ─── PublishInput — blocks-only ──────────────────────────────────────────────
+
+export interface PublishInput {
+  title: string;
+  kind: PublishKind;
+  blocks: Block[];
+  summary?: string;
+  tags?: string[];
+  supersedes?: string;
+}
 
 function isPublishKind(val: unknown): val is PublishKind {
   return typeof val === "string" && (PUBLISH_KINDS as readonly string[]).includes(val);
@@ -645,7 +951,7 @@ function validateBlock(raw: unknown, path: string, depth: number): BlockValidati
   return errors;
 }
 
-function validateBlocksArray(raw: unknown): BlockValidationResult {
+export function validateBlocksArray(raw: unknown): BlockValidationResult {
   if (!Array.isArray(raw)) {
     return { ok: false, errors: [{ path: "blocks", message: "blocks must be an array" }] };
   }
@@ -725,15 +1031,18 @@ export function validatePublishInput(input: unknown): ValidationResult<PublishIn
   }
   const kind = raw["kind"];
 
-  // XOR: exactly one of html or blocks
-  const hasHtml = "html" in raw && raw["html"] !== undefined;
-  const hasBlocks = "blocks" in raw && raw["blocks"] !== undefined;
-
-  if (hasHtml && hasBlocks) {
-    return { ok: false, error: "provide exactly one of html or blocks, not both" };
-  }
-  if (!hasHtml && !hasBlocks) {
-    return { ok: false, error: "provide exactly one of html or blocks" };
+  // blocks — required, non-empty
+  if (
+    !("blocks" in raw) ||
+    raw["blocks"] === undefined ||
+    !Array.isArray(raw["blocks"]) ||
+    raw["blocks"].length === 0
+  ) {
+    return {
+      ok: false,
+      error:
+        "cesium_publish requires a non-empty `blocks` array. Call `cesium_styleguide` for the block catalog.",
+    };
   }
 
   // summary (optional)
@@ -765,69 +1074,16 @@ export function validatePublishInput(input: unknown): ValidationResult<PublishIn
     }
   }
 
-  const commonFields = {
-    title,
-    kind,
-    ...(typeof raw["summary"] === "string" ? { summary: raw["summary"] } : {}),
-    ...(Array.isArray(raw["tags"]) ? { tags: raw["tags"] as string[] } : {}),
-    ...(typeof raw["supersedes"] === "string" ? { supersedes: raw["supersedes"] } : {}),
-  };
-
-  if (hasHtml) {
-    // html branch
-    if (typeof raw["html"] !== "string" || raw["html"].trim() === "") {
-      return { ok: false, error: "html is required and must be a non-empty string" };
-    }
-    return {
-      ok: true,
-      value: { ...commonFields, html: raw["html"] },
-    };
-  } else {
-    // blocks branch
-    const blocksResult = validateBlocksArray(raw["blocks"]);
-    if (!blocksResult.ok) {
-      const errorMessages = blocksResult.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
-      return { ok: false, error: `blocks validation failed — ${errorMessages}` };
-    }
-    return {
-      ok: true,
-      value: { ...commonFields, blocks: blocksResult.blocks },
-    };
-  }
-}
-
-const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
-
-function walkNodes(nodes: ChildNode[], visitor: (node: ChildNode) => void): void {
-  for (const node of nodes) {
-    visitor(node);
-    if (ta.isElementNode(node)) {
-      walkNodes(ta.getChildNodes(node as Element) as ChildNode[], visitor);
-    }
+  const blocksResult = validateBlocksArray(raw["blocks"]);
+  if (!blocksResult.ok) {
+    const errorMessages = blocksResult.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+    return { ok: false, error: `blocks validation failed — ${errorMessages}` };
   }
-}
 
-export function htmlBodyWarnings(htmlBody: string): string[] {
-  try {
-    const warnings: string[] = [];
-    const fragment = parseFragment(htmlBody);
-    const children = ta.getChildNodes(fragment) as ChildNode[];
-    let hasHeading = false;
+  const value: PublishInput = { title, kind, blocks: blocksResult.blocks };
+  if (typeof raw["summary"] === "string") value.summary = raw["summary"];
+  if (Array.isArray(raw["tags"])) value.tags = raw["tags"] as string[];
+  if (typeof raw["supersedes"] === "string") value.supersedes = raw["supersedes"];
 
-    walkNodes(children, (node) => {
-      if (ta.isElementNode(node)) {
-        const el = node as Element;
-        const tag = ta.getTagName(el);
-        if (HEADING_TAGS.has(tag)) hasHeading = true;
-      }
-    });
-
-    if (!hasHeading) {
-      warnings.push("no headings found — consider adding an <h1> or <h2>");
-    }
-
-    return warnings;
-  } catch {
-    return [];
-  }
+  return { ok: true, value };
 }

package/src/render/wrap.ts

@@ -5,7 +5,13 @@ import { buildThemeCss } from "../storage/theme-write.ts";
 import { renderControl, renderAnswered } from "./controls.ts";
 import { getClientJs } from "./client-js.ts";
 import { faviconLinkTag } from "./favicon.ts";
-import type { InteractiveData, Question } from "./validate.ts";
+import type {
+  InteractiveData,
+  InteractiveAskData,
+  InteractiveAnnotateData,
+  Question,
+  VerdictMode,
+} from "./validate.ts";
 
 export interface ArtifactMeta {
   id: string;
@@ -25,7 +31,6 @@ export interface ArtifactMeta {
   supersedes: string | null;
   supersededBy: string | null;
   contentSha256: string;
-  inputMode: "html" | "blocks";
 }
 
 export interface WrapOptions {
@@ -80,7 +85,7 @@ const BACK_LINK_STYLE = "color: var(--muted); text-decoration: none;";
 
 // ─── Interactive rendering ─────────────────────────────────────────────────────
 
-function renderQuestionSection(q: Question, interactive: InteractiveData): string {
+function renderQuestionSection(q: Question, interactive: InteractiveAskData): string {
   const answered = interactive.answers[q.id];
 
   if (answered !== undefined) {
@@ -90,11 +95,62 @@ function renderQuestionSection(q: Question, interactive: InteractiveData): strin
   return renderControl(q);
 }
 
+function renderVerdictButtons(verdictMode: VerdictMode, isOpen: boolean): string {
+  // When open, render buttons WITHOUT disabled — client JS gates them based on
+  // comment count and session status. When not open, mark all disabled.
+  const disabled = isOpen ? "" : ' disabled aria-disabled="true"';
+  const buttons: string[] = [];
+
+  buttons.push(
+    `<button type="button" class="cs-verdict-btn cs-verdict-approve" data-verdict="approve"${disabled}>Approve</button>`,
+  );
+
+  if (verdictMode === "approve-or-reject" || verdictMode === "full") {
+    buttons.push(
+      `<button type="button" class="cs-verdict-btn cs-verdict-request_changes" data-verdict="request_changes"${disabled}>Request changes</button>`,
+    );
+  }
+
+  if (verdictMode === "full") {
+    buttons.push(
+      `<button type="button" class="cs-verdict-btn cs-verdict-comment" data-verdict="comment"${disabled}>Comment</button>`,
+    );
+  }
+
+  return buttons.join("\n      ");
+}
+
+function renderAnnotateScaffold(interactive: InteractiveAnnotateData): string {
+  const isOpen = interactive.status === "open";
+  const verdictButtons = renderVerdictButtons(interactive.verdictMode, isOpen);
+
+  return `<section class="cs-annotate-scaffold" data-cesium-annotate-scaffold data-cesium-verdict-mode="${interactive.verdictMode}" data-cesium-status="${interactive.status}">
+  <template id="cs-annotate-comment-popup">
+    <div class="cs-comment-popup" role="dialog" aria-label="Add a comment">
+      <textarea class="cs-comment-input" placeholder="Add a comment\u2026"></textarea>
+      <div class="cs-comment-actions">
+        <button type="button" class="cs-comment-save" disabled>Save</button>
+        <button type="button" class="cs-comment-cancel">Cancel</button>
+      </div>
+    </div>
+  </template>
+  <aside class="cs-comment-rail" data-cesium-comment-rail aria-label="Review comments"></aside>
+  <footer class="cs-verdict-footer">
+    <span class="cs-comment-count" data-cesium-comment-count>0 comments</span>
+    ${verdictButtons}
+  </footer>
+</section>`;
+}
+
 function renderInteractive(interactive: InteractiveData): string {
-  const sections = interactive.questions
-    .map((q) => renderQuestionSection(q, interactive))
-    .join("\n");
-  return `\n<section class="cs-questions">\n${sections}\n</section>`;
+  if (interactive.kind === "ask") {
+    const sections = interactive.questions
+      .map((q) => renderQuestionSection(q, interactive))
+      .join("\n");
+    return `\n<section class="cs-questions">\n${sections}\n</section>`;
+  }
+  // interactive.kind === "annotate"
+  return `\n${renderAnnotateScaffold(interactive)}`;
 }
 
 function renderBackNav(meta: ArtifactMeta): string {
@@ -148,8 +204,10 @@ export function wrapDocument(opts: WrapOptions): string {
   // cascade order — so theme upgrades retroactively apply to served artifacts
   // while standalone copies retain their generation-time look.
   const themeCss = buildThemeCss(theme);
-  // Embed interactive into the cesium-meta JSON block when present
-  const metaPayload: Record<string, unknown> = { ...meta };
+  // Embed interactive into the cesium-meta JSON block when present.
+  // inputMode is frozen at "blocks" on-disk for stability; the field is kept
+  // on emitted metadata so older readers/tools that look for it still see a value.
+  const metaPayload: Record<string, unknown> = { ...meta, inputMode: "blocks" };
   if (interactive !== undefined) {
     metaPayload["interactive"] = interactive;
   }