@cfbender/cesium 0.3.5

package/src/render/controls.ts

@@ -0,0 +1,302 @@
+// Pure HTML render functions for each interactive question type.
+// renderControl  — pre-submission interactive control
+// renderAnswered — post-submission read-only answered section
+
+import type { Question, AnswerValue } from "./validate.ts";
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function escapeAttr(str: string): string {
+  return escapeHtml(str);
+}
+
+// ─── Header shared by both control and answered sections ──────────────────────
+
+function renderSectionHeader(q: Question): string {
+  const qTextEsc = escapeHtml(q.question);
+  const contextLine =
+    q.context !== undefined ? `\n  <p class="cs-context">${escapeHtml(q.context)}</p>` : "";
+  const eyebrow = q.context !== undefined ? `QUESTION | ${escapeHtml(q.context)}` : "QUESTION";
+  return `  <p class="eyebrow">${eyebrow}</p>
+  <h3 class="h-section">${qTextEsc}</h3>${contextLine}`;
+}
+
+// ─── renderControl — interactive (pre-submission) ─────────────────────────────
+
+function renderPickOneControl(q: Extract<Question, { type: "pick_one" }>): string {
+  const buttons = q.options
+    .map((opt) => {
+      const isRecommended = q.recommended !== undefined && q.recommended === opt.id;
+      const cls = isRecommended ? "cs-pick cs-recommended" : "cs-pick";
+      const recommendedChip = isRecommended
+        ? `\n    <span class="eyebrow" style="color: var(--accent);">RECOMMENDED</span>`
+        : "";
+      const descLine =
+        opt.description !== undefined
+          ? `\n    <p class="cs-pick-desc">${escapeHtml(opt.description)}</p>`
+          : "";
+      return `  <button class="${cls}" data-value="${escapeAttr(opt.id)}">
+    <strong>${escapeHtml(opt.label)}</strong>${recommendedChip}${descLine}
+  </button>`;
+    })
+    .join("\n");
+  return buttons;
+}
+
+function renderPickManyControl(q: Extract<Question, { type: "pick_many" }>): string {
+  const hint =
+    q.min !== undefined || q.max !== undefined
+      ? (() => {
+          const parts: string[] = [];
+          if (q.min !== undefined) parts.push(`at least ${q.min}`);
+          if (q.max !== undefined) parts.push(`at most ${q.max}`);
+          return `\n  <p class="eyebrow">PICK ${parts.join(" / ")}</p>`;
+        })()
+      : "";
+  const checkboxes = q.options
+    .map((opt) => {
+      const descLine =
+        opt.description !== undefined
+          ? `\n    <p class="cs-pick-desc">${escapeHtml(opt.description)}</p>`
+          : "";
+      return `  <label class="cs-pick">
+    <input type="checkbox" data-value="${escapeAttr(opt.id)}">
+    <strong>${escapeHtml(opt.label)}</strong>${descLine}
+  </label>`;
+    })
+    .join("\n");
+  return `${hint}
+${checkboxes}
+  <button class="cs-submit" disabled>Submit</button>`;
+}
+
+function renderConfirmControl(q: Extract<Question, { type: "confirm" }>): string {
+  const yesLabel = escapeHtml(q.yesLabel ?? "Yes");
+  const noLabel = escapeHtml(q.noLabel ?? "No");
+  return `  <div class="cs-confirm-row">
+    <button class="cs-confirm cs-yes" data-value="yes">${yesLabel}</button>
+    <button class="cs-confirm cs-no" data-value="no">${noLabel}</button>
+  </div>`;
+}
+
+function renderAskTextControl(q: Extract<Question, { type: "ask_text" }>): string {
+  const placeholder = q.placeholder !== undefined ? escapeAttr(q.placeholder) : "";
+  const idAttr = escapeAttr(q.id);
+  const skipButton =
+    q.optional === true
+      ? `\n  <div class="cs-button-row">\n    <button class="cs-submit" data-question-id="${idAttr}" disabled>Submit</button>\n    <button class="cs-skip" data-question-id="${idAttr}">Skip</button>\n  </div>`
+      : `\n  <button class="cs-submit" disabled>Submit</button>`;
+  if (q.multiline === true) {
+    return `  <textarea class="cs-text" rows="4" placeholder="${placeholder}"></textarea>${skipButton}`;
+  }
+  return `  <input type="text" class="cs-text" placeholder="${placeholder}">${skipButton}`;
+}
+
+function renderSliderControl(q: Extract<Question, { type: "slider" }>): string {
+  const min = q.min;
+  const max = q.max;
+  const step = q.step ?? 1;
+  const defaultVal = q.defaultValue ?? min;
+  return `  <input type="range" class="cs-slider" min="${min}" max="${max}" step="${step}" value="${defaultVal}">
+  <output class="cs-slider-out">${defaultVal}</output>
+  <button class="cs-submit">Submit</button>`;
+}
+
+function renderReactControl(q: Extract<Question, { type: "react" }>): string {
+  const mode = q.mode ?? "approve";
+  const commentTextarea =
+    q.allowComment === true
+      ? `\n  <textarea class="cs-react-comment" placeholder="Optional comment..."></textarea>`
+      : "";
+
+  let buttons: string;
+  if (mode === "thumbs") {
+    buttons = `  <button class="cs-react" data-value="up">Thumbs up</button>
+  <button class="cs-react" data-value="down">Thumbs down</button>`;
+  } else {
+    buttons = `  <button class="cs-react" data-value="approve">Approve</button>
+  <button class="cs-react" data-value="reject">Reject</button>
+  <button class="cs-react" data-value="comment">Just a comment</button>`;
+  }
+
+  return `${commentTextarea}
+  <div class="cs-react-row">
+${buttons}
+  </div>`;
+}
+
+/** Renders the interactive (pre-submission) control HTML for a question. */
+export function renderControl(question: Question): string {
+  const idAttr = escapeAttr(question.id);
+  const header = renderSectionHeader(question);
+  let controlHtml: string;
+
+  switch (question.type) {
+    case "pick_one":
+      controlHtml = renderPickOneControl(question);
+      break;
+    case "pick_many":
+      controlHtml = renderPickManyControl(question);
+      break;
+    case "confirm":
+      controlHtml = renderConfirmControl(question);
+      break;
+    case "ask_text":
+      controlHtml = renderAskTextControl(question);
+      break;
+    case "slider":
+      controlHtml = renderSliderControl(question);
+      break;
+    case "react":
+      controlHtml = renderReactControl(question);
+      break;
+  }
+
+  return `<section class="cs-control-${question.type}" data-question-id="${idAttr}">
+${header}
+${controlHtml}
+</section>`;
+}
+
+// ─── renderAnswered — read-only post-submission ───────────────────────────────
+
+function renderAnsweredPickOne(
+  q: Extract<Question, { type: "pick_one" }>,
+  answer: Extract<AnswerValue, { type: "pick_one" }>,
+): string {
+  const opt = q.options.find((o) => o.id === answer.selected);
+  const label = opt !== undefined ? escapeHtml(opt.label) : escapeHtml(answer.selected);
+  const descLine =
+    opt?.description !== undefined
+      ? `\n    <p class="cs-pick-desc">${escapeHtml(opt.description)}</p>`
+      : "";
+  return `  <div class="cs-pick cs-pick-final">
+    <strong>${label}</strong>${descLine}
+  </div>`;
+}
+
+function renderAnsweredPickMany(
+  q: Extract<Question, { type: "pick_many" }>,
+  answer: Extract<AnswerValue, { type: "pick_many" }>,
+): string {
+  return answer.selected
+    .map((sel) => {
+      const opt = q.options.find((o) => o.id === sel);
+      const label = opt !== undefined ? escapeHtml(opt.label) : escapeHtml(sel);
+      const descLine =
+        opt?.description !== undefined
+          ? `\n    <p class="cs-pick-desc">${escapeHtml(opt.description)}</p>`
+          : "";
+      return `  <div class="cs-pick cs-pick-final">
+    <strong>${label}</strong>${descLine}
+  </div>`;
+    })
+    .join("\n");
+}
+
+function renderAnsweredConfirm(
+  q: Extract<Question, { type: "confirm" }>,
+  answer: Extract<AnswerValue, { type: "confirm" }>,
+): string {
+  const yesClass =
+    answer.choice === "yes" ? "cs-confirm cs-confirm-final cs-yes" : "cs-confirm cs-no";
+  const noClass =
+    answer.choice === "no" ? "cs-confirm cs-confirm-final cs-no" : "cs-confirm cs-yes";
+  const yesLabel = escapeHtml(q.yesLabel ?? "Yes");
+  const noLabel = escapeHtml(q.noLabel ?? "No");
+  if (answer.choice === "yes") {
+    return `  <div class="cs-confirm-row">
+    <button class="${yesClass}" disabled>${yesLabel}</button>
+    <button class="${noClass}" disabled aria-disabled="true" style="opacity: 0.4;">${noLabel}</button>
+  </div>`;
+  }
+  return `  <div class="cs-confirm-row">
+    <button class="${yesClass}" disabled aria-disabled="true" style="opacity: 0.4;">${yesLabel}</button>
+    <button class="${noClass}" disabled>${noLabel}</button>
+  </div>`;
+}
+
+function renderAnsweredAskText(
+  q: Extract<Question, { type: "ask_text" }>,
+  answer: Extract<AnswerValue, { type: "ask_text" }>,
+): string {
+  if (answer.text === "" && q.optional === true) {
+    return `  <p class="cs-answered-skipped"><em>(skipped)</em></p>`;
+  }
+  const escaped = escapeHtml(answer.text);
+  const withBreaks = escaped.replace(/\n/g, "<br>");
+  return `  <blockquote class="cs-answered-text">${withBreaks}</blockquote>`;
+}
+
+function renderAnsweredSlider(answer: Extract<AnswerValue, { type: "slider" }>): string {
+  return `  <p class="cs-slider-final">Value: <strong>${answer.value}</strong></p>`;
+}
+
+function renderAnsweredReact(answer: Extract<AnswerValue, { type: "react" }>): string {
+  const decisionClass = `cs-react cs-confirm-final`;
+  const commentHtml =
+    answer.comment !== undefined && answer.comment !== ""
+      ? `\n  <p class="cs-comment">${escapeHtml(answer.comment)}</p>`
+      : "";
+  return `  <div class="cs-react-row">
+    <button class="${decisionClass}" disabled>${escapeHtml(answer.decision)}</button>
+  </div>${commentHtml}`;
+}
+
+/** Renders the read-only post-submission answered section for a question. */
+export function renderAnswered(question: Question, answer: AnswerValue): string {
+  const idAttr = escapeAttr(question.id);
+  const qTextEsc = escapeHtml(question.question);
+  let valueHtml: string;
+
+  switch (answer.type) {
+    case "pick_one": {
+      if (question.type !== "pick_one") {
+        valueHtml = "";
+        break;
+      }
+      valueHtml = renderAnsweredPickOne(question, answer);
+      break;
+    }
+    case "pick_many": {
+      if (question.type !== "pick_many") {
+        valueHtml = "";
+        break;
+      }
+      valueHtml = renderAnsweredPickMany(question, answer);
+      break;
+    }
+    case "confirm": {
+      if (question.type !== "confirm") {
+        valueHtml = "";
+        break;
+      }
+      valueHtml = renderAnsweredConfirm(question, answer);
+      break;
+    }
+    case "ask_text":
+      valueHtml = renderAnsweredAskText(
+        question as Extract<Question, { type: "ask_text" }>,
+        answer,
+      );
+      break;
+    case "slider":
+      valueHtml = renderAnsweredSlider(answer);
+      break;
+    case "react":
+      valueHtml = renderAnsweredReact(answer);
+      break;
+  }
+
+  return `<section class="cs-answered" data-question-id="${idAttr}">
+  <p class="eyebrow">YOU ANSWERED</p>
+  <h3 class="h-section">${qTextEsc}</h3>
+${valueHtml}
+</section>`;
+}

