@patterkit/core 0.10.1 → 0.11.0

package/dist/index.cjs

@@ -141,10 +141,73 @@ function walkContainer(children, selector, out) {
 }
 
 // src/validate.ts
-function choiceLoopsBack(choice, ...targets) {
-  const back = new Set(targets.filter((s) => typeof s === "string" && s.length > 0));
-  const hits = (n) => n.type === "snippet" ? !!n.jump && back.has(n.jump.to) : (n.children ?? []).some(hits);
-  return (choice.children ?? []).some(hits);
+function jumpGraph(scenes, start) {
+  const firstBlock = /* @__PURE__ */ new Map();
+  const blocks = /* @__PURE__ */ new Set();
+  const wellFormed = scenes.filter((sc) => typeof sc?.id === "string" && Array.isArray(sc.blocks));
+  for (const scene of wellFormed) {
+    const first = scene.blocks[0];
+    if (typeof first?.id === "string") firstBlock.set(scene.id, first.id);
+    for (const b of scene.blocks) if (typeof b?.id === "string") blocks.add(b.id);
+  }
+  const resolve = (to) => blocks.has(to) ? to : firstBlock.get(to);
+  const next = /* @__PURE__ */ new Map();
+  const jumpedInto = /* @__PURE__ */ new Set();
+  const calledInto = /* @__PURE__ */ new Set();
+  for (const scene of wellFormed) {
+    for (const block of scene.blocks) {
+      if (typeof block?.id !== "string" || !Array.isArray(block.children)) continue;
+      const out = /* @__PURE__ */ new Set();
+      for (const to of jumpTargets(block.children, resolve)) {
+        out.add(to.block);
+        (to.call ? calledInto : jumpedInto).add(to.block);
+      }
+      next.set(block.id, out);
+    }
+  }
+  const begin = start ? start.block !== void 0 && blocks.has(start.block) ? start.block : firstBlock.get(start.scene) : void 0;
+  const fallbackBegin = wellFormed[0] ? firstBlock.get(wellFormed[0].id) : void 0;
+  if (begin ?? fallbackBegin) jumpedInto.add(begin ?? fallbackBegin);
+  return { next, jumpedInto, calledInto, resolve };
+}
+function jumpTargets(nodes, resolve) {
+  const out = [];
+  (0, import_model.walkNodes)(nodes.filter((n) => n && typeof n === "object"), (n) => {
+    if (n.type !== "snippet" || !n.jump || typeof n.jump.to !== "string" || n.jump.to === "END") return;
+    const block = resolve(n.jump.to);
+    if (block !== void 0) out.push({ block, call: n.jump.mode === "call" });
+  });
+  return out;
+}
+function leadsBack(graph, nodes, home) {
+  const queue = jumpTargets(nodes, graph.resolve).map((t) => t.block);
+  const seen = /* @__PURE__ */ new Set();
+  while (queue.length > 0) {
+    const b = queue.shift();
+    if (b === home) return true;
+    if (seen.has(b)) continue;
+    seen.add(b);
+    for (const n of graph.next.get(b) ?? []) queue.push(n);
+  }
+  return false;
+}
+function whatFollowsChoices(children) {
+  const out = /* @__PURE__ */ new Map();
+  const visit = (nodes, inOrder, after, once, options) => {
+    nodes.forEach((n, i) => {
+      if (!n || typeof n !== "object") return;
+      const inOnce = once || options && n.sticky !== true;
+      if (n.type !== "group") return;
+      const follows = inOrder ? [...nodes.slice(i + 1), ...after] : after;
+      if (n.selector === "choice") out.set(n.id, { follows, once });
+      if (Array.isArray(n.children)) visit(n.children, (n.selector ?? "run") === "run", follows, inOnce, n.selector === "choice");
+    });
+  };
+  visit(children, true, [], false, false);
+  return out;
+}
+function carriesOn(nodes) {
+  return nodes.some((n) => !isContentlessNode(n) && !(n.type === "snippet" && (n.beats?.length ?? 0) === 0 && n.jump?.to === "END"));
 }
 function isContentlessNode(node) {
   if (node.type === "snippet") return (node.beats?.length ?? 0) === 0 && !node.jump;
@@ -211,6 +274,7 @@ function validateProject(input) {
   const addressable = /* @__PURE__ */ new Set();
   const sceneGameIds = /* @__PURE__ */ new Map();
   const jumps = [];
+  const graph = jumpGraph(Array.isArray(scenes) ? scenes : [], project.start);
   const castNames = new Set((project.cast ?? []).map((c) => c.name));
   const qualifierIds = project.qualifiers === void 0 || Array.isArray(project.qualifiers) ? new Set((0, import_model.projectQualifiers)(project).flatMap((q) => isQualifierEntry(q) && typeof q.gameId === "string" ? [q.gameId] : [])) : null;
   const checkPad = (value, what, id) => {
@@ -361,6 +425,7 @@ function validateProject(input) {
           message: `${n.type} '${n.id}' in block '${block.id}' never runs: snippet '${n.jumper}' before it always jumps ${where2}`
         });
       }
+      const afterChoice = whatFollowsChoices(block.children);
       (0, import_model.walkNodes)(block.children, (node) => {
         const inBlock = `block '${block.id}'`;
         checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
@@ -402,10 +467,27 @@ function validateProject(input) {
               issues.push({ code: "multiple-fallbacks", message: `choice '${node.id}' in ${inBlock} has ${fallbacks} fallback options (at most one allowed)`, id: node.id });
             }
             const hasUnconditionalEscape = (node.children ?? []).some((opt) => !opt.condition);
-            if ((node.children?.length ?? 0) > 0 && !hasUnconditionalEscape) {
-              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} has no unconditional option or fallback - it runs dry (falls through) if every condition fails`, id: node.id, severity: "warning" });
-            } else if (!hasSticky && fallbacks === 0 && choiceLoopsBack(node, block.id, bgid, scene.id, sgid)) {
-              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} can be re-entered but every option is once-only with no fallback - it will run dry`, id: node.id, severity: "warning" });
+            const { follows, once } = afterChoice.get(node.id) ?? { follows: [], once: false };
+            const noGuaranteedPath = (node.children?.length ?? 0) > 0 && !hasUnconditionalEscape;
+            const exhausts = !noGuaranteedPath && !once && !hasSticky && fallbacks === 0 && leadsBack(graph, [...node.children ?? [], ...follows], block.id);
+            if (noGuaranteedPath || exhausts) {
+              const why = noGuaranteedPath ? "has no unconditional option or fallback, so it runs dry if every condition fails" : "can be played again but every option is once-only with no fallback, so it runs dry once they're used";
+              const returns = graph.calledInto.has(block.id) && !graph.jumpedInto.has(block.id);
+              if (carriesOn(follows) || returns) {
+                issues.push({
+                  code: "choice-can-empty",
+                  severity: "info",
+                  id: node.id,
+                  message: `choice '${node.id}' in ${inBlock} ${why}; play then carries on ${returns && !carriesOn(follows) ? "where the block was called from" : "after it"}`
+                });
+              } else {
+                issues.push({
+                  code: "choice-ends-dry",
+                  severity: "warning",
+                  id: node.id,
+                  message: `choice '${node.id}' in ${inBlock} ${why}, and nothing follows it, so the dialogue would end there; add a fallback to say what happens then`
+                });
+              }
             }
           }
           return;

package/dist/index.d.cts

@@ -26,13 +26,14 @@ interface StringifyOptions {
 declare function canonicalStringify(value: unknown, opts?: StringifyOptions): string;
 
 interface ValidationIssue {
-    code: "duplicate-id" | "missing-id" | "malformed-node" | "missing-name" | "empty-scene" | "empty-snippet" | "empty-container" | "dangling-jump" | "jump-into-non-addressable" | "invalid-gameid" | "duplicate-gameid" | "unknown-character" | "unknown-qualifier" | "invalid-qualifier" | "invalid-pad" | "pad-overlaps-seam" | "prompt-pad-without-beat" | "qualifier-without-speaker" | "invalid-speaker-label" | "unused-speaker-label" | "invalid-temporary" | "invalid-declaration" | "invalid-status-ladder" | "invalid-locales" | "invalid-captions" | "missing-prompt" | "invalid-prompt" | "multiple-fallbacks" | "choice-can-empty" | "invalid-status-value" | "unknown-doc-class" | "invalid-tag" | "invalid-gamedata-field" | "invalid-gamedata-value" | "jump-cycle" | "unreachable-after-jump" | "no-start" | "dangling-start";
+    code: "duplicate-id" | "missing-id" | "malformed-node" | "missing-name" | "empty-scene" | "empty-snippet" | "empty-container" | "dangling-jump" | "jump-into-non-addressable" | "invalid-gameid" | "duplicate-gameid" | "unknown-character" | "unknown-qualifier" | "invalid-qualifier" | "invalid-pad" | "pad-overlaps-seam" | "prompt-pad-without-beat" | "qualifier-without-speaker" | "invalid-speaker-label" | "unused-speaker-label" | "invalid-temporary" | "invalid-declaration" | "invalid-status-ladder" | "invalid-locales" | "invalid-captions" | "missing-prompt" | "invalid-prompt" | "multiple-fallbacks" | "choice-can-empty" | "choice-ends-dry" | "invalid-status-value" | "unknown-doc-class" | "invalid-tag" | "invalid-gamedata-field" | "invalid-gamedata-value" | "jump-cycle" | "unreachable-after-jump" | "no-start" | "dangling-start";
     message: string;
     /** Id of the offending node/beat, where applicable. */
     id?: string;
     /** Absent means an error: the project should not be built. A warning still compiles and plays (a choice
-     *  that can run dry gathers or falls through at runtime), and every front end shows it as one. */
-    severity?: "warning";
+     *  that can run dry and end the dialogue), and every front end shows it as one. An `info` is a note, not a
+     *  problem (a choice that can run dry and then carry on, which is often meant): shown, never counted. */
+    severity?: "warning" | "info";
     /** A quality gameData value off its field's ladder (a deleted or renamed stage, most often): the field, the
      *  value, and the stages to offer in its place, in ladder order. An editor's quick fix reads it. */
     offLadder?: {

package/dist/index.d.ts

@@ -26,13 +26,14 @@ interface StringifyOptions {
 declare function canonicalStringify(value: unknown, opts?: StringifyOptions): string;
 
 interface ValidationIssue {
-    code: "duplicate-id" | "missing-id" | "malformed-node" | "missing-name" | "empty-scene" | "empty-snippet" | "empty-container" | "dangling-jump" | "jump-into-non-addressable" | "invalid-gameid" | "duplicate-gameid" | "unknown-character" | "unknown-qualifier" | "invalid-qualifier" | "invalid-pad" | "pad-overlaps-seam" | "prompt-pad-without-beat" | "qualifier-without-speaker" | "invalid-speaker-label" | "unused-speaker-label" | "invalid-temporary" | "invalid-declaration" | "invalid-status-ladder" | "invalid-locales" | "invalid-captions" | "missing-prompt" | "invalid-prompt" | "multiple-fallbacks" | "choice-can-empty" | "invalid-status-value" | "unknown-doc-class" | "invalid-tag" | "invalid-gamedata-field" | "invalid-gamedata-value" | "jump-cycle" | "unreachable-after-jump" | "no-start" | "dangling-start";
+    code: "duplicate-id" | "missing-id" | "malformed-node" | "missing-name" | "empty-scene" | "empty-snippet" | "empty-container" | "dangling-jump" | "jump-into-non-addressable" | "invalid-gameid" | "duplicate-gameid" | "unknown-character" | "unknown-qualifier" | "invalid-qualifier" | "invalid-pad" | "pad-overlaps-seam" | "prompt-pad-without-beat" | "qualifier-without-speaker" | "invalid-speaker-label" | "unused-speaker-label" | "invalid-temporary" | "invalid-declaration" | "invalid-status-ladder" | "invalid-locales" | "invalid-captions" | "missing-prompt" | "invalid-prompt" | "multiple-fallbacks" | "choice-can-empty" | "choice-ends-dry" | "invalid-status-value" | "unknown-doc-class" | "invalid-tag" | "invalid-gamedata-field" | "invalid-gamedata-value" | "jump-cycle" | "unreachable-after-jump" | "no-start" | "dangling-start";
     message: string;
     /** Id of the offending node/beat, where applicable. */
     id?: string;
     /** Absent means an error: the project should not be built. A warning still compiles and plays (a choice
-     *  that can run dry gathers or falls through at runtime), and every front end shows it as one. */
-    severity?: "warning";
+     *  that can run dry and end the dialogue), and every front end shows it as one. An `info` is a note, not a
+     *  problem (a choice that can run dry and then carry on, which is often meant): shown, never counted. */
+    severity?: "warning" | "info";
     /** A quality gameData value off its field's ladder (a deleted or renamed stage, most often): the field, the
      *  value, and the stages to offer in its place, in ladder order. An editor's quick fix reads it. */
     offLadder?: {

package/dist/index.js

@@ -102,10 +102,73 @@ function walkContainer(children, selector, out) {
 }
 
 // src/validate.ts
-function choiceLoopsBack(choice, ...targets) {
-  const back = new Set(targets.filter((s) => typeof s === "string" && s.length > 0));
-  const hits = (n) => n.type === "snippet" ? !!n.jump && back.has(n.jump.to) : (n.children ?? []).some(hits);
-  return (choice.children ?? []).some(hits);
+function jumpGraph(scenes, start) {
+  const firstBlock = /* @__PURE__ */ new Map();
+  const blocks = /* @__PURE__ */ new Set();
+  const wellFormed = scenes.filter((sc) => typeof sc?.id === "string" && Array.isArray(sc.blocks));
+  for (const scene of wellFormed) {
+    const first = scene.blocks[0];
+    if (typeof first?.id === "string") firstBlock.set(scene.id, first.id);
+    for (const b of scene.blocks) if (typeof b?.id === "string") blocks.add(b.id);
+  }
+  const resolve = (to) => blocks.has(to) ? to : firstBlock.get(to);
+  const next = /* @__PURE__ */ new Map();
+  const jumpedInto = /* @__PURE__ */ new Set();
+  const calledInto = /* @__PURE__ */ new Set();
+  for (const scene of wellFormed) {
+    for (const block of scene.blocks) {
+      if (typeof block?.id !== "string" || !Array.isArray(block.children)) continue;
+      const out = /* @__PURE__ */ new Set();
+      for (const to of jumpTargets(block.children, resolve)) {
+        out.add(to.block);
+        (to.call ? calledInto : jumpedInto).add(to.block);
+      }
+      next.set(block.id, out);
+    }
+  }
+  const begin = start ? start.block !== void 0 && blocks.has(start.block) ? start.block : firstBlock.get(start.scene) : void 0;
+  const fallbackBegin = wellFormed[0] ? firstBlock.get(wellFormed[0].id) : void 0;
+  if (begin ?? fallbackBegin) jumpedInto.add(begin ?? fallbackBegin);
+  return { next, jumpedInto, calledInto, resolve };
+}
+function jumpTargets(nodes, resolve) {
+  const out = [];
+  walkNodes(nodes.filter((n) => n && typeof n === "object"), (n) => {
+    if (n.type !== "snippet" || !n.jump || typeof n.jump.to !== "string" || n.jump.to === "END") return;
+    const block = resolve(n.jump.to);
+    if (block !== void 0) out.push({ block, call: n.jump.mode === "call" });
+  });
+  return out;
+}
+function leadsBack(graph, nodes, home) {
+  const queue = jumpTargets(nodes, graph.resolve).map((t) => t.block);
+  const seen = /* @__PURE__ */ new Set();
+  while (queue.length > 0) {
+    const b = queue.shift();
+    if (b === home) return true;
+    if (seen.has(b)) continue;
+    seen.add(b);
+    for (const n of graph.next.get(b) ?? []) queue.push(n);
+  }
+  return false;
+}
+function whatFollowsChoices(children) {
+  const out = /* @__PURE__ */ new Map();
+  const visit = (nodes, inOrder, after, once, options) => {
+    nodes.forEach((n, i) => {
+      if (!n || typeof n !== "object") return;
+      const inOnce = once || options && n.sticky !== true;
+      if (n.type !== "group") return;
+      const follows = inOrder ? [...nodes.slice(i + 1), ...after] : after;
+      if (n.selector === "choice") out.set(n.id, { follows, once });
+      if (Array.isArray(n.children)) visit(n.children, (n.selector ?? "run") === "run", follows, inOnce, n.selector === "choice");
+    });
+  };
+  visit(children, true, [], false, false);
+  return out;
+}
+function carriesOn(nodes) {
+  return nodes.some((n) => !isContentlessNode(n) && !(n.type === "snippet" && (n.beats?.length ?? 0) === 0 && n.jump?.to === "END"));
 }
 function isContentlessNode(node) {
   if (node.type === "snippet") return (node.beats?.length ?? 0) === 0 && !node.jump;
@@ -172,6 +235,7 @@ function validateProject(input) {
   const addressable = /* @__PURE__ */ new Set();
   const sceneGameIds = /* @__PURE__ */ new Map();
   const jumps = [];
+  const graph = jumpGraph(Array.isArray(scenes) ? scenes : [], project.start);
   const castNames = new Set((project.cast ?? []).map((c) => c.name));
   const qualifierIds = project.qualifiers === void 0 || Array.isArray(project.qualifiers) ? new Set(projectQualifiers(project).flatMap((q) => isQualifierEntry(q) && typeof q.gameId === "string" ? [q.gameId] : [])) : null;
   const checkPad = (value, what, id) => {
@@ -322,6 +386,7 @@ function validateProject(input) {
           message: `${n.type} '${n.id}' in block '${block.id}' never runs: snippet '${n.jumper}' before it always jumps ${where2}`
         });
       }
+      const afterChoice = whatFollowsChoices(block.children);
       walkNodes(block.children, (node) => {
         const inBlock = `block '${block.id}'`;
         checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
@@ -363,10 +428,27 @@ function validateProject(input) {
               issues.push({ code: "multiple-fallbacks", message: `choice '${node.id}' in ${inBlock} has ${fallbacks} fallback options (at most one allowed)`, id: node.id });
             }
             const hasUnconditionalEscape = (node.children ?? []).some((opt) => !opt.condition);
-            if ((node.children?.length ?? 0) > 0 && !hasUnconditionalEscape) {
-              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} has no unconditional option or fallback - it runs dry (falls through) if every condition fails`, id: node.id, severity: "warning" });
-            } else if (!hasSticky && fallbacks === 0 && choiceLoopsBack(node, block.id, bgid, scene.id, sgid)) {
-              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} can be re-entered but every option is once-only with no fallback - it will run dry`, id: node.id, severity: "warning" });
+            const { follows, once } = afterChoice.get(node.id) ?? { follows: [], once: false };
+            const noGuaranteedPath = (node.children?.length ?? 0) > 0 && !hasUnconditionalEscape;
+            const exhausts = !noGuaranteedPath && !once && !hasSticky && fallbacks === 0 && leadsBack(graph, [...node.children ?? [], ...follows], block.id);
+            if (noGuaranteedPath || exhausts) {
+              const why = noGuaranteedPath ? "has no unconditional option or fallback, so it runs dry if every condition fails" : "can be played again but every option is once-only with no fallback, so it runs dry once they're used";
+              const returns = graph.calledInto.has(block.id) && !graph.jumpedInto.has(block.id);
+              if (carriesOn(follows) || returns) {
+                issues.push({
+                  code: "choice-can-empty",
+                  severity: "info",
+                  id: node.id,
+                  message: `choice '${node.id}' in ${inBlock} ${why}; play then carries on ${returns && !carriesOn(follows) ? "where the block was called from" : "after it"}`
+                });
+              } else {
+                issues.push({
+                  code: "choice-ends-dry",
+                  severity: "warning",
+                  id: node.id,
+                  message: `choice '${node.id}' in ${inBlock} ${why}, and nothing follows it, so the dialogue would end there; add a fallback to say what happens then`
+                });
+              }
             }
           }
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/core",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Patter core: stable id generation, readable-handle computation, canonical (de)serialisation, and the structural validator.",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@patterkit/model": "0.22.0",
+    "@patterkit/model": "0.23.0",
     "@wildwinter/expr": "^0.6.0",
     "@wildwinter/toolkit": "^0.4.0",
     "json5": "^2.2.3"