@heroiclands/package-build 4.0.0 → 6.0.0

package/types/content-config.d.mts

@@ -1,3 +1,19 @@
+/**
+ * Whether this package publishes the pages its content tree compiles to.
+ *
+ * The one question every reader of the mode actually asks — the site build, to
+ * decide whether to walk the tree at all, and the link-manifest emitter, to
+ * decide whether an entry carries a web `path`. Written once here so the two
+ * cannot come to disagree about what a mode means.
+ *
+ * @param {{publish: {site: SiteMode}}} config - A resolved configuration.
+ * @returns {boolean} Whether content pages are published.
+ */
+export function publishesContentPages(config: {
+    publish: {
+        site: SiteMode;
+    };
+}): boolean;
 /**
  * Validate and normalize a content configuration.
  *
@@ -76,6 +92,77 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
     landing: "readme";
 }>;
+/**
+ * How much of a package reaches the web.
+ *
+ * Every HeroicLands package publishes something: a top-level, human-authored
+ * homepage at `https://www.heroiclands.org/<contentPackage>/` saying what the
+ * module is, which system it needs and how to install it (#50). So there is no
+ * value here meaning *no web presence at all* — homepage-only is the **floor**,
+ * and the default.
+ *
+ * - `homepage` — the authored homepage, and **no other page**. The content tree
+ *   is not walked for pages, `site.sections` / `site.trees` / `site.landing`
+ *   emit nothing, and link-manifest entries carry no web `path`.
+ * - `content` — the homepage *plus* every page the content tree publishes: the
+ *   knowledgebase, the extra trees, the section landings.
+ *
+ * **Homepage-only is a first-class mode, not an accommodation.**
+ * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
+ * Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's
+ * terms) must each publish a homepage and nothing beneath it — two packages
+ * under two different fan-content licences. The boundary is **published
+ * content**: journal text, artwork, item descriptions, compiled notes. A
+ * human-authored page announcing the module discloses none of it. Because the
+ * failure mode is silent — a `site:` block added later ships licensed content
+ * with nobody noticing — the mode fences the content surfaces off rather than
+ * trusting a configuration to stay empty.
+ *
+ * This was a boolean until 5.0.0, and `false` read as "no web presence", which
+ * no longer describes any package. Both spellings are refused rather than
+ * mapped: a value silently reinterpreted reads to its author as though it still
+ * means what it said.
+ *
+ * @typedef {"homepage" | "content"} SiteMode
+ */
+/**
+ * The publishing modes {@link PublishSwitches.site} may name, floor first.
+ *
+ * @satisfies {readonly SiteMode[]}
+ */
+export const SITE_MODES: readonly ["homepage", "content"];
+/**
+ * How much of a package reaches the web.
+ *
+ * Every HeroicLands package publishes something: a top-level, human-authored
+ * homepage at `https://www.heroiclands.org/<contentPackage>/` saying what the
+ * module is, which system it needs and how to install it (#50). So there is no
+ * value here meaning *no web presence at all* — homepage-only is the **floor**,
+ * and the default.
+ *
+ * - `homepage` — the authored homepage, and **no other page**. The content tree
+ *   is not walked for pages, `site.sections` / `site.trees` / `site.landing`
+ *   emit nothing, and link-manifest entries carry no web `path`.
+ * - `content` — the homepage *plus* every page the content tree publishes: the
+ *   knowledgebase, the extra trees, the section landings.
+ *
+ * **Homepage-only is a first-class mode, not an accommodation.**
+ * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
+ * Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's
+ * terms) must each publish a homepage and nothing beneath it — two packages
+ * under two different fan-content licences. The boundary is **published
+ * content**: journal text, artwork, item descriptions, compiled notes. A
+ * human-authored page announcing the module discloses none of it. Because the
+ * failure mode is silent — a `site:` block added later ships licensed content
+ * with nobody noticing — the mode fences the content surfaces off rather than
+ * trusting a configuration to stay empty.
+ *
+ * This was a boolean until 5.0.0, and `false` read as "no web presence", which
+ * no longer describes any package. Both spellings are refused rather than
+ * mapped: a value silently reinterpreted reads to its author as though it still
+ * means what it said.
+ */
+export type SiteMode = "homepage" | "content";
 export type PackageKind = "systems" | "modules";
 export type PackDocumentType = "Actor" | "Adventure" | "Item" | "JournalEntry" | "Macro" | "Scene";
 /**
@@ -272,9 +359,10 @@ export type ManifestSwitches = {
 };
 export type PublishSwitches = {
     /**
-     * Render this package's knowledgebase/site pages.
+     * How much of this package reaches the web.
+     * See {@link SITE_MODES}.
      */
