@heroiclands/package-build 8.0.0 → 9.0.0

package/engine/schema-check.mjs

@@ -277,10 +277,7 @@ export function resolveSchemaArtifact(config) {
     });
 
     // The system checking itself, against the schema its own build published.
-    if (
-        config.packageKind === "systems" &&
-        config.foundryPackage === systemId
-    ) {
+    if (config.packageKind === "systems" && config.foundryPackage === systemId) {
         const own = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
         return fs.existsSync(own) ? read(own) : null;
     }

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.
  *
@@ -119,10 +150,7 @@ export function registryOf(src, name) {
             }
             if (ts.isObjectLiteralExpression(init)) {
                 for (const p of init.properties) {
-                    if (
-                        ts.isPropertyAssignment(p) &&
-                        ts.isIdentifier(p.initializer)
-                    ) {
+                    if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.initializer)) {
                         out.set(propName(p.name), p.initializer.text);
                     }
                 }
@@ -185,10 +213,7 @@ function resolveSpecifier(fromDir, spec, aliases) {
     }
     if (!base) return null;
     for (const ext of EXTENSIONS) {
-        for (const candidate of [
-            `${base}${ext}`,
-            path.join(base, `index${ext}`),
-        ]) {
+        for (const candidate of [`${base}${ext}`, path.join(base, `index${ext}`)]) {
             if (fs.existsSync(candidate)) return candidate;
         }
     }
@@ -212,11 +237,7 @@ function importSourceOf(src, name, aliases) {
         if (!bindings.elements.some((e) => e.name.text === name)) return;
         const spec = node.moduleSpecifier;
         if (!ts.isStringLiteral(spec)) return;
-        found = resolveSpecifier(
-            path.dirname(src.fileName),
-            spec.text,
-            aliases,
-        );
+        found = resolveSpecifier(path.dirname(src.fileName), spec.text, aliases);
     });
     return found;
 }
