@heroiclands/package-build 8.0.0 → 9.0.0

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # @heroiclands/package-build
 
+## 9.0.0
+
+### Major Changes
+
+- 8e48f7e: Raise the shared `printWidth` from 80 to 100.
+  
+  **Breaking for every consumer**, in the one way this configuration always is: a
+  repository that updates and runs `lint:format` will find every file reported
+  until it reformats. Nothing about a built package, an emitted document or a
+  manifest changes — this is hygiene, and it reaches users not at all.
+  
+  **80 was inherited, not chosen.** The usual argument for it is reading measure,
+  and that argument does not apply here: `proseWrap` is left at Prettier's default
+  of `preserve`, so authored prose is **never reflowed**. Measured across the
+  content trees, prose lines run to a p90 of 378 characters and a maximum of
+  5,531, entirely untouched by this number. What `printWidth` actually governs is
+  TypeScript and the YAML of a note's frontmatter.
+  
+  **Both were measurably cramped.** Reformatting a third of the SoHL source at
+  each width:
+  
+  | width | total lines | vs 80 | lines still over width |
+  | ----- | ----------- | ----- | ---------------------- |
+  | 80    | 31,198      | —     | **1,399**              |
+  | 90    | 30,328      | −2.8% | 193                    |
+  | 100   | 29,672      | −4.9% | 75                     |
+  | 120   | 28,850      | −7.5% | 25                     |
+  
+  The last column is the argument. At 80, Prettier _cannot_ honour the limit on
+  1,399 lines — long string literals, `@src/…` specifiers, generic signatures — so
+  those lines are over-width regardless and their surroundings were broken up for
+  nothing. At 100 that falls to 75.
+  
+  The same knee appears in content. An item entry written in flow style —
+  `{ shortcode: X, type: skill, name: …, system: { … } }` — typically lands in the
+  low 90s, so of 318,030 entries across the two largest trees, 90.8% fit on one
+  line at 80 and **95.3% at 100**, with almost nothing gained in between. 120 buys
+  another 0.8 points and is not worth a second reformat.
+  
+  **This package's own config stops restating the values.** `prettier.config.js`
+  carried its own copy of all twelve options with a comment saying they were
+  "matched to" the SoHL repository — already the wrong authority once
+  `PRETTIER_BASE` existed here, and a copy is a copy: raising the width would have
+  left the package that _defines_ the shared style as the one repository not
+  written in it. It now re-exports `PRETTIER_CONFIG`, so there is nothing left to
+  drift.
+  
+  This release reformats this repository: 147 files, 2,677 lines shorter.
+  
+  **Bump**
+  
+  _Major._ Consumers' `lint:format` fails until they reformat, which is the whole
+  of the breakage and is a one-command fix.
+
+## 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/bin/content-build.mjs

@@ -59,11 +59,7 @@ import log from "loglevel";
 import prefix from "loglevel-plugin-prefix";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
