@supersuit/hyperspec 0.5.0 → 0.7.0

package/src/stations/claims.mjs

@@ -0,0 +1,155 @@
+// Station "claims" (hyperspec 0.6). Reads writing.sources.ledger, a JSONL file
+// where each line is one claim: { "text": <claim as it appears in the draft>, "source":
+// <non-empty>, "span"?: <quote or locator> }. Two things are checked per line, and whether a
+// sentence in the draft even IS a factual claim is never attempted here: that is judgment, and
+// the ledger is the closed list of what counts as a claim. This station only checks that the
+// ledger and the draft agree with each other:
+//
+//   - the claim's text still appears verbatim in the draft (normalized for whitespace and quote
+//     characters, but not case) -- otherwise the ledger is stale (station-claims-stale);
+//   - the claim carries a real, non-placeholder source -- otherwise it is unsourced
+//     (station-claims-unsourced, downgraded to a warning when writing.sources.unsourced_claim is
+//     "warn", the same closed-set field src/writing-fields.mjs already validates on the spec).
+//
+// The ledger path resolves relative to the spec (spec.dir), the same way every other path-bearing
+// writing field does. A missing or unreadable ledger fails the whole station on its own
+// (station-claims-ledger-missing); a malformed JSONL line (not JSON, not an object, or missing
+// text) is its own finding naming the line number, and does not stop the rest of the file from
+// being read.
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { str } from "../placeholder.mjs";
+import { lineAt, truncate } from "./util.mjs";
+
+export const name = "claims";
+
+// Quote characters normalized to their straight ASCII form, then whitespace runs collapsed to a
+// single space and the ends trimmed. "text matching is exact after normalizing whitespace and
+// quote characters": case is NOT normalized, so a claim's text must
+// still match the draft's actual capitalization.
+function normalize(text) {
+  return String(text)
+    .replace(/[‘’‚‛]/g, "'")
+    .replace(/[“”„‟]/g, '"')
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// Where a claim's text first appears in the original draft, under the same normalization the match
+// uses (any whitespace run for a space, any quote character for a quote), or -1.
+function firstOccurrence(text, claimText) {
+  const body = [...normalize(claimText)].map((c) => (c === " " ? "\\s+" : c === "'" ? "['‘’‚‛]" : c === '"' ? '["“”„‟]' : c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))).join("");
+  const m = new RegExp(body).exec(text);
+  return m ? m.index : -1;
+}
+
+// The claims ledger as the claims station reads it, shared with the persona judge
+// (src/judges/persona.mjs), so both see the same claims. { path, missing, lines }: path is
+// writing.sources.ledger as written (null when unset); missing is true when it is set but cannot be
+// read; lines holds every non-blank line, 1-based as n, each either { n, text } (a claim with
+// non-empty text; claim is the parsed object) or { n, problem } naming why it is not one.
+export function readClaimsLedger(spec) {
+  const ledgerPath = str(spec?.data?.writing?.sources?.ledger);
+  if (!ledgerPath) return { path: null, missing: false, lines: [] };
+  let raw;
+  try {
+    // A leading UTF-8 BOM (written by default by several Windows/Excel-adjacent editors) is not
+    // valid JSON leading whitespace, so it must come off before line 1 is parsed, or a genuinely
+    // well-formed first line reports as broken JSON for a reason that has nothing to do with its
+    // content.
+    raw = readFileSync(resolve(spec?.dir || ".", ledgerPath), "utf8").replace(/^\uFEFF/, "");
+  } catch {
+    return { path: ledgerPath, missing: true, lines: [] };
+  }
+  const lines = [];
+  raw.split("\n").forEach((text, i) => {
+    if (text.trim() === "") return;
+    const n = i + 1;
+    let obj;
+    try { obj = JSON.parse(text); } catch { lines.push({ n, problem: "is not valid JSON" }); return; }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) { lines.push({ n, problem: "is not a JSON object" }); return; }
+    const claimText = typeof obj.text === "string" ? obj.text : "";
+    if (!claimText.trim()) { lines.push({ n, problem: "has no text" }); return; }
+    lines.push({ n, text: claimText, claim: obj });
+  });
+  return { path: ledgerPath, missing: false, lines };
+}
+
+const PROBLEM_FIX = {
+  "is not valid JSON": "Fix the JSON on that line.",
+  "is not a JSON object": 'Each ledger line must be a JSON object: {"text": "...", "source": "..."}.',
+  "has no text": "Add text: the claim exactly as it appears in the draft.",
+};
+
+export function run(spec, draft) {
+  const sources = spec?.data?.writing?.sources ?? {};
+  const ledgerPath = str(sources.ledger);
+  const unsourcedSeverity = str(sources.unsourced_claim) === "warn" ? "warn" : "fail";
+
+  if (!ledgerPath) {
+    // writing.sources.ledger is a required field (lint test 1), so by the time check runs (lint
+    // already passed) a real spec always has one; this is defense in depth for a caller that
+    // builds a spec object by hand and skips lint, mirroring how form.mjs treats its own inputs
+    // as never fully trusted either.
+    return { station: name, status: "skip", findings: [], reason: "writing.sources.ledger is not set" };
+  }
+
+  const ledger = readClaimsLedger(spec);
+  if (ledger.missing) {
+    return {
+      station: name,
+      status: "fail",
+      findings: [{
+        station: name,
+        id: "station-claims-ledger-missing",
+        severity: "fail",
+        message: `writing.sources.ledger "${ledgerPath}" does not exist or cannot be read`,
+        fix: `Create ${ledgerPath} as JSONL, one claim per line: {"text": "...", "source": "..."}.`,
+      }],
+    };
+  }
+
+  const findings = [];
+  const draftNorm = normalize(draft.text);
+
+  for (const { n, problem, text: claimText, claim: obj } of ledger.lines) {
+    if (problem) {
+      findings.push({
+        station: name,
+        id: `station-claims-json-line-${n}`,
+        severity: "fail",
+        message: `writing.sources.ledger "${ledgerPath}" line ${n} ${problem}`,
+        fix: PROBLEM_FIX[problem],
+      });
+      continue;
+    }
+
+    const tag = truncate(claimText, 80);
+
+    if (!draftNorm.includes(normalize(claimText))) {
+      findings.push({
+        station: name,
+        id: "station-claims-stale",
+        severity: "fail",
+        message: `ledger line ${n}, "${tag}", does not appear verbatim in the draft`,
+        fix: "Update the ledger's text to match the draft exactly, or remove the stale claim.",
+      });
+    }
+
+    if (!str(obj.source)) {
+      const at = firstOccurrence(draft.text, claimText);
+      findings.push({
+        station: name,
+        id: "station-claims-unsourced",
+        severity: unsourcedSeverity,
+        ...(at >= 0 ? { line: lineAt(draft.text, at) } : {}),
+        message: `ledger line ${n}, "${tag}", has no source (or it is a placeholder)`,
+        fix: "Add a real source: to the claim, or remove it from the ledger.",
+      });
+    }
+  }
+
+  const status = findings.some((x) => x.severity === "fail") ? "fail" : "pass";
+  return { station: name, status, findings };
+}

