@heroiclands/package-build 5.0.0 → 6.0.0

package/types/engine/content-links.d.mts

@@ -26,18 +26,69 @@ export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectori
     manifestDir?: string | undefined;
     skipDirectories?: readonly string[] | undefined;
 }): object;
+/**
+ * Every defect in the addresses a package homepage carries.
+ *
+ * **Why the homepage needs its own audit at all.** Every other note addresses
+ * the corpus with wikilinks, which {@link auditLinks} resolves. A homepage does
+ * not and cannot: it is published *verbatim* by every publishing mode, including
+ * the homepage-only mode two fan-licensed packages ship under, where the content
+ * tree is never walked and there is no index for a wikilink to resolve against.
+ * So a landing addresses the web the way the web does — markdown links and
+ * `url:` fields — and nothing was looking at those. SoHL's landing pointed at
+ * `kb/creature/` and `kb/character/` from the day those types merged into
+ * `being`: two 404s on the package's front page, through every build.
+ *
+ * **What is checkable, stated plainly.** Only an address into this site is, and
+ * only against facts this build already holds:
+ *
+ * - A **retired content type** in the path. The engine knows what used to exist
+ *   and what replaced it, so this is a fact rather than a guess — and it is
+ *   exactly the SoHL defect.
+ * - A **hardcoded absolute URL** into this package's own prefix, or into one a
+ *   vendored manifest names. Both have a better form to write, which is why they
+ *   are reported; a bare `/<package>/` is left alone, because a package
+ *   homepage is in no manifest and there is nothing better to write.
+ * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
+ *   time. `href:` means "already resolved, use verbatim", so the same leading
+ *   slash is correct there and is not reported.
+ * - A **wikilink**, which nothing on this page will ever resolve.
+ *
+ * **What is not checkable, and is not attempted.** Whether an external URL
+ * answers — there is no network at build time, and a build must not fail because
+ * a third party is down. And whether a live in-site address names a page that
+ * exists: several of the surfaces a landing routes to are produced by other
+ * tools entirely (generated API documentation, hand-authored Hugo sections), so
+ * this build does not hold the set of published pages and would report a working
+ * link as dead.
+ *
+ * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
+ * @returns {Array<{note: object, field: string, url: string, text: string,
+ *   occurrence: number, message: string}>} One finding per defect, `text` and
+ *   `occurrence` locating it in the note's raw source.
+ */
+export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Array<{
+    note: object;
+    field: string;
+    url: string;
+    text: string;
+    occurrence: number;
+    message: string;
+}>;
 /**
  * Every link in a tree that lands nowhere.
  *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
- *   frontmatterLinks: object[], usedManifest: Set<string>}} The findings, and
- *   which addresses a foreign manifest answered.
+ *   frontmatterLinks: object[], homepageLinks: object[],
+ *   usedManifest: Set<string>}} The findings, and which addresses a foreign
+ *   manifest answered.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];
     deadAddresses: object[];
     frontmatterLinks: object[];
+    homepageLinks: object[];
     usedManifest: Set<string>;
 };
 /**

package/types/engine/diagnostics.d.mts

@@ -150,3 +150,31 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
     line?: number;
     column?: number;
 };
+/**
+ * Where a **key or value in a YAML document** sits, addressed by its path.
+ *
+ * {@link positionOfLiteral} is the plain search, and it is the wrong tool for a
+ * configuration file: a pack name like `items` or `actors` appears in the
+ * `packs:` block, in a folder's list, in a path, and often in prose, so the
+ * first occurrence is routinely not the one the finding is about — which is the
+ * one thing the located form exists to prevent.
+ *
+ * A path resolves the exact node instead. The document is re-parsed here rather
+ * than threaded from the loader because the loader returns plain data: `yaml`
+ * discards ranges once a document is materialised, and carrying a parallel
+ * position tree through configuration resolution would be a second
+ * representation of the same file to keep in step.
+ *
+ * Every failure — unparseable text, an `.mjs` configuration, a path that
+ * resolves to nothing — yields `{}`, so a caller spreads the result and the
+ * position is dropped rather than guessed.
+ *
+ * @param {string} text - The document's contents.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node: map keys as
+ *   strings, sequence entries as numbers.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string | number>): {
+    line?: number;
+    column?: number;
+};

package/types/engine/generate.d.mts

@@ -6,8 +6,9 @@
  * and an actor's embedded items may be sourced from any of them. Finding one
  * pack and stopping is how embedded-item resolution would silently miss every
  * item that landed in another. Returned in configured order, which is also the
- * order they compile in, so a pack later in the list cannot be read before it
- * is written.
+ * order they compile in — {@link orderPassesByDependency} keeps the declared
+ * order among packs of one type — and every one of them is written before the
+ * actors pass that reads them.
  *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
@@ -16,6 +17,53 @@
  *   caller that needs one, refuses that itself.
  */
 export function itemPackJsonDirs(config?: object): string[];