-    site: boolean;
+    site: SiteMode;
     manifests: ManifestSwitches;
 };
 export type ManifestSwitchesInput = {
@@ -394,8 +482,19 @@ export type DocsSpec = {
     itemFields?: DocPageSpec | undefined;
 };
 export type PublishSwitchesInput = {
-    site?: boolean | undefined;
+    site?: SiteMode | undefined;
     manifests?: ManifestSwitchesInput | undefined;
+    address?: AddressSchemeInput | undefined;
+};
+export type AddressSchemeInput = {
+    /**
+     * Where the content tree mounts inside the package.
+     */
+    prefix?: string | undefined;
+    /**
+     * Which note addresses a whole section.
+     */
+    landing?: string | undefined;
 };
 /**
  * One entry of a consumer's `itemBuilders` registry.
@@ -502,7 +601,9 @@ export type ContentBuildConfigInput = {
      */
     relationships?: Relationships | undefined;
     /**
-     * Publishing switches. Each defaults to off.
+     * Publishing switches. The manifest
+     * switches default to off; `site`
+     * defaults to `homepage`, the floor.
      */
     publish?: PublishSwitchesInput | undefined;
 };

package/types/engine/base-compiler.d.mts

@@ -57,6 +57,28 @@ export class BasePackCompiler {
      * @type {boolean}
      */
     static convertsWikilinks: boolean;
+    /**
+     * The document types whose **compiled output** this pass reads.
+     *
+     * Empty for every pass that reads only the content tree. The actors pass
+     * is the exception: a being names its embedded items by
+     * `(type, shortcode)`, and it resolves them against the JSON the item
+     * passes wrote — so an Actor pass must run after every Item pass, and it
+     * says so here.
+     *
+     * The generator derives the compile order from this (#73), so the order
+     * `packs:` declares is presentation only — it is the manifest's `packs`
+     * array as well, and a consumer orders that for a reader. A pass that
+     * reads another's output states the dependency once, in the class that
+     * does the reading, instead of every consuming repository having to know
+     * it when writing its pack list.
+     *
+     * A consumer registering a compiler of its own declares its dependencies
+     * the same way; a type no pack declares is simply not waited for.
+     *
+     * @type {readonly string[]}
+     */
+    static readsPackOutputOf: readonly string[];
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.

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

@@ -0,0 +1,125 @@
+/**
+ * Whether a note's frontmatter declares the homepage type.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether it is a homepage note.
+ */
+export function isHomepage(fm: object | null | undefined): boolean;
+/**
+ * The title a homepage publishes under.
+ *
+ * The one defaulted value on the page, and it defaults to the package's own
+ * `packageBuild.manifest.title` — the name Foundry already shows for the
+ * package — so a homepage that adds nothing to it need not restate it. An
+ * authored `title` wins, because a front page is allowed to greet a reader
+ * differently from a package browser.
+ *
+ * Falls back to `contentPackage` last, so a package that has no manifest of its
+ * own still yields a titled page rather than a blank heading.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {object} config - The resolved configuration.
+ * @returns {string} The title.
+ */
+export function homepageTitle(fm: object | null | undefined, config: object): string;
+/**
+ * The frontmatter a homepage publishes with.
+ *
+ * The note's own, plus the two derived values every emitted page carries: the
+ * resolved `title`, and the package the build derived — no note declares one
+ * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * `.Params.package`.
+ *
+ * An authored `aliases` is dropped for the same reason it is on every other
+ * page: Obsidian reads it as names a reader might call the note, Hugo reads it
+ * as URL redirects, and passing it through would publish a redirect stub at
+ * each one.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package this build publishes.
+ * @param {string} options.title - The resolved title.
+ * @returns {object} The frontmatter to write.
+ */
+export function homepageFrontmatter(fm: object, { contentPackage, title }: {
+    contentPackage: string;
+    title: string;
+}): object;
+/**
+ * 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.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_TYPE: string;
+/**
+ * What a homepage note may write under `sohl:` — nothing.
+ *
+ * Empty on purpose, and declared rather than omitted: a type with no vocabulary
+ * and a type that is unknown are different findings, and only the second is an
+ * authoring error. The whole envelope is the two top-level keys `type` and an
+ * optional `title`; there is no game-system data on a page that compiles to no
+ * document.
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
+/**
+ * Where a homepage is written, relative to the package's site root.
+ *
+ * Hugo's section landing, because the page *is* the package's landing: the
+ * package root is a section and this is its index.
+ *
+ * @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/index.d.mts

@@ -7,6 +7,8 @@ export * as packRouter from "./pack-router.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
+export * as homepage from "./homepage.mjs";
+export * as noteSchemas from "./note-schemas.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";

package/types/engine/note-schemas.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+export const ENGINE_NOTE_SCHEMAS: Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>;

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

@@ -41,6 +41,49 @@ export function collectTreePages(tree: object, ctx: object): {
     pages: object[];
     fmLinkFindings: object[];
 };
+/**
+ * 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: string, ctx: object): {
+    pages: 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 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: string, pages: readonly object[], config: object): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -63,6 +106,17 @@ export function collectTreePages(tree: object, ctx: object): {
  * @returns {object} The gate results and, when they pass, the built index.
  */
 export function siteGates(pages: object[], findings: object, { manifestDir }: object): object;
+/**
+ * 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(): object;
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates: any): boolean;
 /**

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;