@supersuit/hyperspec 0.4.0 → 0.5.0

package/src/writing-fields.mjs

@@ -18,9 +18,11 @@
 // (test 1), because dialogue cannot be specified without them. relationships stays optional: a
 // character may genuinely relate to no one yet, and nothing gives it a closed set or a count.
 
-import { statSync } from "node:fs";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
 import { str } from "./placeholder.mjs";
 import { readSegments } from "./segments.mjs";
+import { readScope, isGoldenFileName, measureFeatures, featuresText, DNA_FORMAT } from "./dna.mjs";
 
 const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
 const list = (v) => (Array.isArray(v) ? v : []);
@@ -131,16 +133,149 @@ const UNRESOLVABLE_BECAUSE = {
 
 // ---------------------------------------------------------------- 2. dna ----------------------
 
+// writing.dna.scope_dir (0.5, optional): the path (relative to the spec, like every other path in
+// this file) to a scoped-DNA folder built by `hyperspec dna init`/`dna measure` (src/dna.mjs).
+// The KEY being absent means none of the checks below run: 0.4 behavior, unchanged. A key that IS
+// present but placeholder-ish (TODO, tbd, an empty string) fails on its own (test 1,
+// writing-dna-scope-dir, naming the value) before any of this runs, since a real value is what
+// every check below needs. Present with a real value, four things must all hold:
+// - scope.md's writer/form/audience/purpose agree with dna.writer/dna.scope (test 1);
+// - every dna.goldens[].path is one of the goldens readScope actually reads: resolved through
+//   any symlink, a golden-named file directly in the scope's REAL goldens/ folder (test 5,
+//   writing-dna-golden-leak, naming the golden and the scope). Anything else feeds the spec a
+//   passage that is never checked or measured under this scope. A goldens/ folder that itself
+//   resolves outside the scope is readScope's own finding (writing-dna-goldens-outside), which
+//   stands in for the per-golden findings it would otherwise cause;
+// - every golden IN the scope passes its own field checks, exactly readScope's findings, reused
+//   rather than re-derived, with displayDir set to the scope_dir string the spec wrote (never a
+//   resolved filesystem path, so a finding here never names this machine's folders);
+// - <scope_dir>/features.json is current: byte for byte what `dna measure` would write now
+//   (test 6), with the stale finding naming what differs.
+function isInsideDir(parentAbs, childAbs) {
+  return childAbs === parentAbs || childAbs.startsWith(parentAbs + sep);
+}
+
+const realOrNull = (p) => { try { return realpathSync(p); } catch { return null; } };
+
+// Why a listed golden is not one of the scope's goldens, as the words of the leak finding, or
+// null when it is one. lexicalGoldens is <scope_dir>/goldens as written; realGoldens is where
+// that folder really is.
+function leakReason(lexicalGoldens, realGoldens, goldenAbs) {
+  const real = realOrNull(goldenAbs);
+  if (real && realGoldens && dirname(real) === realGoldens && isGoldenFileName(basename(real))) return null;
+  if (!isInsideDir(lexicalGoldens, goldenAbs)) return "outside";
+  if (!real || !realGoldens || !isInsideDir(realGoldens, real)) return "symlink";
+  return "not-a-golden";
+}
+
+function leakFinding(idPrefix, reason, p, i, scopeDirRaw) {
+  const where = `${scopeDirRaw}/goldens/`;
+  if (reason === "outside") {
+    return f(5, `${idPrefix}-golden-leak`, "fail",
+      `golden "${p}" feeds only work that shares its scope; it does not live under ${where}`,
+      `Move ${p} into ${where}, or point dna.goldens[${i + 1}].path at a golden already there.`);
+  }
+  if (reason === "symlink") {
+    return f(5, `${idPrefix}-golden-leak`, "fail",
+      `golden "${p}" is a symlink that resolves outside ${where} (or sits in a folder that does), so it feeds this scope a passage from somewhere else`,
+      `Replace the link at ${p} with the passage itself, as a file in ${where} with why, approved_by and source.`);
+  }
+  return f(5, `${idPrefix}-golden-leak`, "fail",
+    `golden "${p}" is not one of the scope's goldens: only .md files directly in ${where}, other than README.md, are read, checked and measured`,
+    `Put the passage in its own .md file directly in ${where}, with why, approved_by and source, and point dna.goldens[${i + 1}].path at it.`);
+}
+
+// One field of the spec's own dna claim against the same field read off scope.md. Silent when
+// either side is empty: an empty spec-side value already fails its own presence check above (e.g.
+// writing-dna-writer), and an empty disk-side value already fails as one of readScope's own
+// findings (e.g. writing-dna-scope-file-writer); comparing two things when one is already known-broken
+// would just be a second name for the same defect, not a second defect.
+function scopeMismatch(out, idPrefix, scopeDirRaw, label, idSuffix, specVal, diskVal) {
+  const a = str(specVal);
+  const b = str(diskVal);
+  if (!a || !b || a.trim().toLowerCase() === b.trim().toLowerCase()) return;
+  out.push(f(1, `${idPrefix}-scope-mismatch-${idSuffix}`, "fail",
+    `writing.dna.scope_dir "${scopeDirRaw}": ${label} "${a}" does not match ${scopeDirRaw}/scope.md's ${label} "${b}"`,
+    `Make writing.dna's ${label} and ${scopeDirRaw}/scope.md's ${label} agree; one of them is wrong.`));
+}
+
+// Whether <scope>/features.json is what `dna measure` would write now. Returns "missing" (absent
+// or not JSON), null (current), or the words naming what differs: goldens added, removed or
+// changed by hash; scope fields that differ from scope.md; a dna format this linter does not
+// know; features that differ from a fresh measurement (only named when the goldens themselves
+// are unchanged, since changed goldens explain every number); and, when nothing more specific
+// differs, bytes dna measure would not have written.
+function featuresStaleness(featuresPath, diskScope, diskGoldens) {
+  let text;
+  let recorded;
+  try {
+    text = readFileSync(featuresPath, "utf8");
+    recorded = JSON.parse(text);
+  } catch {
+    return "missing";
+  }
+  if (!recorded || typeof recorded !== "object" || Array.isArray(recorded)) return "missing";
+  const parts = [];
+  const recordedGoldens = new Map(list(recorded.goldens).map((g) => [str(g?.path), str(g?.sha256)]));
+  const current = new Map(diskGoldens.map((g) => [g.path, g.sha256]));
+  const added = [...current.keys()].filter((p) => !recordedGoldens.has(p)).sort();
+  const removed = [...recordedGoldens.keys()].filter((p) => !current.has(p)).sort();
+  const changed = [...current.keys()].filter((p) => recordedGoldens.has(p) && recordedGoldens.get(p) !== current.get(p)).sort();
+  if (added.length) parts.push(`added ${added.join(", ")}`);
+  if (removed.length) parts.push(`removed ${removed.join(", ")}`);
+  if (changed.length) parts.push(`changed ${changed.join(", ")}`);
+  if (recorded.dna !== DNA_FORMAT) parts.push(`dna version ${JSON.stringify(recorded.dna ?? null)} is not the "${DNA_FORMAT}" this linter knows`);
+  if (!diskScope) return parts.length ? parts.join("; ") : null;
+
+  const recordedScope = isObj(recorded.scope) ? recorded.scope : {};
+  const scopeFields = ["writer", "form", "audience", "purpose"].filter((k) => recordedScope[k] !== diskScope[k]);
+  if (scopeFields.length) parts.push(`scope changed: ${scopeFields.join(", ")}`);
+  const features = measureFeatures(diskGoldens.map((g) => g.text));
+  if (!added.length && !removed.length && !changed.length) {
+    const recordedFeatures = isObj(recorded.features) ? recorded.features : {};
+    const keys = [...new Set([...Object.keys(features), ...Object.keys(recordedFeatures)])];
+    const differ = keys.filter((k) => JSON.stringify(features[k]) !== JSON.stringify(recordedFeatures[k]));
+    if (differ.length) parts.push(`features differ from a fresh measurement: ${differ.join(", ")}`);
+  }
+  if (!parts.length && text !== featuresText({ scope: diskScope, goldens: diskGoldens, features }).text) {
+    parts.push("the file is not byte for byte what `hyperspec dna measure` writes");
+  }
+  return parts.length ? parts.join("; ") : null;
+}
+
 function dnaFields(raw, d, here, idPrefix) {
   const out = [];
   if (!str(raw.writer)) out.push(f(1, `${idPrefix}-writer`, "fail", "writing.dna has no writer", "Add writer:."));
   const scope = isObj(raw.scope) ? raw.scope : {};
+  // scope-<field> is the spec's own writing.dna.scope, the id 0.4.0 shipped; scope-file-<field>
+  // (src/dna.mjs) is a scope folder's scope.md.
   if (!str(scope.form)) out.push(f(1, `${idPrefix}-scope-form`, "fail", "writing.dna.scope has no form", "Add scope.form:."));
   if (!str(scope.audience)) out.push(f(1, `${idPrefix}-scope-audience`, "fail", "writing.dna.scope has no audience", "Add scope.audience:."));
   if (!str(scope.purpose)) out.push(f(1, `${idPrefix}-scope-purpose`, "fail", "writing.dna.scope has no purpose", "Add scope.purpose:."));
   const rulesPath = str(raw.rules);
   if (!rulesPath) out.push(f(1, `${idPrefix}-rules`, "fail", "writing.dna has no rules", "Add rules: the path to the always-on writing style."));
   else out.push(...pathFindings(here, rulesPath, `${idPrefix}-rules`, "dna.rules", "Fix the path, or add the file."));
+
+  // scope_dir is optional, so its KEY being absent from writing.dna is never a finding (the
+  // whole scope_dir section below simply does not run). But a key that IS present with a
+  // placeholder-ish value (TODO, tbd, an empty string, ...) is a different situation: the operator
+  // wrote something and str() silently reads it as "not there", which would otherwise make a
+  // half-filled skeleton lint clean by accident. That gets its own finding, naming the value, and
+  // is why this check reads raw.scope_dir directly rather than through scopeDirRaw.
+  if (raw.scope_dir !== undefined && !str(raw.scope_dir)) {
+    out.push(f(1, `${idPrefix}-scope-dir`, "fail",
+      `writing.dna.scope_dir "${raw.scope_dir}" looks like a placeholder`,
+      "Point scope_dir: at a real scope folder (built with hyperspec dna init), or remove the field entirely; it is optional."));
+  }
+  const scopeDirRaw = str(raw.scope_dir);
+  const scopeDirAbs = scopeDirRaw ? here(scopeDirRaw) : null;
+  const disk = scopeDirRaw ? readScope(scopeDirAbs, { displayDir: scopeDirRaw }) : null;
+  const diskIds = new Set((disk?.findings ?? []).map((x) => x.id));
+  const goldensOutside = diskIds.has("writing-dna-goldens-outside");
+  const lexicalGoldens = scopeDirRaw ? here(join(scopeDirRaw, "goldens")) : null;
+  const realScope = scopeDirRaw ? realOrNull(scopeDirAbs) : null;
+  const realGoldens = realScope ? join(realScope, "goldens") : null;
+
   const goldens = list(raw.goldens);
   if (!goldens.length) out.push(f(1, `${idPrefix}-goldens`, "fail", "writing.dna has no goldens", "Add at least one golden under dna.goldens."));
   goldens.forEach((g, i) => {
@@ -148,7 +283,44 @@ function dnaFields(raw, d, here, idPrefix) {
     if (!p) out.push(f(1, `${idPrefix}-golden-${i}-path`, "fail", `dna.goldens[${i + 1}] has no path`, "Add path: to the golden."));
     else out.push(...pathFindings(here, p, `${idPrefix}-golden-${i}`, "golden", "Fix the path, or add the golden file."));
     if (!str(g?.why)) out.push(f(6, `${idPrefix}-golden-${i}-why`, "fail", `golden "${p || `#${i + 1}`}" has no why`, "Add why: what it shows that an adjective could not."));
+    // Checked only once the path resolves to a real file: a missing or non-file path is already
+    // reported above under test 6, and is not also a leak.
+    if (scopeDirRaw && p && pathKind(here, p) === "file") {
+      const reason = leakReason(lexicalGoldens, realGoldens, here(p));
+      // A goldens/ folder that resolves outside the scope already has its own finding, which
+      // names the cause for every golden listed through it.
+      const coveredByFolder = goldensOutside && isInsideDir(lexicalGoldens, here(p));
+      if (reason && !coveredByFolder) out.push(leakFinding(idPrefix, reason, p, i, scopeDirRaw));
+    }
   });
+
+  if (scopeDirRaw) {
+    const { scope: diskScope, goldens: diskGoldens, findings: diskFindings } = disk;
+    out.push(...diskFindings);
+
+    if (diskScope) {
+      scopeMismatch(out, idPrefix, scopeDirRaw, "writer", "writer", raw.writer, diskScope.writer);
+      scopeMismatch(out, idPrefix, scopeDirRaw, "form", "form", scope.form, diskScope.form);
+      scopeMismatch(out, idPrefix, scopeDirRaw, "audience", "audience", scope.audience, diskScope.audience);
+      scopeMismatch(out, idPrefix, scopeDirRaw, "purpose", "purpose", scope.purpose, diskScope.purpose);
+    }
+
+    // With the goldens folder unreadable or somewhere else, there is nothing to compare
+    // features.json against; that folder's own finding says what to fix first.
+    if (!goldensOutside && !diskIds.has("writing-dna-goldens-missing")) {
+      const stale = featuresStaleness(join(scopeDirAbs, "features.json"), diskScope, diskGoldens);
+      if (stale === "missing") {
+        out.push(f(6, `${idPrefix}-features-missing`, "fail",
+          `writing.dna.scope_dir "${scopeDirRaw}" has no features.json (or it is not valid JSON)`,
+          `Run \`hyperspec dna measure ${scopeDirRaw}\`.`));
+      } else if (stale) {
+        out.push(f(6, `${idPrefix}-features-stale`, "fail",
+          `writing.dna.scope_dir "${scopeDirRaw}"'s features.json is stale: ${stale}`,
+          `Run \`hyperspec dna measure ${scopeDirRaw}\` again.`));
+      }
+    }
+  }
+
   return out;
 }
 

package/src/writing-template.mjs

@@ -20,6 +20,13 @@
 // materials check.station is the marking station itself, since that check is the same for every
 // writing spec: the linter enforces it, and there is nothing for the operator to decide there.
 //
+// dna.scope_dir is the one optional field shown, and it is a real `scope_dir: TODO` like every
+// other placeholder here. scope_dir is optional, so str() blanking a bare TODO would read as
+// "absent", and a spec filled in everywhere else would pass with the placeholder still sitting
+// there. Its own check closes that hole (writing-dna-scope-dir, src/writing-fields.mjs): a
+// scope_dir key that is PRESENT with a placeholder-ish value fails on its own, the same as every
+// other field here, so the skeleton can show it the same way as every other field.
+//
 // init with no --profile never imports or calls this file: template.mjs's own template() is
 // untouched, so a bare init is still byte-for-byte what it always was.
 import { scalar } from "./template.mjs";
@@ -110,6 +117,7 @@ writing:
     author: TODO
   dna:
     writer: TODO
+    scope_dir: TODO
     scope:
       form: TODO
       audience: TODO

package/examples/writing/essay/goldens/close.md

@@ -1,2 +0,0 @@
-So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
-because the first answer is the one they rehearsed and the second one is the one you came for.

package/examples/writing/essay/goldens/opening.md

@@ -1,2 +0,0 @@
-Your first one-on-one with a new report is the only meeting on your calendar where they should
-set the agenda. Everything else you run. This one you hand over.