@heroiclands/package-build 4.0.0 → 6.0.0

package/engine/site-build.mjs

@@ -63,6 +63,13 @@ import {
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
+import {
+    HOMEPAGE_DESTINATION,
+    homepageFrontmatter,
+    homepageTitle,
+    isHomepage,
+} from "./homepage.mjs";
+import { publishesContentPages } from "../content-config.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -137,6 +144,10 @@ export function collectContentPages(contentBase, ctx) {
         // (#56).
         const pkg = ctx.contentPackage;
         if (!ctx.packages.has(pkg) || !fm.type) continue;
+        // A homepage is addressed by the *package*, not by its own name, so it
+        // never takes a section and a slug (#51). {@link collectHomepages}
+        // gathers it instead.
+        if (isHomepage(fm)) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
             fmLinkFindings.push({ file, ...hit });
@@ -249,6 +260,68 @@ export function collectTreePages(tree, ctx) {
     return { pages, fmLinkFindings };
 }
 
+/**
+ * The package's homepage notes — the authored page at `/<contentPackage>/`.
+ *
+ * A separate walk from {@link collectContentPages} rather than a branch inside
+ * it, because in homepage-only mode it is the **whole** of the site build: the
+ * content tree is never read for pages at all, so the licensing constraint two
+ * packages ship under is a property of the code path rather than of a
+ * configuration that happens to be empty (#55).
+ *
+ * Returned as a list rather than as the one note there should be. Requiring
+ * exactly one is #52's, and it is a separate decision — this reports what it
+ * found so a count is visible either way.
+ *
+ * @param {string} contentBase - Absolute path to the content tree.
+ * @param {object} ctx - `{ skipDirectories }`.
+ * @returns {{pages: object[]}} The homepage notes, in walk order.
+ */
+export function collectHomepages(contentBase, ctx) {
+    const pages = [];
+    for (const file of walkSiteTree(contentBase, ctx.skipDirectories)) {
+        const note = readNote(file);
+        if (!note || !isHomepage(note.fm)) continue;
+        pages.push({ kind: "homepage", file, fm: note.fm, body: note.body });
+    }
+    return { pages };
+}
+
+/**
+ * Writes each homepage at the package's own root.
+ *
+ * Its own writer, deliberately small. A homepage is authored markdown published
+ * verbatim — no table expansion, no section landing and no link resolution — so
+ * routing it through {@link renderPages} would buy it a pipeline it has no input
+ * for, and would make homepage-only mode depend on the index, the foreign
+ * manifests and the table universe that mode exists to not build.
+ *
+ * **Verbatim is the answer to #54, not a gap left by it.** A landing's links
+ * could not be *resolved* here without giving `homepage` mode the index its
+ * licensing fence exists to not build, so they are **checked** instead:
+ * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
+ * markdown links, and reports a wikilink on the page rather than resolving one.
+ *
+ * @param {string} outRoot - The package's site root — the configured `site.out`,
+ *   one level above the content mount.
+ * @param {readonly object[]} pages - From {@link collectHomepages}.
+ * @param {object} config - The resolved configuration, for the package name and
+ *   the default title.
+ * @returns {number} How many pages were written.
+ */
+export function writeHomepages(outRoot, pages, config) {
+    for (const page of pages) {
+        const data = homepageFrontmatter(page.fm, {
+            contentPackage: config.contentPackage,
+            title: homepageTitle(page.fm, config),
+        });
+        const dest = path.join(outRoot, HOMEPAGE_DESTINATION);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, matter.stringify(page.body, data));
+    }
+    return pages.length;
+}
+
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -318,6 +391,30 @@ export function siteGates(pages, findings, { manifestDir }) {
     return out;
 }
 
