@supersuit/hyperspec 0.8.0 → 0.9.0

package/src/judges/panel.mjs

@@ -0,0 +1,135 @@
+// The panel (hyperspec 0.9): the draft read by several readers at once, each through their own
+// lens, the way a draft is pressure-tested by hand before it ships. Every other judgment station
+// asks one question with a right answer; the panel asks each reader what works, what to improve,
+// what is missing and what to remove, and every answer is a finding somebody has to answer.
+//
+// One packet per reader (panel-<id>.packet.json): the readers writing.panel declares, or with none
+// declared the default three (a skeptic, a newcomer and an expert), and always the spec's own
+// audience reader, added last as "buyer", because a panel that never includes the person the piece
+// is for tests everything except whether it works. Every item a reader lists carries evidence
+// copied from the draft (src/evidence.mjs's rule; a missing item anchors to the passage nearest
+// where it belongs), so a review can never be of a stale or truncated copy.
+//
+// The panel never fails a draft: its findings are warnings, and each improve, missing and remove
+// item goes to the triage file (src/triage.mjs), where the operator answers it and `check` holds
+// every answer to the draft. What works is counted, never triaged: there is nothing to answer.
+
+import { str } from "../placeholder.mjs";
+
+export const name = "panel";
+
+export const PANEL_INSTRUCTIONS = [
+  "Read inputs.draft as inputs.reader: the person inputs.reader.who describes, knowing only what inputs.reader.knows lists and what anyone would, reading for inputs.reader.lens.",
+  "List what works for this reader under good, what should change under improve, what this reader needs that the draft does not give under missing, and what should go under remove.",
+  "Every item is { evidence, note }. evidence is a passage copied verbatim from inputs.draft, at least three whole words; for a missing item, quote the passage nearest to where the missing thing belongs. note says what and why, in a sentence, in this reader's terms.",
+  "A list may be empty. Report what this reader would say, not what another reader would.",
+  "Answer only in the verdict shape given in verdict_schema.",
+].join(" ");
+
+// The default panel, used when writing.panel is not declared. The buyer is added to it, as to any.
+export const DEFAULT_PANEL = Object.freeze([
+  Object.freeze({ id: "skeptic", who: "a skeptic who doubts the piece's central claim and wants it earned", knows: Object.freeze([]), lens: "what is asserted without support, overstated, or does not follow" }),
+  Object.freeze({ id: "novice", who: "a newcomer to the subject, meeting its ideas for the first time", knows: Object.freeze([]), lens: "every term, step or assumption the piece does not explain" }),
+  Object.freeze({ id: "expert", who: "an expert in the piece's subject", knows: Object.freeze([]), lens: "what is wrong, out of date, oversimplified or missing for someone who knows the field" }),
+]);
+
+export const KINDS = Object.freeze(["good", "improve", "missing", "remove"]);
+
+const isObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const texts = (v) => (Array.isArray(v) ? v.map(str).filter(Boolean) : []);
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+
+// null when the panel applies: its buyer is the audience's reader, so it needs a written audience
+// block whose check names a rubric, the reader station's own condition.
+export function skipReason(spec) {
+  const audience = spec.data?.writing?.audience;
+  if (!isObject(audience)) return "writing.audience is not written (deferred); the panel's buyer is the audience's reader";
+  if (!str(audience.check?.rubric)) return "writing.audience.check has no rubric";
+  return null;
+}
+
+// Every reader on this spec's panel, in order: the declared readers (or the default three), then
+// the buyer. Each is { id, who, knows, lens }.
+export function variants(spec) {
+  const declared = spec.data?.writing?.panel;
+  const readers = Array.isArray(declared) && declared.length
+    ? declared.filter(isObject).map((r) => ({ id: str(r.id), who: str(r.who), knows: texts(r.knows), lens: str(r.lens) })).filter((r) => r.id && r.id !== "buyer")
+    : DEFAULT_PANEL.map((r) => ({ id: r.id, who: r.who, knows: [...r.knows], lens: r.lens }));
+  const a = spec.data.writing.audience;
+  const buyer = { id: "buyer", who: str(a.who), knows: texts(a.knows), lens: `what they want from this piece: ${str(a.wants)}` };
+  return [...readers, buyer];
+}
+
+// Which reader a packet is for, as it says; record rebuilds the packet for that reader and
+// compares every byte, so a changed name is caught with the rest.
+export const variantOf = (packet) => packet?.inputs?.reader?.id;
+
+const itemSchema = {
+  type: "object",
+  required: ["evidence", "note"],
+  properties: {
+    evidence: { type: "string", description: "a passage copied verbatim from the draft, at least three words; for a missing item, the passage nearest where it belongs" },
+    note: { type: "string", description: "what and why, in a sentence" },
+  },
+};
+
+// The packet's rubric (audience.check.rubric, verbatim: the buyer's test is the piece's), inputs
+// (the reader and the draft) and verdict schema. No answer key.
+export function packet(spec, draft, reader) {
+  return {
+    rubric: spec.data.writing.audience.check.rubric,
+    inputs: {
+      reader: { id: reader.id, who: reader.who, knows: reader.knows, lens: reader.lens },
+      draft: draft.text,
+    },
+    verdict_schema: {
+      type: "object",
+      required: [...KINDS],
+      properties: {
+        good: { type: "array", description: "what works for this reader; empty when nothing does", items: itemSchema },
+        improve: { type: "array", description: "what should change", items: itemSchema },
+        missing: { type: "array", description: "what this reader needs that the draft does not give", items: itemSchema },
+        remove: { type: "array", description: "what should go", items: itemSchema },
+      },
+    },
+    key: null,
+  };
+}
+
+// Every problem with the verdict, as findings; every evidence span must be in the draft.
+export function validate(verdict, pkt, t) {
+  if (!isObject(verdict)) return [t.shape("the verdict is not a JSON object", "Write one object: { good, improve, missing, remove }.")];
+  const out = [];
+  for (const kind of KINDS) {
+    if (!Array.isArray(verdict[kind])) { out.push(t.shape(`${kind} is missing or not a list`, `Give ${kind}: one { evidence, note } per item, or [] when there is none.`)); continue; }
+    verdict[kind].forEach((item, i) => {
+      const at = `${kind}[${i}]`;
+      if (!isObject(item)) { out.push(t.shape(`${at} is not an object`, "Write it as { evidence, note }.")); return; }
+      if (!nonEmpty(item.note)) out.push(t.shape(`${at}.note is missing or empty`, "Say what and why, in a sentence."));
+      out.push(...t.evidence(item.evidence, `${at}.evidence`));
+    });
+  }
+  return out;
+}
+
+const WORD = { improve: "would improve", missing: "misses", remove: "would remove" };
+
+// Always passes: every improve, missing and remove item is a warning at its evidence's line, and a
+// finding for the triage file. The summary counts all four lists.
+export function derive(verdict, pkt, t) {
+  const reader = pkt.inputs.reader.id;
+  const findings = [];
+  const triage = [];
+  for (const kind of ["improve", "missing", "remove"]) {
+    for (const item of verdict[kind]) {
+      const note = item.note.trim();
+      if (kind === "improve") findings.push({ ...t.finding("judge-panel-improve", `${reader} ${WORD[kind]} this: ${note}`, "Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.", t.lineOf(item.evidence)), severity: "warn" });
+      if (kind === "missing") findings.push({ ...t.finding("judge-panel-missing", `${reader} ${WORD[kind]} something here: ${note}`, "Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.", t.lineOf(item.evidence)), severity: "warn" });
+      if (kind === "remove") findings.push({ ...t.finding("judge-panel-remove", `${reader} ${WORD[kind]} this: ${note}`, "Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.", t.lineOf(item.evidence)), severity: "warn" });
+      triage.push({ kind, text: note, evidence: item.evidence });
+    }
+  }
+  const n = (k) => verdict[k].length;
+  const summary = `${reader}: ${n("good")} good, ${n("improve")} to improve, ${n("missing")} missing, ${n("remove")} to remove`;
+  return { status: "pass", findings, summary, triage };
+}

