@patterkit/core 0.4.1 → 0.6.0

package/dist/index.cjs

@@ -167,6 +167,45 @@ function validateProject(input) {
   const sceneGameIds = /* @__PURE__ */ new Map();
   const jumps = [];
   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) => {
+    if (value === void 0) return;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < import_model.PAD_AFTER_MIN || value > import_model.PAD_AFTER_MAX) {
+      issues.push({ code: "invalid-pad", message: `${what} pause '${String(value)}' must be a number of seconds from ${import_model.PAD_AFTER_MIN} to ${import_model.PAD_AFTER_MAX}`, id });
+    }
+  };
+  const checkSeamPad = (beats) => {
+    const last = (beats ?? []).at(-1);
+    if (!last || last.kind !== "line" && last.kind !== "text" || typeof last.padAfter !== "number" || last.padAfter >= 0) return;
+    issues.push({
+      code: "pad-overlaps-seam",
+      severity: "warning",
+      id: last.id,
+      message: `beat '${last.id}' is its snippet's last line, so its negative pause can't cut in on what follows; it plays as no pause`
+    });
+  };
+  const checkPromptPad = (option) => {
+    const p = option.prompt;
+    if (!p || p.kind !== "line" && p.kind !== "text" || typeof p.padAfter !== "number" || p.padAfter >= 0) return;
+    if ((option.selector ?? "run") !== "run" || !Array.isArray(option.children)) return;
+    const first = option.children[0];
+    if (first && (first.type !== "snippet" || first.condition || (first.beats?.length ?? 0) > 0)) return;
+    issues.push({
+      code: "prompt-pad-without-beat",
+      severity: "warning",
+      id: p.id,
+      message: `prompt '${p.id}' has a negative pause, but its option plays nothing before it moves on, so nothing cuts in on it`
+    });
+  };
+  const checkQualifier = (beat, what) => {
+    if (beat.kind !== "line" || beat.qualifier === void 0) return;
+    if (qualifierIds && !qualifierIds.has(beat.qualifier)) {
+      issues.push({ code: "unknown-qualifier", message: `${what} '${beat.id}' qualifier '${beat.qualifier}' is not in the project's qualifiers`, id: beat.id });
+    }
+    if (!beat.character) {
+      issues.push({ code: "qualifier-without-speaker", severity: "warning", message: `${what} '${beat.id}' has the qualifier '${beat.qualifier}' but no speaker`, id: beat.id });
+    }
+  };
   const checkTags = (tags, where, id) => {
     for (const t of tags ?? []) {
       if (typeof t !== "string" || t.length === 0 || /[\s,]/.test(t)) {
@@ -191,6 +230,7 @@ function validateProject(input) {
   validateProjectFile(project, issues);
   for (const scene of scenes) {
     seeId(scene.id, "scene", "project");
+    checkPad(scene.padAfterDefault, `scene '${scene.id}' default`, scene.id);
     const where = `scene '${scene.id}'`;
     if (typeof scene.id === "string") addressable.add(scene.id);
     if (!scene.name?.trim()) {
@@ -226,6 +266,7 @@ function validateProject(input) {
     }
     for (const block of scene.blocks) {
       seeId(block.id, "block", where);
+      checkPad(block.padAfterDefault, `block '${block.id}' default`, block.id);
       checkTags(block.tags, `block '${block.id}'`, block.id);
       if (typeof block.id === "string") addressable.add(block.id);
       if (!block.name?.trim()) {
@@ -266,6 +307,12 @@ function validateProject(input) {
       (0, import_model.walkNodes)(block.children, (node) => {
         const inBlock = `block '${block.id}'`;
         checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
+        checkPad(node.padAfterDefault, `${node.type} '${node.id}' default`, node.id);
+        if (node.type === "group" && node.prompt) checkPad(node.prompt.padAfter, `prompt '${node.prompt.id}'`, node.prompt.id);
+        if (node.type === "snippet") {
+          for (const beat of node.beats ?? []) if (beat.kind !== "gameEvent") checkPad(beat.padAfter, `beat '${beat.id}'`, beat.id);
+          checkSeamPad(node.beats);
+        }
         if (node.type === "group") {
           seeId(node.id, "group", inBlock);
           if (!Array.isArray(node.children)) {
@@ -290,6 +337,8 @@ function validateProject(input) {
                 if (p.kind === "line" && p.character && !castNames.has(p.character)) {
                   issues.push({ code: "unknown-character", message: `prompt '${p.id}' speaker '${p.character}' is not in the project cast`, id: p.id });
                 }
+                checkQualifier(p, "prompt");
+                checkPromptPad(opt);
               }
             }
             if (fallbacks > 1) {
@@ -319,6 +368,7 @@ function validateProject(input) {
               id: beat.id
             });
           }
+          checkQualifier(beat, "beat");
         }
         if (node.jump) jumps.push({ to: node.jump.to, from: node.id });
       });
@@ -340,6 +390,9 @@ function validateProject(input) {
   }
   return issues;
 }
+function isQualifierEntry(q) {
+  return typeof q === "object" && q !== null && !Array.isArray(q);
+}
 function validateProjectFile(project, issues) {
   checkDecls(project.properties, "project properties", issues);
   for (const scope of project.scopeRegistry?.scopes ?? []) {
@@ -391,6 +444,30 @@ function validateProjectFile(project, issues) {
   if (project.recordingStatuses) {
     checkLadderNames(project.recordingStatuses.map((s) => s.name), "recordingStatuses", issues);
   }
+  const pad = project.padAfterDefault;
+  if (pad !== void 0 && (typeof pad !== "number" || !Number.isFinite(pad) || pad < import_model.PAD_AFTER_MIN || pad > import_model.PAD_AFTER_MAX)) {
+    issues.push({ code: "invalid-pad", message: `the project default pause '${String(pad)}' must be a number of seconds from ${import_model.PAD_AFTER_MIN} to ${import_model.PAD_AFTER_MAX}` });
+  }
+  const seenQualifiers = /* @__PURE__ */ new Set();
+  const qualifiers = project.qualifiers;
+  if (qualifiers !== void 0 && !Array.isArray(qualifiers)) {
+    issues.push({ code: "invalid-qualifier", message: "qualifiers must be a list" });
+  }
+  for (const q of Array.isArray(qualifiers) ? qualifiers : []) {
+    if (!isQualifierEntry(q)) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier '${String(q)}' is not a qualifier (a name and an address)` });
+      continue;
+    }
+    if (typeof q.name !== "string" || !q.name.trim()) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier '${String(q.gameId)}' has no name` });
+    }
+    if (typeof q.gameId !== "string" || !(0, import_model2.isValidGameId)(q.gameId)) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier '${String(q.name)}' address '${String(q.gameId)}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)` });
+    } else if (seenQualifiers.has(q.gameId)) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier address '${q.gameId}' is used more than once` });
+    }
+    if (typeof q.gameId === "string") seenQualifiers.add(q.gameId);
+  }
   for (const [kind, fields] of Object.entries(project.gameDataFields ?? {})) {
     const seen = /* @__PURE__ */ new Set();
     for (const f of fields ?? []) {

package/dist/index.d.cts

@@ -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" | "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";
+    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-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;

package/dist/index.d.ts

@@ -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" | "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";
+    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-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;

package/dist/index.js

@@ -55,7 +55,7 @@ ${indent}}`;
 }
 
 // src/validate.ts
-import { walkNodes, DEFAULT_WRITING_STATUSES, DEFAULT_RECORDING_STATUSES, DEFAULT_DOCUMENTATION_CLASSES } from "@patterkit/model";
+import { walkNodes, DEFAULT_WRITING_STATUSES, DEFAULT_RECORDING_STATUSES, DEFAULT_DOCUMENTATION_CLASSES, projectQualifiers, PAD_AFTER_MIN, PAD_AFTER_MAX } from "@patterkit/model";
 import { isValidGameId, effectiveGameId } from "@patterkit/model";
 import { isValidPropertyName, propertyNameify, RESERVED_PROPERTY_NAMES } from "@patterkit/model";
 function choiceLoopsBack(choice, ...targets) {
@@ -129,6 +129,45 @@ function validateProject(input) {
   const sceneGameIds = /* @__PURE__ */ new Map();
   const jumps = [];
   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) => {
+    if (value === void 0) return;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < PAD_AFTER_MIN || value > PAD_AFTER_MAX) {
+      issues.push({ code: "invalid-pad", message: `${what} pause '${String(value)}' must be a number of seconds from ${PAD_AFTER_MIN} to ${PAD_AFTER_MAX}`, id });
+    }
+  };
+  const checkSeamPad = (beats) => {
+    const last = (beats ?? []).at(-1);
+    if (!last || last.kind !== "line" && last.kind !== "text" || typeof last.padAfter !== "number" || last.padAfter >= 0) return;
+    issues.push({
+      code: "pad-overlaps-seam",
+      severity: "warning",
+      id: last.id,
+      message: `beat '${last.id}' is its snippet's last line, so its negative pause can't cut in on what follows; it plays as no pause`
+    });
+  };
+  const checkPromptPad = (option) => {
+    const p = option.prompt;
+    if (!p || p.kind !== "line" && p.kind !== "text" || typeof p.padAfter !== "number" || p.padAfter >= 0) return;
+    if ((option.selector ?? "run") !== "run" || !Array.isArray(option.children)) return;
+    const first = option.children[0];
+    if (first && (first.type !== "snippet" || first.condition || (first.beats?.length ?? 0) > 0)) return;
+    issues.push({
+      code: "prompt-pad-without-beat",
+      severity: "warning",
+      id: p.id,
+      message: `prompt '${p.id}' has a negative pause, but its option plays nothing before it moves on, so nothing cuts in on it`
+    });
+  };
+  const checkQualifier = (beat, what) => {
+    if (beat.kind !== "line" || beat.qualifier === void 0) return;
+    if (qualifierIds && !qualifierIds.has(beat.qualifier)) {
+      issues.push({ code: "unknown-qualifier", message: `${what} '${beat.id}' qualifier '${beat.qualifier}' is not in the project's qualifiers`, id: beat.id });
+    }
+    if (!beat.character) {
+      issues.push({ code: "qualifier-without-speaker", severity: "warning", message: `${what} '${beat.id}' has the qualifier '${beat.qualifier}' but no speaker`, id: beat.id });
+    }
+  };
   const checkTags = (tags, where, id) => {
     for (const t of tags ?? []) {
       if (typeof t !== "string" || t.length === 0 || /[\s,]/.test(t)) {
@@ -153,6 +192,7 @@ function validateProject(input) {
   validateProjectFile(project, issues);
   for (const scene of scenes) {
     seeId(scene.id, "scene", "project");
+    checkPad(scene.padAfterDefault, `scene '${scene.id}' default`, scene.id);
     const where = `scene '${scene.id}'`;
     if (typeof scene.id === "string") addressable.add(scene.id);
     if (!scene.name?.trim()) {
@@ -188,6 +228,7 @@ function validateProject(input) {
     }
     for (const block of scene.blocks) {
       seeId(block.id, "block", where);
+      checkPad(block.padAfterDefault, `block '${block.id}' default`, block.id);
       checkTags(block.tags, `block '${block.id}'`, block.id);
       if (typeof block.id === "string") addressable.add(block.id);
       if (!block.name?.trim()) {
@@ -228,6 +269,12 @@ function validateProject(input) {
       walkNodes(block.children, (node) => {
         const inBlock = `block '${block.id}'`;
         checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
+        checkPad(node.padAfterDefault, `${node.type} '${node.id}' default`, node.id);
+        if (node.type === "group" && node.prompt) checkPad(node.prompt.padAfter, `prompt '${node.prompt.id}'`, node.prompt.id);
+        if (node.type === "snippet") {
+          for (const beat of node.beats ?? []) if (beat.kind !== "gameEvent") checkPad(beat.padAfter, `beat '${beat.id}'`, beat.id);
+          checkSeamPad(node.beats);
+        }
         if (node.type === "group") {
           seeId(node.id, "group", inBlock);
           if (!Array.isArray(node.children)) {
@@ -252,6 +299,8 @@ function validateProject(input) {
                 if (p.kind === "line" && p.character && !castNames.has(p.character)) {
                   issues.push({ code: "unknown-character", message: `prompt '${p.id}' speaker '${p.character}' is not in the project cast`, id: p.id });
                 }
+                checkQualifier(p, "prompt");
+                checkPromptPad(opt);
               }
             }
             if (fallbacks > 1) {
@@ -281,6 +330,7 @@ function validateProject(input) {
               id: beat.id
             });
           }
+          checkQualifier(beat, "beat");
         }
         if (node.jump) jumps.push({ to: node.jump.to, from: node.id });
       });
@@ -302,6 +352,9 @@ function validateProject(input) {
   }
   return issues;
 }
+function isQualifierEntry(q) {
+  return typeof q === "object" && q !== null && !Array.isArray(q);
+}
 function validateProjectFile(project, issues) {
   checkDecls(project.properties, "project properties", issues);
   for (const scope of project.scopeRegistry?.scopes ?? []) {
@@ -353,6 +406,30 @@ function validateProjectFile(project, issues) {
   if (project.recordingStatuses) {
     checkLadderNames(project.recordingStatuses.map((s) => s.name), "recordingStatuses", issues);
   }
+  const pad = project.padAfterDefault;
+  if (pad !== void 0 && (typeof pad !== "number" || !Number.isFinite(pad) || pad < PAD_AFTER_MIN || pad > PAD_AFTER_MAX)) {
+    issues.push({ code: "invalid-pad", message: `the project default pause '${String(pad)}' must be a number of seconds from ${PAD_AFTER_MIN} to ${PAD_AFTER_MAX}` });
+  }
+  const seenQualifiers = /* @__PURE__ */ new Set();
+  const qualifiers = project.qualifiers;
+  if (qualifiers !== void 0 && !Array.isArray(qualifiers)) {
+    issues.push({ code: "invalid-qualifier", message: "qualifiers must be a list" });
+  }
+  for (const q of Array.isArray(qualifiers) ? qualifiers : []) {
+    if (!isQualifierEntry(q)) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier '${String(q)}' is not a qualifier (a name and an address)` });
+      continue;
+    }
+    if (typeof q.name !== "string" || !q.name.trim()) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier '${String(q.gameId)}' has no name` });
+    }
+    if (typeof q.gameId !== "string" || !isValidGameId(q.gameId)) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier '${String(q.name)}' address '${String(q.gameId)}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)` });
+    } else if (seenQualifiers.has(q.gameId)) {
+      issues.push({ code: "invalid-qualifier", message: `qualifier address '${q.gameId}' is used more than once` });
+    }
+    if (typeof q.gameId === "string") seenQualifiers.add(q.gameId);
+  }
   for (const [kind, fields] of Object.entries(project.gameDataFields ?? {})) {
     const seen = /* @__PURE__ */ new Set();
     for (const f of fields ?? []) {

package/package.json

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