package/src/stations/dna.mjs

@@ -0,0 +1,126 @@
+// Station "dna" (hyperspec 0.6). Measures the draft the way `hyperspec dna measure`
+// measures a scope's goldens (dna.mjs's measureFeatures, the same function, never a second copy)
+// and compares it with the scope's recorded features.json. Pure and deterministic: arithmetic on
+// two features objects, no model call and no judgment about whether a difference matters beyond the
+// band rule below.
+//
+// Runs only when writing.dna.scope_dir is set (no scope_dir: skip) and its features.json is
+// current. "Current" is lint's own test-6 notion, read through the one function lint uses
+// (writing-fields.mjs's featuresStaleness): a missing or stale features.json, or a scope whose
+// goldens folder cannot be read, makes this station skip with the reason. Lint already fails the
+// spec for each of those, and check runs no station on a spec lint fails, so the skip is defense in
+// depth for a direct caller; comparing a draft against numbers that no longer describe the goldens
+// would report drift from something that is not the writer's voice.
+//
+// Compared features, and only when the scope's features.json records them: sentence_length.mean,
+// paragraph_length.mean_sentences and paragraph_length.mean_words (the two paragraph-length means),
+// and every per-1000-words rate (each rates_per_1000_words entry, plus contraction_rate and the
+// three person rates, which measureFeatures computes per 1000 words too). Counts, medians, p90,
+// mean word length and signature words are not compared. For a scope value v the band is
+// v / 1.5 (floor 0) to max(v * 1.5, v + 5), edges inside; a draft value outside it is one
+// station-dna-drift finding carrying both values and the band.
+//
+// The em dash has one rule of its own: when the scope's em dash rate is 0 and the draft's is above
+// 0, that is station-dna-em-dash, and the em dash's band finding is not also reported (it is the
+// same defect, and the stricter rule already names it). Fenced and inline code are masked out of
+// the draft before it is measured, like every station that reads prose.
+//
+// Severity: both findings are WARNINGS, never failures, so the station's status is pass
+// whenever it runs. This station measures; judging whether the draft is in the writer's voice
+// belongs to the lineup judge of a later release, and a band over a handful of goldens is evidence
+// for that judge, not a verdict.
+
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { str } from "../placeholder.mjs";
+import { measureFeatures, readScope } from "../dna.mjs";
+import { featuresStaleness } from "../writing-fields.mjs";
+import { lineAt, maskCode } from "./util.mjs";
+
+export const name = "dna";
+
+const MEANS = [["sentence_length", "mean"], ["paragraph_length", "mean_sentences"], ["paragraph_length", "mean_words"]];
+const FLAT_RATES = ["contraction_rate", "first_person_singular_rate", "first_person_plural_rate", "second_person_rate"];
+const EM_DASH = "rates_per_1000_words.em_dash";
+
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const fmt = (x) => String(Math.round(x * 1000) / 1000);
+
+// Every compared feature as [dotted name, scope value, draft value], in a fixed order, for the
+// features the scope records as numbers. A draft value that is not a number reads as 0.
+function comparable(scope, draft) {
+  const out = [];
+  const add = (key, s, d) => { if (isNum(s)) out.push([key, s, isNum(d) ? d : 0]); };
+  for (const [group, field] of MEANS) add(`${group}.${field}`, scope?.[group]?.[field], draft?.[group]?.[field]);
+  const rates = isObj(scope?.rates_per_1000_words) ? scope.rates_per_1000_words : {};
+  for (const k of Object.keys(rates)) add(`rates_per_1000_words.${k}`, rates[k], draft?.rates_per_1000_words?.[k]);
+  for (const k of FLAT_RATES) add(k, scope?.[k], draft?.[k]);
+  return out;
+}
+
+// compareFeatures(scopeFeatures, draftFeatures): the band rule alone, over two measureFeatures-shaped
+// objects. Returns [{ feature, scope, draft, low, high }] for every compared feature outside its band.
+export function compareFeatures(scopeFeatures, draftFeatures) {
+  const drift = [];
+  for (const [feature, s, d] of comparable(scopeFeatures, draftFeatures)) {
+    const low = Math.max(0, s / 1.5);
+    const high = Math.max(s * 1.5, s + 5);
+    if (d < low || d > high) drift.push({ feature, scope: s, draft: d, low, high });
+  }
+  return drift;
+}
+
+const skip = (reason) => ({ station: name, status: "skip", findings: [], reason });
+
+export function run(spec, draft) {
+  const scopeDir = str(spec?.data?.writing?.dna?.scope_dir);
+  if (!scopeDir) return skip("writing.dna.scope_dir is not set");
+
+  const scopeAbs = resolve(spec?.dir || ".", scopeDir);
+  const measure = `run \`hyperspec dna measure ${scopeDir}\``;
+  const disk = readScope(scopeAbs, { displayDir: scopeDir });
+  if (disk.findings.some((x) => x.id === "writing-dna-goldens-missing" || x.id === "writing-dna-goldens-outside")) {
+    return skip(`writing.dna.scope_dir "${scopeDir}": its goldens cannot be read (run \`hyperspec lint\` for details)`);
+  }
+  const featuresPath = join(scopeAbs, "features.json");
+  const stale = featuresStaleness(featuresPath, disk.scope, disk.goldens);
+  if (stale === "missing") return skip(`writing.dna.scope_dir "${scopeDir}" has no features.json (or it is not valid JSON); ${measure}`);
+  if (stale) return skip(`writing.dna.scope_dir "${scopeDir}"'s features.json is stale: ${stale}; ${measure}`);
+
+  let scopeFeatures;
+  try { scopeFeatures = JSON.parse(readFileSync(featuresPath, "utf8")).features; } catch { scopeFeatures = null; }
+  if (!isObj(scopeFeatures)) return skip(`writing.dna.scope_dir "${scopeDir}" has no features.json (or it is not valid JSON); ${measure}`);
+
+  const masked = maskCode(draft.text);
+  const draftFeatures = measureFeatures([masked]);
+  const findings = [];
+
+  const scopeEm = scopeFeatures.rates_per_1000_words?.em_dash;
+  const draftEm = draftFeatures.rates_per_1000_words.em_dash;
+  const emDashRule = scopeEm === 0 && draftEm > 0;
+  if (emDashRule) {
+    findings.push({
+      station: name,
+      id: "station-dna-em-dash",
+      severity: "warn",
+      line: lineAt(draft.text, masked.indexOf("\u2014")),
+      message: `the draft uses em dashes (${fmt(draftEm)} per 1000 words); the scope's goldens use none (0)`,
+      fix: "Rewrite each em dash as the punctuation the goldens use instead: a comma, a colon, parentheses or a new sentence.",
+    });
+  }
+
+  for (const d of compareFeatures(scopeFeatures, draftFeatures)) {
+    if (emDashRule && d.feature === EM_DASH) continue;
+    findings.push({
+      station: name,
+      id: "station-dna-drift",
+      severity: "warn",
+      message: `${d.feature} is ${fmt(d.draft)} in the draft; the scope's goldens measure ${fmt(d.scope)}, band ${fmt(d.low)} to ${fmt(d.high)}`,
+      fix: `Bring ${d.feature} back inside the band, or, if the scope no longer describes this writer, re-measure it with better goldens.`,
+    });
+  }
+
+  // Every finding here is a warning, so the station passes whenever it runs.
+  return { station: name, status: findings.some((x) => x.severity === "fail") ? "fail" : "pass", findings };
+}