+/**
+ * The passes to run, ordered so that each one follows the output it reads.
+ *
+ * **Declaration order is presentation, not compile order (#73).** The same
+ * `packs:` list is the manifest's `packs` array, which a consumer orders for a
+ * reader browsing compendiums; the actors pass, meanwhile, resolves each
+ * being's embedded items against the item passes' *output*. Making one list
+ * satisfy both meant an Actor pack declared first compiled only where a
+ * previous run had already left `build/packs-json` populated — green on a warm
+ * tree, exit 1 on every fresh checkout and every CI runner, and `build/` is
+ * gitignored so that is the state CI always starts from.
+ *
+ * **The reordering is the smallest one that works.** Each step takes the
+ * *earliest declared* pass whose dependencies are all already emitted, so a
+ * list that was already in a workable order comes back untouched, and one that
+ * was not moves exactly the passes that had to move. A dependency is satisfied
+ * only when **every** pack of that type has run: a being addresses an item by
+ * `(type, shortcode)` without knowing which Item pack ships it, so waiting for
+ * one of several would resolve some beings and silently fail others.
+ *
+ * A dependency on a type this configuration declares no pack of is not waited
+ * for. A package may ship an Actor pack and no Item pack; the pass that needs
+ * one refuses on its own, with a message about items rather than about order.
+ *
+ * @param {readonly object[]} packs - The passes to be run, as declared.
+ * @returns {object[]} A new list, in compile order. The input is untouched.
+ * @throws {Error} If the passes read each other's output in a cycle, which no
+ *   order can satisfy. Only reachable from a mis-declared compiler, so it names
+ *   the passes rather than blaming the pack list.
+ */
+export function orderPassesByDependency(packs: readonly object[]): object[];
+/**
+ * The dependencies this run cannot satisfy by ordering, because the pass that
+ * would produce them is not in it.
+ *
+ * Ordering answers the whole-package build; a run restricted to one pack
+ * (`content-build package compile <name>`) cannot conjure the passes it left
+ * out. Where their output is already on disk from an earlier run that is fine
+ * — it is how compiling one pack at a time is meant to work — so this reports
+ * only what is genuinely absent, and names the pack that would write it rather
+ * than the directory that is missing.
+ *
+ * @param {readonly object[]} running - The passes this run will execute.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string[]} One message per unsatisfiable dependency.
+ */
+export function unsatisfiedPassDependencies(running: readonly object[], config: object): string[];
 /**
  * The passes that compiled nothing when they were expected to compile
  * something — a build failure, not a quiet no-op.

package/types/engine/homepage.d.mts

@@ -46,49 +46,40 @@ export function homepageFrontmatter(fm: object, { contentPackage, title }: {
     title: string;
 }): object;
 /**
- * The package homepage — a note that compiles to a **page** rather than to a
- * compendium document (#51).
- *
- * Every HeroicLands package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
- * and what a reader finds there is one markdown file in the content tree,
- * written by a person: what the module is, which system it needs, how to install
- * it, where its source lives. Nothing about it is derived.
- *
- * **Authored, not assembled.** An earlier sketch generated the page in tiers —
- * identity and licence from the manifest, install URL from the release address,
- * "requires" links from `relationships`, a card per configured section. It would
- * have worked and needed almost no authoring, and it produces a page nobody
- * chose the contents of. The things that matter most on these pages cannot be
- * derived: that Kethira requires buying the book from Keléstia, what Thalorna's
- * setting *is*, which of twenty sections a reader should start with. So the only
- * thing defaulted here is the title, from `packageBuild.manifest.title`, so that
- * the package's name is not written twice.
- *
- * **Dispatched by `type`, not by filename.** A fixed `homepage.md` the walker
- * special-cased would be the anomaly: notes are routed by frontmatter, not by
- * location, and `NOTE_SCHEMAS` already routes `doc`, `macro`, `being` and the
- * map types. `homepage` is one more entry whose compile step emits a page. It is
- * deliberately not `README.md`: `landing: readme` already means "a `README.md`
- * is its section's landing page", and `sohl-thalorna/assets/content/README.md`
- * is a developer explainer about the source tree — adopting that name would make
- * Thalorna's public front page its build documentation.
- *
- * **Engine, not `sohl/`.** The `engine/` ÷ `sohl/` line separates *note-format*
- * knowledge from *game-system* knowledge, and a homepage is note format: it
- * carries no `system` block, mirrors no item builder, and would mean the same
- * thing for a game system that is not SoHL. Reachability is the symptom that
- * makes it obvious — `HarnMaster-3-FoundryVTT` declares no `itemBuilders`, so a
- * type living in the SoHL registry would be unavailable to HM3 and to every HM3
- * module, which is most of the packages that need a homepage and nothing else.
- *
- * **Its address is the package's, not the note's.** A homepage publishes at
- * `/<contentPackage>/` because that is where the package is, so `name.full`,
- * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
- * module simply never reads them). It compiles into no document, so it carries
- * no compendium UUID and appears in no pack and in no link-manifest entry.
- *
- * @module
+ * Every address a homepage carries, wherever it is written.
+ *
+ * **Both halves of the page are in scope, and that is the finding rather than
+ * the assumption.** Of the six homepages authored today, four carry every link
+ * in the body as ordinary markdown and two carry them in `landing:` — and the
+ * one whose dead links prompted the check has an *empty body*, so a body-only
+ * reading would have found nothing at all on it. A dead link in a card is
+ * exactly as broken as one in a paragraph.
+ *
+ * Three shapes are gathered, and the caller needs to tell them apart because
+ * the rules differ:
+ *
+ * - **`url`** — package-relative, resolved against the site by the theme.
+ * - **`href`** — already resolved, used verbatim.
+ * - **prose and body markdown links** — emitted as written and resolved by the
+ *   browser against the landing's own address, which *is* the package root, so
+ *   a relative one means the same thing a `url` does.
+ *
+ * `banner:` is not an address: it is an image path resolved through the CDN
+ * base, and `banner: none` is a sentinel rather than a target. Top-level
+ * `title` and `description` are not walked either — they are set as text, never
+ * rendered as markdown.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {string} [body] - The note's markdown body.
+ * @returns {Array<{field: string, url: string, kind: string}>} Every address,
+ *   frontmatter first and then the body, each with the dotted path it was
+ *   written at.
  */
