@wildwinter/toolkit 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# @wildwinter/toolkit
+
+## 0.2.1
+
+### Changed
+
+- **A claim may leave out an enum's or flags' `values`, and a quality's `stages`** (`./extensions`): the host
+  field's declaration is then the vocabulary, and the claim adds its label, help and value help, which may
+  describe values the host does not declare. `effectiveClaim(claim, hostDecl)` merges the two. An extension's
+  own fields still list their values.
+
+## 0.2.0
+
+### Added
+
+- **`@wildwinter/toolkit/extensions`**: the shared spec and merge for Patter extensions and Storylet
+  extensions ([extensions.md](extensions.md)). The manifest and its checks (`manifestProblems`), the value types
+  and their checks (`valueProblems`, `entryProblems`) on the kernel's `valueFits`, `qualityDeclarationProblems`
+  and `stagesEitherSide`, defaults (`defaultOf`, through `defaultFor`), what a bundle carries (`compiledTarget`,
+  `compileEntry`), stage renames (`renameStages`), claims on host fields (`resolvedClaims`, `claimClashes`), the
+  three-way merge engine (`mergeTree`) and its manifest-built strategies (`mergeExtensionData`), the
+  `unresolved` mark (`markUnresolved`, `unresolvedProblems`) and orphaned entries (`orphanedEntries`).
+  Hand-written conformance cases in `conformance/extensions/`. `@wildwinter/expr` and
+  `@wildwinter/scoperegistry` are optional peer dependencies, needed by this entry only.
+
+## 0.1.0
+
+First release. Small shared pieces of the authoring tooling, each of which
+arrived by being found duplicated across the two consuming product families
+rather than by being anticipated.
+
+Nothing here runs in a game, and nothing here is about the expression language:
+that is `@wildwinter/expr`, and game-side sharing is the vendored source in
+`expr/ports`, because C++, C# and GDScript cannot consume an npm package.
+
+### Added
+
+- **`newId` / `slug`** (`ids.ts`): opaque, rejection-sampled base-36 ids, so
+  every alphabet character is equally likely. A plain `byte % 36` over-weights
+  the first four.
+- **`fnv32`** (`hash.ts`): FNV-1a, for short stable handles and change
+  detection. Not cryptographic.
+- **`parseSource`** (`source.ts`): JSON5 with a tolerated byte-order mark, which
+  JSON5 alone will not accept and Windows editors add.
+- **`findMatcher`** (`find.ts`): the escaped, global find regex behind find and
+  replace, so a query of `a.b` means those three characters.
+- **`@wildwinter/toolkit/archive`**: the zip entry guards (`isUnsafeEntry`,
+  `escapesTarget`) and the settings that make an archive byte-reproducible. A
+  separate entry point because it needs `node:path`, and the main entry stays
+  isomorphic so a browser bundle can take it.
+
+  The guards were correct in both families before this, which is the state
+  BEFORE a drift rather than evidence there will not be one: a subtle weakening
+  of one copy is a vulnerability nobody reads a diff for.

package/README.md

