@wildwinter/toolkit 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @wildwinter/toolkit
 
+## 0.3.0
+
+### Removed
+
+- **Claims and settings** (`./extensions`): a manifest's `settings` and a target's `claims`, and with them
+  `ClaimDecl`, `SettingDecl`, `HostSpec.claimable`, `settingValues`, `resolvedClaims`, `claimClashes`, and
+  `effectiveClaim`. An extension's data is always its own; a project-wide value is a field on the `project` target.
+  A manifest that still has `settings` or `claims` is warned of by name (`removed-key`), and the key is ignored.
+
 ## 0.2.7
 
 ### Added

package/conformance/extensions/defaults.json

@@ -28,7 +28,7 @@
         { "name": "tone", "type": "enum", "values": ["calm", "tense"], "valueHelp": { "calm": "x" } },
         { "name": "act", "type": "quality", "stages": ["setup", "turn"], "renamedStages": { "opening": "setup" } },
         { "name": "cue", "type": "record", "fields": [{ "name": "gain", "type": "number", "min": 0, "help": "Loudness." }] }
-      ], "claims": [{ "setting": "moodField", "type": "text" }] },
+      ] },
       "compiled": [
         { "name": "note", "type": "text", "default": "", "required": true },
         { "name": "tone", "type": "enum", "values": ["calm", "tense"], "default": "calm" },

package/conformance/extensions/manifest.json

@@ -24,20 +24,13 @@
       "problems": []
     },
     {
-      "name": "every type, a claim and a setting pass together",
+      "name": "every type passes together",
       "manifest": {
         "schema": "wildwinter/extension@0",
         "id": "probe",
         "name": "Probe",
         "version": "2.1.0",
         "docs": "https://example.com/probe",
-        "settings": [
-          {
-            "name": "moodField",
-            "label": "Mood field",
-            "default": "mood"
-          }
-        ],
         "targets": {
           "storylets": {
             "card": {
@@ -170,17 +163,6 @@
                     "type": "text"
                   }
                 }
-              ],
-              "claims": [
-                {
-                  "setting": "moodField",
-                  "type": "enum",
-                  "values": [
-                    "calm",
-                    "tense"
-                  ],
-                  "help": "The card's mood."
-                }
               ]
             },
             "project": {
@@ -1013,159 +995,6 @@
         }
       ]
     },
-    {
-      "name": "claims: a claimable kind, a declared setting, a scalar, once per setting",
-      "manifest": {
-        "schema": "wildwinter/extension@0",
-        "id": "probe",
-        "name": "Probe",
-        "version": "1.0.0",
-        "settings": [
-          {
-            "name": "moodField",
-            "default": "mood"
-          }
-        ],
-        "targets": {
-          "storylets": {
-            "deck": {
-              "claims": [
-                {
-                  "setting": "moodField",
-                  "type": "text"
-                }
-              ]
-            },
-            "card": {
-              "claims": [
-                {
-                  "setting": "moodField",
-                  "type": "text"
-                },
-                {
-                  "setting": "moodField",
-                  "type": "text"
-                },
-                {
-                  "setting": "nope",
-                  "type": "text"
-                },
-                {
-                  "setting": "moodField",
-                  "type": "record",
-                  "fields": [
-                    {
-                      "name": "a",
-                      "type": "text"
-                    }
-                  ]
-                }
-              ]
-            }
-          }
-        }
-      },
-      "problems": [
-        {
-          "path": "targets.storylets.deck.claims[0]",
-          "code": "claim-kind"
-        },
-        {
-          "path": "targets.storylets.card.claims[1].setting",
-          "code": "claim-duplicate"
-        },
-        {
-          "path": "targets.storylets.card.claims[2].setting",
-          "code": "claim-setting"
-        },
-        {
-          "path": "targets.storylets.card.claims[3].type",
-          "code": "claim-type"
-        },
-        {
-          "path": "targets.storylets.card.claims[3].setting",
-          "code": "claim-duplicate"
-        }
-      ]
-    },
-    {
-      "name": "settings: named once each, defaulting to a field name",
-      "manifest": {
-        "schema": "wildwinter/extension@0",
-        "id": "probe",
-        "name": "Probe",
-        "version": "1.0.0",
-        "settings": [
-          {
-            "name": "a",
-            "default": "x"
-          },
-          {
-            "name": "a",
-            "default": "y"
-          },
-          {
-            "name": "b"
-          },
-          {
-            "name": "c",
-            "default": "not a name"
-          }
-        ],
-        "targets": {
-          "storylets": {
-            "card": {}
-          }
-        }
-      },
-      "problems": [
-        {
-          "path": "settings[1].name",
-          "code": "setting-duplicate"
-        },
-        {
-          "path": "settings[2].default",
-          "code": "setting-default"
-        },
-        {
-          "path": "settings[3].default",
-          "code": "setting-default"
-        }
-      ]
-    },
-    {
-      "name": "an enum claim may leave out its values, and its value help may describe values the host does not declare",
-      "manifest": {
-        "schema": "wildwinter/extension@0",
-        "id": "probe",
-        "name": "Probe",
-        "version": "1.0.0",
-        "settings": [
-          {
-            "name": "moodField",
-            "default": "mood"
-          }
-        ],
-        "targets": {
-          "storylets": {
-            "card": {
-              "claims": [
-                {
-                  "setting": "moodField",
-                  "type": "enum",
-                  "label": "Mood",
-                  "valueHelp": {
-                    "calm": "Unhurried.",
-                    "wild": "Not one the host has."
-                  }
-                }
-              ]
-            }
-          }
-        }
-      },
-      "problems": []
-    },
     {
       "name": "an enum field of the extension's own still lists its values",
       "manifest": {
@@ -1745,6 +1574,51 @@
           "code": "not-a-list"
         }
       ]
