create-pathfinder 4.2.0 → 4.3.0

package/skills/render-artifact/engine/validate/composition.mjs

@@ -0,0 +1,395 @@
+/**
+ * Layer 2 — composition. The specification is internally coherent.
+ *
+ * Everything here is a rule a schema cannot express: uniqueness across the
+ * document, references that resolve, graphs without orphans or cycles, and an
+ * answer that indexes its own options. A structurally perfect specification can
+ * still describe a lesson whose navigation lands nowhere, and that is what this
+ * layer is for.
+ *
+ * Every check walks the specification in document order, so diagnostics come
+ * back in the order a reader would meet the problems.
+ */
+
+import { diagnostic } from "./diagnostics.mjs";
+
+/**
+ * @param {object} spec a specification that passed the structural layer
+ * @returns {import("./diagnostics.mjs").Diagnostic[]}
+ */
+export function validateComposition(spec) {
+  return spec.kind === "diagram"
+    ? validateDiagramComposition(spec)
+    : validateLessonComposition(spec);
+}
+
+/**
+ * @param {object} spec a `lesson` specification that passed the structural layer
+ * @returns {import("./diagnostics.mjs").Diagnostic[]}
+ */
+function validateLessonComposition(spec) {
+  const out = [];
+  const modules = spec.lesson.modules;
+
+  /** Anchors the renderer will emit. Collisions would make two links one link. */
+  const anchors = new Map();
+
+  modules.forEach((module, m) => {
+    const modulePath = `lesson.modules[${m}]`;
+    claimAnchor(anchors, out, module.id, `${modulePath}.id`, `module "${module.title}"`);
+
+    if (module.sections.length === 0) {
+      out.push(diagnostic("composition", "module_empty", `${modulePath}.sections`,
+        "a module must carry at least one section", module.title));
+    }
+
+    module.sections.forEach((section, s) => {
+      const sectionPath = `${modulePath}.sections[${s}]`;
+      claimAnchor(anchors, out, section.id, `${sectionPath}.id`,
+        `${section.type} section in module "${module.title}"`);
+
+      if (section.type === "flow") checkFlow(section, sectionPath, out);
+      if (section.type === "quiz") checkQuiz(section, sectionPath, out);
+    });
+  });
+
+  checkModuleGraph(modules, out);
+  return out;
+}
+
+/**
+ * The `graph` topology's coherence rules.
+ *
+ * Everything here is a rule the schema cannot express, and nothing here is a
+ * rule the schema already made unrepresentable. A node belongs to at most one
+ * group because `group` is a single identifier, so there is no
+ * multiple-membership check below: preventing the state beats detecting it.
+ *
+ * Deliberately legal, and each for a reason about real systems:
+ *
+ *   self-edges      a service calling itself, a state retrying itself
+ *   cycles          retry loops, bidirectional calls
+ *   isolated nodes  something real that is not wired up yet
+ *
+ * Group nesting is the one invalid state a flat array can still represent, and
+ * a single rule covers all three of its shapes: depth greater than one, a
+ * two-group cycle, and a group parented to itself. Each of them is a group
+ * whose parent is not a root.
+ */
+function validateDiagramComposition(spec) {
+  const out = [];
+  const { nodes, edges } = spec.diagram;
+  const groups = spec.diagram.groups ?? [];
+  const paths = spec.diagram.paths ?? [];
+  const views = spec.diagram.views ?? [];
+
+  /** Every identifier the renderer turns into a DOM id, across the artifact. */
+  const anchors = new Map();
+  const nodeIds = new Map();
+  const groupIds = new Map();
+  const edgeIds = new Map();
+
+  groups.forEach((group, g) => {
+    claimAnchor(anchors, out, group.id, `diagram.groups[${g}].id`,
+      `group "${group.label}"`);
+    groupIds.set(group.id, g);
+  });
+
+  nodes.forEach((node, n) => {
+    claimAnchor(anchors, out, node.id, `diagram.nodes[${n}].id`, `node "${node.label}"`);
+    nodeIds.set(node.id, n);
+  });
+
+  edges.forEach((edge, e) => {
+    claimAnchor(anchors, out, edge.id, `diagram.edges[${e}].id`, `edge \`${edge.id}\``);
+    edgeIds.set(edge.id, e);
+  });
+
+  paths.forEach((path, p) => {
+    claimAnchor(anchors, out, path.id, `diagram.paths[${p}].id`, `path "${path.label}"`);
+  });
+
+  views.forEach((view, v) => {
+    claimAnchor(anchors, out, view.id, `diagram.views[${v}].id`, `view "${view.label}"`);
+  });
+
+  // Group membership and nesting.
+  nodes.forEach((node, n) => {
+    if (node.group !== undefined && !groupIds.has(node.group)) {
+      out.push(diagnostic("composition", "unresolved_reference",
+        `diagram.nodes[${n}].group`,
+        `node "${node.label}" belongs to \`${node.group}\`, which is not a group ` +
+        `of this diagram`, node.label));
+    }
+  });
+
+  groups.forEach((group, g) => {
+    if (group.parent === undefined) return;
+    if (!groupIds.has(group.parent)) {
+      out.push(diagnostic("composition", "unresolved_reference",
+        `diagram.groups[${g}].parent`,
+        `group "${group.label}" is inside \`${group.parent}\`, which is not a ` +
+        `group of this diagram`, group.label));
+      return;
+    }
+    const parent = groups[groupIds.get(group.parent)];
+    if (parent.parent !== undefined) {
+      out.push(diagnostic("composition", "group_parent_not_root",
+        `diagram.groups[${g}].parent`,
+        `group "${group.label}" is inside "${parent.label}", which is itself ` +
+        `inside \`${parent.parent}\`. Nesting is one level: a parent must be a ` +
+        `root. This is also what a group cycle and a self-parented group look ` +
+        `like from here.`, group.label));
+    }
+  });
+
+  // Edges.
+  const seenRelations = new Map();
+  edges.forEach((edge, e) => {
+    for (const [end, id] of [["from", edge.from], ["to", edge.to]]) {
+      if (!nodeIds.has(id)) {
+        out.push(diagnostic("composition", "unresolved_reference",
+          `diagram.edges[${e}].${end}`,
+          `edge \`${edge.id}\` runs ${end} \`${id}\`, which is not a node of this ` +
+          `diagram`, edge.id));
+      }
+    }
+
+    // The same relationship asserted twice is a modelling slip, not a second
+    // fact. Two *different* relations between one pair stay legal: an API that
+    // both calls and publishes to a thing is two claims.
+    const key = `${edge.from}\u0000${edge.to}\u0000${edge.relation}`;
+    const previous = seenRelations.get(key);
+    if (previous !== undefined) {
+      out.push(diagnostic("composition", "duplicate_edge", `diagram.edges[${e}]`,
+        `\`${edge.relation}\` from \`${edge.from}\` to \`${edge.to}\` is already ` +
+        `asserted by edge \`${previous}\`; the same relationship twice is one ` +
+        `fact written twice`, edge.id));
+    } else {
+      seenRelations.set(key, edge.id);
+    }
+  });
+
+  // Paths address edges, so the walk is checkable rather than inferred.
+  paths.forEach((path, p) => {
+    let previous = null;
+    path.edges.forEach((id, i) => {
+      if (!edgeIds.has(id)) {
+        out.push(diagnostic("composition", "unresolved_reference",
+          `diagram.paths[${p}].edges[${i}]`,
+          `path "${path.label}" walks \`${id}\`, which is not an edge of this ` +
+          `diagram`, path.label));
+        previous = null;
+        return;
+      }
+      const edge = edges[edgeIds.get(id)];
+      if (previous !== null && previous.to !== edge.from) {
+        out.push(diagnostic("composition", "path_discontinuous",
+          `diagram.paths[${p}].edges[${i}]`,
+          `path "${path.label}" goes \`${previous.id}\`, which ends at ` +
+          `\`${previous.to}\`, then \`${edge.id}\`, which starts at \`${edge.from}\`. ` +
+          `A path is a walk: each edge begins where the last one ended.`,
+          path.label));
+      }
+      previous = edge;
+    });
+  });
+
+  // Views.
+  views.forEach((view, v) => {
+    view.focus.forEach((id, i) => {
+      if (!nodeIds.has(id)) {
+        out.push(diagnostic("composition", "unresolved_reference",
+          `diagram.views[${v}].focus[${i}]`,
+          `view "${view.label}" focuses \`${id}\`, which is not a node of this ` +
+          `diagram`, view.label));
+      }
+    });
+  });
+
+  return out;
+}
+
+/** Identifiers become DOM ids and link targets, so they are unique document-wide. */
+function claimAnchor(anchors, out, id, path, subject) {
+  const previous = anchors.get(id);
+  if (previous) {
+    out.push(diagnostic("composition", "duplicate_identifier", path,
+      `\`${id}\` is already used by ${previous.subject} at ${previous.path}; ` +
+      `identifiers become link targets and must be unique across the artifact`,
+      subject));
+    return;
+  }
+  anchors.set(id, { path, subject });
+}
+
+/**
+ * A flow's first step is its entry. `next` is optional and defaults to the
+ * following step, which is what a linear flow means without saying so.
+ */
+function checkFlow(section, path, out) {
+  const steps = section.steps;
+  const index = new Map();
+
+  steps.forEach((step, i) => {
+    if (index.has(step.id)) {
+      out.push(diagnostic("composition", "duplicate_step_identifier",
+        `${path}.steps[${i}].id`,
+        `\`${step.id}\` is used twice in flow "${section.title}"`, section.title));
+      return;
+    }
+    index.set(step.id, i);
+  });
+
+  const edges = steps.map((step, i) => {
+    if (step.next === undefined) return i + 1 < steps.length ? [i + 1] : [];
+    return step.next.map((target) => index.get(target)).filter((t) => t !== undefined);
+  });
+
+  steps.forEach((step, i) => {
+    for (const target of step.next ?? []) {
+      if (!index.has(target)) {
+        out.push(diagnostic("composition", "unresolved_reference",
+          `${path}.steps[${i}].next`,
+          `step "${step.title}" leads to \`${target}\`, which is not a step of ` +
+          `flow "${section.title}"`, step.title));
+      } else if (index.get(target) === i) {
+        out.push(diagnostic("composition", "graph_cycle", `${path}.steps[${i}].next`,
+          `step "${step.title}" leads to itself`, step.title));
+      }
+    }
+  });
+
+  if (findCycle(edges)) {
+    out.push(diagnostic("composition", "graph_cycle", `${path}.steps`,
+      `flow "${section.title}" contains a cycle; a flow a reader can follow ` +
+      `has an end`, section.title));
+    return;
+  }
+
+  const reached = reachableFrom(edges, 0);
+  steps.forEach((step, i) => {
+    if (!reached.has(i)) {
+      out.push(diagnostic("composition", "orphan_step", `${path}.steps[${i}]`,
+        `step "${step.title}" is not reachable from the flow's first step`,
+        step.title));
+    }
+  });
+}
+
+function checkQuiz(section, path, out) {
+  const seen = new Set();
+  section.questions.forEach((question, q) => {
+    const questionPath = `${path}.questions[${q}]`;
+    if (seen.has(question.id)) {
+      out.push(diagnostic("composition", "duplicate_question_identifier",
+        `${questionPath}.id`,
+        `\`${question.id}\` is used twice in this quiz`, question.prompt));
+    }
+    seen.add(question.id);
+
+    if (question.answer >= question.options.length) {
+      out.push(diagnostic("composition", "answer_out_of_range",
+        `${questionPath}.answer`,
+        `answer is ${question.answer} but the question has ` +
+        `${question.options.length} option(s), indexed 0 to ` +
+        `${question.options.length - 1}`, question.prompt));
+    }
+  });
+}
+
+/**
+ * The module graph. `requires` is optional, so a flat list of modules is a
+ * legal graph with no edges — which is exactly the single-module case, and must
+ * stay legal. Orphans are therefore defined against the roots: with no edges
+ * every module is a root, so nothing is orphaned. Once edges exist, a module
+ * unreachable from every root is a module the reader can never legitimately
+ * arrive at.
+ */
+function checkModuleGraph(modules, out) {
+  const index = new Map(modules.map((module, i) => [module.id, i]));
+  const edges = modules.map(() => []);
+
+  modules.forEach((module, m) => {
+    for (const required of module.requires ?? []) {
+      if (!index.has(required)) {
+        out.push(diagnostic("composition", "unresolved_reference",
+          `lesson.modules[${m}].requires`,
+          `module "${module.title}" requires \`${required}\`, which is not a ` +
+          `module of this lesson`, module.title));
+        continue;
+      }
+      if (index.get(required) === m) {
+        out.push(diagnostic("composition", "graph_cycle",
+          `lesson.modules[${m}].requires`,
+          `module "${module.title}" requires itself`, module.title));
+        continue;
+      }
+      edges[index.get(required)].push(m);
+    }
+  });
+
+  if (findCycle(edges)) {
+    out.push(diagnostic("composition", "graph_cycle", "lesson.modules",
+      "the module graph contains a cycle; prerequisites that lead back to " +
+      "themselves cannot be satisfied in any order"));
+    return;
+  }
+
+  const roots = modules
+    .map((module, m) => ({ module, m }))
+    .filter(({ module }) => (module.requires ?? []).length === 0)
+    .map(({ m }) => m);
+
+  const reached = new Set();
+  for (const root of roots) for (const node of reachableFrom(edges, root)) reached.add(node);
+
+  modules.forEach((module, m) => {
+    if (!reached.has(m)) {
+      out.push(diagnostic("composition", "orphan_module", `lesson.modules[${m}]`,
+        `module "${module.title}" is not reachable from any module without ` +
+        `prerequisites`, module.title));
+    }
+  });
+}
+
+/** Depth-first reachability. Node order is the adjacency order, never a Set's. */
+function reachableFrom(edges, start) {
+  const seen = new Set();
+  const stack = [start];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (seen.has(node)) continue;
+    seen.add(node);
+    for (const next of edges[node]) stack.push(next);
+  }
+  return seen;
+}
+
+/** Iterative depth-first cycle detection over an adjacency list. */
+function findCycle(edges) {
+  const WHITE = 0, GREY = 1, BLACK = 2;
+  const colour = edges.map(() => WHITE);
+
+  for (let start = 0; start < edges.length; start += 1) {
+    if (colour[start] !== WHITE) continue;
+    const stack = [{ node: start, cursor: 0 }];
+    colour[start] = GREY;
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame.cursor >= edges[frame.node].length) {
+        colour[frame.node] = BLACK;
+        stack.pop();
+        continue;
+      }
+      const next = edges[frame.node][frame.cursor];
+      frame.cursor += 1;
+      if (colour[next] === GREY) return true;
+      if (colour[next] === WHITE) {
+        colour[next] = GREY;
+        stack.push({ node: next, cursor: 0 });
+      }
+    }
+  }
+  return false;
+}

