@supersuit/hyperspec 0.4.0 → 0.6.0

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));

package/src/stations/links.mjs

@@ -0,0 +1,275 @@
+// Station "links" (hyperspec 0.6). Checks every Markdown link and
+// every bare http(s):// URL in the draft: an absolute http/https URL must be well-formed (a real
+// host), a mailto: link must carry an address, any other scheme fails outright, a link rooted at
+// "/" is site-root-relative and warns rather than resolving locally (there is
+// no site root here to resolve it against), and any other relative link must resolve to a file
+// that actually exists, relative to the DRAFT's own directory (never the spec's). No network
+// access, ever: well-formed means "the URL parses and names a host", not "the host answers".
+//
+// Three Markdown link forms are checked, all through the same checkUrl:
+//   - inline: [text](url)
+//   - reference, full or collapsed: [text][ref] / [ref][], resolved against a [ref]: url
+//     definition elsewhere in the draft (label matching is case-insensitive and whitespace-
+//     collapsed); a full or collapsed reference with no matching definition is its own
+//     finding, station-links-undefined-reference, naming the label, since the second bracket
+//     pair says a link was meant.
+//   - shortcut reference: [ref] alone (no second bracket pair), checked only when a definition
+//     for that label exists, once every inline link, reference definition and full/collapsed
+//     reference has already been matched and masked out of the text. With no definition it is
+//     ordinary text, as CommonMark renders it: [sic], a task-list [x], a footnote-style [1].
+//
+// Anchors: the "#fragment" part of any link is stripped before checking anything else, so
+// "notes.md#section-two" is checked as "notes.md" (its target heading is never verified), and a
+// link that is nothing but "#fragment" (empty path once the anchor is stripped) always resolves,
+// since it points at the draft itself.
+//
+// Fenced code blocks and inline code spans are masked out (src/stations/util.mjs's maskCode)
+// before ANY of the above runs, so a Markdown link or URL shown as illustrative syntax inside a
+// fence or a `` `span` `` is never checked as a real, followable link.
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { lineAt, maskCode, maskRanges, truncate } from "./util.mjs";
+
+export const name = "links";
+
+// Every "[text](url)" span in `text`, in document order: { start, end, url }. The url is the raw
+// content between the parens, up to the first run of whitespace (a Markdown link may carry a
+// `"title"` after the url, separated by whitespace; that title is not itself a link and is
+// ignored here). `end` is the index just past the closing ")", used both to report a line number
+// and to mask the span out before later scans, so the same URL is never counted twice.
+const MD_LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+function markdownLinks(text) {
+  const out = [];
+  let m;
+  MD_LINK_RE.lastIndex = 0;
+  while ((m = MD_LINK_RE.exec(text))) {
+    const inner = m[2].trim();
+    const url = inner.split(/\s+/)[0];
+    if (url) out.push({ start: m.index, end: m.index + m[0].length, url });
+  }
+  return out;
+}
+
+// A reference definition line: up to 3 spaces of indent, "[label]:", the URL, and an optional
+// title in "quotes", 'quotes' or (parens). One definition per line, the common case; a multi-line
+// definition (title on the following line) is not attempted.
+const DEF_RE = /^[ \t]{0,3}\[([^\]]+)\]:[ \t]*(\S+)[ \t]*(?:"[^"]*"|'[^']*'|\([^)]*\))?[ \t]*$/gm;
+
+const normalizeLabel = (label) => label.trim().toLowerCase().replace(/\s+/g, " ");
+
+// Every reference definition in `text`: a Map from normalized label to { url }, plus the [start,
+// end) span of each whole definition line, ready to mask out (so a definition's own "[label]:" is
+// never later mistaken for a reference USE, and its URL is never also picked up by the bare-URL
+// scan below). The FIRST definition for a given label wins on a duplicate, matching CommonMark.
+function definitions(text) {
+  const defs = new Map();
+  const spans = [];
+  let m;
+  DEF_RE.lastIndex = 0;
+  while ((m = DEF_RE.exec(text))) {
+    const label = normalizeLabel(m[1]);
+    if (!defs.has(label)) defs.set(label, { url: m[2] });
+    spans.push({ start: m.index, end: m.index + m[0].length });
+  }
+  return { defs, spans };
+}
+
+// Every "[text][ref]" (full) or "[text][]" (collapsed, label = text) span, in document order:
+// { start, end, label }. Run AFTER inline links and definitions are already masked out of `text`,
+// so this can only match genuine two-bracket-pair reference syntax.
+const FULL_REF_RE = /\[([^\]]*)\]\[([^\]]*)\]/g;
+
+function fullReferences(text) {
+  const out = [];
+  let m;
+  FULL_REF_RE.lastIndex = 0;
+  while ((m = FULL_REF_RE.exec(text))) {
+    const label = (m[2].trim() || m[1].trim());
+    if (label) out.push({ start: m.index, end: m.index + m[0].length, label });
+  }
+  return out;
+}
+
+// Every remaining "[label]" span, in document order: { start, end, label }. Run AFTER inline
+// links, definitions and full/collapsed references are already masked out, so whatever "[...]"
+// is left is either a shortcut reference or ordinary bracketed prose. The caller keeps only the
+// ones whose label has a definition: CommonMark renders an undefined "[label]" as plain text, so
+// an editorial [sic], a task-list [x] or a footnote-style [1] is never a link.
+const SHORTCUT_REF_RE = /\[([^\]]+)\]/g;
+
+function shortcutReferences(text) {
+  const out = [];
+  let m;
+  SHORTCUT_REF_RE.lastIndex = 0;
+  while ((m = SHORTCUT_REF_RE.exec(text))) {
+    const label = m[1].trim();
+    if (label) out.push({ start: m.index, end: m.index + m[0].length, label });
+  }
+  return out;
+}
+
+// Every bare "http://" or "https://" URL left in `text` (after every other link form has been
+// masked out of it), stopping at whitespace or a closing bracket/paren/angle-bracket that is more
+// likely to be surrounding punctuation than part of the URL itself. The host part may be empty,
+// so a bare "https://" is matched and fails as malformed rather than passing unseen.
+const BARE_URL_RE = /https?:\/\/[^\s)>\]]*/g;
+
+function bareUrls(text) {
+  const out = [];
+  let m;
+  BARE_URL_RE.lastIndex = 0;
+  while ((m = BARE_URL_RE.exec(text))) out.push({ start: m.index, end: m.index + m[0].length, url: m[0] });
+  return out;
+}
+
+const SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):/;
+
+// Classifies one URL, with its "#..." anchor already known to the caller as stripped: "http" (the
+// scheme itself, lowercased, is on `scheme`), "mailto", "other-scheme" (anything else with a
+// scheme prefix), or "relative" (no scheme prefix at all: a bare path, root-relative or relative).
+function classify(withoutAnchor) {
+  const m = SCHEME_RE.exec(withoutAnchor);
+  if (!m) return { kind: "relative", path: withoutAnchor };
+  const scheme = m[1].toLowerCase();
+  if (scheme === "http" || scheme === "https") return { kind: "http", scheme };
+  if (scheme === "mailto") return { kind: "mailto" };
+  return { kind: "other-scheme", scheme };
+}
+
+// Why `url` is broken (or merely unresolvable locally), as one of "malformed-http",
+// "malformed-mailto", "bad-scheme", "root-relative" or "broken-relative", or null when it is
+// fine. draftDirAbs is the draft's own directory (resolved once by the caller), which every
+// relative link resolves against, never the spec's directory.
+function checkUrl(url, draftDirAbs) {
+  const hashIdx = url.indexOf("#");
+  const withoutAnchor = hashIdx === -1 ? url : url.slice(0, hashIdx);
+  const c = classify(withoutAnchor);
+
+  if (c.kind === "http") {
+    try {
+      const u = new URL(url);
+      if (!u.hostname) return "malformed-http";
+    } catch {
+      return "malformed-http";
+    }
+    return null;
+  }
+  if (c.kind === "mailto") {
+    const address = withoutAnchor.slice("mailto:".length).split("?")[0].trim();
+    return address ? null : "malformed-mailto";
+  }
+  if (c.kind === "other-scheme") return "bad-scheme";
+
+  // relative: an empty path (the link was nothing but "#fragment", or literally empty) always
+  // resolves, since it points at the draft's own file, which exists by construction (check.mjs
+  // only ever builds a draft object after successfully reading it).
+  if (!c.path) return null;
+  // A link rooted at "/" names a path from some site's root, which this station has no way to
+  // resolve (there is no "site" here, only the draft's own folder), so it is neither a pass nor a
+  // fail -- a warning, naming the fact that it cannot be checked locally.
+  if (c.path.startsWith("/")) return "root-relative";
+  const target = resolve(draftDirAbs, c.path);
+  return existsSync(target) ? null : "broken-relative";
+}
+
+const REASON = {
+  "malformed-http": {
+    id: "station-links-malformed",
+    severity: "fail",
+    text: (url) => `link "${url}" is not a well-formed http/https URL (no host)`,
+    fix: "Fix the URL to include a scheme (http:// or https://) and a real host.",
+  },
+  "malformed-mailto": {
+    id: "station-links-malformed",
+    severity: "fail",
+    text: (url) => `link "${url}" is a mailto: link with no address`,
+    fix: "Add a real address after mailto:, or remove the link.",
+  },
+  "bad-scheme": {
+    id: "station-links-bad-scheme",
+    severity: "fail",
+    text: (url) => `link "${url}" uses a scheme that is not http, https or mailto`,
+    fix: "Use an http(s):// URL, a mailto: link, or a path relative to the draft.",
+  },
+  "root-relative": {
+    id: "station-links-root-relative",
+    severity: "warn",
+    text: (url) => `link "${url}" is site-root-relative and cannot be resolved against a file on disk`,
+    fix: "Point the link at a path relative to the draft, or use a full URL, if it must be checked.",
+  },
+  "broken-relative": {
+    id: "station-links-broken-relative",
+    severity: "fail",
+    text: (url) => `relative link "${url}" does not resolve to a file next to the draft`,
+    fix: "Fix the path, or add the file the link points at.",
+  },
+};
+
+function reasonFinding(reason, url, line) {
+  const r = REASON[reason];
+  return { station: name, id: r.id, severity: r.severity, line, message: r.text(truncate(url, 80)), fix: r.fix };
+}
+
+function undefinedReferenceFinding(label, line) {
+  const shown = truncate(label, 80);
+  return {
+    station: name,
+    id: "station-links-undefined-reference",
+    severity: "fail",
+    line,
+    message: `reference "${shown}" has no matching "[${shown}]: url" definition`,
+    fix: `Add a "[${shown}]: <url>" definition, or fix the reference to match a label that already has one.`,
+  };
+}
+
+export function run(spec, draft) {
+  const draftDirAbs = dirname(resolve(draft.path));
+
+  // Masking pipeline: code first, then each link form in turn, each pass working on the text the
+  // previous pass left behind, so nothing is ever matched twice by a later, looser pattern (a
+  // reference definition's own brackets are not a shortcut reference; the leftover "[text]" half
+  // of a masked-out "[text][ref]" pair is not itself a shortcut reference; a URL already read as
+  // part of a Markdown link is not also a bare URL). Every span carries its ORIGINAL start offset
+  // throughout, since maskRanges never shifts anything, only blanks it, so draft.text and lineAt
+  // stay valid for every one of them regardless of how many passes it survived.
+  let working = maskCode(draft.text);
+
+  const mdLinks = markdownLinks(working);
+  working = maskRanges(working, mdLinks);
+
+  const { defs, spans: defSpans } = definitions(working);
+  working = maskRanges(working, defSpans);
+
+  const fullRefs = fullReferences(working);
+  working = maskRanges(working, fullRefs);
+
+  const shortcutRefs = shortcutReferences(working).filter((r) => defs.has(normalizeLabel(r.label)));
+  working = maskRanges(working, shortcutRefs);
+
+  const bare = bareUrls(working);
+
+  const entries = [];
+
+  for (const { start, url } of [...mdLinks, ...bare]) {
+    const reason = checkUrl(url, draftDirAbs);
+    if (reason) entries.push({ start, finding: reasonFinding(reason, url, lineAt(draft.text, start)) });
+  }
+
+  for (const { start, label } of [...fullRefs, ...shortcutRefs]) {
+    const line = lineAt(draft.text, start);
+    const def = defs.get(normalizeLabel(label));
+    if (!def) {
+      entries.push({ start, finding: undefinedReferenceFinding(label, line) });
+      continue;
+    }
+    const reason = checkUrl(def.url, draftDirAbs);
+    if (reason) entries.push({ start, finding: reasonFinding(reason, def.url, line) });
+  }
+
+  entries.sort((a, b) => a.start - b.start);
+  const findings = entries.map((e) => e.finding);
+  const status = findings.some((f) => f.severity === "fail") ? "fail" : "pass";
+  return { station: name, status, findings };
+}