+/**
+ * The gate result of a build that ran none of them.
+ *
+ * Homepage-only publishes one authored page and resolves nothing, so every gate
+ * here is about a surface that mode does not have. The shape is returned all the
+ * same, because a caller reads the same fields whichever mode ran and a `null`
+ * would make each of them a special case.
+ *
+ * @returns {object} An all-clear gate result.
+ */
+export function emptyGates() {
+    return {
+        frontmatterLinks: [],
+        slugErrors: [],
+        collisions: [],
+        staleManifests: [],
+        unaddressable: [],
+        conflicts: [],
+        index: null,
+        foreign: null,
+        manifests: null,
+    };
+}
+
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates) {
     return Boolean(
@@ -706,6 +803,10 @@ export function buildSite({ config, outRoot } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
+    // Homepage-only or homepage-plus-content (#55). The floor is the homepage,
+    // so this decides whether the *content* surfaces are published, never
+    // whether anything is.
+    const publishesContent = publishesContentPages(resolved);
 
     // Where the package is served, and where its content mounts inside it. The
     // two are separate facts: `base` is the package's own address on the site
@@ -722,9 +823,16 @@ export function buildSite({ config, outRoot } = {}) {
     // directory it was launched from (#1508).
     const outBase = resolveOutputRoot(resolved.rootDir, site.out);
     const out =
-        outRoot ?
-            path.resolve(outRoot)
-        :   path.join(outBase, scheme.prefix.replace(/\/$/, ""));
+        outRoot ? path.resolve(outRoot)
+        : 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;
+    // 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],
@@ -744,6 +852,25 @@ export function buildSite({ config, outRoot } = {}) {
     // note was deleted or renamed would otherwise linger and keep publishing.
     fs.rmSync(outBase, { recursive: true, force: true });
 
+    const homepages = collectHomepages(resolved.paths.content, ctx).pages;
+
+    // Homepage-only stops here, and stopping is the point: nothing below reads
+    // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
+    // cannot publish one whatever else their `site:` block declares (#55).
+    if (!publishesContent) {
+        return {
+            gates: emptyGates(),
+            manifests: null,
+            tableErrors: [],
+            wikiErrors: [],
+            stats: {
+                homepages: writeHomepages(homeRoot, homepages, resolved),
+                landings: 0,
+                out: homeRoot,
+            },
+        };
+    }
+
     const content = collectContentPages(resolved.paths.content, ctx);
     const pages = [...content.pages];
     const fmLinkFindings = [...content.fmLinkFindings];
@@ -804,12 +931,21 @@ export function buildSite({ config, outRoot } = {}) {
         sectionTitle: site.backfillSections ? pluralTitle : null,
     });
 
+    // Last, and outside the mount: the package's front page is not part of the
+    // content tree it introduces.
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
+
     return {
         gates,
         manifests: gates.manifests,
         tableErrors: rendered.tableErrors,
         wikiErrors: rendered.wikiErrors,
-        stats: { ...rendered.byKind, landings, out },
+        stats: {
+            ...rendered.byKind,
+            homepages: homepagesWritten,
+            landings,
+            out,
+        },
     };
 }
 

package/manifest.mjs

@@ -49,8 +49,11 @@
  */
 
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 
+import { emitDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
+
 /**
  * The two package kinds Foundry defines, as the artifact name each one's
  * manifest and release archive are called.
@@ -197,6 +200,130 @@ export function manifestPacks(config) {
     });
 }
 
+/**
+ * Where a `packFolders` declaration lives in the configuration file.
+ *
+ * @type {readonly string[]}
+ */
+const PACK_FOLDERS_PATH = Object.freeze([
+    "packageBuild",
+    "manifest",
+    "packFolders",
+]);
+
+/**
+ * Every pack name a folder tree names, with the folder that named it.
+ *
+ * Foundry nests pack folders three deep — `PackageCompendiumFolder` re-declares
+ * itself while `depth < 4` — so a rule reading only the top level would miss
+ * every nested name in both directions: a broken one it never checked, and a
+ * working one it would then report as ungrouped.
+ *
+ * @param {unknown} folders - A `packFolders` list, or a nested `folders` list.
+ * @param {Array<string|number>} at - Config key path of `folders`.
+ * @returns {Array<{pack: string, folder: string, keyPath: Array<string|number>}>}
+ *   One entry per named pack, in declaration order, depth first.
+ */
+function namedPacks(folders, at) {
+    if (!Array.isArray(folders)) return [];
+    const found = [];
+    folders.forEach((folder, index) => {
+        if (folder === null || typeof folder !== "object") return;
+        const name = String(folder.name ?? "");
+        const packs = Array.isArray(folder.packs) ? folder.packs : [];
+        packs.forEach((pack, position) => {
+            found.push({
+                pack: String(pack),
+                folder: name,
+                keyPath: [...at, index, "packs", position],
+            });
+        });
+        found.push(...namedPacks(folder.folders, [...at, index, "folders"]));
+    });
+    return found;
+}
+
+/**
+ * What `packFolders` and the derived `packs[]` disagree about.
+ *
+ * `packFolders` is the one **declared** manifest key that names something the
+ * build **derives**: every other declared key states a fact about the package
+ * (`title`, `socket`, `grid`) or addresses a staged file (`esmodules`,
+ * `styles`, `languages`), and a staged file is a different relation, checked
+ * against the stage rather than against configuration. So this is the one place
+ * a declaration can go stale against a value the build already computed — and
+ * until now nothing compared them (#81).
+ *
+ * `HarnMaster-3-FoundryVTT` shipped the consequence: its folder named four
+ * packs, three of which had not existed since the compendium was consolidated,
+ * and omitted `items` — 1,577 of 1,597 documents, loose in Foundry's compendium
+ * browser, with the build reporting nothing (HM3#420).
+ *
+ * **The two findings are not the same finding**, and giving them one severity
+ * gets one of them wrong:
+ *
+ * - _A folder names a pack that does not exist_ is an **error**. Foundry
+ *   resolves the name against the package's own packs and silently skips what
+ *   it cannot find, so the declaration does nothing at all; there is no
+ *   arrangement in which it is intended, and the fix is unambiguous.
+ * - _A pack no folder names_ is a **warning**. It is legal and can be
+ *   deliberate — a package may want one pack at the root — so failing on it
+ *   would break working packages for a matter of taste. But a package that
+ *   bothered to declare a folder rarely meant to leave one out, which is
+ *   exactly how HM3's `items` went unnoticed.
+ * - _A package declaring no folders_ says **nothing**. Everything at the root
+ *   is the majority arrangement, not an omission.
+ *
+ * Errors come first, in declaration order, then warnings in pack order: the
+ * unresolvable names are what a reader fixes, and a folder gaining a name often
+ * settles a warning too.
+ *
+ * @param {object} options
+ * @param {unknown} [options.packFolders] - The declared `packFolders`.
+ * @param {ReadonlyArray<{name: string}>} [options.packs] - The derived packs,
+ *   as {@link manifestPacks} returns them.
+ * @returns {Array<{severity: "error"|"warning", message: string, pack: string,
+ *   folder?: string, keyPath: Array<string|number>}>} The findings, ordered.
+ */
+export function packFolderFindings({ packFolders, packs = [] }) {
+    if (!Array.isArray(packFolders) || packFolders.length === 0) return [];
+
+    const shipped = packs.map((pack) => pack?.name).filter(Boolean);
+    const known = new Set(shipped);
+    const named = namedPacks(packFolders, PACK_FOLDERS_PATH);
+    const grouped = new Set(named.map((entry) => entry.pack));
+
+    const findings = named
+        .filter((entry) => !known.has(entry.pack))
+        .map((entry) => ({
+            severity: /** @type {const} */ ("error"),
+            pack: entry.pack,
+            folder: entry.folder,
+            keyPath: entry.keyPath,
+            message:
+                `packFolders: folder "${entry.folder}" names pack ` +
+                `"${entry.pack}", which this package does not ship ` +
+                `(packs: ${shipped.join(", ")})`,
+        }));
+
+    for (const name of shipped) {
+        if (grouped.has(name)) continue;
+        findings.push({
+            severity: /** @type {const} */ ("warning"),
+            pack: name,
+            // No folder omitted it in particular — every one of them did — so
+            // the position is the declaration a reader edits, not one entry
+            // inside it. Each warning names its own pack, so they stay
+            // distinguishable despite sharing a line.
+            keyPath: [...PACK_FOLDERS_PATH],
+            message:
+                `packFolders: pack "${name}" is named by no folder, so it ` +
+                `ships outside every folder this package declares`,
+        });
+    }
+    return findings;
+}
+
 /**
  * Relationship keys that direct the **build**, rather than describe the
  * package.
@@ -330,16 +457,66 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     return ordered;
 }
 
+/**
+ * Report what {@link packFolderFindings} found, and say whether it was fatal.
+ *
+ * The position comes from the configuration file, when one was named and can be
+ * read: a `packFolders` finding is about a line of YAML, and the file is the
+ * only place a line exists. Anything that cannot be established — an `.mjs`
+ * configuration, an unreadable file, a path that resolves to nothing — is
+ * dropped rather than guessed, so the diagnostic degrades from
+ * `file:line:column:` to `file:` to no locator at all.
+ *
+ * @param {ReturnType<typeof packFolderFindings>} findings - What was found.
+ * @param {string} [configFile] - Absolute path of the configuration file.
+ * @returns {number} How many of them were errors.
+ */
+function reportPackFolders(findings, configFile) {
+    if (!findings.length) return 0;
+
+    let text;
+    if (configFile) {
+        try {
+            text = fsSync.readFileSync(configFile, "utf8");
+        } catch {
+            text = undefined;
+        }
+    }
+
+    let errors = 0;
+    for (const finding of findings) {
+        if (finding.severity === "error") errors += 1;
+        emitDiagnostic({
+            ...(configFile ? { file: configFile } : {}),
+            ...(text ? positionOfYamlPath(text, finding.keyPath) : {}),
+            severity: finding.severity,
+            message: finding.message,
+        });
+    }
+    return errors;
+}
+
 /**
  * Write the generated manifest into the staged package.
  *
+ * The declared `packFolders` is checked against the derived `packs[]` first,
+ * and an unresolvable name **stops the write**: a manifest already known to
+ * describe packs the package does not ship should not reach the stage, where
+ * the next command would deploy it (#81). See {@link packFolderFindings} for
+ * the rule and why its two findings carry different severities.
+ *
  * @param {object} options - As {@link buildManifest}, plus where to write.
  * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {string} options.outDir - Directory to write into.
  * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @param {string} [options.configFile] - Absolute path of the configuration
+ *   file the manifest was resolved from, so a finding about it can be located.
+ *   Omitting it costs the position, not the finding.
  * @returns {Promise<{path: string, manifest: object}>} Where it went, and what.
+ * @throws {Error} When a `packFolders` entry names a pack the package does not
+ *   ship. Nothing is written in that case.
  */
 export async function writeManifest({
     config,
@@ -347,8 +524,26 @@ export async function writeManifest({
     artifact,
     outDir,
     flags,
+    configFile,
 }) {
     const manifest = buildManifest({ config, packageJson, artifact, flags });
+
+    const errors = reportPackFolders(
+        packFolderFindings({
+            packFolders: manifest.packFolders,
+            packs: manifest.packs,
+        }),
+        configFile,
+    );
+    if (errors) {
+        throw new Error(
+            `packFolders names ${errors} pack${errors === 1 ? "" : "s"} this ` +
+                `package does not ship (reported above). Foundry skips a name ` +
+                `it cannot resolve, so the folder would ship missing those ` +
+                `packs — correct \`packageBuild.manifest.packFolders\`.`,
+        );
+    }
+
     await fs.mkdir(outDir, { recursive: true });
     const outPath = path.join(outDir, `${artifact}.json`);
     // Trailing newline: the file is committed to a release archive and read by

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "4.0.0",
+    "version": "6.0.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",

package/sohl/actors.mjs

@@ -186,8 +186,16 @@ function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
     const shadowed = [];
     for (const itemsSourceDir of itemsSourceDirs) {
         if (!fs.existsSync(itemsSourceDir)) {
+            // The generator orders the actors pass after every Item pass (#73),
+            // so a whole-package build cannot reach this. What can is a run
+            // restricted to this one pack, or a caller constructing the
+            // compiler itself — neither of which reordering a pack list fixes,
+            // so the message no longer suggests it.
             throw new Error(
-                `Items source directory ${itemsSourceDir} does not exist — actors must be generated after items`,
+                `Items source directory ${itemsSourceDir} does not exist — ` +
+                    `a being resolves its embedded items against the Item ` +
+                    `packs' compiled output, so those packs must be compiled ` +
+                    `before this one`,
             );
         }
         for (const name of fs.readdirSync(itemsSourceDir)) {
@@ -310,6 +318,11 @@ export class Actors extends BasePackCompiler {
     static id = "actors";
     static label = "actor";
 
+    // A being's embedded items are resolved against the *output* of the item
+    // passes, so every Item pack compiles before this one. Declared rather than
+    // left to the order `packs:` happens to list (#73).
+    static readsPackOutputOf = Object.freeze(["Item"]);
+
     /** @type {readonly string[]} */
     itemsSourceDirs;
     foreignSourceDirs;

package/sohl/item-fields.mjs

@@ -231,11 +231,6 @@ const GEAR_COMMON = Object.freeze([
         value: true,
         describe: "Whether it is being carried. Possession state.",
     },
-    {
-        to: "isEquipped",
-        value: false,
-        describe: "Whether it is equipped. Possession state.",
-    },
 ]);
 
 /* --------------------------------------------------------------------- */

package/sohl/kb-passes.mjs

@@ -27,35 +27,98 @@
  * map sits, what the API is served at, which GitHub tree to link into — is
  * options, supplied beside the name.
  *
- * Neither pass ever fails a build. A `{@link}` the map does not know degrades to
- * a code span, and a relative link that resolves outside the documentation tree
- * becomes a GitHub blob URL. Both are legible to a reader; a broken link or a
- * failed build for a syntax example in prose would not be.
+ * Neither *rewrite* ever fails a build. A `{@link}` the map does not know
+ * degrades to a code span, and a relative link that resolves outside the
+ * documentation tree becomes a GitHub blob URL. Both are legible to a reader; a
+ * broken link or a failed build for a syntax example in prose would not be.
+ *
+ * Building the bundle is a different matter: a `symbolMap` that is configured
+ * and cannot be used fails, loudly, before a page is rendered (#75). Degrading
+ * a tag the map does not know is a judgement about *prose*; degrading every tag
+ * on the site because the map was never read is a build that lied.
  *
  * @module
  */
 
 import fs from "node:fs";
 import path from "node:path";
+import log from "loglevel";
 
 /**
  * Reads the TypeDoc symbol map, or an empty one.
  *
- * Absent is not an error: the map is generated by `npm run docs`, and a
- * knowledgebase build that runs before it — or in a checkout that has never run
- * it — should publish prose with `{@link}` tags degraded to code spans rather
- * than refuse to build.
+ * **Not configuring a map is the empty case, and it is silent.** The map is
+ * generated by `npm run docs`, and a knowledgebase build in a repository that
+ * has no API documentation should publish prose with `{@link}` tags degraded to
+ * code spans rather than refuse to build.
+ *
+ * **Configuring one that cannot be used is a defect, and it fails the build.**
+ * A missing file, a malformed one, a permissions error and a path typo used to
+ * be indistinguishable from each other *and* from a correctly configured build
+ * with no symbols: a bare `catch` returned `{}` for all five. Nothing then
+ * compares an emitted page against what its source asked for, so the first
+ * observer of a broken map was a reader who clicked nothing, because every
+ * `{@link}` on the published site had quietly become a code span (#75).
+ *
+ * The path is resolved against the **repository root**, never the process cwd.
+ * `site.passOptions.symbolMap` is authored repo-relative, so a cwd-relative
+ * read misses the moment `content-build site` is driven from anywhere but the
+ * repository root — which is exactly how #51's end-to-end verification, running
+ * through `PACKAGE_BUILD_CONFIG` from outside the tree, found this.
  *
  * @param {string|undefined} file - Path to the map, if configured.
+ * @param {string|undefined} repoRoot - The repository root to resolve against.
  * @returns {Record<string, string>} Qualified name → API page path.
+ * @throws {Error} When a configured map cannot be resolved, read, parsed, or is
+ *   not a name → page object.
  */
-function readSymbolMap(file) {
+function readSymbolMap(file, repoRoot) {
     if (!file) return {};
+
+    // Refused rather than quietly resolved against the cwd, which is the
+    // defect this function was fixed for: a fallback would let it return.
+    if (!path.isAbsolute(file) && !repoRoot) {
+        throw new Error(
+            `site.passOptions.symbolMap ${JSON.stringify(file)} is relative ` +
+                `and no repoRoot was supplied to resolve it against`,
+        );
+    }
+    const resolved = path.resolve(repoRoot ?? "", file);
+
+    let raw;
     try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    } catch {
-        return {};
+        raw = fs.readFileSync(resolved, "utf8");
+    } catch (err) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} cannot be read: ` +
+                `${err.message}`,
+        );
     }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} is not valid JSON: ` +
+                `${err.message}`,
+        );
+    }
+
+    // `[]`, `"x"` and `null` all parse, and then every lookup misses — the same
+    // silent degradation reached a different way.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} is not an object mapping ` +
+                `qualified names to API page paths`,
+        );
+    }
+
+    // Reported because a map that loaded and a map that loaded empty are
+    // otherwise indistinguishable without reading the emitted HTML — and an
+    // empty one degrades every tag exactly as a missing one used to.
+    log.info(`resolved ${Object.keys(parsed).length} API symbols from ${file}`);
+    return parsed;
 }
 
 /**
@@ -182,14 +245,18 @@ export function rewriteRepoLinks(body, docRel, options) {
  * Both run inside code-fence protection, so neither can rewrite a fenced example.
  *
  * @param {object} options - Resolved from `site.passOptions`.
- * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map.
+ * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map,
+ *   relative to `repoRoot`. Absent means no API links; present and unusable is
+ *   a build failure.
  * @param {string} [options.apiBase] - Where the API documentation is served.
  * @param {string} [options.blob] - GitHub blob base for repository files.
  * @param {string} options.repoRoot - The repository root, for relative paths.
  * @returns {{beforeLinks: Function, afterLinks: Function}} The bundle.
+ * @throws {Error} When a configured `symbolMap` cannot be resolved, read,
+ *   parsed, or is not a name → page object.
  */
 export function sohlKbPass(options) {
-    const symbols = readSymbolMap(options.symbolMap);
+    const symbols = readSymbolMap(options.symbolMap, options.repoRoot);
     const apiBase = options.apiBase ?? "";
     return {
         beforeLinks: (text) => resolveApiLinks(text, symbols, apiBase),

package/sohl/note-schemas.mjs

@@ -38,6 +38,7 @@
  */
 
 import { AS_AUTHORED, NUMBER, STRING } from "../engine/field-spec.mjs";
+import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { ITEM_FIELDS } from "./item-fields.mjs";
 
 /** A map-valued property, whose entries the compiler walks by key. */
@@ -302,9 +303,16 @@ const PRESENTATION_FIELDS = Object.freeze({
  * Every content type this package compiles, and what a note of that type may
  * write.
  *
+ * The engine's own types are merged in first, so a SoHL tree is checked against
+ * one vocabulary rather than two. They are declared there rather than here
+ * because they are note-format knowledge — a `homepage` carries no `system`
+ * block and would mean the same thing for a game system that is not SoHL — and
+ * because a package declaring no `itemBuilders` never reaches this file (#51).
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const NOTE_SCHEMAS = Object.freeze({
+    ...ENGINE_NOTE_SCHEMAS,
     ...Object.fromEntries(
         Object.entries(ITEM_FIELDS).map(([type, fields]) => [
             type,