@heroiclands/package-build 19.0.0 → 20.2.0

package/engine/note-claims.mjs

@@ -12,8 +12,9 @@
  */
 
 /**
- * **Which note types a configuration compiles at all** — and the finding for a
- * note whose type nothing claims (#146).
+ * **Which note types a configuration compiles at all** — the finding for a note
+ * whose type nothing claims (#146), and the one for a note that loses a
+ * document while the rest of it compiles (#152).
  *
  * Every compile pass answers one question about a note: _is this mine?_ A note
  * every pass answers "no" to is skipped as quietly as the thousands that
@@ -50,6 +51,27 @@
  * who invented a word. Collapsing the two would send `harn-ensemble` to correct
  * five perfectly good notes.
  *
+ * ## The partial case is a third condition, and it was invisible (#152)
+ *
+ * The table above asks whether a note is compiled *at all*, and a note that
+ * compiles one of its two documents answers yes. But a note produces more than
+ * one document as a matter of course — an item note an Item and the
+ * JournalEntry its prose becomes, a map note a Scene and a JournalEntry, an
+ * actor note an Actor and a JournalEntry since #337 — so a configuration
+ * missing a pack for *one* of them dropped that document while the rest of the
+ * note compiled into a pack that does exist. The build succeeded and shipped
+ * half of what was written.
+ *
+ * | condition | what it means | whose fix |
+ * | --- | --- | --- |
+ * | some documents have a pack, one does not | this note compiles, and one of its documents is lost | configuration |
+ *
+ * {@link documentClassesFor} is the question this needs and the type-level
+ * table could not answer: not "is anything claiming this note" but "which
+ * documents does this note produce", asked per note, because documentation is
+ * per note — a doc-carrying note with an empty body produces no JournalEntry at
+ * all, and `Journals.skipNote` is where that is decided.
+ *
  * ## The claim table mirrors `selects`, and a test holds them together
  *
  * Which note types a pass claims is stated by that pass's `selects`, and the
@@ -61,7 +83,7 @@
  * @module
  */
 
-import { assertSuppliedCorpus } from "./helpers.mjs";
+import { assertSuppliedCorpus, parseMarkdownFile } from "./helpers.mjs";
 // The record accessors only: this module is imported by the content index, so
 // importing the index back would close a cycle (#243).
 import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
@@ -252,6 +274,115 @@ export function noteTypesClaimedBy(docType, sources) {
     }
 }
 
