chalk-talk 0.16.0 → 0.17.0

package/scripts/build.mjs

@@ -22,7 +22,7 @@ import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { runPages } from './browser.mjs'
 import { fill, inline } from './page.mjs'
-import { ChalkTextError, chaptersFor, parseChalk, PROP_ALIASES, PROP_NAMES, validateScene } from './contract.mjs'
+import { ChalkTextError, chaptersFor, parseChalk, PROP_ALIASES, PROP_NAMES, purposeWarnings, validateScene } from './contract.mjs'
 import { syntaxForLine, syntaxForStep } from './syntax.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
@@ -149,10 +149,17 @@ if (scenes.some((s) => Object.keys(s.lotties ?? {}).length)) {
 }
 writeFileSync(out, page)
 
+// back-of-napkin: what a drawing of its purpose usually misses (a pitch with no ask…) — drawn anyway, to fix like a
+// review finding (exit 3).
+let warned = false
 scenes.forEach((scene, k) => {
   const values = Object.keys(scene.params ?? {}).length + Object.keys(scene.switches ?? {}).length
   const who = course ? `  (${k + 1}) ${scene.title}: ` : '  '
   console.log(`✓ contract${who}${scene.steps.length} steps, ${chaptersFor(scene).length} chapters, ${values} values`)
+  for (const w of purposeWarnings(scene)) {
+    console.log(`! ${scene.kind.padEnd(9)}${course ? ` (${k + 1})` : ''} ${w.text}`)
+    warned = true
+  }
 })
 
 // Onda C: a figure made with `define` is seen by nobody when the build passes at once (the review measures, it does
@@ -172,7 +179,7 @@ const ran = jobs.length ? await runPages(jobs, { timeout }) : { results: [] }
 const name = (exe) => basename(exe).replace(/\.exe$/i, '')
 const result = (what, k) => ran.results?.[jobs.findIndex((j) => j.what === what && j.k === k)]
 
-let code = 0
+let code = warned ? 3 : 0
 if (noReview) console.log('• review    skipped (--no-review); the page checks itself when opened')
 else if (!ran.results) console.log('• review    no Chrome, Chromium or Edge here: the page checks itself when opened')
 else {

package/scripts/contract.mjs

@@ -1,4 +1,4 @@
-// GENERATED by tools/assets.mjs from the drawing engine v0.256.1. Do not edit.
+// GENERATED by tools/assets.mjs from the drawing engine v0.257.0. Do not edit.
 var WORDS = ["and", "or", "not"];
 
 var PROP_NAMES = [
@@ -417,6 +417,7 @@ var hasFace = (name) => {
 };
 
 var MOTIONS = ["spin", "drive", "steam", "talk", "pulse", "float"];
+var KINDS = ["lesson", "pitch", "arch", "decision", "data", "timeline", "story"];
 var MAX_DEFS = 8;
 var MAX_LOTTIES = 6;
 var MAX_LOTTIE_CHARS = 2e5;
@@ -878,6 +879,9 @@ function validateScene(data) {
     if (!ok) throw new Error('locale: expected a language tag such as "en-US" or "pt-BR".');
   }
   choice(s.background, ["dots", "grid", "plain"], "background");
+  choice(s.kind, KINDS, "kind");
+  optionalText(s.source, "source");
+  if (s.quiz !== void 0 && s.kind !== void 0 && s.kind !== "lesson") throw new Error(`quiz: only a lesson has a quiz (this drawing is a ${s.kind}).`);
   choice(s.theme, ["paper", "chalkboard"], "theme");
   if (s.quiz !== void 0) {
     object(s.quiz, "quiz");
@@ -1424,6 +1428,12 @@ function parseChalk(text2, props) {
       case "locale":
         scene.locale = one("a language tag");
         continue;
+      case "kind":
+        scene.kind = one("what the drawing is for");
+        continue;
+      case "source":
+        scene.source = one("where the numbers come from");
+        continue;
       case "background":
         scene.background = one("dots, grid or plain");
         continue;
@@ -1589,7 +1599,8 @@ function printChalk(scene, props) {
   const out = [];
   if (scene.id !== void 0) out.push(`id ${scene.id}`);
   if (scene.title !== void 0) out.push(`title ${scene.title}`);
-  for (const k of ["category", "theme", "locale", "background"]) if (scene[k] !== void 0) out.push(`${k} ${scene[k]}`);
+  for (const k of ["kind", "category", "theme", "locale", "background"]) if (scene[k] !== void 0) out.push(`${k} ${scene[k]}`);
+  if (scene.source !== void 0) out.push(`source ${q(scene.source)}`);
   if (scene.width !== 900 || scene.height !== 560) out.push(`size ${scene.width}x${scene.height}`);
   for (const [k, p] of Object.entries(scene.params ?? {})) {
     out.push(`param ${k} ${q(p.label)} ${p.min}..${p.max}${p.step !== 1 ? ` step=${p.step}` : ""} = ${p.value}`);
@@ -1617,13 +1628,48 @@ function printChalk(scene, props) {
   }
   return out.join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
 }
+
+function all(steps) {
+  return steps.flatMap((s) => {
+    const inner = "steps" in s && Array.isArray(s.steps) ? s.steps : "step" in s && s.step ? [s.step] : [];
+    return [s, ...all(inner)];
+  });
+}
+function purposeWarnings(scene) {
+  const steps = all(scene.steps);
+  const last = chaptersFor(scene).at(-1);
+  const endsLit = last ? all(scene.steps.slice(last.start, last.end + 1)).some((s) => s.type === "highlight") : false;
+  const switches = Object.keys(scene.switches ?? {}).length > 0;
+  const params = Object.keys(scene.params ?? {}).length > 0;
+  const out = [];
+  switch (scene.kind) {
+    case "pitch":
+      if (!endsLit) out.push({ key: "pitch-ask", text: "the pitch does not end with an ask (no highlight in its last chapter)" });
+      break;
+    case "arch":
+      if (!switches && !steps.some((s) => s.type === "when")) out.push({ key: "arch-failure", text: "no failure drawn: what happens when something goes down? (no switch, no when)" });
+      break;
+    case "decision":
+      if (!endsLit && !params && !switches) out.push({ key: "decision-winner", text: "the decision does not say which option wins, nor why (no highlight in its last chapter, no value)" });
+      break;
+    case "data":
+      if (!scene.source?.trim()) out.push({ key: "data-source", text: "where do these numbers come from? (no source)" });
+      break;
+    case "timeline":
+      if (!steps.some((s) => s.type === "timeline")) out.push({ key: "timeline-line", text: "the timeline has no line (no timeline step)" });
+      break;
+  }
+  return out;
+}
 export {
   ChalkTextError,
+  KINDS,
   PROP_ALIASES,
   PROP_NAMES,
   chaptersFor,
   defaultValues,
   parseChalk,
   printChalk,
+  purposeWarnings,
   validateScene
 };