@patterkit/core 0.9.6 → 0.10.1

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   hash4: () => hash4,
   humanizeNodeRefs: () => humanizeNodeRefs,
   isValidGameId: () => import_model5.isValidGameId,
+  neverRunNodes: () => neverRunNodes,
   newId: () => import_toolkit.newId,
   parseSource: () => import_toolkit3.parseSource,
   planProject: () => planProject,
@@ -97,6 +98,49 @@ var import_model = require("@patterkit/model");
 var import_model2 = require("@patterkit/model");
 var import_model3 = require("@patterkit/model");
 var import_expr = require("@wildwinter/expr");
+
+// src/never-runs.ts
+var isNode = (n) => !!n && typeof n === "object" && typeof n.id === "string";
+function neverRunNodes(children) {
+  const out = [];
+  walkContainer(children, "run", out);
+  return out;
+}
+function walkContainer(children, selector, out) {
+  if (!Array.isArray(children)) return void 0;
+  if (selector === "run") {
+    let jumper;
+    for (const n of children) {
+      if (!isNode(n)) continue;
+      if (jumper !== void 0) {
+        out.push({ id: n.id, type: n.type, reason: "after-jump", ...jumper });
+        continue;
+      }
+      if (n.type === "snippet") {
+        if (!n.condition && n.jump && typeof n.jump.to === "string" && n.jump.mode !== "call") jumper = { jumper: n.id, to: n.jump.to };
+        continue;
+      }
+      const inner = walkContainer(n.children, n.selector ?? "run", out);
+      if (inner !== void 0 && !n.condition && !n.prompt && (n.selector ?? "run") === "run") jumper = inner;
+    }
+    return jumper;
+  }
+  let winner;
+  for (const n of children) {
+    if (!isNode(n)) continue;
+    if (selector === "branch") {
+      if (winner !== void 0) {
+        out.push({ id: n.id, type: n.type, reason: "branch-shadowed", by: winner });
+        continue;
+      }
+      if (!n.condition) winner = n.id;
+    }
+    if (n.type === "group") walkContainer(n.children, n.selector ?? "run", out);
+  }
+  return void 0;
+}
+
+// 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);
@@ -306,6 +350,17 @@ function validateProject(input) {
       } else {
         reportEmpty(block.children);
       }
+      for (const n of neverRunNodes(block.children)) {
+        if (n.reason !== "after-jump") continue;
+        const where2 = n.to === "END" ? "to END" : `to '${n.to}'`;
+        issues.push({
+          code: "unreachable-after-jump",
+          severity: "warning",
+          id: n.id,
+          jumper: n.jumper,
+          message: `${n.type} '${n.id}' in block '${block.id}' never runs: snippet '${n.jumper}' before it always jumps ${where2}`
+        });
+      }
       (0, import_model.walkNodes)(block.children, (node) => {
         const inBlock = `block '${block.id}'`;
         checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
@@ -404,6 +459,32 @@ function validateProject(input) {
       });
     }
   }