package/src/stations/private.mjs

@@ -0,0 +1,117 @@
+// Station "private" (hyperspec 0.6). No run of 8 or more consecutive words from
+// any `private` segment of a marked material may appear in the draft. Pure and deterministic: a
+// word-level match over normalized text, no model call and no judgment about what would count as
+// a paraphrase (a paraphrase is not caught, by design; a verbatim run is).
+//
+// Normalization, applied the same way to the draft and to every private segment: split into words
+// with dna.mjs's wordsOf (already lowercased, the one word definition every station shares), then
+// drop apostrophes from each word, so case, punctuation and whitespace never decide a match and
+// "don't", "don’t" and "dont" are one word. Fenced code and inline code are masked out of the
+// draft first (util.mjs's maskCode), like every other station that reads prose.
+//
+// A private segment of 8 or more words fails when any 8-word window of it appears in the draft. One
+// of 4 to 7 words is checked as a whole: all of its words, in order, anywhere in the draft. One
+// under 4 words is not checked at all: two or three words ("Yes, Tuesday.") match
+// ordinary prose, so checking them would fail drafts that leak nothing. Skipping silently would
+// hide that a private passage went unchecked, so the station reports how many it skipped as ONE
+// warning, station-private-short-skipped, carrying the count and never the text (the text is
+// the private part). Each leak is reported once, as the longest run the segment and the draft share from where
+// the match starts, so a whole pasted paragraph is one finding rather than one per window; a
+// segment that leaks in two separate places is two findings. Every finding names the material, the
+// segment and the leaked run (normalized words, at most 80 characters), with the draft line where
+// the run starts.
+
+import { wordsOf } from "../dna.mjs";
+import { lineAt, maskCode, markedSegments, truncate } from "./util.mjs";
+
+export const name = "private";
+
+const WINDOW = 8;
+const MIN_CHECKED = 4;
+// dna.mjs's WORD_RE, repeated here only because wordsOf returns words without their offsets and a
+// finding needs the line a leak starts on; the segment side goes through wordsOf itself.
+const WORD_RE = /[\p{L}\p{N}'’]+/gu;
+const stripApostrophes = (w) => w.replace(/['’]/g, "");
+
+// The draft's words, normalized, each with the offset it starts at (for the finding's line).
+function draftWords(text) {
+  const out = [];
+  WORD_RE.lastIndex = 0;
+  let m;
+  while ((m = WORD_RE.exec(text))) {
+    const w = stripApostrophes(m[0].toLowerCase());
+    if (w) out.push({ w, at: m.index });
+  }
+  return out;
+}
+
+const segmentWords = (text) => wordsOf(text).map(stripApostrophes).filter(Boolean);
+
+// The first index in `words` (draft word objects) where `seq` (strings) appears contiguously, or -1.
+function findSequence(words, seq) {
+  outer: for (let i = 0; i + seq.length <= words.length; i++) {
+    for (let k = 0; k < seq.length; k++) if (words[i + k].w !== seq[k]) continue outer;
+    return i;
+  }
+  return -1;
+}
+
+export function run(spec, draft, ctx) {
+  const words = draftWords(maskCode(draft.text));
+  // First draft position of every 8-word window, so each private window is one map lookup.
+  const windows = new Map();
+  for (let i = 0; i + WINDOW <= words.length; i++) {
+    const key = words.slice(i, i + WINDOW).map((x) => x.w).join(" ");
+    if (!windows.has(key)) windows.set(key, i);
+  }
+
+  const findings = [];
+  let skippedShort = 0;
+  const leak = (material, segId, run, at) => findings.push({
+    station: name,
+    id: "station-private-leak",
+    severity: "fail",
+    line: lineAt(draft.text, at),
+    message: `material ${material}, segment ${segId} is private, and the draft repeats it: "${truncate(run.join(" "), 80)}"`,
+    fix: "Rewrite the passage in words that do not repeat the private material, or relabel the segment if it is not private.",
+  });
+
+  for (const { material, segments } of markedSegments(spec, ctx)) {
+    for (const seg of segments) {
+      if (seg.label !== "private" || typeof seg.text !== "string") continue;
+      const segId = typeof seg.id === "string" && seg.id.trim() ? seg.id.trim() : "(no id)";
+      const tokens = segmentWords(seg.text);
+      if (!tokens.length) continue;
+      if (tokens.length < MIN_CHECKED) { skippedShort++; continue; }
+
+      if (tokens.length < WINDOW) {
+        const at = findSequence(words, tokens);
+        if (at !== -1) leak(material, segId, tokens, words[at].at);
+        continue;
+      }
+
+      let i = 0;
+      while (i + WINDOW <= tokens.length) {
+        const start = windows.get(tokens.slice(i, i + WINDOW).join(" "));
+        if (start === undefined) { i++; continue; }
+        // Extend the shared run as far as the segment and the draft keep agreeing.
+        let len = WINDOW;
+        while (i + len < tokens.length && start + len < words.length && tokens[i + len] === words[start + len].w) len++;
+        leak(material, segId, tokens.slice(i, i + len), words[start].at);
+        i += len;
+      }
+    }
+  }
+
+  if (skippedShort) {
+    findings.push({
+      station: name,
+      id: "station-private-short-skipped",
+      severity: "warn",
+      message: `${skippedShort} private segment${skippedShort === 1 ? " is" : "s are"} under ${MIN_CHECKED} words and ${skippedShort === 1 ? "was" : "were"} not checked`,
+      fix: `Check the draft against ${skippedShort === 1 ? "it" : "them"} by hand, or widen the private segment to ${MIN_CHECKED} or more words.`,
+    });
+  }
+
+  return { station: name, status: findings.some((x) => x.severity === "fail") ? "fail" : "pass", findings };
+}