package/src/render/critique.ts

@@ -0,0 +1,360 @@
+// Pure HTML body analyzer — walks parse5 AST and returns structured findings + 0-100 score.
+// Deterministic and pure: same input always yields the same output.
+
+import { parseFragment, defaultTreeAdapter as ta } from "parse5";
+import type { DefaultTreeAdapterMap, DefaultTreeAdapterTypes, ParserOptions } from "parse5";
+
+type ChildNode = DefaultTreeAdapterTypes.ChildNode;
+type Element = DefaultTreeAdapterTypes.Element;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type CritiqueSeverity = "info" | "suggest" | "warn";
+
+export interface CritiqueFinding {
+  severity: CritiqueSeverity;
+  /** Stable kebab-case identifier, e.g. "no-tldr". */
+  code: string;
+  /** Single sentence, agent-readable. */
+  message: string;
+  /** Populated when the rule represents an aggregate count. */
+  count?: number;
+}
+
+export interface CritiqueResult {
+  /** 0-100 score computed from findings. */
+  score: number;
+  /** Ordered: warn → suggest → info, then alphabetically by code. */
+  findings: CritiqueFinding[];
+  /** Sum of all text node values in the body (visible text content length). */
+  textLength: number;
+}
+
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+
+const HTTP_RE = /^https?:\/\//i;
+
+/** The only cesium-* class the framework ships with. All others are unknown. */
+const KNOWN_CESIUM_CLASSES = new Set(["cesium-back"]);
+
+/** Callout severity modifiers — a callout needs at least one of these. */
+const CALLOUT_MODIFIERS = new Set(["note", "warn", "risk"]);
+
+/** Inline highlight span classes for .code blocks. */
+const CODE_HIGHLIGHT_CLASSES = new Set(["kw", "str", "cm", "fn"]);
+
+const SEVERITY_DEDUCTION: Record<CritiqueSeverity, number> = {
+  warn: 10,
+  suggest: 3,
+  info: 1,
+};
+
+const SEVERITY_ORDER: Record<CritiqueSeverity, number> = {
+  warn: 0,
+  suggest: 1,
+  info: 2,
+};
+
+// ---------------------------------------------------------------------------
+// Tree-walking helpers
+// ---------------------------------------------------------------------------
+
+function walkNodes(nodes: readonly 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);
+    }
+  }
+}
+
+function getClasses(el: Element): Set<string> {
+  const attr = ta.getAttrList(el).find((a) => a.name === "class");
+  if (!attr || !attr.value.trim()) return new Set();
+  return new Set(attr.value.trim().split(/\s+/));
+}
+
+function attrVal(el: Element, name: string): string | undefined {
+  return ta.getAttrList(el).find((a) => a.name === name)?.value;
+}
+
+/** Recursively sum all text-node values — gives the visible text content length. */
+function collectTextLength(nodes: readonly ChildNode[]): number {
+  let total = 0;
+  for (const node of nodes) {
+    if (ta.isTextNode(node)) {
+      total += node.value.length;
+    } else if (ta.isElementNode(node)) {
+      total += collectTextLength(ta.getChildNodes(node as Element) as ChildNode[]);
+    }
+  }
+  return total;
+}
+
+/** Returns true if any descendant of `el` carries a code-highlight class. */
+function hasHighlightDescendant(el: Element): boolean {
+  let found = false;
+  walkNodes(ta.getChildNodes(el) as ChildNode[], (node) => {
+    if (found || !ta.isElementNode(node)) return;
+    const cls = getClasses(node as Element);
+    for (const c of CODE_HIGHLIGHT_CLASSES) {
+      if (cls.has(c)) {
+        found = true;
+        return;
+      }
+    }
+  });
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// Scoring + ordering
+// ---------------------------------------------------------------------------
+
+function computeScore(findings: readonly CritiqueFinding[]): number {
+  let score = 100;
+  for (const f of findings) {
+    score -= SEVERITY_DEDUCTION[f.severity];
+  }
+  return Math.max(0, score);
+}
+
+function sortFindings(findings: CritiqueFinding[]): CritiqueFinding[] {
+  return [...findings].toSorted((a, b) => {
+    const sevDiff = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return a.code.localeCompare(b.code);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main analyzer — pure, deterministic
+// ---------------------------------------------------------------------------
+
+export function critique(htmlBody: string): CritiqueResult {
+  const fragment = parseFragment(htmlBody);
+  const children = ta.getChildNodes(fragment) as ChildNode[];
+  const findings: CritiqueFinding[] = [];
+
+  // Visible text content length
+  const textLength = collectTextLength(children);
+
+  // Counters / flags accumulated in the single tree walk
+  let hDisplayCount = 0;
+  let hSectionCount = 0;
+  let tldrCount = 0;
+  let eyebrowCount = 0;
+  let calloutNoModifierCount = 0;
+  let externalResourceFound = false;
+  let inlineStyleCount = 0;
+  let hasSection = false;
+  const unknownCesiumClasses = new Set<string>();
+  let codeBlocksWithoutHighlights = 0;
+
+  walkNodes(children, (node) => {
+    if (!ta.isElementNode(node)) return;
+    const el = node as Element;
+    const tag = ta.getTagName(el);
+    const cls = getClasses(el);
+
+    // Section tag present?
+    if (tag === "section") hasSection = true;
+
+    // --- External resource detection (warn) ---
+    if (!externalResourceFound) {
+      if (tag === "script" && attrVal(el, "src") !== undefined) {
+        externalResourceFound = true;
+      } else if (tag === "link") {
+        const rel = (attrVal(el, "rel") ?? "").toLowerCase();
+        const href = attrVal(el, "href") ?? "";
+        if (rel === "stylesheet" && HTTP_RE.test(href)) {
+          externalResourceFound = true;
+        }
+      } else if (tag === "img") {
+        const src = attrVal(el, "src") ?? "";
+        if (HTTP_RE.test(src)) {
+          externalResourceFound = true;
+        }
+      }
+    }
+
+    // --- Class-based counts ---
+    if (cls.has("h-display")) hDisplayCount++;
+    if (cls.has("h-section")) hSectionCount++;
+    if (cls.has("tldr")) tldrCount++;
+    if (cls.has("eyebrow")) eyebrowCount++;
+
+    // Callout without a severity modifier
+    if (cls.has("callout")) {
+      let hasModifier = false;
+      for (const mod of CALLOUT_MODIFIERS) {
+        if (cls.has(mod)) {
+          hasModifier = true;
+          break;
+        }
+      }
+      if (!hasModifier) calloutNoModifierCount++;
+    }
+
+    // Unknown cesium-* class names
+    for (const c of cls) {
+      if (c.startsWith("cesium-") && !KNOWN_CESIUM_CLASSES.has(c)) {
+        unknownCesiumClasses.add(c);
+      }
+    }
+
+    // .code block without inline highlights
+    if (cls.has("code") && !hasHighlightDescendant(el)) {
+      codeBlocksWithoutHighlights++;
+    }
+
+    // Inline style attribute
+    if (attrVal(el, "style") !== undefined) inlineStyleCount++;
+  });
+
+  // Detect parse errors via a second parseFragment pass with onParseError
+  let parseErrors = 0;
+  const parseOpts: ParserOptions<DefaultTreeAdapterMap> = {
+    onParseError: () => {
+      parseErrors++;
+    },
+  };
+  parseFragment(htmlBody, parseOpts);
+
+  // ---------------------------------------------------------------------------
+  // Emit warn-level findings
+  // ---------------------------------------------------------------------------
+
+  if (externalResourceFound) {
+    findings.push({
+      severity: "warn",
+      code: "external-resource",
+      message:
+        "External resource will be stripped at publish time. Use inline styles/scripts/data URIs.",
+    });
+  }
+
+  if (hDisplayCount > 1) {
+    findings.push({
+      severity: "warn",
+      code: "multiple-h-display",
+      message: "Only one .h-display per artifact (it's the page title).",
+    });
+  }
+
+  if (parseErrors > 0) {
+    findings.push({
+      severity: "warn",
+      code: "unbalanced-html",
+      message:
+        "Body has structural HTML issues; the browser will attempt recovery but layout may break.",
+    });
+  }
+
+  if (unknownCesiumClasses.size > 0) {
+    findings.push({
+      severity: "warn",
+      code: "unknown-cesium-class",
+      message: `Found ${unknownCesiumClasses.size} unknown cesium-* class names; the framework only ships with the documented vocabulary.`,
+      count: unknownCesiumClasses.size,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Emit suggest-level findings
+  // ---------------------------------------------------------------------------
+
+  if (hDisplayCount === 0) {
+    findings.push({
+      severity: "suggest",
+      code: "no-h-display",
+      message: "No .h-display heading; agent should give the artifact a clear page title.",
+    });
+  }
+
+  if (tldrCount === 0 && textLength > 1500) {
+    findings.push({
+      severity: "suggest",
+      code: "no-tldr",
+      message: "Long artifact with no .tldr summary; consider adding one near the top.",
+    });
+  }
+
+  if (eyebrowCount === 0) {
+    findings.push({
+      severity: "suggest",
+      code: "no-eyebrow",
+      message: "No .eyebrow micro-labels — they help anchor sections and document type.",
+    });
+  }
+
+  if (textLength > 1200 && hSectionCount === 0 && !hasSection) {
+    findings.push({
+      severity: "suggest",
+      code: "unsectioned-long-body",
+      message: "Long body has no section markers; readability suffers.",
+    });
+  }
+
+  if (calloutNoModifierCount > 0) {
+    findings.push({
+      severity: "suggest",
+      code: "callout-without-modifier",
+      message: `${calloutNoModifierCount} callout${calloutNoModifierCount === 1 ? "" : "s"} have no severity modifier (.note/.warn/.risk).`,
+      count: calloutNoModifierCount,
+    });
+  }
+
+  if (textLength < 250) {
+    findings.push({
+      severity: "suggest",
+      code: "body-too-short",
+      message:
+        "Very short body; a terminal reply may be more appropriate than a published artifact.",
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Emit info-level findings
+  // ---------------------------------------------------------------------------
+
+  if (textLength > 25000) {
+    findings.push({
+      severity: "info",
+      code: "body-very-long",
+      message: "Very long artifact; consider splitting into linked smaller pieces.",
+    });
+  }
+
+  if (codeBlocksWithoutHighlights > 0) {
+    findings.push({
+      severity: "info",
+      code: "code-without-highlights",
+      message:
+        "Code blocks render without inline highlights; readers benefit from .kw/.str/.cm/.fn spans.",
+      count: codeBlocksWithoutHighlights,
+    });
+  }
+
+  if (inlineStyleCount > 8) {
+    findings.push({
+      severity: "info",
+      code: "inline-style-heavy",
+      message: "Heavy reliance on inline styles; named classes are usually clearer.",
+      count: inlineStyleCount,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Sort, score, return
+  // ---------------------------------------------------------------------------
+
+  const sorted = sortFindings(findings);
+  const score = computeScore(sorted);
+
+  return { score, findings: sorted, textLength };
+}