-import {
-    compilePacks,
-    cleanPacks,
-    unpackPacks,
-} from "../engine/compendiums.mjs";
+import { compilePacks, cleanPacks, unpackPacks } from "../engine/compendiums.mjs";
 import { loadPackConfig } from "../engine/pack-config.mjs";
 import {
     fetchAllCatalogs,
@@ -93,11 +89,7 @@ import {
     gatesFailed,
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
-import {
-    auditLinks,
-    buildLinkIndex,
-    walkReachability,
-} from "../engine/content-links.mjs";
+import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
 import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
 import {
     readItemAddresses,
@@ -143,9 +135,7 @@ function configuredPacks() {
  * @returns {string} The `version` field of this package's manifest.
  */
 function ownVersion() {
-    return JSON.parse(
-        fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-    ).version;
+    return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 }
 
 // Configure loglevel
@@ -176,8 +166,7 @@ prefix.apply(log, {
  */
 function reportFailure(err) {
     const message = err instanceof Error ? err.message : String(err);
-    if (/** @type {{located?: boolean}} */ (err)?.located)
-        console.error(message);
+    if (/** @type {{located?: boolean}} */ (err)?.located) console.error(message);
     else log.error(message);
 }
 
@@ -245,13 +234,11 @@ function docsCommand() {
                 choices: ["item-fields"],
             });
             yargs.option("out", {
-                describe:
-                    "Write to this file instead of the configured location.",
+                describe: "Write to this file instead of the configured location.",
                 type: "string",
             });
             yargs.option("check", {
-                describe:
-                    "Compare against the file already there; write nothing.",
+                describe: "Compare against the file already there; write nothing.",
                 type: "boolean",
                 default: false,
             });
@@ -274,13 +261,10 @@ function docsCommand() {
                 const config = loadPackConfig();
                 const spec = config.docs?.itemFields ?? {};
                 const destination =
-                    argv.out ??
-                    (spec.out ? path.resolve(config.rootDir, spec.out) : null);
+                    argv.out ?? (spec.out ? path.resolve(config.rootDir, spec.out) : null);
 
                 const page = `${renderItemFieldReference({
-                    ...((title ?? spec.title) ?
-                        { title: title ?? spec.title }
-                    :   {}),
+                    ...((title ?? spec.title) ? { title: title ?? spec.title } : {}),
                     ...(spec.preamble ? { preamble: spec.preamble } : {}),
                     generatedBy: "`content-build docs item-fields`",
                     config,
@@ -296,9 +280,7 @@ function docsCommand() {
                     }
                     const relative = path.relative(config.rootDir, destination);
                     const current =
-                        fs.existsSync(destination) ?
-                            fs.readFileSync(destination, "utf8")
-                        :   "";
+                        fs.existsSync(destination) ? fs.readFileSync(destination, "utf8") : "";
                     if (current !== page) {
                         // Staleness belongs to the whole file, so no line is
                         // named — the diagnostics contract drops a field it
@@ -321,9 +303,7 @@ function docsCommand() {
                         recursive: true,
                     });
                     fs.writeFileSync(destination, page);
-                    log.info(
-                        `Wrote ${path.relative(config.rootDir, destination)}`,
-                    );
+                    log.info(`Wrote ${path.relative(config.rootDir, destination)}`);
                 } else {
                     process.stdout.write(page);
                 }
@@ -353,8 +333,7 @@ function lintCommand() {
         describe: "Check a content tree's addresses and frontmatter",
         builder: (yargs) => {
             yargs.positional("root", {
-                describe:
-                    "Content tree to lint. Defaults to the configured contentBase.",
+                describe: "Content tree to lint. Defaults to the configured contentBase.",
                 type: "string",
             });
             yargs.option("references", {
@@ -468,9 +447,7 @@ function lintCommand() {
                 ];
                 for (const finding of findings) emitDiagnostic(finding);
                 if (findings.length) {
-                    log.error(
-                        `${findings.length} finding(s) across ${addresses.notes} note(s).`,
-                    );
+                    log.error(`${findings.length} finding(s) across ${addresses.notes} note(s).`);
                     process.exitCode = 1;
                 } else {
                     log.info(
@@ -510,19 +487,16 @@ function formatCommand() {
         describe: "Check formatting with the shared Prettier configuration",
         builder: (yargs) => {
             yargs.positional("paths", {
-                describe:
-                    "Files or directories to check. Defaults to the whole repository.",
+                describe: "Files or directories to check. Defaults to the whole repository.",
                 type: "string",
             });
             yargs.option("write", {
-                describe:
-                    "Rewrite unformatted files in place instead of reporting them.",
+                describe: "Rewrite unformatted files in place instead of reporting them.",
                 type: "boolean",
                 default: false,
             });
             yargs.option("check", {
-                describe:
-                    "Report unformatted files without rewriting them (the default).",
+                describe: "Report unformatted files without rewriting them (the default).",
                 type: "boolean",
             });
         },
@@ -532,17 +506,15 @@ function formatCommand() {
                 // it contradicts `--write`; naming both is a mistake worth
                 // saying out loud rather than silently resolving.
                 if (argv.check === true && argv.write) {
-                    log.error(
-                        "--check and --write ask for opposite things; name one.",
-                    );
+                    log.error("--check and --write ask for opposite things; name one.");
                     process.exitCode = 1;
                     return;
                 }
                 const root = process.cwd();
-                const { findings, checked, written } = await checkFormatting(
-                    root,
-                    { paths: argv.paths, write: argv.write },
-                );
+                const { findings, checked, written } = await checkFormatting(root, {
+                    paths: argv.paths,
+                    write: argv.write,
+                });
                 if (argv.write) {
                     log.info(
                         written.length ?
@@ -553,9 +525,7 @@ function formatCommand() {
                 }
                 for (const finding of findings) emitDiagnostic(finding);
                 if (findings.length) {
-                    log.error(
-                        `${findings.length} of ${checked} file(s) are not formatted.`,
-                    );
+                    log.error(`${findings.length} of ${checked} file(s) are not formatted.`);
                     process.exitCode = 1;
                 } else {
                     log.info(`Formatting is clean (${checked} file(s)).`);
@@ -586,8 +556,7 @@ function markdownCommand() {
         describe: "Lint markdown with the shared markdownlint rule set",
         builder: (yargs) => {
             yargs.positional("paths", {
-                describe:
-                    "Globs to lint. Defaults to every markdown file in the repository.",
+                describe: "Globs to lint. Defaults to every markdown file in the repository.",
                 type: "string",
             });
             yargs.option("fix", {
@@ -635,8 +604,7 @@ function linksCommand() {
         describe: "Check that every link in a content tree lands somewhere",
         builder: (yargs) => {
             yargs.positional("root", {
-                describe:
-                    "Content tree to check. Defaults to the configured contentBase.",
+                describe: "Content tree to check. Defaults to the configured contentBase.",
                 type: "string",
             });
             yargs.option("manifests", {
@@ -665,9 +633,7 @@ function linksCommand() {
                             message: `unusable link manifest: ${s.reason}`,
                         });
                     }
-                    log.error(
-                        "Refresh the vendored copy from that package's own build.",
-                    );
+                    log.error("Refresh the vendored copy from that package's own build.");
                     process.exitCode = 1;
                     return;
                 }
@@ -675,14 +641,10 @@ function linksCommand() {
                 // Readable is not the same as addressable: a key shape the
                 // lookup cannot parse makes every cross-package link miss, and
                 // the audit then blames the *notes*.
-                const drifted = unaddressableForeignPackages(
-                    index.foreign.index,
-                );
+                const drifted = unaddressableForeignPackages(index.foreign.index);
                 if (drifted.length) {
                     for (const f of drifted) {
-                        console.error(
-                            formatUnaddressableFinding(f, manifestDir),
-                        );
+                        console.error(formatUnaddressableFinding(f, manifestDir));
                     }
                     process.exitCode = 1;
                     return;
@@ -744,9 +706,7 @@ function linksCommand() {
                     frontmatterLinks.length +
                     homepageLinks.length;
                 if (failures) {
-                    log.error(
-                        `${failures} link problem(s) across ${index.notes.length} note(s).`,
-                    );
+                    log.error(`${failures} link problem(s) across ${index.notes.length} note(s).`);
                     process.exitCode = 1;
                 } else {
                     log.info(
@@ -789,14 +749,12 @@ function manifestCommand() {
         describe: "Emit this package's cross-package link manifest",
         builder: (yargs) => {
             yargs.positional("root", {
-                describe:
-                    "Content tree to read. Defaults to the configured contentBase.",
+                describe: "Content tree to read. Defaults to the configured contentBase.",
                 type: "string",
             });
             yargs.option("out", {
                 describe:
-                    "Directory to write into. Defaults to the configured " +
-                    "`paths.manifestOut`.",
+                    "Directory to write into. Defaults to the configured " + "`paths.manifestOut`.",
                 type: "string",
             });
         },
@@ -825,10 +783,7 @@ function manifestCommand() {
                 // lost its address becomes a dead link in every consumer.
                 for (const s of skipped) {
                     emitDiagnostic({
-                        file: path.join(
-                            argv.root ?? config.paths.content,
-                            s.file,
-                        ),
+                        file: path.join(argv.root ?? config.paths.content, s.file),
                         severity: "warning",
                         message: `no address, so it is absent from the manifest: ${s.reason}`,
                     });
@@ -864,8 +819,7 @@ function siteCommand() {
         describe: "Build a Hugo content tree from the content tree",
         builder: (yargs) => {
             yargs.option("out", {
-                describe:
-                    "Write the mount here instead of the configured `site.out`.",
+                describe: "Write the mount here instead of the configured `site.out`.",
                 type: "string",
             });
         },
@@ -903,26 +857,16 @@ function siteCommand() {
                 }
                 for (const s of gates.staleManifests) {
                     emitDiagnostic({
-                        file: path.join(
-                            loadPackConfig().paths.manifests,
-                            `${s.package}.json`,
-                        ),
+                        file: path.join(loadPackConfig().paths.manifests, `${s.package}.json`),
                         severity: "error",
                         message: `unusable link manifest: ${s.reason}`,
                     });
                 }
                 for (const f of gates.unaddressable) {
-                    console.error(
-                        formatUnaddressable(
-                            f,
-                            loadPackConfig().paths.manifests,
-                        ),
-                    );
+                    console.error(formatUnaddressable(f, loadPackConfig().paths.manifests));
                 }
                 for (const c of gates.conflicts) {
-                    log.error(
-                        `address ${c.key} is also published by ${c.package}`,
-                    );
+                    log.error(`address ${c.key} is also published by ${c.package}`);
                 }
                 if (gatesFailed(gates)) {
                     process.exitCode = 1;
@@ -937,9 +881,7 @@ function siteCommand() {
                     log.error(`bad content table: ${e.reason}  (${e.source})`);
                 }
                 for (const e of result.wikiErrors) {
-                    log.error(
-                        `bad wikilink [[${e.target}]]: ${e.reason}  (${e.file})`,
-                    );
+                    log.error(`bad wikilink [[${e.target}]]: ${e.reason}  (${e.file})`);
                 }
                 if (result.tableErrors.length || result.wikiErrors.length) {
                     process.exitCode = 1;
@@ -989,8 +931,7 @@ function reachabilityCommand() {
         describe: "Check that every document in a corpus is reachable",
         builder: (yargs) => {
             yargs.positional("dir", {
-                describe:
-                    "The corpus directory, relative to the content tree root.",
+                describe: "The corpus directory, relative to the content tree root.",
                 type: "string",
             });
             yargs.positional("file", {
@@ -1008,8 +949,7 @@ function reachabilityCommand() {
                 default: [],
             });
             yargs.option("root", {
-                describe:
-                    "Content tree to read. Defaults to the configured contentBase.",
+                describe: "Content tree to read. Defaults to the configured contentBase.",
                 type: "string",
             });
         },
@@ -1026,9 +966,7 @@ function reachabilityCommand() {
                     stopAt: (n) => indexes.has(String(n.fm.shortcode)),
                 });
 
-                const total = index.notes.filter((n) =>
-                    n.rel.startsWith(`${dir}/`),
-                ).length;
+                const total = index.notes.filter((n) => n.rel.startsWith(`${dir}/`)).length;
 
                 for (const o of orphans) {
                     // Unreachability is a property of the whole document, so
@@ -1052,8 +990,7 @@ function reachabilityCommand() {
                     process.exitCode = 1;
                 } else {
                     log.info(
-                        `All ${total} document(s) in ${dir} are reachable ` +
-                            `from ${argv.file}.`,
+                        `All ${total} document(s) in ${dir} are reachable ` + `from ${argv.file}.`,
                     );
                 }
             } catch (err) {
@@ -1144,8 +1081,7 @@ function depsCommand() {
                     return;
                 }
                 const count = await fetchAllCatalogs(config);
-                if (count)
-                    log.info(`Fetched ${count} dependency catalogue(s).`);
+                if (count) log.info(`Fetched ${count} dependency catalogue(s).`);
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1192,24 +1128,15 @@ async function diffAddresses(config, argv) {
         ...config,
         paths: {
             ...config.paths,
-            foreignCache: path.join(
-                path.dirname(config.paths.foreignCache),
-                "baseline",
-            ),
+            foreignCache: path.join(path.dirname(config.paths.foreignCache), "baseline"),
         },
     };
-    const dir = await fetchCatalogFromPath(
-        cacheConfig,
-        { id: config.foundryPackage },
-        argv.from,
-    );
+    const dir = await fetchCatalogFromPath(cacheConfig, { id: config.foundryPackage }, argv.from);
     // `<id>@<version>`, which is what the diagnostics name the baseline by.
     const label = path.basename(dir);
 
     const itemsRoot = path.join(dir, "items");
-    const baselineDirs = fs
-        .readdirSync(itemsRoot)
-        .map((name) => path.join(itemsRoot, name));
+    const baselineDirs = fs.readdirSync(itemsRoot).map((name) => path.join(itemsRoot, name));
     const currentDirs = itemPackJsonDirs(config);
     if (!currentDirs.length) {
         throw new Error(
@@ -1254,8 +1181,7 @@ async function diffAddresses(config, argv) {
 function addressesCommand() {
     return {
         command: "addresses <action>",
-        describe:
-            "Compare the addresses this build publishes against a release's",
+        describe: "Compare the addresses this build publishes against a release's",
         builder: (yargs) => {
             // Required, for the reason every other action is (#57): an
             // optional one exits 0 having compared nothing.