package/src/stations/index.mjs

@@ -3,7 +3,7 @@
 // src/check.mjs calls; adding a station is adding one file plus one line here, which is the whole
 // point of the registry existing rather than check.mjs importing each station by name itself.
 //
-// The order: form, terms, claims, quotes, private, dna, links, sequence. quotes and private share ctx (util.mjs's
+// The order: form, terms, claims, quotes, private, dna, links, sequence, triage. quotes and private share ctx (util.mjs's
 // markedSegments caches the spec's marked materials there), so a check run reads them once.
 
 import * as form from "./form.mjs";
@@ -14,6 +14,7 @@ import * as privateStation from "./private.mjs";
 import * as dna from "./dna.mjs";
 import * as links from "./links.mjs";
 import * as sequence from "./sequence.mjs";
+import * as triage from "./triage.mjs";
 
 export const STATIONS = Object.freeze([
   { name: form.name, run: form.run },
@@ -24,6 +25,7 @@ export const STATIONS = Object.freeze([
   { name: dna.name, run: dna.run },
   { name: links.name, run: links.run },
   { name: sequence.name, run: sequence.run },
+  { name: triage.name, run: triage.run },
 ]);
 
 export const STATION_NAMES = Object.freeze(STATIONS.map((s) => s.name));

package/src/stations/quotes.mjs

@@ -33,6 +33,14 @@
 // story segment is enough. Sentences come from splitSegments(text, { by: "sentence" }), and every
 // sentence the span overlaps is read, so a curly quote the splitter cuts in two still keeps its
 // attribution.
+//
+// Example phrasings (hyperspec 0.9). A primer shows the reader what to type or say: "write the
+// update for Dana" is an example, not a quotation, and no material holds it. writing.quotes.examples
+// says which quoted spans are examples. `true` makes every span whose sentence names no known
+// speaker an example: it passes unmatched, and a quotation that names its speaker is still held to
+// the materials. A list names the example phrasings themselves, compared the way a span is matched,
+// so every other span is still checked. The list is the stricter choice: under `true`, an invented
+// quotation that names no one passes too.
 
 import { splitSegments } from "../segments.mjs";
 import { STOPWORDS, wordsOf } from "../dna.mjs";
@@ -75,6 +83,18 @@ export function quotedSpans(text) {
   return spans;
 }
 
+// The spec's example setting: { all: true } for `examples: true`, { phrases } (a Set of match keys)
+// for a list, or null when the spec declares none, or `false`.
+export function examplesOf(spec) {
+  const raw = spec?.data?.writing?.quotes?.examples;
+  if (str(raw) === "true") return { all: true };
+  if (Array.isArray(raw)) {
+    const phrases = new Set(raw.map(str).filter(Boolean).map(matchKey).filter(Boolean));
+    return phrases.size ? { phrases } : null;
+  }
+  return null;
+}
+
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 const STOPWORD_SET = new Set(STOPWORDS);
@@ -133,13 +153,19 @@ export function run(spec, draft, ctx) {
     .filter((sp) => sp.re);
 
   const sentences = splitSegments(text, { by: "sentence" });
+  const examples = examplesOf(spec);
   const findings = [];
   for (const span of spans) {
     const key = matchKey(span.inner);
     if (!key) continue;
+    if (examples?.phrases?.has(key)) continue;
     const shown = truncate(span.inner.replace(/\s+/g, " "), 80);
     const line = lineAt(draft.text, span.start);
     const hits = sources.filter((s) => s.norm.includes(key));
+    const around = attributionContext(text, sentences, span);
+    const named = speakers.filter((sp) => sp.re.test(around)).map((sp) => sp.key);
+    // examples: true reads a span that names no known speaker as an example phrasing.
+    if (examples?.all && !named.length) continue;
     if (!hits.length) {
       findings.push({
         station: name,
@@ -151,8 +177,6 @@ export function run(spec, draft, ctx) {
       });
       continue;
     }
-    const around = attributionContext(text, sentences, span);
-    const named = speakers.filter((sp) => sp.re.test(around)).map((sp) => sp.key);
     if (named.length && !hits.some((h) => h.label === "quote" && named.includes(h.speaker))) {
       const who = named.map((k) => shownSpeaker.get(k) ?? k).join(", ");
       findings.push({

package/src/stations/sequence.mjs

@@ -20,6 +20,11 @@
 //   numbering  unit numbers increase through the work
 //   pointers   (warning) a "<unit> N" pointer to a later unit is reported, so it stays a pointer
 //              and never becomes a dependency
+//   quiz       (hyperspec 0.9, only when sequence.quiz names the quiz heading) every defined term is
+//              tested by some question, a simple plural counting; no question uses a term defined
+//              after the unit it is tagged with; every question is tagged; every answer names one
+//              of its question's options. Promoted from the checker the first book written this
+//              way used, so the rules and the question shape are that checker's.
 //
 // A use is a whole-word, case-insensitive match, where a hyphen is part of a word: "context-aware"
 // does not use "context", and "skills" does not use "skill". The station reads the outline from
@@ -60,6 +65,7 @@ export function sequenceOf(spec) {
     termsSection: str(raw.terms_section) || DEFAULTS.terms_section,
     teaser: str(raw.teaser) || DEFAULTS.teaser,
     outline: str(raw.outline) || null,
+    quiz: str(raw.quiz) || null,
     knows: new Set(knows),
   };
 }
@@ -193,6 +199,80 @@ function firstUse(unit, prose, term) {
   return i < 0 ? 0 : unit.startLine + i;
 }
 
+// Whether `text` (code already masked) uses `term`, by the same whole-word rule as firstUse.
+const usesTerm = (text, term) => new RegExp(`(^|[^a-z0-9-])${escapeRe(term)}([^a-z0-9-]|$)`, "i").test(text);
+
+// Every quiz in the draft, read the way the first book written to this shape wrote it:
+//
+//   ## Check yourself: Part 1
+//
+//   1. *(Lesson 1)* You type "draft an email" into a chat app. What did you just send?
+//      - a) A file on your computer
+//      - b) A prompt, sent to a chat app
+//   ...
+//   **Answers:** 1 b · 2 c
+//
+// A quiz starts at an ATX heading whose text starts with `quiz` (any case) and runs to the next
+// heading of its own level or above, or the end of its file. A question is a numbered line tagged
+// "*(<unit> N)*"; it runs to the next numbered line, the answers line or the quiz's end, and its
+// options are the indented "- a) " lines inside it. The answers line is "**Answers:**" followed by
+// "<number> <letter>" pairs, in any separator. Returns { quizzes, questions, untagged }: quizzes
+// counts the quiz headings; each question is { n, unit, line, text, options, answer }, text with
+// code masked (code is not prose), line 1-based in the draft; untagged lists { n, line } for a
+// numbered line in a quiz that carries no tag.
+export function parseQuizzes(draft, { unit, quiz }) {
+  const lines = maskCode(draft.text).split("\n").map((l) => l.replace(/\r$/, ""));
+  const quizRe = new RegExp(`^${escapeRe(quiz)}`, "i");
+  const fileEnds = new Set(list(draft.sources).map((s) => s.startLine + s.lineCount - 1));
+  const numbered = /^[ \t]{0,3}(\d+)\.[ \t]/;
+  const tagged = new RegExp(`^[ \\t]{0,3}(\\d+)\\.[ \\t]+\\*\\([ \\t]*${escapeRe(unit)}[ \\t]+(\\d+)[ \\t]*\\)\\*`, "i");
+  const answersRe = /^[ \t]*\*\*Answers:?\*\*:?(.*)$/i;
+  const optionRe = /^[ \t]+[-*+][ \t]+([a-z])\)[ \t]/i;
+  const out = { quizzes: 0, questions: [], untagged: [] };
+  for (let i = 0; i < lines.length; i++) {
+    const h = ATX.exec(lines[i]);
+    if (!h || !quizRe.test((h[2] ?? "").replace(/(^|[ \t]+)#+[ \t]*$/, "").trim())) continue;
+    out.quizzes += 1;
+    const level = h[1].length;
+    // [i + 1, end): stops before a heading of its level or above, or after its file's last line
+    // (fileEnds holds 1-based line numbers, so fileEnds.has(end) says line index end - 1 was one).
+    let end = i + 1;
+    while (end < lines.length && !fileEnds.has(end)) {
+      const next = ATX.exec(lines[end]);
+      if (next && next[1].length <= level) break;
+      end++;
+    }
+    const answers = new Map();
+    let cur = null;
+    const qs = [];
+    const flush = () => { if (cur) qs.push(cur); cur = null; };
+    for (let j = i + 1; j < end; j++) {
+      const a = answersRe.exec(lines[j]);
+      if (a) {
+        flush();
+        for (const m of a[1].matchAll(/(\d+)[ \t]+([a-z])(?![a-z])/gi)) answers.set(Number(m[1]), m[2].toLowerCase());
+        continue;
+      }
+      const t = tagged.exec(lines[j]);
+      if (t) {
+        flush();
+        cur = { n: Number(t[1]), unit: Number(t[2]), line: j + 1, text: lines[j], options: [] };
+        continue;
+      }
+      const u = numbered.exec(lines[j]);
+      if (u) { flush(); out.untagged.push({ n: Number(u[1]), line: j + 1 }); continue; }
+      if (!cur) continue;
+      cur.text += `\n${lines[j]}`;
+      const o = optionRe.exec(lines[j]);
+      if (o) cur.options.push(o[1].toLowerCase());
+    }
+    flush();
+    for (const q of qs) out.questions.push({ ...q, answer: answers.get(q.n) ?? null });
+    i = end - 1;
+  }
+  return out;
+}
+
 // One finding, in the shape every station returns; line only when there is one to point at.
 const finding = ({ id, severity, message, fix, line }) => ({ station: name, id, severity, ...(line ? { line } : {}), message, fix });
 
@@ -270,6 +350,39 @@ export function run(spec, draft) {
     });
   }
 
+  // quiz: only when the spec names the quiz heading.
+  if (seq.quiz) findings.push(...quizFindings(draft, seq, definedAt));
+
   const status = findings.some((f) => f.severity === "fail") ? "fail" : "pass";
   return { station: name, status, findings };
 }
+
+// The quiz guards, against the terms the units define (term -> defining unit).
+function quizFindings(draft, seq, definedAt) {
+  const U = seq.unit;
+  const out = [];
+  const { quizzes, questions, untagged } = parseQuizzes(draft, seq);
+  if (!quizzes) {
+    return [finding({ id: "station-sequence-quiz-missing", severity: "fail", message: `no "${seq.quiz}" heading in the draft, and writing.form.sequence.quiz names one`, fix: `Add a "## ${seq.quiz}" section of questions, or delete quiz: from the spec.` })];
+  }
+  for (const q of untagged) {
+    out.push(finding({ id: "station-sequence-quiz-untagged", severity: "fail", message: `question ${q.n} names no ${U.toLowerCase()} it tests`, fix: `Start the question "${q.n}. *(${U} N)* ...", naming the ${U.toLowerCase()} it tests.`, line: q.line }));
+  }
+  for (const q of questions) {
+    if (!q.answer || !q.options.includes(q.answer)) {
+      const has = q.options.length ? q.options.join(", ") : "none";
+      out.push(finding({ id: "station-sequence-quiz-answer", severity: "fail", message: q.answer ? `question ${q.n}'s answer is ${q.answer}, which is not one of its options (${has})` : `question ${q.n} has no answer on the quiz's "**Answers:**" line`, fix: `Give question ${q.n} one answer, "${q.n} <letter>", naming one of its options.`, line: q.line }));
+    }
+    for (const [t, at] of definedAt) {
+      if (seq.knows.has(t) || at.n <= q.unit) continue;
+      if (usesTerm(q.text, t)) out.push(finding({ id: "station-sequence-quiz-used-before-defined", severity: "fail", message: `question ${q.n}, tagged ${U} ${q.unit}, uses "${t}", which ${U} ${at.n} defines later`, fix: `Rewrite the question without "${t}", or tag it with ${U} ${at.n} or later.`, line: q.line }));
+    }
+  }
+  // coverage: a simple plural counts, so "skills" tests "skill".
+  for (const [t, at] of definedAt) {
+    if (!questions.some((q) => usesTerm(q.text, t) || usesTerm(q.text, `${t}s`))) {
+      out.push(finding({ id: "station-sequence-quiz-untested", severity: "fail", message: `no quiz question tests "${t}", which ${U} ${at.n} defines`, fix: `Add a question that uses "${t}", tagged ${U} ${at.n} or later.`, line: at.line }));
+    }
+  }
+  return out;
+}

package/src/stations/triage.mjs

@@ -0,0 +1,20 @@
+// Station "triage" (hyperspec 0.9). Every finding a panel reader or an outside review raised about
+// the draft, held to its answer: a finding nobody answered fails, an answer that says the draft now
+// does it (taken) or already did (already-true) fails unless the passage it quotes is in the draft
+// as it is now, and a kept answer fails without its reason. An open finding is a warning: it is a
+// decision for the operator, and the draft can ship while it waits. So is an answer that kept a
+// passage, or left it open, when that passage is no longer in the draft.
+//
+// The rules and the file live in src/triage.mjs, which `hyperspec triage status` reads too, so the
+// station and the command can never disagree. With no triage file yet the station skips.
+
+import { triageState } from "../triage.mjs";
+
+export const name = "triage";
+
+export function run(spec, draft) {
+  const state = triageState(spec, draft);
+  if (state.skip) return { station: name, status: "skip", findings: [], reason: state.skip };
+  const status = state.findings.some((f) => f.severity === "fail") ? "fail" : "pass";
+  return { station: name, status, findings: state.findings };
+}