+    },
+    {
+      "name": "settings and claims were removed: each warned of by name, and ignored",
+      "manifest": {
+        "schema": "wildwinter/extension@0",
+        "id": "probe",
+        "name": "Probe",
+        "version": "1.0.0",
+        "settings": [
+          {
+            "name": "moodField",
+            "default": "mood"
+          }
+        ],
+        "targets": {
+          "storylets": {
+            "card": {
+              "fields": [
+                {
+                  "name": "tone",
+                  "type": "text"
+                }
+              ],
+              "claims": [
+                {
+                  "setting": "moodField",
+                  "type": "enum"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "problems": [
+        {
+          "path": "settings",
+          "code": "removed-key",
+          "severity": "warning"
+        },
+        {
+          "path": "targets.storylets.card.claims",
+          "code": "removed-key",
+          "severity": "warning"
+        }
+      ]
     }
   ]
 }

package/conformance/extensions/values.json

@@ -937,92 +937,6 @@
       ]
     }
   ],
-  "claims": [
-    {
-      "name": "a claim without values takes the host's, and keeps its own label, help and value help",
-      "claim": {
-        "setting": "moodField",
-        "type": "enum",
-        "label": "Mood",
-        "help": "How it feels.",
-        "valueHelp": {
-          "calm": "Unhurried.",
-          "wild": "Unused."
-        }
-      },
-      "host": {
-        "type": "enum",
-        "values": [
-          "calm",
-          "tense"
-        ],
-        "default": "calm"
-      },
-      "effective": {
-        "setting": "moodField",
-        "type": "enum",
-        "label": "Mood",
-        "help": "How it feels.",
-        "valueHelp": {
-          "calm": "Unhurried.",
-          "wild": "Unused."
-        },
-        "values": [
-          "calm",
-          "tense"
-        ],
-        "default": "calm"
-      }
-    },
-    {
-      "name": "a claim's own values stand",
-      "claim": {
-        "setting": "moodField",
-        "type": "enum",
-        "values": [
-          "calm"
-        ]
-      },
-      "host": {
-        "type": "enum",
-        "values": [
-          "calm",
-          "tense"
-        ]
-      },
-      "effective": {
-        "setting": "moodField",
-        "type": "enum",
-        "values": [
-          "calm"
-        ]
-      }
-    },
-    {
-      "name": "a quality claim takes the host's ladder, as a claimed field keeps the host's",
-      "claim": {
-        "setting": "actField",
-        "type": "quality",
-        "label": "Act"
-      },
-      "host": {
-        "type": "quality",
-        "stages": [
-          "setup",
-          "turn"
-        ]
-      },
-      "effective": {
-        "setting": "actField",
-        "type": "quality",
-        "label": "Act",
-        "stages": [
-          "setup",
-          "turn"
-        ]
-      }
-    }
-  ],
   "picks": [
     {
       "name": "choices in source order, each source's in its own",

package/dist/extensions.cjs

@@ -14,13 +14,11 @@ var MANIFEST_FILE_SUFFIX = ".extension.json";
 var HOSTS = {
   patter: {
     kinds: ["scene", "block", "snippet", "line", "text", "gameEvent", "option", "project"],
-    references: ["cast", "scene", "block", "snippet", "line"],
-    claimable: ["scene", "block", "snippet", "line", "text", "gameEvent", "option"]
+    references: ["cast", "scene", "block", "snippet", "line"]
   },
   storylets: {
     kinds: ["box", "tagGroup", "tag", "deck", "card", "outcome", "handTemplate", "hand", "project"],
-    references: ["box", "deck", "card", "outcome", "tag"],
-    claimable: ["card", "outcome"]
+    references: ["box", "deck", "card", "outcome", "tag"]
   }
 };
 var SCALAR_TYPES = ["text", "multiline", "number", "boolean", "enum", "flags", "quality"];
@@ -368,9 +366,14 @@ var VERSION = /^\d+\.\d+\.\d+$/;
 var NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var TYPE_KEYS = ["type", "values", "stages", "renamedStages", "to", "from", "fields", "key", "of", "id", "min", "max", "valueHelp", "default"];
 var FIELD_KEYS = /* @__PURE__ */ new Set([...TYPE_KEYS, "name", "label", "help", "required", "group", "editorOnly"]);
-var CLAIM_KEYS = /* @__PURE__ */ new Set([...TYPE_KEYS, "setting", "label", "help", "required"]);
 var BARE_KEYS = new Set(TYPE_KEYS);
-var MANIFEST_KEYS = /* @__PURE__ */ new Set(["schema", "id", "name", "version", "docs", "settings", "targets", "views", "reads"]);
+var MANIFEST_KEYS = /* @__PURE__ */ new Set(["schema", "id", "name", "version", "docs", "targets", "views", "reads"]);
+var REMOVED_MANIFEST_KEYS = {
+  settings: "settings were removed with claims; declare the extension's own fields, or a project field for a project-wide value"
+};
+var REMOVED_TARGET_KEYS = {
+  claims: "claims on host fields were removed; declare a field of the extension's own, which the runtimes hand the game"
+};
 var VIEW_KEYS = /* @__PURE__ */ new Set(["id", "name", "entry", "element", "hosts"]);
 var ELEMENT = /^[a-z][a-z0-9._]*-[a-z0-9._-]*$/;
 var err2 = (code, path, message) => ({ severity: "error", code, path, message });
@@ -381,7 +384,7 @@ function manifestProblems(manifest) {
   const out = [];
   if (!isObject(manifest)) return [err2("not-an-object", "", "a manifest is a JSON object")];
   const m = manifest;
-  unknownKeys(m, MANIFEST_KEYS, "", out);
+  unknownKeys(m, MANIFEST_KEYS, "", out, REMOVED_MANIFEST_KEYS);
   if (m["schema"] !== MANIFEST_SCHEMA) {
     out.push(err2("schema", "schema", `the schema tag is ${JSON.stringify(m["schema"])}, not "${MANIFEST_SCHEMA}"`));
   }
@@ -393,7 +396,6 @@ function manifestProblems(manifest) {
     out.push(err2("version", "version", "the version is major.minor.patch, such as 1.0.0"));
   }
   if (m["docs"] !== void 0 && typeof m["docs"] !== "string") out.push(err2("docs", "docs", "docs is a link, as text"));
-  const settings = settingsProblems(m["settings"], out);
   viewsProblems(m["views"], m["targets"], out);
   readsProblems(m["reads"], m["id"], out);
   const targets = m["targets"];
@@ -418,7 +420,7 @@ function manifestProblems(manifest) {
         out.push(err2("unknown-kind", kindPath, `"${kind}" is not a node kind of ${host}; it has ${spec.kinds.join(", ")}`));
         continue;
       }
-      targetProblems(host, kind, target, kindPath, settings, out);
+      targetProblems(host, target, kindPath, out);
     }
     pickListProblems(kinds, hostPath, out);
   }
@@ -564,81 +566,23 @@ function viewsFor(manifest, host) {
   const targeted = Object.keys(manifest.targets ?? {});
   return (Array.isArray(manifest.views) ? manifest.views : []).filter((v) => isObject(v) && typeof v.id === "string" && ID.test(v.id) && typeof v.name === "string" && isViewEntry(v.entry) && typeof v.element === "string" && ELEMENT.test(v.element) && (v.hosts === void 0 ? targeted.includes(host) : Array.isArray(v.hosts) && v.hosts.includes(host)));
 }
-function unknownKeys(obj, known, path, out) {
+function unknownKeys(obj, known, path, out, removed = {}) {
   for (const k of Object.keys(obj)) {
-    if (!known.has(k)) {
+    if (own(removed, k)) {
+      out.push({ severity: "warning", code: "removed-key", path: atKey(path, k), message: `"${k}" is ignored: ${removed[k]}` });
+    } else if (!known.has(k)) {
       out.push({ severity: "warning", code: "unknown-key", path: atKey(path, k), message: `"${k}" means nothing here; it is ignored` });
     }
   }
 }
-function settingsProblems(settings, out) {
-  const names = /* @__PURE__ */ new Set();
-  if (settings === void 0) return names;
-  if (!Array.isArray(settings)) {
-    out.push(err2("not-a-list", "settings", "settings are a list"));
-    return names;
-  }
-  settings.forEach((s, i) => {
-    const at = atIndex("settings", i);
-    if (!isObject(s)) {
-      out.push(err2("not-an-object", at, "a setting is an object"));
-      return;
-    }
-    const name = s["name"];
-    if (typeof name !== "string" || !NAME.test(name)) {
-      out.push(err2("setting-name", atKey(at, "name"), "a setting's name is an identifier"));
-    } else if (names.has(name)) {
-      out.push(err2("setting-duplicate", atKey(at, "name"), `setting "${name}" is declared twice`));
-    } else {
-      names.add(name);
-    }
-    const dflt = s.default;
-    if (typeof dflt !== "string" || !NAME.test(dflt)) {
-      out.push(err2("setting-default", atKey(at, "default"), "a setting names a host field by default, so its default is a field name"));
-    }
-  });
-  return names;
-}
-function targetProblems(host, kind, target, path, settings, out) {
+function targetProblems(host, target, path, out) {
   if (!isObject(target)) {
     out.push(err2("not-an-object", path, "a target is an object"));
     return;
   }
-  unknownKeys(target, /* @__PURE__ */ new Set(["fields", "claims"]), path, out);
+  unknownKeys(target, /* @__PURE__ */ new Set(["fields"]), path, out, REMOVED_TARGET_KEYS);
   const t = target;
   if (t.fields !== void 0) fieldListProblems(host, t.fields, atKey(path, "fields"), true, out);
-  if (t.claims === void 0) return;
-  if (!Array.isArray(t.claims)) {
-    out.push(err2("not-a-list", atKey(path, "claims"), "claims are a list"));
-    return;
-  }
-  const claimable = HOSTS[host].claimable.includes(kind);
-  const claimed = /* @__PURE__ */ new Set();
-  t.claims.forEach((c, i) => {
-    const at = atIndex(atKey(path, "claims"), i);
-    if (!claimable) {
-      out.push(err2("claim-kind", at, `a ${kind} has no host fields to claim; ${host} has them on ${HOSTS[host].claimable.join(", ")}`));
-      return;
-    }
-    if (!isObject(c)) {
-      out.push(err2("not-an-object", at, "a claim is an object"));
-      return;
-    }
-    const claim = c;
-    unknownKeys(c, CLAIM_KEYS, at, out);
-    if (!SCALAR_TYPES.includes(claim.type)) {
-      out.push(err2("claim-type", atKey(at, "type"), "a claim presents a host field, which is a scalar"));
-    } else {
-      typeProblems(host, claim, at, false, out, true);
-    }
-    if (typeof claim.setting !== "string" || !settings.has(claim.setting)) {
-      out.push(err2("claim-setting", atKey(at, "setting"), `a claim names its field through a setting, and "${String(claim.setting)}" is not one of the manifest's settings`));
-    } else if (claimed.has(claim.setting)) {
-      out.push(err2("claim-duplicate", atKey(at, "setting"), `setting "${claim.setting}" is claimed twice for one kind`));
-    } else {
-      claimed.add(claim.setting);
-    }
-  });
 }
 function fieldListProblems(host, fields, path, topLevel, out) {
   if (!Array.isArray(fields)) {
@@ -672,7 +616,7 @@ function fieldListProblems(host, fields, path, topLevel, out) {
     }
   });
 }
-function typeProblems(host, decl, path, named, out, claim = false) {
+function typeProblems(host, decl, path, named, out) {
   const typeAt = atKey(path, "type");
   if (decl.type === "string") {
     out.push(err2("string-type", typeAt, 'the text type is spelled "text"'));
@@ -688,7 +632,6 @@ function typeProblems(host, decl, path, named, out, claim = false) {
     case "enum":
     case "flags": {
       const values = decl.values;
-      if (claim && values === void 0) break;
       if (!Array.isArray(values) || values.length === 0) {
         out.push(err2("values-empty", at("values"), `an ${decl.type === "enum" ? "enum" : "flags field"} lists its values`));
         sound = false;
@@ -707,7 +650,6 @@ function typeProblems(host, decl, path, named, out, claim = false) {
       break;
     }
     case "quality": {
-      if (claim && decl.stages === void 0) break;
       for (const p of expr.qualityDeclarationProblems(decl.stages)) {
         out.push(err2(
           `quality-${p.kind === "default-not-a-stage" ? "default" : p.kind}`,
@@ -770,11 +712,7 @@ function typeProblems(host, decl, path, named, out, claim = false) {
     }
   }
   if (decl.renamedStages !== void 0) renamedStagesProblems(decl, at("renamedStages"), out);
-  if (decl.valueHelp !== void 0 && claim) {
-    if (!isObject(decl.valueHelp) || !["enum", "flags", "quality"].includes(decl.type)) {
-      out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, or a quality's stages"));
-    }
-  } else if (decl.valueHelp !== void 0) {
+  if (decl.valueHelp !== void 0) {
     const vocabulary = decl.type === "quality" ? decl.stages : decl.type === "enum" || decl.type === "flags" ? decl.values : decl.type === "pick" ? pickWords(decl.from) : void 0;
     if (vocabulary === void 0 || !isObject(decl.valueHelp)) {
       out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, a quality's stages, or a pick's words"));
@@ -815,56 +753,10 @@ function renamedStagesProblems(decl, path, out) {
     }
   }
 }
-function settingValues(manifest, chosen) {
-  const out = {};
-  for (const s of manifest.settings ?? []) {
-    const v = chosen !== void 0 && own(chosen, s.name) ? chosen[s.name] : void 0;
-    out[s.name] = typeof v === "string" && v !== "" ? v : s.default;
-  }
-  return out;
-}
-function resolvedClaims(manifest, host, chosen) {
-  const settings = settingValues(manifest, chosen);
-  const out = [];
-  for (const [kind, target] of Object.entries(manifest.targets[host] ?? {})) {
-    for (const claim of target.claims ?? []) {
-      const field = settings[claim.setting];
-      if (field !== void 0) out.push({ extension: manifest.id, host, kind, field, claim });
-    }
-  }
-  return out;
-}
-function claimClashes(claims) {
-  const out = [];
-  const first = /* @__PURE__ */ new Map();
-  for (const c of claims) {
-    const key = `${c.host}\0${c.kind}\0${c.field}`;
-    const prior = first.get(key);
-    if (prior === void 0) {
-      first.set(key, c);
-      continue;
-    }
-    if (prior.extension === c.extension) continue;
-    out.push(err2(
-      "claim-clash",
-      `${c.kind}.${c.field}`,
-      `extensions "${prior.extension}" and "${c.extension}" both claim the ${c.kind} field "${c.field}"`
-    ));
-  }
-  return out;
-}
 function targetOf(manifest, host, kind) {
   const kinds = manifest?.targets[host];
   return kinds !== void 0 && own(kinds, kind) ? kinds[kind] : void 0;
 }
-function effectiveClaim(claim, hostDecl) {
-  return {
-    ...claim,
-    ...claim.values === void 0 && hostDecl.values !== void 0 ? { values: hostDecl.values } : {},
-    ...claim.stages === void 0 && hostDecl.stages !== void 0 ? { stages: hostDecl.stages } : {},
-    ...claim.default === void 0 && hostDecl.default !== void 0 ? { default: hostDecl.default } : {}
-  };
-}
 
 // src/extensions/merge.ts
 var ATOMIC = { kind: "atomic" };
@@ -1214,11 +1106,9 @@ exports.UNRESOLVED_KEY = UNRESOLVED_KEY;
 exports.VALUE_TYPES = VALUE_TYPES;
 exports.atIndex = atIndex;
 exports.atKey = atKey;
-exports.claimClashes = claimClashes;
 exports.compileEntry = compileEntry;
 exports.compiledTarget = compiledTarget;
 exports.defaultOf = defaultOf;
-exports.effectiveClaim = effectiveClaim;
 exports.entryProblems = entryProblems;
 exports.extensionDataStrategy = extensionDataStrategy;
 exports.isTextList = isTextList;
@@ -1237,8 +1127,6 @@ exports.pickChoices = pickChoices;
 exports.pickClashes = pickClashes;
 exports.pickLists = pickLists;
 exports.renameStages = renameStages;
-exports.resolvedClaims = resolvedClaims;
-exports.settingValues = settingValues;
 exports.stableStringify = stableStringify;
 exports.strategyForTarget = strategyForTarget;
 exports.strategyForType = strategyForType;