+export function homepageAddresses(fm: object | null | undefined, body?: string): Array<{
+    field: string;
+    url: string;
+    kind: string;
+}>;
 /**
  * The note type that compiles to the package homepage.
  *
@@ -116,3 +107,19 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  * @type {string}
  */
 export const HOMEPAGE_DESTINATION: string;
+/**
+ * The two frontmatter keys that hold an address, and what each one means.
+ *
+ * They are **not** interchangeable, and a check that treated them as one would
+ * be wrong about both. The theme resolves a `url` against the site with
+ * `relURL`, so a package writes `kb/rules/` and is served `/sohl/kb/rules/`
+ * without ever naming its own prefix. An `href` is an address that is *already*
+ * resolved and is used verbatim — which is what `cards.source: sections` fills
+ * in, since a section's permalink already carries the prefix.
+ *
+ * So a leading `/` is a defect in a `url` (it is prefixed a second time) and
+ * correct in an `href`.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const HOMEPAGE_ADDRESS_KEYS: ReadonlySet<string>;

package/types/engine/pack-config.d.mts

@@ -56,6 +56,19 @@ export function configFromData(data: unknown, configPath: string): import("../co
  *   compilers know neither what to compile nor where to put it.
  */
 export function loadPackConfig(): import("../config.mjs").ContentBuildConfig;
+/**
+ * The file {@link loadPackConfig} resolved the configuration from.
+ *
+ * A diagnostic about a *configured* value has to name the file it was declared
+ * in, and re-deriving that path at the point of the finding would be a second
+ * resolution free to disagree with the first — the `PACKAGE_BUILD_CONFIG`
+ * override, the upward walk and the one-file-per-directory rule all have to
+ * come out the same way. This reports the path actually read.
+ *
+ * @returns {string} Its absolute path.
+ * @throws {Error} As {@link loadPackConfig}, when there is no configuration.
+ */
+export function packConfigPath(): string;
 /** The stem every consuming repository declares its build under. */
 export const CONFIG_BASENAME: "package-build.config";
 /**

package/types/engine/site-build.d.mts

@@ -65,10 +65,16 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * 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 (until #54) 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 — 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.

package/types/manifest.d.mts

@@ -59,6 +59,60 @@ export function releaseUrls({ repoUrl, version, artifact }: {
  * @returns {object[]} The manifest's `packs` array.
  */
 export function manifestPacks(config: object): object[];
+/**
+ * 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 }: {
+    packFolders?: unknown;
+    packs?: readonly {
+        name: string;
+    }[] | undefined;
+}): Array<{
+    severity: "error" | "warning";
+    message: string;
+    pack: string;
+    folder?: string;
+    keyPath: Array<string | number>;
+}>;
 /**
  * The `relationships` block as published — every declared dependency, with the
  * build's own keys dropped.
@@ -109,20 +163,32 @@ export function buildManifest({ config, packageJson, artifact, flags }: {
 /**
  * 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 function writeManifest({ config, packageJson, artifact, outDir, flags, }: {
+export function writeManifest({ config, packageJson, artifact, outDir, flags, configFile, }: {
     config: object;
     packageJson: object;
     artifact: string;
     outDir: string;
     flags?: Record<string, object> | undefined;
+    configFile?: string | undefined;
 }): Promise<{
     path: string;
     manifest: object;

package/types/sohl/kb-passes.d.mts

@@ -54,11 +54,15 @@ export function rewriteRepoLinks(body: string, docRel: string, options: object):
  * 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: {
     symbolMap?: string | undefined;