portable-agent-layer 0.31.0 → 0.33.0

package/assets/skills/presentation/tools/doctor.ts

@@ -4,34 +4,33 @@
 // Usage:
 //   bun doctor.ts <deck-dir> [--strict]
 //
-// Reads slides/*.md (or legacy content.md), runs layout-aware lint rules,
-// prints per-slide findings + a summary, and exits 0 (clean) or 1 (errors).
-// --strict promotes warnings to errors.
+// Reads slides/*.md (or legacy content.md), runs slide-scope and deck-scope
+// rules from `lib/lint-rules.ts`, prints per-slide findings + a summary,
+// and exits 0 (clean) or 1 (errors). --strict promotes warnings to errors.
 //
-// Rules are heuristic — thresholds documented in SKILL.md. Doctor is a
+// Rules are heuristic — thresholds documented in SKILL.md. The doctor is a
 // safety-net, not a style guide; intentionally permissive.
 
-import { constants as fsConst } from "node:fs";
-import { access, readdir } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { readText } from "./lib/inline";
-
-export type Severity = "E" | "W";
-export type Finding = { rule: string; severity: Severity; msg: string };
-export type SlideReport = { name: string; layout: string; findings: Finding[] };
-
-async function exists(p: string): Promise<boolean> {
-  try {
-    await access(p, fsConst.F_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
+import {
+  countAtxHeading,
+  extractLayout,
+  fileExists,
+  stripNotes,
+} from "./lib/lint-helpers";
+import { RULES } from "./lib/lint-rules";
+import type { DeckContext, Finding, SlideContext, SlideReport } from "./lib/lint-types";
+
+// Re-export for backward compatibility with external callers (tests, etc.)
+// that imported these directly from doctor.ts.
+export { extractLayout } from "./lib/lint-helpers";
+export type { DeckContext, Finding, SlideContext, SlideReport } from "./lib/lint-types";
 
 async function loadSlides(deckDir: string): Promise<{ name: string; body: string }[]> {
   const slidesDir = join(deckDir, "slides");
-  if (await exists(slidesDir)) {
+  if (await fileExists(slidesDir)) {
     const files = (await readdir(slidesDir)).filter((f) => f.endsWith(".md")).sort();
     if (files.length === 0) throw new Error(`slides/ is empty at ${slidesDir}`);
     return Promise.all(
@@ -39,313 +38,111 @@ async function loadSlides(deckDir: string): Promise<{ name: string; body: string
     );
   }
   const legacy = join(deckDir, "content.md");
-  if (await exists(legacy)) {
+  if (await fileExists(legacy)) {
     const raw = await readText(legacy);
     return raw.split(/^---$/m).map((body, i) => ({ name: `slide-${i + 1}`, body }));
   }
   throw new Error(`no slides/ directory or content.md found in ${deckDir}`);
 }
 
-export function extractLayout(body: string): string {
-  const m = /<!--\s*\.slide:\s*data-layout="([^"]+)"\s*-->/i.exec(body);
-  return m ? m[1] : "content";
-}
-
-function stripNotes(body: string): string {
-  // Remove speaker notes — every line from `Note:` onward at line start.
-  const lines = body.split("\n");
-  const cut = lines.findIndex((l) => /^Note:/i.test(l.trim()));
-  return cut === -1 ? body : lines.slice(0, cut).join("\n");
-}
-
-function countAtxHeading(body: string, level: 1 | 2): string[] {
-  const re = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`, "gm");
-  return Array.from(body.matchAll(re), (m) => m[1]);
+function buildSlideContext(
+  slide: { name: string; body: string },
+  index: number,
+  deckDir: string
+): SlideContext {
+  const body = slide.body;
+  const bodyNoNotes = stripNotes(body);
+  return {
+    name: slide.name,
+    body,
+    bodyNoNotes,
+    layout: extractLayout(body),
+    deckDir,
+    heads1: countAtxHeading(bodyNoNotes, 1),
+    heads2: countAtxHeading(bodyNoNotes, 2),
+    index,
+  };
 }
 
-function countTopLevelListItems(body: string): number {
-  // Count lines starting with `- `, `* `, or `N. ` at column 0 (no leading indent).
-  let n = 0;
-  for (const line of body.split("\n")) {
-    if (/^(?:[-*]\s+|\d+\.\s+)/.test(line)) n++;
+export async function lintDeck(deckDir: string): Promise<{
+  slides: SlideContext[];
+  reports: SlideReport[];
+  deckFindings: Finding[];
+}> {
+  const raw = await loadSlides(deckDir);
+  const slides = raw.map((s, i) => buildSlideContext(s, i, deckDir));
+  const deckCtx: DeckContext = { deckDir, slides };
+
+  // Slide-scope rules
+  const reports: SlideReport[] = [];
+  for (const ctx of slides) {
+    const findings: Finding[] = [];
+    for (const rule of RULES) {
+      if (rule.scope !== "slide") continue;
+      if (rule.appliesTo && !rule.appliesTo(ctx)) continue;
+      findings.push(...(await rule.check(ctx)));
+    }
+    reports.push({ name: ctx.name, layout: ctx.layout, findings });
   }
-  return n;
-}
 
-function findImageRefs(body: string): string[] {
-  // Skip lines inside fenced code blocks — they're examples, not references.
-  const out: string[] = [];
-  const lines = body.split("\n");
-  let inFence = false;
-  for (const line of lines) {
-    if (/^```/.test(line)) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence) continue;
-    for (const m of line.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
-      const ref = m[1].trim();
-      if (!/^(https?:|data:)/i.test(ref)) out.push(ref);
-    }
+  // Deck-scope rules
+  const deckFindings: Finding[] = [];
+  for (const rule of RULES) {
+    if (rule.scope !== "deck") continue;
+    deckFindings.push(...(await rule.check(deckCtx)));
   }
-  return out;
-}
 
-function codeBlockLineCounts(body: string): number[] {
-  const counts: number[] = [];
-  const lines = body.split("\n");
-  let inBlock = false;
-  let n = 0;
-  for (const l of lines) {
-    if (/^```/.test(l)) {
-      if (inBlock) {
-        counts.push(n);
-        n = 0;
-        inBlock = false;
-      } else {
-        inBlock = true;
-      }
-    } else if (inBlock) {
-      n++;
-    }
-  }
-  return counts;
+  return { slides, reports, deckFindings };
 }
 
+// Public: kept for any external caller that imported `lintSlide` directly.
 export async function lintSlide(
   slide: { name: string; body: string },
   deckDir: string
 ): Promise<SlideReport> {
-  const layout = extractLayout(slide.body);
-  const body = stripNotes(slide.body);
+  const ctx = buildSlideContext(slide, 0, deckDir);
   const findings: Finding[] = [];
-
-  const has = (s: string) => body.includes(s);
-  const heads1 = countAtxHeading(body, 1);
-  const heads2 = countAtxHeading(body, 2);
-
-  // ── Global rules ──────────────────────────────────────────────────────
-  if (!/<!--\s*\.slide:\s*data-layout=/i.test(slide.body)) {
-    findings.push({
-      rule: "no-layout",
-      severity: "W",
-      msg: "no <!-- .slide: data-layout=\"...\" --> directive — defaults to 'content'",
-    });
-  }
-  for (const h of heads1) {
-    if (h.length > 60) {
-      findings.push({
-        rule: "long-title",
-        severity: "W",
-        msg: `h1 is ${h.length} chars (soft limit 60): "${h.slice(0, 50)}…"`,
-      });
-    }
-  }
-  for (const h of heads2) {
-    if (h.length > 100) {
-      findings.push({
-        rule: "long-subtitle",
-        severity: "W",
-        msg: `h2 is ${h.length} chars (soft limit 100)`,
-      });
-    }
-  }
-  for (const ref of findImageRefs(body)) {
-    const abs = resolve(deckDir, ref);
-    if (!(await exists(abs))) {
-      findings.push({
-        rule: "missing-asset",
-        severity: "E",
-        msg: `image referenced but not found: ${ref}`,
-      });
-    }
+  for (const rule of RULES) {
+    if (rule.scope !== "slide") continue;
+    if (rule.appliesTo && !rule.appliesTo(ctx)) continue;
+    findings.push(...(await rule.check(ctx)));
   }
+  return { name: ctx.name, layout: ctx.layout, findings };
+}
 
-  // ── Layout-specific rules ─────────────────────────────────────────────
-  switch (layout) {
-    case "title":
-    case "closing": {
-      if (heads1.length === 0) {
-        findings.push({
-          rule: "title-no-h1",
-          severity: "E",
-          msg: "missing h1 (deck title)",
-        });
-      }
-      break;
-    }
-    case "section": {
-      if (heads1.length === 0) {
-        findings.push({
-          rule: "section-no-h1",
-          severity: "W",
-          msg: "section divider with no h1",
-        });
-      }
-      break;
-    }
-    case "agenda": {
-      const items = countTopLevelListItems(body);
-      if (items > 10) {
-        findings.push({
-          rule: "agenda-overflow",
-          severity: "W",
-          msg: `${items} items — agenda fits 10 cleanly; split into two slides`,
-        });
-      }
-      if (items === 0) {
-        findings.push({
-          rule: "agenda-empty",
-          severity: "E",
-          msg: "agenda layout has no list items",
-        });
-      }
-      break;
-    }
-    case "content": {
-      const items = countTopLevelListItems(body);
-      if (items > 7) {
-        findings.push({
-          rule: "content-bullets",
-          severity: "W",
-          msg: `${items} bullets — content slides fit ~7 cleanly`,
-        });
-      }
-      break;
-    }
-    case "comparison": {
-      if (!has(`class="compare"`)) {
-        findings.push({
-          rule: "comparison-wrapper",
-          severity: "E",
-          msg: 'missing <div class="compare"> wrapper',
-        });
-      }
-      const options = (body.match(/class="option"/g) || []).length;
-      if (options === 0) {
-        findings.push({
-          rule: "comparison-empty",
-          severity: "E",
-          msg: "no .option blocks found",
-        });
-      } else if (options > 3) {
-        findings.push({
-          rule: "comparison-count",
-          severity: "W",
-          msg: `${options} options — comparison fits 2–3 cleanly`,
-        });
-      }
-      break;
-    }
-    case "metric-grid": {
-      if (!has(`class="metrics"`)) {
-        findings.push({
-          rule: "metric-grid-wrapper",
-          severity: "E",
-          msg: 'missing <div class="metrics"> wrapper',
-        });
-      }
-      const metrics = (body.match(/class="metric"/g) || []).length;
-      if (metrics === 0) {
-        findings.push({
-          rule: "metric-grid-empty",
-          severity: "E",
-          msg: "no .metric blocks found",
-        });
-      } else if (metrics !== 3) {
-        findings.push({
-          rule: "metric-grid-count",
-          severity: "W",
-          msg: `${metrics} metrics — grid is 3-column, expects exactly 3`,
-        });
-      }
-      break;
-    }
-    case "two-column": {
-      if (!has(`class="col-left"`) || !has(`class="col-right"`)) {
-        findings.push({
-          rule: "two-column-wrappers",
-          severity: "E",
-          msg: 'missing <div class="col-left"> or <div class="col-right">',
-        });
-      }
-      break;
-    }
-    case "image-text": {
-      if (!has(`class="image"`) || !has(`class="text"`)) {
-        findings.push({
-          rule: "image-text-wrappers",
-          severity: "E",
-          msg: 'missing <div class="image"> or <div class="text">',
-        });
-      }
-      break;
-    }
-    case "big-stat": {
-      if (heads1.length === 0) {
-        findings.push({
-          rule: "big-stat-no-h1",
-          severity: "E",
-          msg: "missing h1 (the stat itself)",
-        });
-      } else if (heads1.length > 1) {
-        findings.push({
-          rule: "big-stat-multi-h1",
-          severity: "W",
-          msg: "multiple h1s — big-stat shows one number",
-        });
-      }
-      break;
-    }
-    case "quote":
-    case "pull-quote": {
-      if (!/^>\s+/m.test(body)) {
-        findings.push({
-          rule: "quote-no-blockquote",
-          severity: "E",
-          msg: "no blockquote (`> ...`) found",
-        });
-      }
-      break;
-    }
-    case "code": {
-      const blocks = codeBlockLineCounts(body);
-      if (blocks.length === 0) {
-        findings.push({
-          rule: "code-no-block",
-          severity: "E",
-          msg: "no fenced code block found",
-        });
-      }
-      for (const n of blocks) {
-        if (n > 25) {
-          findings.push({
-            rule: "code-too-long",
-            severity: "W",
-            msg: `code block has ${n} lines — fits ~25 before overflow`,
-          });
-        }
-      }
-      break;
+function pad(s: string, n: number): string {
+  return s + " ".repeat(Math.max(0, n - s.length));
+}
+
+function printSlideFindings(reports: SlideReport[], deckBase: string, count: number) {
+  let printed = false;
+  for (const r of reports) {
+    if (r.findings.length === 0) continue;
+    if (!printed) {
+      console.log(`Doctor — ${deckBase} (${count} slides)`);
+      console.log("");
+      printed = true;
     }
-    case "table": {
-      const rows = body.split("\n").filter((l) => /^\s*\|.*\|\s*$/.test(l)).length;
-      if (rows > 10) {
-        findings.push({
-          rule: "table-rows",
-          severity: "W",
-          msg: `${rows} table rows — gets cramped past ~8`,
-        });
-      }
-      break;
+    console.log(`  ${pad(r.name, 32)} [${r.layout}]`);
+    for (const f of r.findings) {
+      const sev = f.severity === "E" ? "ERROR" : "WARN ";
+      const symbol = f.severity === "E" ? "✗" : "⚠";
+      console.log(`    ${symbol} ${sev}  ${f.rule.padEnd(28)} ${f.msg}`);
     }
   }
-
-  return { name: slide.name, layout, findings };
+  return printed;
 }
 
-function pad(s: string, n: number): string {
-  return s + " ".repeat(Math.max(0, n - s.length));
+function printDeckFindings(deckFindings: Finding[], anyPrintedAlready: boolean): boolean {
+  if (deckFindings.length === 0) return anyPrintedAlready;
+  if (anyPrintedAlready) console.log("");
+  console.log("  (deck-level)");
+  for (const f of deckFindings) {
+    const sev = f.severity === "E" ? "ERROR" : "WARN ";
+    const symbol = f.severity === "E" ? "✗" : "⚠";
+    console.log(`    ${symbol} ${sev}  ${f.rule.padEnd(28)} ${f.msg}`);
+  }
+  return true;
 }
 
 async function main() {
@@ -357,29 +154,20 @@ async function main() {
   const deckDir = resolve(argv[0]);
   const strict = argv.includes("--strict");
 
-  const slides = await loadSlides(deckDir);
-  const reports = await Promise.all(slides.map((s) => lintSlide(s, deckDir)));
+  const { slides, reports, deckFindings } = await lintDeck(deckDir);
 
   let errors = 0;
   let warnings = 0;
-  let printed = false;
-
   for (const r of reports) {
-    if (r.findings.length === 0) continue;
-    if (!printed) {
-      console.log(`Doctor — ${basename(deckDir)} (${slides.length} slides)`);
-      console.log("");
-      printed = true;
-    }
-    console.log(`  ${pad(r.name, 32)} [${r.layout}]`);
     for (const f of r.findings) {
-      const sev = f.severity === "E" ? "ERROR" : "WARN ";
-      const symbol = f.severity === "E" ? "✗" : "⚠";
-      console.log(`    ${symbol} ${sev}  ${f.rule.padEnd(22)} ${f.msg}`);
       if (f.severity === "E") errors++;
       else warnings++;
     }
   }
+  for (const f of deckFindings) {
+    if (f.severity === "E") errors++;
+    else warnings++;
+  }
 
   const total = errors + warnings;
   if (total === 0) {
@@ -387,6 +175,9 @@ async function main() {
     process.exit(0);
   }
 
+  const anyPrinted = printSlideFindings(reports, basename(deckDir), slides.length);
+  printDeckFindings(deckFindings, anyPrinted);
+
   console.log("");
   console.log(
     `Summary: ${errors} error(s), ${warnings} warning(s) across ${slides.length} slides`
@@ -396,8 +187,6 @@ async function main() {
   process.exit(exitCode);
 }
 
-// Only run as a CLI when invoked directly — allows test files to import lintSlide
-// without triggering the argv parsing / process.exit path.
 if (import.meta.main) {
   main().catch((e) => {
     console.error(e?.message ?? e);

package/assets/skills/presentation/tools/lib/lint-helpers.ts

@@ -0,0 +1,150 @@
+// presentation skill — pure helpers for the lint pipeline.
+//
+// Each function operates on raw markdown strings or pre-processed pieces.
+// No fs, no console, no side effects — easy to test in isolation.
+
+import { constants as fsConst } from "node:fs";
+import { access } from "node:fs/promises";
+
+export async function fileExists(p: string): Promise<boolean> {
+  try {
+    await access(p, fsConst.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function extractLayout(body: string): string {
+  const m = /<!--\s*\.slide:\s*data-layout="([^"]+)"\s*-->/i.exec(body);
+  return m ? m[1] : "content";
+}
+
+export function hasLayoutDirective(body: string): boolean {
+  return /<!--\s*\.slide:\s*data-layout=/i.test(body);
+}
+
+export function stripNotes(body: string): string {
+  // Remove speaker notes — every line from `Note:` onward at line start.
+  const lines = body.split("\n");
+  const cut = lines.findIndex((l) => /^Note:/i.test(l.trim()));
+  return cut === -1 ? body : lines.slice(0, cut).join("\n");
+}
+
+export function extractNotes(body: string): string {
+  // Return only the speaker notes portion (everything from `Note:` onward).
+  const lines = body.split("\n");
+  const cut = lines.findIndex((l) => /^Note:/i.test(l.trim()));
+  return cut === -1 ? "" : lines.slice(cut).join("\n");
+}
+
+export function countAtxHeading(body: string, level: 1 | 2): string[] {
+  const re = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`, "gm");
+  return Array.from(body.matchAll(re), (m) => m[1]);
+}
+
+export function countTopLevelListItems(body: string): number {
+  // Count lines starting with `- `, `* `, or `N. ` at column 0 (no leading indent).
+  let n = 0;
+  for (const line of body.split("\n")) {
+    if (/^(?:[-*]\s+|\d+\.\s+)/.test(line)) n++;
+  }
+  return n;
+}
+
+export function countAllListItems(body: string): number {
+  // Count all list items at any indentation (top-level + sub-bullets).
+  // The visual budget is "lines you read on the slide" — sub-bullets count.
+  let n = 0;
+  for (const line of body.split("\n")) {
+    if (/^\s*(?:[-*]\s+|\d+\.\s+)/.test(line)) n++;
+  }
+  return n;
+}
+
+export type ListItem = {
+  indent: number; // leading whitespace columns
+  content: string; // text after the bullet marker
+  raw: string; // the full line
+};
+
+export function listItems(body: string): ListItem[] {
+  const out: ListItem[] = [];
+  for (const line of body.split("\n")) {
+    const m = line.match(/^(\s*)(?:[-*]\s+|\d+\.\s+)(.*)$/);
+    if (!m) continue;
+    out.push({ indent: m[1].length, content: m[2], raw: line });
+  }
+  return out;
+}
+
+export function findImageRefs(body: string): string[] {
+  // Skip lines inside fenced code blocks — they're examples, not references.
+  const out: string[] = [];
+  const lines = body.split("\n");
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    for (const m of line.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
+      const ref = m[1].trim();
+      if (!/^(https?:|data:)/i.test(ref)) out.push(ref);
+    }
+  }
+  return out;
+}
+
+export function codeBlockLineCounts(body: string): number[] {
+  const counts: number[] = [];
+  const lines = body.split("\n");
+  let inBlock = false;
+  let n = 0;
+  for (const l of lines) {
+    if (/^```/.test(l)) {
+      if (inBlock) {
+        counts.push(n);
+        n = 0;
+        inBlock = false;
+      } else {
+        inBlock = true;
+      }
+    } else if (inBlock) {
+      n++;
+    }
+  }
+  return counts;
+}
+
+export function tableRowCount(body: string): number {
+  return body.split("\n").filter((l) => /^\s*\|.*\|\s*$/.test(l)).length;
+}
+
+export function stripCodeAndLinks(s: string): string {
+  // Remove inline code spans and markdown link bodies — useful when checking
+  // bullet content for prose-style patterns without false positives on code
+  // or URLs.
+  return s.replace(/`[^`]*`/g, "").replace(/\[[^\]]*\]\([^)]*\)/g, "");
+}
+
+export function wordCount(s: string): number {
+  // Count each inline code span as 1 word — preserves "label: `value`" patterns
+  // where the substantive content is in the code span. Strip markdown link
+  // bodies so links count as their visible text, not the URL.
+  const withCodeAsWords = s.replace(/`[^`]*`/g, "CODESPAN");
+  const withoutLinks = withCodeAsWords.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+  const cleaned = withoutLinks.trim();
+  if (!cleaned) return 0;
+  return cleaned.split(/\s+/).length;
+}
+
+export function hasNestedChildren(items: ListItem[], parentIndex: number): boolean {
+  // Returns true if the item at parentIndex has any directly-following items
+  // at greater indent (i.e., it acts as a parent to a sub-bullet group).
+  const parent = items[parentIndex];
+  if (!parent) return false;
+  const next = items[parentIndex + 1];
+  return !!next && next.indent > parent.indent;
+}