@heroiclands/package-build 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # @heroiclands/package-build
 
+## 8.1.0
+
+### Minor Changes
+
+- 333c340: Follow a spread of an imported schema function, and refuse a computed field name.
+  
+  Two defects in `package-build schema`, both found by running it against real
+  content rather than by reading it.
+  
+  **A shared base schema spread from another file was dropped, in silence.** A
+  concrete DataModel spreads a shared builder by name — `...defineSohlDataSchema()`
+  — and the resolver looked for that function only in the file doing the
+  spreading. When it was imported, the lookup found nothing and the spread
+  contributed nothing, with no error: a spread of a missing function read exactly
+  like a spread of an empty one.
+  
+  The effect was not small. Every SoHL Item and Actor subtype lost `shortcode`,
+  `actionDefs`, `lastRun` and `scheduledActions` from the published schema. So
+  content correctly authoring `system.shortcode` — which SoHL requires to be
+  unique per `(type, shortcode)` on an actor, and which content therefore sets
+  deliberately — was reported as emitting a field no DataModel declares. The check
+  was accusing the content of the reader's own blind spot, which is worse than not
+  checking: it is a false accusation delivered with the same confidence as a true
+  one.
+  
+  An imported spread is now resolved through the import, with a same-file
+  definition still taking precedence.
+  
+  **A computed field name is now refused rather than published as source text.**
+  `[`${name}Date`]: worldTimeDateField()` takes its real name from an argument
+  this reader does not evaluate, and the previous behaviour handed back the source
+  text — putting a field called ``[`${name}Date`]`` into the schema. That field
+  matches nothing any builder could emit: absent for checking purposes while
+  looking present, and permanently reported as unemitted.
+  
+  It now stops, naming the file and the key:
+  
+  ```text
+  temporal-fields.ts declares a schema field with a computed name,
+  `[`${name}DurationFormula`]`, whose value depends on an argument this reader
+  does not evaluate. Write the keys out so the published schema can name them.
+  ```
+  
+  Stopping is the same stance `compareFields` already takes on an artifact of the
+  wrong version: the schema is a contract other repositories read, so a contract
+  this cannot state is worth failing for rather than approximating. The fix
+  belongs at the source, where the names are actually decided.
+  
+  **Bump**
+  
+  _Minor._ Repositories whose schemas spread an imported builder will publish more
+  fields than before — which is the correction. A repository using computed field
+  names now fails where it previously produced a wrong artifact; none does today
+  except the one this was found on, and that is being fixed at the source.
+
+### Patch Changes
+
+- 2319a56: Bump `markdown-it` from 15.0.0 to 15.0.1 (#121).
+  
+  The surface is unchanged from the 15.0.0 adoption: one constructor,
+  `markdownit({ html: true })` in `engine/helpers.mjs`, and three `md.render()`
+  call sites — `engine/helpers.mjs`, `engine/journals.mjs` and `sohl/actors.mjs`.
+  No plugin is installed, no renderer rule is overridden, and `linkify` is left at
+  its default `false`. That last fact decides most of this release.
+  
+  **Two of the five changes cannot reach a build that never linkifies.**
+  
+  | Release note                                              | Reaches here?                                                    |
+  | --------------------------------------------------------- | ---------------------------------------------------------------- |
+  | _Security:_ quadratic complexity replacing fuzzy links    | No — `linkify` is `false`, so the fuzzy-link replacer never runs |
+  | _Security:_ quadratic complexity in scheme backscan       | No — same; the rule is the inline **linkify** rule               |
+  | Preserve brackets around IPv6 literals in `normalizeLink` | Yes, in principle — no content in any consumer writes one        |
+  | Preserve spaces in all-space code spans (#1180)           | Yes, for runs of three or more spaces only                       |
+  | Code spans after unclosed link/image labels (#1201)       | Yes, for an unclosed `[` followed by an odd-length backtick run  |
+  
+  Calling the first two "security" fixes is upstream's framing and the honest
+  reading of it here is that this package was never exposed: both are complexity
+  bounds on `linkify-it` code paths that are unreachable with the linkifier off.
+  Taking the bump is hygiene, not remediation.
+  
+  **The three real fixes were measured, not assumed.** Both versions were rendered
+  through `markdownit({ html: true })` — this package's exact configuration — and
+  compared:
+  
+  ```text
+  a `   ` b   15.0.0 → <p>a <code> </code> b</p>      15.0.1 → <p>a <code>   </code> b</p>
+  [`a`b`      15.0.0 → <p>[`a`b`</p>                  15.0.1 → <p>[<code>a</code>b`</p>
+  [x](http://[::1]/)
+              15.0.0 → href="http://%5B::1%5D/"       15.0.1 → href="http://[::1]/"
+  ```
+  
+  Each has a narrow trigger. The code-span fix moves output only at three spaces
+  or more — 15.0.0 stripped one space from each end of an all-space span, so one-
+  and two-space spans were already correct and stay byte-identical. The unclosed-
+  label fix needs the backtick run to be **odd**: `[Sword `hp`and`ac`` renders
+  the same on both, because its four backticks close. And the IPv6 fix only fires
+  on a bracketed address literal in a link, image or autolink destination, which
+  15.0.0 percent-encoded into a host no browser resolves.
+  
+  **Verified against every consumer, and against a search rather than a guess.**
+  All 14,995 `.md` files across the six HeroicLands content repositories — `sohl`,
+  `hm3`, `thalorna`, `kethira`, `harnensemble` and `harnadventures` — were parsed
+  the way `parseMarkdownFile` parses them and rendered through both versions.
+  Every one is byte-identical. Scanning the same corpus explains why rather than
+  leaving it to luck: zero files contain an IPv6 URL, zero contain an all-space
+  code span of three or more spaces, and the 109 files that do use `` ` ` `` use
+  the one-space form the fix does not touch. Beyond the corpus, an exhaustive
+  render of all 488,280 strings up to eight characters over `[`, `]`, `` ` ``,
+  `x` and `!` — the alphabet the label-and-backtick fix is about — found the
+  divergence set to be exactly the shapes above and nothing else. The repository's
+  1,713 tests pass unchanged.
+  
+  **Bump**
+  
+  _Patch, not minor._ No export, option, or emitted document changes shape. The
+  only behaviour that moves is markdown that was rendered wrongly before, on
+  constructs no consumer writes, and the two changes advertised as security fixes
+  are unreachable from this configuration.
+
 ## 8.0.0
 
 ### Major Changes

package/engine/schema-extract.mjs

@@ -95,6 +95,37 @@ function propName(name) {
     return name.getText();
 }
 
+/**
+ * A *field* name, which unlike a property name elsewhere must be knowable.
+ *
+ * A computed key — `[`${name}Date`]: worldTimeDateField()` — depends on an
+ * argument this reader does not evaluate, so its real name is not in the file.
+ * {@link propName} would hand back the source text, and a field called
+ * ``[`${name}Date`]`` matches nothing a builder could ever emit: it is absent
+ * from the schema for checking purposes while *looking* present, and it shows
+ * up as permanently unemitted noise.
+ *
+ * So this refuses rather than guessing. The schema is a contract other
+ * repositories read, and a contract it cannot state is worth stopping for —
+ * the same reason `compareFields` refuses an artifact of the wrong version
+ * instead of resolving it anyway. Writing the keys out fixes it at the source,
+ * where the names are actually decided.
+ *
+ * @param {ts.PropertyName} name - The property name node.
+ * @param {string} file - For the message.
+ * @returns {string} The literal field name.
+ * @throws {Error} When the name is computed.
+ */
+function fieldName(name, file) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+    throw new Error(
+        `${path.basename(file)} declares a schema field with a computed name, ` +
+            `\`${name.getText()}\`, whose value depends on an argument this ` +
+            `reader does not evaluate. Write the keys out so the published ` +
+            `schema can name them.`,
+    );
+}
+
 /**
  * The `subtype: ClassName` entries of a registry object literal.
  *
@@ -424,16 +455,16 @@ function isSchemaField(expr) {
 }
 
 /** The keys of a `new SchemaField({ … })`, recursively dotted. */
-function nestedKeysOf(expr) {
+function nestedKeysOf(expr, file) {
     if (!isSchemaField(expr)) return [];
     const arg = expr.arguments?.[0];
     if (!arg || !ts.isObjectLiteralExpression(arg)) return [];
     const out = [];
     for (const p of arg.properties) {
         if (!ts.isPropertyAssignment(p)) continue;
-        const key = propName(p.name);
+        const key = fieldName(p.name, file);
         out.push(key);
-        for (const child of nestedKeysOf(p.initializer)) {
+        for (const child of nestedKeysOf(p.initializer, file)) {
             out.push(`${key}.${child}`);
         }
     }
@@ -445,7 +476,7 @@ function nestedKeysOf(expr) {
  *
  * @returns {{own: string[], edges: object[]}}
  */
-function readLiteral(literal) {
+function readLiteral(literal, file) {
     const own = [];
     const edges = [];
     for (const p of literal.properties) {
@@ -455,9 +486,9 @@ function readLiteral(literal) {
             continue;
         }
         if (!ts.isPropertyAssignment(p)) continue;
-        const key = propName(p.name);
+        const key = fieldName(p.name, file);
         own.push(key);
-        for (const child of nestedKeysOf(p.initializer)) {
+        for (const child of nestedKeysOf(p.initializer, file)) {
             own.push(`${key}.${child}`);
         }
     }
@@ -505,7 +536,7 @@ export function fieldsForClass({ file, className, aliases, cache, rootDir }) {
 
     /** Walk a schema literal, following the spreads inside it. */
     const walkLiteral = (located, literal, into, superName) => {
-        const { own: fields, edges } = readLiteral(literal);
+        const { own: fields, edges } = readLiteral(literal, located.file);
         into.push(...fields);
         for (const edge of edges) followEdge(located, edge, superName);
     };
@@ -516,12 +547,34 @@ export function fieldsForClass({ file, className, aliases, cache, rootDir }) {
             const key = `local:${located.file}:${edge.name}`;
             if (seen.has(key)) return;
             seen.add(key);
-            // A local spread inside a subtype's own definition is still the
-            // parent's contribution — a shared `defineXDataSchema()` is where
-            // the common fields come from — so it lands in `inherited`
-            // whichever file it is written in.
+            // A spread of a schema-building function is the parent's
+            // contribution — a shared `defineXDataSchema()` is where the common
+            // fields come from — so it lands in `inherited` whichever file it
+            // is written in.
             const lit = literalReturnedBy(located.src, edge.name);
-            if (lit) walkLiteral(located, lit, inherited, superName);
+            if (lit) {
+                walkLiteral(located, lit, inherited, superName);
+                return;
+            }
+            // Not declared here, so it was imported. Following it matters more
+            // than it looks: the shared base schema is spread by name from the
+            // file that exports it, and resolving only same-file functions
+            // dropped it **entirely and in silence** — every SoHL subtype lost
+            // `shortcode` and `actionDefs`, so content correctly authoring
+            // `system.shortcode` was reported as undeclared. A spread that
+            // resolves to nothing must not read as a spread of nothing.
+            const from = importSourceOf(located.src, edge.name, aliases);
+            if (!from) return;
+            const importedSrc = parse(from, cache);
+            const importedLit = literalReturnedBy(importedSrc, edge.name);
+            if (importedLit) {
+                walkLiteral(
+                    { file: from, src: importedSrc },
+                    importedLit,
+                    inherited,
+                    superName,
+                );
+            }
             return;
         }
         const name = edge.kind === "super" ? superName : edge.name;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "8.0.0",
+    "version": "8.1.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",