@@ -255,9 +276,7 @@ function locateClass(fromFile, className, aliases, cache) {
     if (!imported) return null;
     const importedSrc = parse(imported, cache);
     const importedDecl = classDeclIn(importedSrc, className);
-    return importedDecl ?
-            { file: imported, src: importedSrc, decl: importedDecl }
-        :   null;
+    return importedDecl ? { file: imported, src: importedSrc, decl: importedDecl } : null;
 }
 
 /**
@@ -272,8 +291,7 @@ function superClassOf(decl) {
     for (const clause of decl.heritageClauses ?? []) {
         if (clause.token !== ts.SyntaxKind.ExtendsKeyword) continue;
         const [type] = clause.types;
-        if (type && ts.isIdentifier(type.expression))
-            return type.expression.text;
+        if (type && ts.isIdentifier(type.expression)) return type.expression.text;
     }
     return null;
 }
@@ -319,9 +337,8 @@ function literalReturnedBy(src, fnName) {
         if (isTarget) {
             const body =
                 ts.isFunctionDeclaration(node) ? node.body
-                : node.initializer && ts.isArrowFunction(node.initializer) ?
-                    node.initializer.body
-                :   null;
+                : node.initializer && ts.isArrowFunction(node.initializer) ? node.initializer.body
+                : null;
             if (body) literal = returnedLiteral(body);
         }
         ts.forEachChild(node, visit);
@@ -373,14 +390,10 @@ function isObjectAssign(expr) {
  */
 function schemaContributions(src, decl) {
     const method = decl.members.find(
-        (m) =>
-            ts.isMethodDeclaration(m) &&
-            propName(m.name) === "defineSchema" &&
-            m.body,
+        (m) => ts.isMethodDeclaration(m) && propName(m.name) === "defineSchema" && m.body,
     );
     // No `defineSchema()` — the whole schema is the parent's.
-    if (!method)
-        return { literals: [], edges: [{ kind: "super", name: null }] };
+    if (!method) return { literals: [], edges: [{ kind: "super", name: null }] };
 
     const direct = returnedLiteral(method.body);
     if (direct) return { literals: [direct], edges: [] };
@@ -424,16 +437,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 +458,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 +468,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 +518,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 +529,29 @@ 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;
@@ -563,12 +593,7 @@ export function fieldsForClass({ file, className, aliases, cache, rootDir }) {
  * @param {string} opts.version - The package version.
  * @returns {object} The artifact `schema-check.mjs` reads.
  */
-export function buildSchemaArtifact({
-    rootDir,
-    registries,
-    packageId,
-    version,
-}) {
+export function buildSchemaArtifact({ rootDir, registries, packageId, version }) {
     const aliases = pathAliases(rootDir);
     const cache = new Map();
     const documents = {};

package/engine/site-build.mjs

@@ -56,10 +56,7 @@ import { expandContentTables } from "./content-tables.mjs";
 import { buildSiteIndex, wikiContext } from "./site-index.mjs";
 import { frontmatterWikilinks, resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { loadForeignManifests, manifestsComplete } from "./kb-manifest.mjs";
-import {
-    formatUnaddressableFinding,
-    unaddressableForeignPackages,
-} from "./foreign-manifests.mjs";
+import { formatUnaddressableFinding, unaddressableForeignPackages } from "./foreign-manifests.mjs";
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
@@ -192,10 +189,7 @@ export function collectContentPages(contentBase, ctx) {
             // authoring folder, for grouped landings.
             folder: path.basename(path.dirname(file)),
             sec,
-            url:
-                isReadme ?
-                    `${ctx.mount}${sec}/`
-                :   `${ctx.mount}${sec}/${slug}/`,
+            url: isReadme ? `${ctx.mount}${sec}/` : `${ctx.mount}${sec}/${slug}/`,
             isReadme,
         });
     }
@@ -231,10 +225,8 @@ export function collectTreePages(tree, ctx) {
         const isReadme = base.toLowerCase() === "readme.md";
         const sec = fm.category ?? tree.section;
         const h1 = /^#\s+(.+?)\s*$/m.exec(body);
-        const h1Title =
-            h1 ? h1[1].replace(/\{@link\s+[^}]*\}/g, "").trim() : null;
-        const name =
-            fm.name?.full ?? fm.title ?? h1Title ?? path.basename(base, ".md");
+        const h1Title = h1 ? h1[1].replace(/\{@link\s+[^}]*\}/g, "").trim() : null;
+        const name = fm.name?.full ?? fm.title ?? h1Title ?? path.basename(base, ".md");
         const slug = fm.slug ?? slugify(path.basename(base, ".md"));
         const relNoExt = rel.slice(0, -3).toLowerCase();
         const dir = path.posix.dirname(relNoExt);
@@ -562,9 +554,7 @@ export function pageDestination(page) {
             :   path.join(page.sec, `${page.slug}.md`);
     }
     const rel =
-        page.isReadme ?
-            path.posix.join(path.posix.dirname(page.rel), "_index.md")
-        :   page.rel;
+        page.isReadme ? path.posix.join(path.posix.dirname(page.rel), "_index.md") : page.rel;
     return path.join(page.sec, rel);
 }
 
@@ -640,10 +630,7 @@ export function renderPages(pages, options) {
         const data = pageFrontmatter(page, { readmeSections, decorate });
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(
-            dest,
-            matter.stringify(protectCode(body, resolve), data),
-        );
+        fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
@@ -676,10 +663,7 @@ export function renderPages(pages, options) {
  * @param {object} options - `{ sections, landing, sectionTitle }`.
  * @returns {number} How many landings were written.
  */
-export function writeSectionLandings(
-    outRoot,
-    { sections = {}, landing, sectionTitle },
-) {
+export function writeSectionLandings(outRoot, { sections = {}, landing, sectionTitle }) {
     let written = 0;
 
     // The mount's own landing carries a `type` of its own. Hugo's template
@@ -689,10 +673,7 @@ export function writeSectionLandings(
     // template out of the path where it could be inherited.
     if (landing) {
         fs.mkdirSync(outRoot, { recursive: true });
-        fs.writeFileSync(
-            path.join(outRoot, "_index.md"),
-            matter.stringify("", landing),
-        );
+        fs.writeFileSync(path.join(outRoot, "_index.md"), matter.stringify("", landing));
         written += 1;
     }
 
@@ -713,10 +694,7 @@ export function writeSectionLandings(
         if (!entry.isDirectory()) continue;
         const index = path.join(outRoot, entry.name, "_index.md");
         if (fs.existsSync(index)) continue;
-        fs.writeFileSync(
-            index,
-            matter.stringify("", { title: sectionTitle(entry.name) }),
-        );
+        fs.writeFileSync(index, matter.stringify("", { title: sectionTitle(entry.name) }));
         written += 1;
     }
     return written;
@@ -859,19 +837,16 @@ export function buildSite({ config, outRoot } = {}) {
     const outBase = resolveOutputRoot(resolved.rootDir, site.out);
     const out =
         outRoot ? path.resolve(outRoot)
-        : publishesContent ?
-            path.join(outBase, scheme.prefix.replace(/\/$/, ""))
+        : publishesContent ? path.join(outBase, scheme.prefix.replace(/\/$/, ""))
             // Homepage-only has no content mount, so the package's root *is*
             // the output root and `--out` redirects the whole of it.
-        :   outBase;
+        : outBase;
     // The homepage publishes at `/<contentPackage>/`, which is the package's
     // own root — one level above the content mount, and the same directory in
     // homepage-only mode.
     const homeRoot = publishesContent ? outBase : out;
 
-    const packages = new Set(
-        site.packages.length ? site.packages : [resolved.contentPackage],
-    );
+    const packages = new Set(site.packages.length ? site.packages : [resolved.contentPackage]);
 
     const ctx = {
         packages,

package/engine/site-index.mjs

@@ -152,10 +152,7 @@ function mergeForeign(index, foreignIndex) {
         const parts = readCanonicalKey(key);
         if (!parts) continue;
         const shortKey = `${parts.type}/${parts.shortcode}`;
-        if (
-            short.has(shortKey) &&
-            short.get(shortKey).package !== value.package
-        ) {
+        if (short.has(shortKey) && short.get(shortKey).package !== value.package) {
             ambiguous.add(shortKey);
         } else {
             short.set(shortKey, value);
@@ -242,10 +239,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             // The page's package is the configured one — the site collection
             // resolves it and records it as `pkg`. Never read out of
             // frontmatter: `package:` is retired (#56).
-            index.set(
-                canonicalKey(e.pkg ?? contentPackage(), type, shortcode),
-                value,
-            );
+            index.set(canonicalKey(e.pkg ?? contentPackage(), type, shortcode), value);
             // In Foundry an item and its documentation are two documents, so
             // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
             // item note renders as one page which *is* its documentation, so
@@ -315,13 +309,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
  */
 export function wikiContext(
     built,
-    {
-        src,
-        type = null,
-        errors,
-        foreignIndex = new Map(),
-        manifestsComplete = true,
-    },
+    { src, type = null, errors, foreignIndex = new Map(), manifestsComplete = true },
 ) {
     return {
         index: built.index,

package/engine/web-wikilinks.mjs

@@ -46,12 +46,7 @@ import { slugify } from "./content-slug.mjs";
 // Re-exported so a site build keeps one import path for the whole of link
 // resolution: the same rule that names a page also names an anchor within it.
 export { slugify };
-import {
-    authoredLabel,
-    WIKILINK,
-    isSamePage,
-    parseWikilink,
-} from "./wikilink-syntax.mjs";
+import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
 
 /** KB heading/anchor slug: lowercase, non-alphanumerics to single hyphens. */
 
@@ -280,9 +275,7 @@ export function resolveWebWikilinks(body, ctx) {
             // Both separators qualify: `type-shortcode` is the canonical form
             // (#1398), and a hyphen inside a note *name* ("Grukar-ahk") is not
             // one, which is why the rule is the packs' own (#1409).
-            const text =
-                label ??
-                (isAddress(target, ctx.contentTypes) ? hit.name : target);
+            const text = label ?? (isAddress(target, ctx.contentTypes) ? hit.name : target);
             // A pack-only package publishes Foundry addresses and no pages
             // (#1516), so its entries carry no `path` and resolve to no URL.
             // The address is real — this is not a typo and must not fail the
@@ -295,8 +288,7 @@ export function resolveWebWikilinks(body, ctx) {
         }
 
         const slash = target.indexOf("/");
-        const prefix =
-            slash === -1 ? null : target.slice(0, slash).toLowerCase();
+        const prefix = slash === -1 ? null : target.slice(0, slash).toLowerCase();
         // Deliberately *not* extended to the hyphen form, which is also how a
         // note addresses content in a package this build does not publish
         // (`Rules/Bestiary.md` → `being-grkrahk`, a real note in the `thalorna`
@@ -307,8 +299,7 @@ export function resolveWebWikilinks(body, ctx) {
         // which holds the reviewed list of cross-package exceptions — and which,
         // unlike this build, runs as part of `npm run lint` on every change.
         const badQualified =
-            prefix !== null &&
-            (ctx.sections.has(prefix) || ctx.contentTypes.has(prefix));
+            prefix !== null && (ctx.sections.has(prefix) || ctx.contentTypes.has(prefix));
         // The hyphen form is the canonical address (#1398) and is what the
         // authored content writes. It could not be guarded while some packages
         // were invisible here: `Rules/Bestiary.md` addresses `being-grkrahk`,