package/skills/render-artifact/engine/validate/diagnostics.mjs

@@ -0,0 +1,83 @@
+/**
+ * The one diagnostic shape, and the layers that produce it.
+ *
+ * Four layers, each supporting a distinct claim and reported distinctly. A
+ * caller that collapses them into "valid / invalid" throws away the only thing
+ * that makes the result honest: *which* claim was checked. Delivery validation
+ * proves the artifact was checked; it never proves the artifact looks correct.
+ */
+
+/** The layers, in the order they run. Later layers assume earlier ones passed. */
+export const LAYERS = Object.freeze(["structural", "composition", "evidence", "delivery"]);
+
+/** What each layer's passing result does and does not entitle a caller to say. */
+export const LAYER_CLAIMS = Object.freeze({
+  structural: "the specification satisfies its schema",
+  composition: "identifiers, references, graphs, and answers are coherent",
+  evidence: "every citation resolves at the declared commit",
+  delivery: "the artifact was rendered, digested, and committed atomically",
+});
+
+/**
+ * @typedef {object} Diagnostic
+ * @property {"structural"|"composition"|"evidence"|"delivery"} layer
+ * @property {string} code     stable, greppable, never localised
+ * @property {string} path     where in the specification, in reader terms
+ * @property {string} message  what is wrong
+ * @property {string} [subject] the thing being talked about, named by title or id
+ */
+
+/** @returns {Diagnostic} */
+export function diagnostic(layer, code, path, message, subject) {
+  const result = { layer, code, path, message };
+  if (subject !== undefined) result.subject = subject;
+  return result;
+}
+
+/**
+ * Property names that are presentation control, rejected rather than ignored.
+ *
+ * `additionalProperties: false` already rejects every one of these — this list
+ * exists to change the *diagnostic*, not the outcome. "`color` is not part of
+ * this contract" is true but unhelpful; a producer who wrote it believed
+ * presentation was theirs to set, and the error should say so. Matched on the
+ * property name at any depth, because that is the level at which the mistake
+ * is made.
+ */
+export const PRESENTATION_CONTROLS = Object.freeze(new Set([
+  "align", "background", "background_color", "backgroundColor", "border",
+  "class", "class_name", "className", "color", "colors", "colour", "column",
+  "coordinates", "css", "font", "font_family", "font_size", "fontSize",
+  "gap", "grid", "height", "html", "icon", "layout", "margin", "padding",
+  "position", "preset", "size", "spacing", "style", "styles", "template",
+  "theme", "theme_default", "variant", "width", "x", "y", "z_index", "zIndex",
+
+  // The drawing controls. A producer describing a diagram reaches for these
+  // first, and every one of them is the renderer deciding where something goes
+  // rather than the producer saying what it is. `emphasis` belongs here for a
+  // subtler reason than the rest: it is not a coordinate, but it is the
+  // producer setting how much ink a thing gets. Emphasis is derived from
+  // authored paths — say why it matters, and the renderer decides how loud.
+  "anchor", "animation", "col", "cols", "dot", "edge_style", "emphasis",
+  "importance", "lane", "lanes", "offset", "orientation", "pos", "rank",
+  "route", "routing", "rx", "ry", "shape", "side", "stage", "stroke", "svg",
+  "viewbox", "viewBox", "weight", "x1", "x2", "y1", "y2", "zoom",
+]));
+
+/** Is this property name one a producer must never control? */
+export function isPresentationControl(name) {
+  return PRESENTATION_CONTROLS.has(name);
+}
+
+/**
+ * Group diagnostics by layer, preserving order within each.
+ * Returned as an array in `LAYERS` order so reporting never depends on
+ * insertion or hash order.
+ */
+export function byLayer(diagnostics) {
+  return LAYERS.map((layer) => ({
+    layer,
+    claim: LAYER_CLAIMS[layer],
+    diagnostics: diagnostics.filter((d) => d.layer === layer),
+  }));
+}