package/src/stations/form.mjs

@@ -0,0 +1,115 @@
+// Station "form" (hyperspec 0.6). The first of hyperspec check's deterministic
+// stations: it checks a draft's word count against writing.form.length, and checks that every
+// writing.form.required_parts entry actually shows up in the draft. Pure and deterministic, like
+// every station: (spec, draft) in, a result out, no filesystem access beyond what the caller
+// already read, no model call.
+//
+// Length: writing.form.length.unit is only measured when it is exactly "words" (lint already
+// requires the key to be present; a spec naming an unmeasured unit, e.g. "characters" or
+// "minutes", is not wrong, this build just cannot grade it yet). When the unit is not "words"
+// the whole station skips, findings included, rather than silently passing or half-checking: a
+// length this build cannot read is not evidence the length is fine, and running required_parts
+// alone while staying silent about length would read as a check that covered more than it did.
+//
+// Required parts: a required part is judged present two ways, either one is enough, because
+// required_parts sometimes names a heading-shaped thing ("claim", "evidence", "close") and
+// sometimes names a field a form fills in inline rather than under its own heading (a memo's
+// "To:", an email's "Subject:"). Neither the schema nor the draft says which kind a given part
+// is, so both checks always run for every part, regardless of the form's name:
+//   - an ATX heading (up to three spaces of indent, 1 to 6 "#" characters, a space, the text, an
+//     optional closing run of "#"s) whose text, trimmed and case-folded, equals the part name; or
+//   - a line whose text, trimmed and case-folded, starts with the part name immediately
+//     followed by ":".
+// Fenced and inline code are masked first. This is a literal, narrow reading on purpose: it will
+// miss a heading spelled "## The Claim" against a required part "claim", a Setext heading
+// (underlined with === or ---), or one styled "**Claim**". Widening the match is a later
+// station's decision once real drafts show what this narrow reading actually misses.
+
+import { wordsOf } from "../dna.mjs";
+import { maskCode } from "./util.mjs";
+
+export const name = "form";
+
+// An ATX heading as CommonMark reads it: up to three spaces of indent, 1 to 6 "#"s, then a space
+// or tab and the text (or nothing); an optional closing run of "#"s is not part of the text.
+const ATX_HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*))?$/;
+const headingText = (m) => (m[2] ?? "").replace(/(^|[ \t]+)#+[ \t]*$/, "").trim();
+
+// A finding id's slug half: lowercase, non [a-z0-9] runs collapsed to one "-", no leading or
+// trailing "-". Falls back to `fallback` when nothing alphanumeric survives (e.g. a required
+// part that is pure punctuation), so an id is never left with a trailing "station-form-required-part-".
+function slug(text, fallback) {
+  const s = String(text).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || fallback;
+}
+
+// Whether `part` shows up in the draft, either as a matching ATX heading or as a line starting
+// "<part>:" (both compared trimmed and case-folded).
+function partPresent(lines, part) {
+  const needle = part.trim().toLowerCase();
+  for (const line of lines) {
+    const heading = ATX_HEADING.exec(line);
+    if (heading && headingText(heading).toLowerCase() === needle) return true;
+    if (line.trim().toLowerCase().startsWith(`${needle}:`)) return true;
+  }
+  return false;
+}
+
+// run(spec, draft): spec is a loadSpec()-shaped object (spec.data.writing.form is what this
+// station reads); draft is { path, text, lines, sha256 } as src/check.mjs builds it. ctx (a
+// third argument every station receives) is unused here: form shares nothing with the other
+// stations.
+export function run(spec, draft) {
+  const form = spec?.data?.writing?.form ?? {};
+  const length = form.length && typeof form.length === "object" ? form.length : {};
+  // Trimmed and case-folded for the comparison: lint only requires length.unit to be non-
+  // placeholder text (writing-fields.mjs's formFields), not literally the lowercase word
+  // "words", so a spec author who writes "Words" or "WORDS" still gets the word count checked
+  // rather than a silent skip. The reason message on a genuine skip still shows the unit as
+  // written, never lowercased, since that is what the spec actually says.
+  const rawUnit = typeof length.unit === "string" ? length.unit.trim() : "";
+  const unit = rawUnit.toLowerCase();
+
+  if (unit !== "words") {
+    return { station: name, status: "skip", findings: [], reason: `length unit ${rawUnit || "(none)"} is not measured yet` };
+  }
+
+  const findings = [];
+  const min = Number(length.min);
+  const max = Number(length.max);
+  const count = wordsOf(draft.text).length;
+  if (!(count >= min && count <= max)) {
+    findings.push({
+      station: name,
+      id: "station-form-length",
+      severity: "fail",
+      message: `word count ${count} is outside writing.form.length (${min} to ${max} words)`,
+      fix: `Trim or expand the draft to ${min}-${max} words; it is currently ${count}.`,
+    });
+  }
+
+  // Code is masked first, like every station that reads prose: a heading shown inside a fenced
+  // block is an example, not the draft's own part.
+  const lines = maskCode(draft.text).split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+  const parts = Array.isArray(form.required_parts) ? form.required_parts.filter((p) => typeof p === "string" && p.trim()) : [];
+  const usedIds = new Set();
+  for (const part of parts) {
+    if (partPresent(lines, part)) continue;
+    let id = `station-form-required-part-${slug(part, "part")}`;
+    // Two required parts that slug to the same string (e.g. "Close" and "close!") would
+    // otherwise collide on one finding id; the second and later ones get a numeric suffix so
+    // every missing part still gets its own finding.
+    let n = 2;
+    while (usedIds.has(id)) { id = `station-form-required-part-${slug(part, "part")}-${n}`; n += 1; }
+    usedIds.add(id);
+    findings.push({
+      station: name,
+      id,
+      severity: "fail",
+      message: `required part "${part}" does not appear as a heading or a "${part}:" line`,
+      fix: `Add a heading ("# ${part}") or a line starting "${part}:" for required part "${part}".`,
+    });
+  }
+
+  return { station: name, status: findings.length ? "fail" : "pass", findings };
+}

package/src/stations/index.mjs

@@ -0,0 +1,27 @@
+// The station registry: every station `hyperspec check` knows about, in run order. Each entry's
+// run is the pure function (spec, draft, ctx) -> { station, status, findings, reason? } that
+// 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. 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";
+import * as terms from "./terms.mjs";
+import * as claims from "./claims.mjs";
+import * as quotes from "./quotes.mjs";
+import * as privateStation from "./private.mjs";
+import * as dna from "./dna.mjs";
+import * as links from "./links.mjs";
+
+export const STATIONS = Object.freeze([
+  { name: form.name, run: form.run },
+  { name: terms.name, run: terms.run },
+  { name: claims.name, run: claims.run },
+  { name: quotes.name, run: quotes.run },
+  { name: privateStation.name, run: privateStation.run },
+  { name: dna.name, run: dna.run },
+  { name: links.name, run: links.run },
+]);
+
+export const STATION_NAMES = Object.freeze(STATIONS.map((s) => s.name));