+  const wellFormed = scenes.filter((sc) => typeof sc?.id === "string" && Array.isArray(sc.blocks));
+  if (wellFormed.length > 0) {
+    const start = project.start;
+    const scene = start ? wellFormed.find((sc) => sc.id === start.scene) : void 0;
+    if (!start) {
+      issues.push({
+        code: "no-start",
+        severity: "warning",
+        message: "no start scene is set, so a game that doesn't name a scene starts at the first one"
+      });
+    } else if (!scene) {
+      issues.push({
+        code: "dangling-start",
+        severity: "warning",
+        id: start.scene,
+        message: `the start scene '${start.scene}' isn't in the project, so a game that doesn't name a scene starts at the first one`
+      });
+    } else if (start.block !== void 0 && !scene.blocks.some((b) => b?.id === start.block)) {
+      issues.push({
+        code: "dangling-start",
+        severity: "warning",
+        id: start.block,
+        message: `the start block '${start.block}' isn't in scene '${scene.id}', so the game starts at that scene's first block`
+      });
+    }
+  }
   return issues;
 }
 function isQualifierEntry(q) {
@@ -776,6 +857,7 @@ function planScene(target, scaffold) {
   hash4,
   humanizeNodeRefs,
   isValidGameId,
+  neverRunNodes,
   newId,
   parseSource,
   planProject,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 export { newId, parseSource } from '@wildwinter/toolkit';
-import { ProjectFile, Scene, AuthoringFile } from '@patterkit/model';
+import { ProjectFile, Scene, AuthoringFile, Selector } from '@patterkit/model';
 export { effectiveGameId, gameIdify, isValidGameId } from '@patterkit/model';
 
 /** Slugify an author name into a filename- / address-safe segment. */
@@ -26,7 +26,7 @@ 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";
+    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";
     message: string;
     /** Id of the offending node/beat, where applicable. */
     id?: string;
@@ -40,6 +40,8 @@ interface ValidationIssue {
         bad: string;
         options: string[];
     };
+    /** `unreachable-after-jump`: the snippet whose jump means this node never runs (`id` is the node). */
+    jumper?: string;
 }
 interface ProjectInput {
     project: ProjectFile;
@@ -50,6 +52,43 @@ interface ProjectInput {
 /** Validate a project's structural invariants. Returns an empty array when valid. */
 declare function validateProject(input: ProjectInput): ValidationIssue[];
 
+/** The shape the walk reads: an authored node (condition as source text) or a compiled one (an
+ *  expression), so the validator and coverage both pass theirs as they are. */
+interface RunTreeNode {
+    id: string;
+    type: "group" | "snippet";
+    condition?: unknown;
+    selector?: Selector;
+    prompt?: unknown;
+    children?: readonly RunTreeNode[];
+    jump?: {
+        to: string;
+        mode?: "jump" | "call";
+    };
+}
+/** A node that never runs, and why. Only the outermost such node is listed: everything inside it never
+ *  runs either. */
+type NeverRuns = 
+/** After an unconditioned snippet that jumps, in the same run. `jumper` is that snippet (inside a plain
+ *  run group before this node, when that is where the jump is); `to` is where it jumps (`END` included). */
+{
+    id: string;
+    type: "group" | "snippet";
+    reason: "after-jump";
+    jumper: string;
+    to: string;
+}
+/** In a `branch`, after a sibling with no condition, which is always picked first. */
+ | {
+    id: string;
+    type: "group" | "snippet";
+    reason: "branch-shadowed";
+    by: string;
+};
+/** The nodes in a block that can never run, in script order. `children` is the block's children (a run).
+ *  Malformed shapes (a missing children array, a node that is not one) are skipped, never thrown on. */
+declare function neverRunNodes(children: unknown): NeverRuns[];
+
 interface SceneScaffold {
     /** The scene's name: the card's title. */
     name: string;
@@ -98,4 +137,4 @@ declare function planProject(opts: {
 /** Plan a stub scene for a card. Pure: nothing is read or written. */
 declare function planScene(target: ScenePlanTarget, scaffold: SceneScaffold): ScenePlan;
 
-export { type ProjectInput, type ScenePlan, type ScenePlanTarget, type SceneScaffold, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, planProject, planScene, slug, validateProject };
+export { type NeverRuns, type ProjectInput, type RunTreeNode, type ScenePlan, type ScenePlanTarget, type SceneScaffold, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, neverRunNodes, planProject, planScene, slug, validateProject };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { newId, parseSource } from '@wildwinter/toolkit';
-import { ProjectFile, Scene, AuthoringFile } from '@patterkit/model';
+import { ProjectFile, Scene, AuthoringFile, Selector } from '@patterkit/model';
 export { effectiveGameId, gameIdify, isValidGameId } from '@patterkit/model';
 
 /** Slugify an author name into a filename- / address-safe segment. */
@@ -26,7 +26,7 @@ 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";
+    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";
     message: string;
     /** Id of the offending node/beat, where applicable. */
     id?: string;
@@ -40,6 +40,8 @@ interface ValidationIssue {
         bad: string;
         options: string[];
     };
+    /** `unreachable-after-jump`: the snippet whose jump means this node never runs (`id` is the node). */
+    jumper?: string;
 }
 interface ProjectInput {
     project: ProjectFile;
@@ -50,6 +52,43 @@ interface ProjectInput {
 /** Validate a project's structural invariants. Returns an empty array when valid. */
 declare function validateProject(input: ProjectInput): ValidationIssue[];
 
+/** The shape the walk reads: an authored node (condition as source text) or a compiled one (an
+ *  expression), so the validator and coverage both pass theirs as they are. */
+interface RunTreeNode {
+    id: string;
+    type: "group" | "snippet";
+    condition?: unknown;
+    selector?: Selector;
+    prompt?: unknown;
+    children?: readonly RunTreeNode[];
+    jump?: {
+        to: string;
+        mode?: "jump" | "call";
+    };
+}
+/** A node that never runs, and why. Only the outermost such node is listed: everything inside it never
+ *  runs either. */
+type NeverRuns = 
+/** After an unconditioned snippet that jumps, in the same run. `jumper` is that snippet (inside a plain
+ *  run group before this node, when that is where the jump is); `to` is where it jumps (`END` included). */
+{
+    id: string;
+    type: "group" | "snippet";
+    reason: "after-jump";
+    jumper: string;
+    to: string;
+}
+/** In a `branch`, after a sibling with no condition, which is always picked first. */
+ | {
+    id: string;
+    type: "group" | "snippet";
+    reason: "branch-shadowed";
+    by: string;
+};
+/** The nodes in a block that can never run, in script order. `children` is the block's children (a run).
+ *  Malformed shapes (a missing children array, a node that is not one) are skipped, never thrown on. */
+declare function neverRunNodes(children: unknown): NeverRuns[];
+
 interface SceneScaffold {
     /** The scene's name: the card's title. */
     name: string;
@@ -98,4 +137,4 @@ declare function planProject(opts: {
 /** Plan a stub scene for a card. Pure: nothing is read or written. */
 declare function planScene(target: ScenePlanTarget, scaffold: SceneScaffold): ScenePlan;
 
-export { type ProjectInput, type ScenePlan, type ScenePlanTarget, type SceneScaffold, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, planProject, planScene, slug, validateProject };
+export { type NeverRuns, type ProjectInput, type RunTreeNode, type ScenePlan, type ScenePlanTarget, type SceneScaffold, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, humanizeNodeRefs, neverRunNodes, planProject, planScene, slug, validateProject };

package/dist/index.js

@@ -59,6 +59,49 @@ import { walkNodes, DEFAULT_WRITING_STATUSES, DEFAULT_RECORDING_STATUSES, DEFAUL
 import { isValidGameId, effectiveGameId } from "@patterkit/model";
 import { isValidPropertyName, propertyNameify, RESERVED_PROPERTY_NAMES } from "@patterkit/model";
 import { qualityDeclarationProblems, stagesEitherSide, valueFits } from "@wildwinter/expr";
+
+// src/never-runs.ts
+var isNode = (n) => !!n && typeof n === "object" && typeof n.id === "string";
+function neverRunNodes(children) {
+  const out = [];
+  walkContainer(children, "run", out);
+  return out;
+}
+function walkContainer(children, selector, out) {
+  if (!Array.isArray(children)) return void 0;
+  if (selector === "run") {
+    let jumper;
+    for (const n of children) {
+      if (!isNode(n)) continue;
+      if (jumper !== void 0) {
+        out.push({ id: n.id, type: n.type, reason: "after-jump", ...jumper });
+        continue;
+      }
+      if (n.type === "snippet") {
+        if (!n.condition && n.jump && typeof n.jump.to === "string" && n.jump.mode !== "call") jumper = { jumper: n.id, to: n.jump.to };
+        continue;
+      }
+      const inner = walkContainer(n.children, n.selector ?? "run", out);
+      if (inner !== void 0 && !n.condition && !n.prompt && (n.selector ?? "run") === "run") jumper = inner;
+    }
+    return jumper;
+  }
+  let winner;
+  for (const n of children) {
+    if (!isNode(n)) continue;
+    if (selector === "branch") {
+      if (winner !== void 0) {
+        out.push({ id: n.id, type: n.type, reason: "branch-shadowed", by: winner });
+        continue;
+      }
+      if (!n.condition) winner = n.id;
+    }
+    if (n.type === "group") walkContainer(n.children, n.selector ?? "run", out);
+  }
+  return void 0;
+}
+
+// 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);
@@ -268,6 +311,17 @@ function validateProject(input) {
       } else {
         reportEmpty(block.children);
       }
+      for (const n of neverRunNodes(block.children)) {
+        if (n.reason !== "after-jump") continue;
+        const where2 = n.to === "END" ? "to END" : `to '${n.to}'`;
+        issues.push({
+          code: "unreachable-after-jump",
+          severity: "warning",
+          id: n.id,
+          jumper: n.jumper,
+          message: `${n.type} '${n.id}' in block '${block.id}' never runs: snippet '${n.jumper}' before it always jumps ${where2}`
+        });
+      }
       walkNodes(block.children, (node) => {
         const inBlock = `block '${block.id}'`;
         checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
@@ -366,6 +420,32 @@ function validateProject(input) {
       });
     }
   }
+  const wellFormed = scenes.filter((sc) => typeof sc?.id === "string" && Array.isArray(sc.blocks));
+  if (wellFormed.length > 0) {
+    const start = project.start;
+    const scene = start ? wellFormed.find((sc) => sc.id === start.scene) : void 0;
+    if (!start) {
+      issues.push({
+        code: "no-start",
+        severity: "warning",
+        message: "no start scene is set, so a game that doesn't name a scene starts at the first one"
+      });
+    } else if (!scene) {
+      issues.push({
+        code: "dangling-start",
+        severity: "warning",
+        id: start.scene,
+        message: `the start scene '${start.scene}' isn't in the project, so a game that doesn't name a scene starts at the first one`
+      });
+    } else if (start.block !== void 0 && !scene.blocks.some((b) => b?.id === start.block)) {
+      issues.push({
+        code: "dangling-start",
+        severity: "warning",
+        id: start.block,
+        message: `the start block '${start.block}' isn't in scene '${scene.id}', so the game starts at that scene's first block`
+      });
+    }
+  }
   return issues;
 }
 function isQualifierEntry(q) {
@@ -737,6 +817,7 @@ export {
   hash4,
   humanizeNodeRefs,
   isValidGameId2 as isValidGameId,
+  neverRunNodes,
   newId,
   parseSource,
   planProject,

package/package.json

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