create-evda 0.1.1 → 0.1.3

package/lib/kinds.mjs

@@ -0,0 +1,301 @@
+// The six person-layer kinds (Spec 07, section 2): note, person-profile, course, piece, rule,
+// hypothesis. A folder's `folder.evda.json` names its type; an entry in that folder is one of these.
+//
+// The shape of each kind is its SCHEMA in the reference vault, copied here as
+// lib/kinds.schema.json by scripts/build-kinds.mjs (with a drift check), and read by `parseShape`
+// the way the substrate's generated parsers read it: first problem wins, same path, same words.
+// The cross-field rules are a second implementation of common/src/<kind>.ts, because this package
+// imports nothing from the workspace. `common/src/person-kinds.vectors.json` is what the two agree
+// about, and test/kinds.test.mjs runs every vector here and requires exactly its problems.
+//
+// Entry files: a `.json` or `.yaml` file holding one entity, or a markdown file whose frontmatter
+// carries `kind:`. For a note in markdown, the body is the words when the frontmatter has none.
+
+import { readFileSync } from "node:fs";
+import { parseYaml } from "./yaml.mjs";
+
+const SCHEMAS = JSON.parse(readFileSync(new URL("./kinds.schema.json", import.meta.url), "utf8")).kinds;
+
+export const PERSON_KINDS = Object.keys(SCHEMAS);
+
+// folder.evda.json `type` -> entity kind. `record` is the Spec 07 name for the owner's words; the
+// substrate's own `record` kind is a row of tabular data, so the entity is `note`.
+export const KIND_FOR_TYPE = { record: "note", person: "person-profile", course: "course", piece: "piece", rule: "rule", hypothesis: "hypothesis" };
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const absent = (v) => v === undefined || v === null;
+const EXPECT = { string: "expected string", "iso-date": "expected string", enum: "expected string", number: "expected number", boolean: "expected boolean", object: "expected object", array: "expected array" };
+
+class Shape extends Error {}
+
+function field(value, f, path) {
+  switch (f.type) {
+    case "string":
+    case "iso-date":
+      if (typeof value !== "string") throw new Shape(`${path}: expected string`);
+      return value;
+    case "enum":
+      if (typeof value !== "string") throw new Shape(`${path}: expected string`);
+      if (!f.values.includes(value)) throw new Shape(`${path}: expected one of ${f.values.join("|")}`);
+      return value;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new Shape(`${path}: expected number`);
+      return value;
+    case "boolean":
+      if (typeof value !== "boolean") throw new Shape(`${path}: expected boolean`);
+      return value;
+    case "array": {
+      if (!Array.isArray(value)) throw new Shape(`${path}: expected array`);
+      if (f.minItems !== undefined && value.length < f.minItems) throw new Shape(`${path}: expected at least ${f.minItems} items`);
+      if (f.maxItems !== undefined && value.length > f.maxItems) throw new Shape(`${path}: expected at most ${f.maxItems} items`);
+      return value.map((v, i) => field(v, f.items, `${path}[${i}]`));
+    }
+    case "object": {
+      if (!isObject(value)) throw new Shape(`${path}: expected object`);
+      if (!f.fields) return value;
+      return fields(value, f.fields, path, f.extras === "passthrough");
+    }
+    default:
+      throw new Shape(`${path}: field type ${f.type} is not one this tool reads`);
+  }
+}
+
+function fields(root, decl, path, passthrough) {
+  const out = passthrough ? { ...root } : {};
+  for (const [name, f] of Object.entries(decl)) {
+    const v = root[name];
+    if (absent(v)) {
+      if (f.default !== undefined) out[name] = f.default;
+      else if (f.optional) delete out[name];
+      else throw new Shape(`${path}.${name}: ${EXPECT[f.type] ?? "expected a value"}`);
+      continue;
+    }
+    out[name] = field(v, f, `${path}.${name}`);
+  }
+  return out;
+}
+
+// The shape parser: returns { dto } or { problem }, as the generated parser would throw it.
+export function parseShape(kind, raw) {
+  const schema = SCHEMAS[kind];
+  if (!schema) return { problem: `$.kind: "${kind}" is not a person-layer kind (${PERSON_KINDS.join(", ")})` };
+  try {
+    if (!isObject(raw)) throw new Shape("$: expected object");
+    const head = {};
+    if (typeof raw.id !== "string") throw new Shape("$.id: expected string");
+    head.id = raw.id;
+    if (typeof raw.kind !== "string") throw new Shape("$.kind: expected string");
+    if (raw.kind !== kind) throw new Shape(`$.kind: expected '${kind}'`);
+    head.kind = raw.kind;
+    if (typeof raw.schemaVersion !== "string") throw new Shape("$.schemaVersion: expected string");
+    head.schemaVersion = raw.schemaVersion;
+    return { dto: { ...head, ...fields(raw, schema.fields, "$", false) } };
+  } catch (e) {
+    if (e instanceof Shape) return { problem: e.message };
+    throw e;
+  }
+}
+
+// ---- cross-field rules, mirroring common/src/person-kind-check.ts and common/src/<kind>.ts ----
+
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+export function isDay(value) {
+  if (typeof value !== "string") return false;
+  const m = DAY.exec(value);
+  if (!m) return false;
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+  return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
+}
+const dayProblem = (path, v) => (isDay(v) ? null : `${path}: "${String(v)}" is not a day. Write YYYY-MM-DD.`);
+const emptyProblem = (path, v, what) => (typeof v === "string" && v.trim() !== "" ? null : `${path}: is empty. ${what}`);
+const hasText = (s) => typeof s === "string" && s.trim() !== "";
+function duplicates(ids) {
+  const seen = new Set();
+  const twice = new Set();
+  for (const id of ids) (seen.has(id) ? twice : seen).add(id);
+  return [...twice];
+}
+
+const WORD_NUMBER = "one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|dozen|once|twice";
+const NUMBER = `(?:\\d+(?:\\.\\d+)?|${WORD_NUMBER})`;
+const PATTERNS = [
+  /\b(?:streak|streaks|in a row|consecutive)\b/i,
+  new RegExp(`\\b(?:at most|at least|no more than|no fewer than|no less than|more than|fewer than|less than|up to|maximum of|minimum of|limit of|cap of|budget of|threshold of)\\s+(?:a\\s+)?${NUMBER}\\b`, "i"),
+  new RegExp(`\\b${NUMBER}\\s+or\\s+(?:more|fewer|less)\\b`, "i"),
+  new RegExp(`\\b${NUMBER}\\b[^.;:]{0,30}?\\b(?:times?|days?|nights?|weeks?|months?|hours?|minutes?)\\b`, "i"),
+  new RegExp(`\\b${NUMBER}\\s+(?:in|out of)\\s+${NUMBER}\\b`, "i"),
+  new RegExp(`\\b(?:once|twice)\\s+(?:a|an|per|each|every)\\b`, "i"),
+  new RegExp(`\\b${NUMBER}\\s+(?:a|an|per)\\s+(?:day|night|week|month|year)\\b`, "i"),
+  /\d\s*%|\bpercent\b/i,
+];
+
+// The words in a rule's statement that set a threshold, a count or a streak, or null.
+export function thresholdIn(statement) {
+  for (const p of PATTERNS) {
+    const m = p.exec(statement);
+    if (m) return m[0];
+  }
+  return null;
+}
+
+const TIME = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
+const CHECKS = {
+  note(dto, { owner }) {
+    const out = [];
+    const push = (p) => p && out.push(p);
+    push(dayProblem("$.date", dto.date));
+    push(emptyProblem("$.words", dto.words, "A note holds the owner's words, and an empty one holds nothing."));
+    if (dto.author !== owner) out.push(`$.author: "${dto.author}" is not the owner "${owner}". A note holds the owner's words only; anyone else's account belongs in their own record.`);
+    return out;
+  },
+
+  "person-profile"(dto, { owner }) {
+    const out = [];
+    const push = (p) => p && out.push(p);
+    const obs = dto.observations;
+    const byId = new Map(obs.map((o) => [o.id, o]));
+    for (const id of duplicates(obs.map((o) => o.id))) out.push(`$.observations: id "${id}" is used more than once. supersededBy points at an id, so each must name one observation.`);
+    obs.forEach((o, i) => {
+      const at = `$.observations[${i}]`;
+      push(dayProblem(`${at}.since`, o.since));
+      push(emptyProblem(`${at}.text`, o.text, "An observation says something."));
+      if (o.supersededBy !== undefined) {
+        const next = byId.get(o.supersededBy);
+        if (o.supersededBy === o.id) out.push(`${at}.supersededBy: names itself. An observation is superseded by a later one.`);
+        else if (!next) out.push(`${at}.supersededBy: names "${o.supersededBy}", which is not an observation in this profile.`);
+        else if (next.since < o.since) out.push(`${at}.supersededBy: names "${next.id}", dated ${next.since}, which is before this one (${o.since}). A later observation supersedes an earlier one.`);
+        else {
+          const seen = new Set([o.id]);
+          let cur = next;
+          while (cur) {
+            if (seen.has(cur.id)) { out.push(`${at}.supersededBy: the chain from "${o.id}" loops back to "${cur.id}".`); break; }
+            seen.add(cur.id);
+            cur = cur.supersededBy !== undefined ? byId.get(cur.supersededBy) : undefined;
+          }
+        }
+      }
+      if (o.quote) {
+        push(emptyProblem(`${at}.quote.words`, o.quote.words, "A quote holds words."));
+        if (o.quote.said !== undefined) push(dayProblem(`${at}.quote.said`, o.quote.said));
+        if (o.quote.provenance === "owner" && o.quote.by !== owner) out.push(`${at}.quote: marked as the owner's words, but by is "${o.quote.by}", not the owner "${owner}". Words someone else produced are provenance agent.`);
+        if (o.quote.provenance === "agent" && o.quote.by === owner) out.push(`${at}.quote: marked as an agent's summary, but by is the owner "${owner}". The owner's own words are provenance owner.`);
+      }
+    });
+    return out;
+  },
+
+  course(dto) {
+    const out = [];
+    const push = (p) => p && out.push(p);
+    (dto.sessions ?? []).forEach((s, i) => {
+      const at = `$.sessions[${i}]`;
+      const startOk = TIME.test(s.start);
+      const endOk = TIME.test(s.end);
+      if (!startOk) out.push(`${at}.start: "${s.start}" is not a time. Write HH:MM, 24-hour.`);
+      if (!endOk) out.push(`${at}.end: "${s.end}" is not a time. Write HH:MM, 24-hour.`);
+      if (startOk && endOk && s.end <= s.start) out.push(`${at}: ends at ${s.end}, which is not after it starts (${s.start}).`);
+      for (const d of duplicates(s.days)) out.push(`${at}.days: "${d}" is listed more than once.`);
+    });
+    const assignments = dto.assignments ?? [];
+    for (const id of duplicates(assignments.map((a) => a.id))) out.push(`$.assignments: id "${id}" is used more than once.`);
+    assignments.forEach((a, i) => { if (a.due !== undefined) push(dayProblem(`$.assignments[${i}].due`, a.due)); });
+    const ids = new Set(assignments.map((a) => a.id));
+    const deadlines = dto.deadlines ?? [];
+    for (const id of duplicates(deadlines.map((d) => d.id))) out.push(`$.deadlines: id "${id}" is used more than once.`);
+    deadlines.forEach((d, i) => {
+      push(dayProblem(`$.deadlines[${i}].at`, d.at));
+      if (d.assignment !== undefined && !ids.has(d.assignment)) out.push(`$.deadlines[${i}].assignment: names "${d.assignment}", which is not an assignment in this course.`);
+    });
+    return out;
+  },
+
+  piece(dto) {
+    const out = [];
+    const release = dto.release;
+    if (release?.date !== undefined) { const p = dayProblem("$.release.date", release.date); if (p) out.push(p); }
+    if (dto.status === "published" && release?.date === undefined) out.push("$.release.date: is missing. A published piece says the day it went out.");
+    if (dto.status === "idea" && release !== undefined) out.push("$.release: is present on an idea. An idea has not been released; set status to draft, published or retired first.");
+    return out;
+  },
+
+  rule(dto) {
+    const out = [];
+    const push = (p) => p && out.push(p);
+    push(emptyProblem("$.statement", dto.statement, "A rule says something."));
+    const number = thresholdIn(dto.statement);
+    if (number !== null) out.push(`$.statement: sets a threshold, a count or a streak ("${number}"). A rule is never a number about a person's life; put any counting in the check, as a measurement.`);
+    push(dayProblem("$.since", dto.since));
+    push(emptyProblem("$.from.words", dto.from.words, "A rule carries the correction that made it, verbatim."));
+    push(emptyProblem("$.check", dto.check, "A rule is a test, and a test says how it could come back false."));
+    if (dto.status === "revised" && dto.revisedBy === undefined) out.push("$.revisedBy: is missing. A revised rule names the rule that replaced it.");
+    if (dto.status !== "revised" && dto.revisedBy !== undefined) out.push(`$.revisedBy: is present on a ${dto.status} rule. Only a revised rule names its replacement.`);
+    if (dto.revisedBy !== undefined && dto.revisedBy === dto.id) out.push("$.revisedBy: names this rule. A revision is a new rule.");
+    if (dto.status === "retired" && (dto.retiredBecause === undefined || dto.retiredBecause.trim() === "")) out.push("$.retiredBecause: is missing. A retired rule is kept with the reason it stopped fitting.");
+    if (dto.status !== "retired" && dto.retiredBecause !== undefined) out.push(`$.retiredBecause: is present on a ${dto.status} rule.`);
+    return out;
+  },
+
+  hypothesis(dto) {
+    const out = [];
+    const push = (p) => p && out.push(p);
+    push(emptyProblem("$.claim", dto.claim, "A hypothesis is a claim stated so it could be wrong."));
+    push(emptyProblem("$.falsifier", dto.falsifier, "Say what would kill the claim, or say here that nothing yet can."));
+    push(dayProblem("$.raised.date", dto.raised.date));
+    if (dto.due !== undefined) push(dayProblem("$.due", dto.due));
+    if (dto.origin.kind === "reasoning" && dto.raised.by !== "agent") out.push("$.origin: is reasoning, but the owner raised this claim. Reasoning is an origin for an agent-raised claim only; the owner's claim has their words (quote) or a path.");
+    push(emptyProblem("$.origin.text", dto.origin.text, "An origin names the quote, the path, or the reasoning."));
+    (dto.pushback ?? []).forEach((p, i) => {
+      push(dayProblem(`$.pushback[${i}].date`, p.date));
+      push(emptyProblem(`$.pushback[${i}].words`, p.words, "Pushback is the owner's words, verbatim."));
+    });
+    (dto.evidence ?? []).forEach((e, i) => {
+      push(dayProblem(`$.evidence[${i}].date`, e.date));
+      push(emptyProblem(`$.evidence[${i}].source`, e.source, "Evidence names where it was found."));
+    });
+    if ((dto.status === "standing" || dto.status === "falsified") && !hasText(dto.outcome)) {
+      out.push(`$.outcome: is missing on a ${dto.status} claim. ${dto.status === "standing" ? "Standing means tested and survived" : "Falsified means tested and failed"}, so it says what the test found.`);
+    }
+    if (dto.status === "open" && hasText(dto.outcome)) out.push("$.outcome: is written on an open claim. An outcome is written only when the test resolves.");
+    if (dto.status === "refined" && dto.supersededBy === undefined) out.push("$.supersededBy: is missing on a refined claim. A refinement is a new entry, and this one names it.");
+    if (dto.supersededBy !== undefined && dto.supersededBy === dto.id) out.push("$.supersededBy: names this claim. A refinement is a new entry.");
+    if (dto.supersedes !== undefined && dto.supersedes === dto.id) out.push("$.supersedes: names this claim. A refinement is a new entry.");
+    return out;
+  },
+};
+
+// Read one entry of a person-layer kind. Returns { dto, problems }: problems is the shape parser's
+// one message, or every cross-field problem; dto is null when the shape failed. `owner` is the
+// record's holder id, which note and person-profile need.
+export function readEntry(kind, raw, { owner } = {}) {
+  const { dto, problem } = parseShape(kind, raw);
+  if (problem) return { dto: null, problems: [problem] };
+  return { dto, problems: CHECKS[kind](dto, { owner }) };
+}
+
+// Whether a claim comes back on its own: only when `parked` was set false. A due date never does.
+export const hypothesisSurfaces = (dto) => dto.parked === false;
+
+// An entry file's contents as an object, or { error } when the file cannot be read as one, or null
+// when the file is not an entry at all (markdown with no `kind:` in its frontmatter).
+export function entryFromFile(name, text) {
+  if (/\.json$/i.test(name)) {
+    try { return { raw: JSON.parse(text) }; } catch (e) { return { error: `is not valid JSON (${e.message}).` }; }
+  }
+  if (/\.ya?ml$/i.test(name)) {
+    try { return { raw: parseYaml(text) }; } catch (e) { return { error: e.message }; }
+  }
+  if (/\.md$/i.test(name)) {
+    const lines = text.split("\n");
+    if (lines[0] !== "---") return null;
+    const end = lines.indexOf("---", 1);
+    if (end === -1) return null;
+    let front;
+    try { front = parseYaml(lines.slice(1, end).join("\n")); } catch (e) { return /^kind:/m.test(lines.slice(1, end).join("\n")) ? { error: e.message } : null; }
+    if (!isObject(front) || front.kind === undefined) return null;
+    const raw = { ...front };
+    if (raw.kind === "note" && absent(raw.words)) raw.words = lines.slice(end + 1).join("\n").trim();
+    return { raw };
+  }
+  return null;
+}