+/**
+ * Every Foundry document class {@link noteTypesClaimedBy} answers for.
+ *
+ * The switch above, read the other way round. It is written out rather than
+ * derived because a `switch` cannot be enumerated — and
+ * `tests/unclaimed-note-types.test.ts` holds the two together by checking that
+ * no class outside this list claims anything, so a row added there and not here
+ * fails rather than going quiet.
+ *
+ * Order is the order a reader meets them in a message, not a precedence.
+ *
+ * @type {readonly string[]}
+ */
+export const CLAIMABLE_DOCUMENT_TYPES = Object.freeze([
+    "Item",
+    "Actor",
+    "JournalEntry",
+    "Macro",
+    "Scene",
+    "Adventure",
+]);
+
+/**
+ * Every document class a note of one type compiles into (#152).
+ *
+ * **A note produces more than one document, and that is the ordinary case.** An
+ * item note compiles an Item *and* the JournalEntry its prose becomes; a map
+ * note a Scene and a JournalEntry; since #337 an actor note an Actor and a
+ * JournalEntry too. {@link claimedNoteTypes} unions over the configured packs
+ * and so answers "is this note compiled *at all*", which is #146's question and
+ * cannot see a note that compiles one of its two documents and loses the other.
+ *
+ * Asked of the **claim table** rather than of a list of its own, so the set of
+ * documents a type produces and the set of passes that claim it are one
+ * statement. A pass that starts claiming a type starts producing its document
+ * here, with nothing to remember.
+ *
+ * **Union across systems, never per system.** A type one system maps and
+ * another does not appears once, because the `Item` and `Actor` rows already
+ * fold the maps together — so this cannot report a document class a system
+ * deliberately declines to produce, which is the silence #79 requires.
+ *
+ * ## The JournalEntry row is the one that is per *note*
+ *
+ * Every other row is a property of the type: a `macro` note produces a Macro, a
+ * map note a Scene, whatever either says. Documentation is not. `Journals`
+ * declines a doc-carrying note whose body is empty — *"an item with no prose
+ * gets no doc, and the items pass leaves its description empty rather than
+ * pointing at nothing"* — so whether an item note produces a JournalEntry is
+ * decided by the note, not by its type.
+ *
+ * That distinction is the whole difference between a useful finding and a
+ * useless one. `sohl-kethira-basic` declares no JournalEntry pack and ships 393
+ * notes whose descriptions are *deliberately* empty, under the Fan Material
+ * Guidelines its configuration explains at length. A type-level answer would
+ * report every one of them for losing a document none of them produces. Asking
+ * per note, it reports none, and still reports `harn-ensemble`'s 2,517 beings,
+ * whose `{#appearance}` and `{#dossier}` prose is real and is lost.
+ *
+ * `hasProse` is therefore how the caller answers that, and it is a **thunk** so
+ * that the file is read only where the answer could change the outcome. Omitted,
+ * the answer is the type's full potential — every document such a note *could*
+ * produce — which is what a caller asking about a type rather than a note wants.
+ *
+ * @param {string} type - The note's declared `type`, current spelling.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {(() => boolean)|boolean} [opts.hasProse] - Whether *this note* carries
+ *   a body. Omitted, the type's potential is reported.
+ * @returns {string[]} The document classes, in {@link CLAIMABLE_DOCUMENT_TYPES}
+ *   order. Empty for a type nothing compiles.
+ */
+export function documentClassesFor(type, sources, { hasProse } = {}) {
+    const resolved = resolveSources(sources);
+    return CLAIMABLE_DOCUMENT_TYPES.filter((docType) => {
+        if (!noteTypesClaimedBy(docType, resolved).has(type)) return false;
+        if (docType !== "JournalEntry") return true;
+        // A type whose *whole* document is the journal always produces one;
+        // there is no body condition, because the body is the document.
+        if (JOURNAL_TYPES.has(type)) return true;
+        if (hasProse === undefined) return true;
+        return Boolean(typeof hasProse === "function" ? hasProse() : hasProse);
+    });
+}
+
+/**
+ * Whether a note carries a body at all — the condition `Journals.skipNote`
+ * applies, asked from the outside (#152).
+ *
+ * Read from the file rather than from the index record, because a record
+ * carries a note's frontmatter and its derived address and not its prose. The
+ * walk that calls this is already reading the same file to locate the `type:`
+ * key for a finding's position, so this is the same cost in the same place —
+ * and it is called only for a note whose documentation would otherwise be
+ * reported as lost.
+ *
+ * @param {string} absPath - The note's path.
+ * @returns {boolean} True when the body has content.
+ */
+function noteHasProse(absPath) {
+    try {
+        return Boolean(parseMarkdownFile(absPath).body);
+    } catch {
+        // Unreadable here means unreadable for the compile too, which reports
+        // it with a message about the file rather than about its documentation.
+        return false;
+    }
+}
+
 /**
  * Every note type some pack in a configuration would compile.
  *
@@ -418,6 +549,44 @@ function specifiedMessage(type) {
     );
 }
 
+/**
+ * The **partial** finding: the note compiles, and one of its documents does not
+ * (#152).
+ *
+ * #146's question is "does anything claim this note", and the answer is yes —
+ * which is exactly why this went unreported. A note produces more than one
+ * document, and a configuration missing a pack for one of them drops that
+ * document while the rest of the note compiles into a pack that does exist. The
+ * build succeeds, the compendium ships, and the missing half is discoverable
+ * only by noticing it is not there.
+ *
+ * The message names the note, the document class with no pack, and the class
+ * that *did* compile — the last because it is what distinguishes this from
+ * #146's finding at a glance: the note is not unclaimed, it is half-claimed, and
+ * the fix is a pack rather than a `type:`.
+ *
+ * @param {string} type - The note's declared `type`.
+ * @param {readonly string[]} missing - Document classes with no pack.
+ * @param {readonly string[]} compiled - Document classes that do have one.
+ * @returns {string} The message.
+ */
+function partialMessage(type, missing, compiled) {
+    // `Item`, `Actor` and `Adventure` take "an". Spelled out rather than left
+    // to read as a typo in a message an author meets at the moment they are
+    // being told something went wrong.
+    const article = (name) => (/^[AEIOU]/.test(name) ? "an" : "a");
+    const list = (classes) => classes.map((name) => `${article(name)} ${name}`).join(" and ");
+    const names = (classes) => classes.join(" and ");
+    return (
+        `a note of type "${type}" compiles into ${list(missing)} as well as ` +
+        `${list(compiled)}, and \`packs:\` declares no ${names(missing)} pack — ` +
+        `so the ${names(missing)} is dropped with no error while the rest of the ` +
+        `note compiles. Declare ${list(missing)} pack in ` +
+        `package-build.config.yaml, or accept the loss deliberately by not ` +
+        `authoring what it would have carried.`
+    );
+}
+
 /**
  * The **authoring** finding: nothing anywhere knows the type.
  *
@@ -455,9 +624,13 @@ function authoringMessage(type) {
  */
 export function unclaimedNoteFindings(config = loadPackConfig(), sources, { records } = {}) {
     const resolved = resolveSources(sources);
-    const claimed = claimedNoteTypes(config, resolved);
     const vocabulary = noteTypeVocabulary(resolved);
     const findings = [];
+    // The document classes this configuration can actually receive a compiled
+    // document into. A **prebuilt** pack is not one of them, for the reason
+    // {@link claimedNoteTypes} states: its JSON is checked in, it has no pass,
+    // and no note is routed into it.
+    const configured = new Set((config.packs ?? []).filter((p) => !p.prebuilt).map((p) => p.type));
 
     // The corpus this compile derived once (#243), required rather than
     // derived here: this module is imported *by* the content index, so it
@@ -481,7 +654,37 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // authored one (#78). The rename itself is reported by the frontmatter
         // lint, which can say what to write instead.
         const current = currentType(type);
-        if (claimed.has(current)) continue;
+
+        // Every document this note produces, against the classes this
+        // configuration has a pack for. Three outcomes, and the middle one is
+        // #152's — it was invisible while the question was only "is anything
+        // claiming this note", because the answer there is yes.
+        const produces = documentClassesFor(current, resolved, {
+            // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
+            // go asks, so a tree with a JournalEntry pack — which is most of
+            // them — reads no bodies at all.
+            hasProse: () => noteHasProse(absPath),
+        });
+        const missing = produces.filter((docType) => !configured.has(docType));
+        const compiled = produces.filter((docType) => configured.has(docType));
+
+        // Every document it produces has somewhere to go.
+        if (produces.length && !missing.length) continue;
+
+        // Some do and some do not: the note compiles, and one of its documents
+        // is dropped in silence. A type nothing produces at all falls past this
+        // to the #146 messages below, where `produces` being empty is itself
+        // part of the answer.
+        if (compiled.length) {
+            findings.push({
+                file: absPath,
+                ...locateFrontmatterKey(absPath, "type", type),
+                severity: /** @type {"error"} */ ("error"),
+                type,
+                message: partialMessage(type, missing, compiled),
+            });
+            continue;
+        }
 
         findings.push({
             file: absPath,

package/engine/note-ids.mjs

@@ -44,6 +44,11 @@ import { documentId } from "./content-address.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { contentPackage } from "./content-package.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+// The folder id's derivation, taken from the pass that owns it rather than
+// restated here — see the `folder` branch below. `folder-notes.mjs` reaches
+// only `content-address`, `address-charset`, `ids` and `retired-fields`, none
+// of which reach this module, so the direction closes no cycle.
+import { FOLDER_TYPE, folderDocId } from "./folder-notes.mjs";
 
 /**
  * A frontmatter value read as a non-blank string, or `undefined`.
@@ -64,6 +69,20 @@ function text(value) {
 /**
  * The document id a note compiles under: its pin, or its address.
  *
+ * **One type hashes its address differently, and that is not an exception to
+ * the rule but an application of it.** A `Folder` is a document of its own
+ * class, and its id is hashed under the `folder` namespace so that a folder and
+ * an item sharing a shortcode cannot derive one id — a collision Foundry would
+ * not report, since it keys folders and documents in separate collections
+ * (#258). So the answer for a folder comes from
+ * {@link module:engine/folder-notes.folderDocId}, the pass that emits those
+ * documents, rather than from a second derivation here.
+ *
+ * That this function ever answered differently was invisible from inside a
+ * build — no pass reads a folder's id from here — and surfaced only in the
+ * content index, which is read from outside and had no way to be checked
+ * against what shipped (#310).
+ *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
  * and inventing an id for one would file it under nothing. Every caller already
@@ -88,7 +107,12 @@ export function noteDocId(fm, { pkg, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS } = {})
     const type = text(fm.type);
     const shortcode = text(fm.shortcode);
     if (!type || !shortcode) return undefined;
-    return documentId(pkg ?? contentPackage(), systemOf(type, maps), type, shortcode);
+    const owner = pkg ?? contentPackage();
+    // Lowercased because `collectFolderNotes` matches the type that way, and
+    // the two must answer alike about the same note or the divergence this
+    // branch closes reopens under a capitalised `type: Folder`.
+    if (type.toLowerCase() === FOLDER_TYPE) return folderDocId(owner, shortcode);
+    return documentId(owner, systemOf(type, maps), type, shortcode);
 }
 
 /**

package/engine/note-vocabulary.mjs

@@ -422,7 +422,14 @@ export const NOTE_VOCABULARY = Object.freeze({
         // values here would put a second, weaker answer beside the real one.
         subTypes: null,
         data: Object.freeze([
-            { name: "portrait", ...TEXT, describe: "Path to the portrait image." },
+            {
+                name: "portrait",
+                ...TEXT,
+                describe:
+                    "Path to the portrait image. Its first segment says which package owns " +
+                    "the file: `systems/…` and `modules/…` are emitted unchanged, anything " +
+                    "else is this package's own and is rooted under its assets.",
+            },
             TEMPLATE_PRIORITY,
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
@@ -466,7 +473,14 @@ export const NOTE_VOCABULARY = Object.freeze({
     vehicle: Object.freeze({
         subTypes: null,
         data: Object.freeze([
-            { name: "portrait", ...TEXT, describe: "Path to the portrait image." },
+            {
+                name: "portrait",
+                ...TEXT,
+                describe:
+                    "Path to the portrait image. Its first segment says which package owns " +
+                    "the file: `systems/…` and `modules/…` are emitted unchanged, anything " +
+                    "else is this package's own and is rooted under its assets.",
+            },
             TEMPLATE_PRIORITY,
         ]),
     }),
@@ -577,16 +591,31 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...TEXT,
                 describe: "Roll formula for the delay between contraction and onset.",
             },
+            {
+                name: "onsetDurationBase",
+                ...NUM,
+                describe: "That delay in seconds, stated outright instead of rolled.",
+            },
             {
                 name: "healingCheckDurationFormula",
                 ...TEXT,
                 describe: "Roll formula for the interval between healing checks.",
             },
+            {
+                name: "healingCheckDurationBase",
+                ...NUM,
+                describe: "That interval in seconds, stated outright instead of rolled.",
+            },
             {
                 name: "resolutionDurationFormula",
                 ...TEXT,
                 describe: "Roll formula for the time from onset to resolution.",
             },
+            {
+                name: "resolutionDurationBase",
+                ...NUM,
+                describe: "That time in seconds, stated outright instead of rolled.",
+            },
         ]),
     }),
 
@@ -719,7 +748,39 @@ export const NOTE_VOCABULARY = Object.freeze({
             "shock",
             "coma",
         ]),
-        data: Object.freeze([TEMPLATE_PRIORITY]),
+        data: Object.freeze([
+            TEMPLATE_PRIORITY,
+            {
+                name: "healingCheckDurationFormula",
+                ...TEXT,
+                describe: "Roll formula for the interval between healing checks.",
+            },
+            {
+                name: "healingCheckDurationBase",
+                ...NUM,
+                describe: "That interval in seconds, stated outright instead of rolled.",
+            },
+            {
+                name: "bloodLossAdvanceDurationFormula",
+                ...TEXT,
+                describe: "Roll formula for the interval between blood-loss advances.",
+            },
+            {
+                name: "bloodLossAdvanceDurationBase",
+                ...NUM,
+                describe: "That interval in seconds. Setting it is what makes the wound bleed.",
+            },
+            {
+                name: "courseDurationFormula",
+                ...TEXT,
+                describe: "Roll formula for the interval between course tests.",
+            },
+            {
+                name: "courseDurationBase",
+                ...NUM,
+                describe: "That interval in seconds, stated outright instead of rolled.",
+            },
+        ]),
     }),
 
     weapongear: Object.freeze({
@@ -809,6 +870,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             "folk",
             "culture",
             "bestiary",
+            "gathering",
         ]),
         // Nothing of its own: a lore note is prose, and what it *is* about is
         // its subType. The specification declares an empty table for it, and
@@ -881,12 +943,17 @@ export const NOTE_VOCABULARY = Object.freeze({
         // derived for them, which is precisely what a subType decides (#174).
         subTypes: Object.freeze(["battlemap", "localmap", "regionalmap"]),
         data: Object.freeze([
-            // The specification spells this `img`, matching every other
-            // note type, while the map compiler reads `image` from
-            // `sohl:` today. It says outright that one of the two has
-            // to move; the container takes the specification's name,
-            // and moving the authored key is the migration's business.
-            { name: "img", ...TEXT, describe: "Path to the map art." },
+            // `img`, as every other note type spells its artwork. A map alone
+            // read `image` out of its `sohl:` block; that spelling is retired
+            // and gone (#149), so the two names are one again.
+            {
+                name: "img",
+                ...TEXT,
+                describe:
+                    "Path to the map art, owned by whichever package its first segment " +
+                    "names — `systems/…` and `modules/…` unchanged, anything else this " +
+                    "package's own.",
+            },
             {
                 name: "dimensions",
                 ...LIST,

package/engine/pack-config.mjs

@@ -47,14 +47,38 @@
  * actually needed: every accessor in the engine funnels through here, so
  * anything that reads configuration throws with the message below.
  *
- * **Located by walking up from this module, not from the working directory.**
- * The config file sits at the root of the repository that installed the
- * toolchain, so climbing out of
- * `node_modules/@heroiclands/package-build/engine/` lands on it either way.
- * Resolving it against `process.cwd()` instead would make the build read a
- * different tree depending on where it was launched from, which is the very
- * property #1508 removed. `PACKAGE_BUILD_CONFIG` names the file explicitly when
- * a consumer keeps it somewhere else.
+ * **Located by walking up from the working directory, and from this module only
+ * when that finds nothing.** The config file sits at the root of the repository
+ * being built, and a build is run inside that repository — so the walk from
+ * `process.cwd()` finds it from the root, from `packages/`, from anywhere
+ * below. Climbing from this module instead finds the same file too, right up
+ * until the installed package is not the one the caller is standing in: a git
+ * worktree nested under its parent checkout with no `node_modules` of its own
+ * resolves `@heroiclands/package-build` out of the *parent's*, because Node's
+ * resolution walks parent directories. `import.meta.dirname` is then inside the
+ * parent, the walk lands on the parent's configuration, and the build compiles
+ * the parent's content tree into the parent's `build/` and exits 0 — saying so
+ * only in paths that are easy to read past (#364).
+ *
+ * That failure is undetectable on exactly the work most likely to provoke it.
+ * The usual tell is a zero diff where a change was expected; an
+ * output-preserving sweep *expects* zero differences, so the tell is gone and a
+ * wrong-tree build produces confident evidence for a tree nobody touched. Order
+ * of resolution is the fix, because reviewer vigilance cannot be.
+ *
+ * The module walk stays, as the fallback for an invocation from outside any
+ * repository, and is never *preferred*: a configuration found above the
+ * installed package rather than above the working directory is not the one a
+ * caller meant. When both walks find one and they disagree, the ignored one is
+ * named in a warning rather than passed over — that disagreement is also the
+ * only cheap signal that this tree is building on another checkout's
+ * `node_modules`. `PACKAGE_BUILD_CONFIG` names the file explicitly and skips
+ * both walks, which is why it was the workaround.
+ *
+ * What #1508 removed stays removed. The property it bought was not "resolve
+ * from the module"; it was that a build reads one tree however it was launched,
+ * and an upward walk from the working directory keeps that — every directory
+ * inside a repository resolves that repository's single configuration.
  *
  * **Loaded synchronously.** A YAML config is parsed synchronously as a matter
  * of course; an `.mjs` one is loaded with `require` rather than `await import`,
@@ -81,7 +105,12 @@ import { createRequire } from "node:module";
 import YAML from "yaml";
 
 import { defineConfig, DERIVED_SYSTEM_VERSION } from "../content-config.mjs";
-import { formatDiagnostic, positionOfYamlPath, yamlKeyPath } from "./diagnostics.mjs";
+import {
+    emitDiagnostic,
+    formatDiagnostic,
+    positionOfYamlPath,
+    yamlKeyPath,
+} from "./diagnostics.mjs";
 
 /** The stem every consuming repository declares its build under. */
 export const CONFIG_BASENAME = "package-build.config";
@@ -144,6 +173,41 @@ export function findConfigFile(from) {
     }
 }
 
+/**
+ * Which configuration file a build launched here should read, and what each
+ * walk found.
+ *
+ * Kept separate from {@link loadPackConfig} because the *choice* is worth being
+ * able to ask about without loading anything: the two walks disagreeing is the
+ * observable form of #364, and a caller that wants to report it — or a test
+ * that wants to describe it — should not have to reproduce the resolution and
+ * risk disagreeing with the loader about it. It performs I/O, and is named for
+ * it, like the {@link findConfigFile} it calls twice.
+ *
+ * `PACKAGE_BUILD_CONFIG` is deliberately not consulted here. An explicit name
+ * is not a search result: {@link loadPackConfig} short-circuits on it before it
+ * ever asks, so there is no walk to report and nothing to disagree with.
+ *
+ * @param {object} [from] - Where to walk up from; both default to the real
+ *   thing, and are parameters only so a caller can describe a tree it is not
+ *   standing in.
+ * @param {string} [from.cwd] - The directory the build was launched in.
+ * @param {string} [from.moduleDir] - The directory this module sits in.
+ * @returns {{path: string|undefined, fromCwd: string|undefined, fromModule: string|undefined}}
+ *   The file to read, and each walk's own answer — the same file in an ordinary
+ *   build, different ones in a worktree resolving the toolchain out of its
+ *   parent checkout.
+ * @throws {Error} As {@link findConfigFile}, when one directory holds more than
+ *   one configuration.
+ */
+export function resolveConfigFile({ cwd = process.cwd(), moduleDir = import.meta.dirname } = {}) {
+    const fromCwd = findConfigFile(cwd);
+    const fromModule = findConfigFile(moduleDir);
+    // `??`, not `||`: the module walk is a fallback for finding *nothing*, never
+    // a tie-break between two answers.
+    return { path: fromCwd ?? fromModule, fromCwd, fromModule };
+}
+
 const require = createRequire(import.meta.url);
 
 /**
@@ -607,20 +671,46 @@ export function loadPackConfig() {
     if (loaded) return loaded;
 
     const explicit = process.env.PACKAGE_BUILD_CONFIG;
-    const configPath = explicit ? path.resolve(explicit) : findConfigFile(import.meta.dirname);
+    const found = explicit ? undefined : resolveConfigFile();
+    const configPath = explicit ? path.resolve(explicit) : found.path;
 
     if (!configPath || !fs.existsSync(configPath)) {
         throw new Error(
             explicit ?
                 `package-build: PACKAGE_BUILD_CONFIG names ${configPath}, ` +
                     `which does not exist.`
+                // Both origins, because either walk could have found one and
+                // naming only the module's would send a reader looking inside
+                // `node_modules/` for a file that belongs in their own root.
             :   `package-build: no ${CONFIG_FILENAMES.join(" or ")} found at ` +
-                    `or above ${import.meta.dirname}. A consuming repository ` +
-                    `declares its build in one file at its root; set ` +
+                    `or above ${process.cwd()}, nor at or above ` +
+                    `${import.meta.dirname}. A consuming repository declares ` +
+                    `its build in one file at its root; set ` +
                     `PACKAGE_BUILD_CONFIG to name it elsewhere.`,
         );
     }
 
+    // Two different files, one of which is about to be ignored. Said out loud
+    // because the alternative is what #364 was: a build that reads the parent
+    // checkout's configuration, compiles the parent's tree, and reports it only
+    // in absolute paths nobody rereads. A warning rather than an error — the
+    // shape is legitimate, and the working directory's answer is the right one
+    // — but never silence.
+    if (found?.fromCwd && found.fromModule && found.fromCwd !== found.fromModule) {
+        emitDiagnostic({
+            severity: "warning",
+            message:
+                `package-build: reading ${found.fromCwd}, the configuration ` +
+                `above this working directory. The installed ` +
+                `@heroiclands/package-build sits under a different ` +
+                `repository, whose own ${found.fromModule} is being ignored — ` +
+                `usually because this tree has no \`node_modules\` of its own ` +
+                `and resolved the toolchain out of a parent checkout. Run ` +
+                `\`npm ci\` here, or set PACKAGE_BUILD_CONFIG, to say which ` +
+                `tree is meant.`,
+        });
+    }
+
     loaded =
         configPath.endsWith(".mjs") ?
             loadCodeConfig(configPath)

package/engine/prose-config.mjs

@@ -134,6 +134,48 @@ export function sharedPrettierOptionsFor(file) {
     return /\.md$/i.test(file) ? { ...PRETTIER_BASE, ...PRETTIER_MARKDOWN } : { ...PRETTIER_BASE };
 }
 
+/**
+ * Where a resolved Prettier configuration disagrees with the shared one.
+ *
+ * The runner resolves each file's options as *either* the consumer's own config
+ * or {@link sharedPrettierOptionsFor}, never a merge. That is what bare Prettier
+ * does and it is the contract — but it means the conventions this package exists
+ * to publish hold by convention alone, and they lapse in two opposite directions
+ * (#133). A consumer that declares any config of its own gets whatever that
+ * config says: spread {@link PRETTIER_BASE} without the markdown override and
+ * every note reindents at 4, the reindentation the override was added to prevent
+ * (#76); write a partial `.prettierrc` such as `{"tabWidth": 2}` and
+ * `printWidth`, `trailingComma`, `experimentalTernaries` and the rest fall back
+ * to Prettier's own defaults. A consumer that declares *nothing* formats one way
+ * under this command and another under a bare `npx prettier`.
+ *
+ * This is the comparison that makes either absence visible. It is a **report,
+ * not a merge**: what a consumer declared still wins, and a deliberate local
+ * choice stays possible — it stops being silent, and nothing here fails a build
+ * over it.
+ *
+ * Every shared value is a primitive, so `!==` is the whole comparison. An option
+ * holding an object would need a deeper one, and the shared set has none —
+ * `overrides` is not compared, because `resolveConfig` has already applied and
+ * removed it by the time a configuration reaches this.
+ *
+ * @param {object|null|undefined} resolved - What `prettier.resolveConfig`
+ *   returned for `file`, with the consumer's own `overrides` already applied.
+ *   `null` — no configuration at all — reports every shared key as absent.
+ * @param {string} file - Path the options were resolved for. Decides whether
+ *   {@link PRETTIER_MARKDOWN} is part of what is expected.
+ * @returns {Array<{key: string, shared: unknown, local: unknown}>} One entry per
+ *   shared key the resolved configuration does not carry the value of, in the
+ *   order {@link PRETTIER_BASE} declares them. `local` is `undefined` where the
+ *   key is absent entirely, which is not the same finding as a key set to
+ *   something else and is reported differently.
+ */
+export function sharedPrettierDivergence(resolved, file) {
+    return Object.entries(sharedPrettierOptionsFor(file))
+        .filter(([key, shared]) => resolved?.[key] !== shared)
+        .map(([key, shared]) => ({ key, shared, local: resolved?.[key] }));
+}
+
 /**
  * The markdownlint rules — the structural checks Prettier cannot make.
  *