@patterkit/core 0.3.2 → 0.4.1

package/dist/index.cjs

@@ -21,12 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   canonicalStringify: () => canonicalStringify,
-  effectiveGameId: () => import_model4.effectiveGameId,
-  gameIdify: () => import_model4.gameIdify,
+  effectiveGameId: () => import_model5.effectiveGameId,
+  gameIdify: () => import_model5.gameIdify,
   hash32: () => hash32,
   hash4: () => hash4,
   humanizeNodeRefs: () => humanizeNodeRefs,
-  isValidGameId: () => import_model4.isValidGameId,
+  isValidGameId: () => import_model5.isValidGameId,
   newId: () => import_toolkit.newId,
   parseSource: () => import_toolkit3.parseSource,
   planProject: () => planProject,
@@ -53,7 +53,7 @@ function hash32(input) {
 }
 
 // src/index.ts
-var import_model4 = require("@patterkit/model");
+var import_model5 = require("@patterkit/model");
 
 // src/noderefs.ts
 var VISIT_FN_RE = /\b(patter_visits|patter_seen|visits|seen)\s*\(\s*(?:(['"])(.*?)\2|([A-Za-z_]\w*))\s*\)/g;
@@ -106,6 +106,59 @@ function isContentlessNode(node) {
   if (node.prompt) return false;
   return Array.isArray(node.children) && node.children.every(isContentlessNode);
 }
+function contentlessJumpCycles(scenes) {
+  const firstBlock = /* @__PURE__ */ new Map();
+  for (const scene of scenes) {
+    const first = Array.isArray(scene.blocks) ? scene.blocks[0] : void 0;
+    if (typeof scene.id === "string" && typeof first?.id === "string") firstBlock.set(scene.id, first.id);
+  }
+  const leads = (children) => {
+    if (!Array.isArray(children)) return void 0;
+    for (const n of children) {
+      if (!n || typeof n !== "object" || n.condition) return void 0;
+      if (n.type === "snippet") {
+        if ((n.beats?.length ?? 0) > 0) return void 0;
+        if (!n.jump) continue;
+        if (n.jump.to === "END") return void 0;
+        const to = firstBlock.get(n.jump.to) ?? n.jump.to;
+        return { via: n.id, to };
+      }
+      if (n.type !== "group" || n.prompt || n.selector !== void 0 && n.selector !== "run") return void 0;
+      const inner = leads(n.children);
+      if (inner !== "through") return inner;
+    }
+    return "through";
+  };
+  const next = /* @__PURE__ */ new Map();
+  for (const scene of scenes) {
+    for (const block of Array.isArray(scene.blocks) ? scene.blocks : []) {
+      const l = leads(block.children);
+      if (l && l !== "through" && typeof block.id === "string") next.set(block.id, l);
+    }
+  }
+  const issues = [];
+  const settled = /* @__PURE__ */ new Set();
+  for (const startId of next.keys()) {
+    const path = [];
+    let at = startId;
+    while (at !== void 0 && !settled.has(at) && !path.includes(at)) {
+      path.push(at);
+      at = next.get(at)?.to;
+    }
+    if (at !== void 0 && path.includes(at)) {
+      const loop = path.slice(path.indexOf(at));
+      const via = loop.map((b) => next.get(b).via);
+      issues.push({
+        code: "jump-cycle",
+        severity: "warning",
+        id: via[0],
+        message: `${via.length === 1 ? `snippet '${via[0]}' jumps` : `snippets ${via.map((v) => `'${v}'`).join(", ")} jump`} round a loop with nothing to deliver (blocks ${[...loop, at].map((b) => `'${b}'`).join(" -> ")}); play reaching it never gets out`
+      });
+    }
+    for (const b of path) settled.add(b);
+  }
+  return issues;
+}
 function validateProject(input) {
   const { project, scenes } = input;
   const issues = [];
@@ -121,6 +174,7 @@ function validateProject(input) {
       }
     }
   };
+  const addressOf = (node) => (0, import_model2.effectiveGameId)({ gameId: node.gameId, name: typeof node.name === "string" ? node.name : "" });
   const seeId = (id, kind, where) => {
     if (typeof id !== "string" || id.length === 0) {
       issues.push({ code: "missing-id", message: `${kind} in ${where} has no id` });
@@ -145,7 +199,7 @@ function validateProject(input) {
     if (scene.gameId && !(0, import_model2.isValidGameId)(scene.gameId)) {
       issues.push({ code: "invalid-gameid", message: `${where} address '${scene.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: scene.id });
     }
-    const sgid = (0, import_model2.effectiveGameId)(scene);
+    const sgid = addressOf(scene);
     if (sgid) {
       const prev = sceneGameIds.get(sgid);
       if (prev && prev !== scene.id) issues.push({ code: "duplicate-gameid", message: `${where} address '${sgid}' is already used by scene '${prev}'`, id: scene.id });
@@ -180,7 +234,7 @@ function validateProject(input) {
       if (block.gameId && !(0, import_model2.isValidGameId)(block.gameId)) {
         issues.push({ code: "invalid-gameid", message: `block '${block.id}' address '${block.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: block.id });
       }
-      const bgid = (0, import_model2.effectiveGameId)(block);
+      const bgid = addressOf(block);
       if (bgid) {
         const prev = blockGameIds.get(bgid);
         if (prev && prev !== block.id) issues.push({ code: "duplicate-gameid", message: `block '${block.id}' address '${bgid}' is already used by block '${prev}' in ${where}`, id: block.id });
@@ -243,9 +297,9 @@ function validateProject(input) {
             }
             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 });
+              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 });
+              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" });
             }
           }
           return;
@@ -254,6 +308,10 @@ function validateProject(input) {
         for (const beat of node.beats ?? []) {
           seeId(beat.id, "beat", `snippet '${node.id}'`);
           checkTags(beat.tags, `beat '${beat.id}'`, beat.id);
+          const kind = beat.kind;
+          if (kind !== "line" && kind !== "text" && kind !== "gameEvent") {
+            issues.push({ code: "malformed-node", message: `beat '${beat.id}' has an unknown kind '${kind}' (line, text, or gameEvent)`, id: beat.id });
+          }
           if (beat.kind === "line" && beat.character && !castNames.has(beat.character)) {
             issues.push({
               code: "unknown-character",
@@ -267,6 +325,7 @@ function validateProject(input) {
     }
   }
   if (input.authoring) validateAuthoring(input.authoring, project, allIds, issues);
+  issues.push(...contentlessJumpCycles(scenes));
   for (const d of jumps) {
     if (d.to === "END") continue;
     if (!allIds.has(d.to)) {
@@ -476,11 +535,12 @@ function defaultMatchesType(value, decl) {
 }
 
 // src/scene-scaffold.ts
+var import_model4 = require("@patterkit/model");
 var trimSlash = (p) => p.replace(/\/+$/, "");
 function planProject(opts) {
   const locale = opts.locale ?? "en";
   const project = {
-    schema: "patter/project@0",
+    schema: import_model4.PROJECT_SCHEMA,
     project: { id: (0, import_toolkit.newId)("proj"), name: opts.name },
     locales: { default: locale, all: [locale] },
     voiced: true
@@ -532,10 +592,10 @@ function planScene(target, scaffold) {
     gameId: scaffold.gameId,
     blocks: [{ id: (0, import_toolkit.newId)("blk"), type: "block", name: "Main", children }]
   };
-  const flow = { schema: "patter/flow@0", scene };
-  const locale = { schema: "patter/strings@0", scene: sceneId, locale: target.locale, default: true, strings };
-  const flowDir = trimSlash(target.layout?.flow ?? "scenes/");
-  const stringsDir = trimSlash(target.layout?.strings ?? "loc/");
+  const flow = { schema: import_model4.FLOW_SCHEMA, scene };
+  const locale = { schema: import_model4.STRINGS_SCHEMA, scene: sceneId, locale: target.locale, default: true, strings };
+  const flowDir = trimSlash((0, import_model4.projectLayout)(target).flow);
+  const stringsDir = trimSlash((0, import_model4.projectLayout)(target).strings);
   return {
     sceneId,
     writes: [

package/dist/index.d.cts

@@ -26,10 +26,13 @@ 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" | "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";
+    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" | "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" | "jump-cycle";
     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";
 }
 interface ProjectInput {
     project: ProjectFile;

package/dist/index.d.ts

@@ -26,10 +26,13 @@ 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" | "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";
+    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" | "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" | "jump-cycle";
     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";
 }
 interface ProjectInput {
     project: ProjectFile;

package/dist/index.js

@@ -68,6 +68,59 @@ function isContentlessNode(node) {
   if (node.prompt) return false;
   return Array.isArray(node.children) && node.children.every(isContentlessNode);
 }
+function contentlessJumpCycles(scenes) {
+  const firstBlock = /* @__PURE__ */ new Map();
+  for (const scene of scenes) {
+    const first = Array.isArray(scene.blocks) ? scene.blocks[0] : void 0;
+    if (typeof scene.id === "string" && typeof first?.id === "string") firstBlock.set(scene.id, first.id);
+  }
+  const leads = (children) => {
+    if (!Array.isArray(children)) return void 0;
+    for (const n of children) {
+      if (!n || typeof n !== "object" || n.condition) return void 0;
+      if (n.type === "snippet") {
+        if ((n.beats?.length ?? 0) > 0) return void 0;
+        if (!n.jump) continue;
+        if (n.jump.to === "END") return void 0;
+        const to = firstBlock.get(n.jump.to) ?? n.jump.to;
+        return { via: n.id, to };
+      }
+      if (n.type !== "group" || n.prompt || n.selector !== void 0 && n.selector !== "run") return void 0;
+      const inner = leads(n.children);
+      if (inner !== "through") return inner;
+    }
+    return "through";
+  };
+  const next = /* @__PURE__ */ new Map();
+  for (const scene of scenes) {
+    for (const block of Array.isArray(scene.blocks) ? scene.blocks : []) {
+      const l = leads(block.children);
+      if (l && l !== "through" && typeof block.id === "string") next.set(block.id, l);
+    }
+  }
+  const issues = [];
+  const settled = /* @__PURE__ */ new Set();
+  for (const startId of next.keys()) {
+    const path = [];
+    let at = startId;
+    while (at !== void 0 && !settled.has(at) && !path.includes(at)) {
+      path.push(at);
+      at = next.get(at)?.to;
+    }
+    if (at !== void 0 && path.includes(at)) {
+      const loop = path.slice(path.indexOf(at));
+      const via = loop.map((b) => next.get(b).via);
+      issues.push({
+        code: "jump-cycle",
+        severity: "warning",
+        id: via[0],
+        message: `${via.length === 1 ? `snippet '${via[0]}' jumps` : `snippets ${via.map((v) => `'${v}'`).join(", ")} jump`} round a loop with nothing to deliver (blocks ${[...loop, at].map((b) => `'${b}'`).join(" -> ")}); play reaching it never gets out`
+      });
+    }
+    for (const b of path) settled.add(b);
+  }
+  return issues;
+}
 function validateProject(input) {
   const { project, scenes } = input;
   const issues = [];
@@ -83,6 +136,7 @@ function validateProject(input) {
       }
     }
   };
+  const addressOf = (node) => effectiveGameId({ gameId: node.gameId, name: typeof node.name === "string" ? node.name : "" });
   const seeId = (id, kind, where) => {
     if (typeof id !== "string" || id.length === 0) {
       issues.push({ code: "missing-id", message: `${kind} in ${where} has no id` });
@@ -107,7 +161,7 @@ function validateProject(input) {
     if (scene.gameId && !isValidGameId(scene.gameId)) {
       issues.push({ code: "invalid-gameid", message: `${where} address '${scene.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: scene.id });
     }
-    const sgid = effectiveGameId(scene);
+    const sgid = addressOf(scene);
     if (sgid) {
       const prev = sceneGameIds.get(sgid);
       if (prev && prev !== scene.id) issues.push({ code: "duplicate-gameid", message: `${where} address '${sgid}' is already used by scene '${prev}'`, id: scene.id });
@@ -142,7 +196,7 @@ function validateProject(input) {
       if (block.gameId && !isValidGameId(block.gameId)) {
         issues.push({ code: "invalid-gameid", message: `block '${block.id}' address '${block.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: block.id });
       }
-      const bgid = effectiveGameId(block);
+      const bgid = addressOf(block);
       if (bgid) {
         const prev = blockGameIds.get(bgid);
         if (prev && prev !== block.id) issues.push({ code: "duplicate-gameid", message: `block '${block.id}' address '${bgid}' is already used by block '${prev}' in ${where}`, id: block.id });
@@ -205,9 +259,9 @@ function validateProject(input) {
             }
             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 });
+              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 });
+              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" });
             }
           }
           return;
@@ -216,6 +270,10 @@ function validateProject(input) {
         for (const beat of node.beats ?? []) {
           seeId(beat.id, "beat", `snippet '${node.id}'`);
           checkTags(beat.tags, `beat '${beat.id}'`, beat.id);
+          const kind = beat.kind;
+          if (kind !== "line" && kind !== "text" && kind !== "gameEvent") {
+            issues.push({ code: "malformed-node", message: `beat '${beat.id}' has an unknown kind '${kind}' (line, text, or gameEvent)`, id: beat.id });
+          }
           if (beat.kind === "line" && beat.character && !castNames.has(beat.character)) {
             issues.push({
               code: "unknown-character",
@@ -229,6 +287,7 @@ function validateProject(input) {
     }
   }
   if (input.authoring) validateAuthoring(input.authoring, project, allIds, issues);
+  issues.push(...contentlessJumpCycles(scenes));
   for (const d of jumps) {
     if (d.to === "END") continue;
     if (!allIds.has(d.to)) {
@@ -438,11 +497,12 @@ function defaultMatchesType(value, decl) {
 }
 
 // src/scene-scaffold.ts
+import { projectLayout, FLOW_SCHEMA, PROJECT_SCHEMA, STRINGS_SCHEMA } from "@patterkit/model";
 var trimSlash = (p) => p.replace(/\/+$/, "");
 function planProject(opts) {
   const locale = opts.locale ?? "en";
   const project = {
-    schema: "patter/project@0",
+    schema: PROJECT_SCHEMA,
     project: { id: newId("proj"), name: opts.name },
     locales: { default: locale, all: [locale] },
     voiced: true
@@ -494,10 +554,10 @@ function planScene(target, scaffold) {
     gameId: scaffold.gameId,
     blocks: [{ id: newId("blk"), type: "block", name: "Main", children }]
   };
-  const flow = { schema: "patter/flow@0", scene };
-  const locale = { schema: "patter/strings@0", scene: sceneId, locale: target.locale, default: true, strings };
-  const flowDir = trimSlash(target.layout?.flow ?? "scenes/");
-  const stringsDir = trimSlash(target.layout?.strings ?? "loc/");
+  const flow = { schema: FLOW_SCHEMA, scene };
+  const locale = { schema: STRINGS_SCHEMA, scene: sceneId, locale: target.locale, default: true, strings };
+  const flowDir = trimSlash(projectLayout(target).flow);
+  const stringsDir = trimSlash(projectLayout(target).strings);
   return {
     sceneId,
     writes: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/core",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "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.9.0",
+    "@patterkit/model": "0.10.0",
     "@wildwinter/toolkit": "^0.1.0",
     "json5": "^2.2.3"
   }