@patterkit/core 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,35 @@
+# @patterkit/core
+
+The low-level building blocks shared by Patter's editor, command line tool, and CI: ids, readable handles,
+reading and writing the source files, and the structural validator.
+
+Most people won't need to install this directly. To play Patter dialogue in a game or web page, use
+[`@patterkit/runtime`](https://www.npmjs.com/package/@patterkit/runtime); to work with Patter projects from
+a terminal or a build script, use [`@patterkit/cli`](https://www.npmjs.com/package/@patterkit/cli).
+
+## What's in it
+
+- **Ids and handles**: `newId` for stable node ids, and `slug`, `hash4`, and `hash32` for the readable
+  handles and content hashes built from them.
+- **Reading and writing source files**: `parseSource` and `canonicalStringify`, which write a project's
+  files in one canonical form so version control shows only real changes.
+- **The structural validator**: `validateProject` checks a project and its scenes hang together (ids,
+  references, and structure) and returns a list of issues.
+- **Scene scaffolding**: `planProject` and `planScene` plan a stub project or scene that another tool can
+  hand to a writer.
+
+```sh
+npm install @patterkit/core
+```
+
+## Part of Patter
+
+[Patter](https://patterkit.dev/) is a branching dialogue format with its own editor (Patterpad), command line
+tool (`patter`), and runtimes for JavaScript, Unity, Unreal, and Godot. This package is one layer of the
+JavaScript tooling, and the other `@patterkit` packages build on it. [How it fits
+together](https://patterkit.dev/architecture/) shows where each piece sits, and the source is in the
+[patter repository](https://github.com/patterkit/patter).
+
+## Licence
+
+MIT

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 = [];
@@ -243,9 +296,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 +307,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 +324,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 +534,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 +591,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 = [];
@@ -205,9 +258,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 +269,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 +286,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 +496,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 +553,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.1",
+  "version": "0.4.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.8.0",
+    "@patterkit/model": "0.10.0",
     "@wildwinter/toolkit": "^0.1.0",
     "json5": "^2.2.3"
   }