@@ -3,7 +3,8 @@
 Small shared pieces of the **authoring tooling** behind
 [Storylet Studio](https://github.com/storylet-studio) and
 [Patter](https://patterkit.com): opaque ids, a stable hash, JSON5 source parsing,
-find/replace matching, and the archive guards.
+find/replace matching, the archive guards, and (in `./extensions`) the spec and merge
+for Patter extensions and Storylet extensions.
 
 **Nothing here runs in a game.** This is the editor/CLI/pipeline side. The
 runtime language lives in [`@wildwinter/expr`](../expr), and unlike that package
@@ -15,7 +16,21 @@ Each was found duplicated, almost but not exactly, across both families. That
 one careless edit away from being correct in one, and nobody reads the diff of a
 file they believe is a copy.
 
-ESM + CJS + types. `json5` is the only dependency.
+ESM + CJS + types. `json5` is the only dependency of the main entry.
+
+## Extensions (`@wildwinter/toolkit/extensions`)
+
+The one part with shared semantics: the manifest a Patter extension or a Storylet extension ships, the types its
+values take, the checks both editors and both command lines run, and the type-driven three-way merge both formats
+use for extension data, with the `unresolved` mark an unresolved merge leaves in a shard. The spec is
+[extensions.md](extensions.md) and its contract the hand-written cases in `conformance/extensions/`.
+
+It is built on the kernel's own value and ladder rules, so it needs `@wildwinter/expr` and
+`@wildwinter/scoperegistry`: optional peer dependencies, which every host of it already has.
+
+```ts
+import { manifestProblems, mergeExtensionData } from "@wildwinter/toolkit/extensions";
+```
 
 ```ts
 import { newId, slug, fnv32, parseSource, findMatcher } from "@wildwinter/toolkit";

package/conformance/extensions/defaults.json

@@ -0,0 +1,69 @@
+{
+  "about": "Defaults, compilation and stage renames. `defaults`: defaultOf for a declaration. `compile`: compiledTarget (declarations as a bundle carries them: editor-only fields gone, every default resolved, label, help, valueHelp and group gone) and compileEntry (a node's values as a bundle carries them: editor-only and undeclared fields gone, renamed stages renamed, otherwise raw). `renames`: renameStages over an entry, with the renames it made.",
+  "defaults": [
+    { "name": "a given default wins", "decl": { "name": "a", "type": "number", "default": 4 }, "default": 4 },
+    { "name": "text", "decl": { "name": "a", "type": "text" }, "default": "" },
+    { "name": "multiline", "decl": { "name": "a", "type": "multiline" }, "default": "" },
+    { "name": "number", "decl": { "name": "a", "type": "number" }, "default": 0 },
+    { "name": "boolean", "decl": { "name": "a", "type": "boolean" }, "default": false },
+    { "name": "enum: the first value", "decl": { "name": "a", "type": "enum", "values": ["x", "y"] }, "default": "x" },
+    { "name": "an enum may default to none chosen", "decl": { "name": "a", "type": "enum", "values": ["x", "y"], "default": "" }, "default": "" },
+    { "name": "flags: none", "decl": { "name": "a", "type": "flags", "values": ["x"] }, "default": [] },
+    { "name": "quality: the first stage", "decl": { "name": "a", "type": "quality", "stages": ["p", "q"] }, "default": "p" },
+    { "name": "reference: none", "decl": { "name": "a", "type": "reference", "to": "card" }, "default": "" },
+    { "name": "record: each field's default", "decl": { "name": "a", "type": "record", "fields": [
+      { "name": "s", "type": "text" }, { "name": "n", "type": "number", "default": 2 }, { "name": "q", "type": "quality", "stages": ["p", "q"] }
+    ] }, "default": { "n": 2, "q": "p", "s": "" } },
+    { "name": "record: a given default wins whole", "decl": { "name": "a", "type": "record", "fields": [{ "name": "s", "type": "text" }], "default": { "s": "x" } }, "default": { "s": "x" } },
+    { "name": "map: empty", "decl": { "name": "a", "type": "map", "key": { "type": "text" }, "of": { "type": "number" } }, "default": {} },
+    { "name": "list: empty", "decl": { "name": "a", "type": "list", "of": { "type": "number" } }, "default": [] }
+  ],
+  "compile": [
+    {
+      "name": "a target as the bundle carries it",
+      "target": { "fields": [
+        { "name": "note", "type": "text", "label": "Note", "help": "Help.", "group": "G", "required": true },
+        { "name": "draft", "type": "multiline", "editorOnly": true },
+        { "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" },
+        { "name": "act", "type": "quality", "stages": ["setup", "turn"], "default": "setup" },
+        { "name": "cue", "type": "record", "fields": [{ "name": "gain", "type": "number", "min": 0, "default": 0 }], "default": { "gain": 0 } }
+      ],
+      "entry": { "note": "n", "draft": "only in the editor", "act": "opening", "stray": 1, "cue": { "gain": 2 } },
+      "compiledEntry": { "act": "setup", "cue": { "gain": 2 }, "note": "n" }
+    },
+    {
+      "name": "an entry with nothing compiled compiles to nothing",
+      "target": { "fields": [{ "name": "draft", "type": "text", "editorOnly": true }] },
+      "compiled": [],
+      "entry": { "draft": "x" },
+      "compiledEntry": null
+    }
+  ],
+  "renames": [
+    {
+      "name": "stages renamed wherever a quality is, at any depth",
+      "target": { "fields": [
+        { "name": "act", "type": "quality", "stages": ["setup", "turn"], "renamedStages": { "opening": "setup", "middle": "turn" } },
+        { "name": "beats", "type": "list", "id": "id", "of": { "type": "record", "fields": [
+          { "name": "id", "type": "text" },
+          { "name": "phase", "type": "quality", "stages": ["in", "out"], "renamedStages": { "enter": "in" } }
+        ] } },
+        { "name": "byTag", "type": "map", "key": { "type": "text" }, "of": { "type": "quality", "stages": ["lo", "hi"], "renamedStages": { "low": "lo" } } },
+        { "name": "tone", "type": "text" }
+      ] },
+      "entry": { "act": "middle", "beats": [{ "id": "b1", "phase": "enter" }, { "id": "b2", "phase": "out" }], "byTag": { "a": "low", "b": "hi" }, "tone": "opening" },
+      "renamed": { "act": "turn", "beats": [{ "id": "b1", "phase": "in" }, { "id": "b2", "phase": "out" }], "byTag": { "a": "lo", "b": "hi" }, "tone": "opening" },
+      "renames": [
+        { "path": "act", "from": "middle", "to": "turn" },
+        { "path": "beats[0].phase", "from": "enter", "to": "in" },
+        { "path": "byTag.a", "from": "low", "to": "lo" }
+      ]
+    }
+  ]
+}