package/skills/render-artifact/engine/validate/diagram-parts.mjs

@@ -0,0 +1,68 @@
+/**
+ * Every place a diagram may carry evidence, in document order, named the way a
+ * reader would name it.
+ *
+ * Two layers need this list and they need it to agree. The structural layer
+ * refuses a citation in a specification that has no source to resolve it
+ * against; the evidence layer requires citations of a `derived` diagram's nodes,
+ * edges and claim-bearing prose. If each walked the specification itself the two
+ * would drift — one would learn about a new place evidence can live and the
+ * other would not — and the drift would show up as a rule that silently stopped
+ * applying to part of the document.
+ *
+ * So the walk is defined once, here, and both layers read it.
+ *
+ * `claim` is the distinction the provenance contract rests on for a group, path
+ * or view: a label is a name, and a name is not a factual assertion that needs
+ * backing. `summary` and `note` are prose that asserts something, so they are
+ * what makes one of these claim-bearing. A node or an edge is claim-bearing by
+ * existing at all — saying a component is there, or that two things relate, is
+ * the assertion — which is why `claim` is not what decides their requirement.
+ *
+ * Imports nothing. It is walked by a layer that spawns Git and by one that does
+ * not, and it has no business knowing which.
+ */
+
+/**
+ * @typedef {object} EvidenceSite
+ * @property {"group"|"node"|"edge"|"path"|"view"} role  what kind of thing it is
+ * @property {string} subject  the thing, named for a diagnostic
+ * @property {string} path     where its evidence lives, in specification terms
+ * @property {object[]} evidence  the citations present, possibly none
+ * @property {boolean} claim   whether it asserts something beyond its own name
+ */
+
+/**
+ * @param {object} diagram a `diagram` body that passed schema validation
+ * @returns {EvidenceSite[]} in document order
+ */
+export function diagramEvidenceSites(diagram) {
+  const sites = [];
+
+  const site = (role, subject, path, holder, claim) => {
+    sites.push({ role, subject, path, evidence: holder.evidence ?? [], claim });
+  };
+
+  // Groups first, then nodes, edges, paths and views. This order is the order
+  // citations are reported in, so it is fixed rather than convenient.
+  (diagram.groups ?? []).forEach((group, g) => {
+    site("group", `group "${group.label}"`, `diagram.groups[${g}].evidence`,
+      group, group.summary !== undefined);
+  });
+  diagram.nodes.forEach((node, n) => {
+    site("node", `node "${node.label}"`, `diagram.nodes[${n}].evidence`, node, true);
+  });
+  diagram.edges.forEach((edge, e) => {
+    site("edge", `edge \`${edge.id}\``, `diagram.edges[${e}].evidence`, edge, true);
+  });
+  (diagram.paths ?? []).forEach((path, p) => {
+    site("path", `path "${path.label}"`, `diagram.paths[${p}].evidence`,
+      path, path.note !== undefined);
+  });
+  (diagram.views ?? []).forEach((view, v) => {
+    site("view", `view "${view.label}"`, `diagram.views[${v}].evidence`,
+      view, view.note !== undefined);
+  });
+
+  return sites;
+}