@heroiclands/package-build 19.0.0 → 20.2.0

package/CONTENT.md

@@ -349,6 +349,21 @@ pack: mysteries
   that type's default implicitly; a type with several designates one with
   `default: true`. Where several exist and none is marked, a declaration is
   **mandatory** and an undeclared note fails the build.
+- **A default is per system, not merely per type** (#58). The rule above counts
+  every pack of a type together, so a tree shipping one Actor pack per system has
+  two and would need a flag — except that asked _per system_ the layout is
+  unambiguous, one pack each, for the same reason a single-pack type needs no
+  flag. And a system is never answered with another system's pack: a type-wide
+  default declaring `system: sohl` does not route the HM3 document, which
+  otherwise had that pass see a pack name that was not its own and skip every
+  note in the tree without a word.
+- **A `pack:` naming another system's pack** is refused where the _block_
+  declares it — `hm3.pack` says where the HM3 document goes, so naming a SoHL
+  pack is a contradiction, reported naming the note and the pack. At the top
+  level it is no contradiction: the shared position is the value a note states
+  once for every system, and a system-specific pack cannot be that value, so it
+  simply does not answer for the other system, which falls through to its own
+  default.
 - **A `pack:` naming no configured pack is a build error**, not a fall-through to
   the default. A typo'd name that quietly landed content in the wrong compendium
   would be silent partial compilation — the failure mode this toolchain's guards
@@ -357,12 +372,43 @@ pack: mysteries
 - **A note's `pack:` names where its _own_ document goes.** Anything derived from
   it — an item's or a macro's prose, which compiles into a JournalEntry of its
   own — lands in the default pack of _that_ type.
-
-**The configuration is found by walking up, not from the working directory.**
-`engine/pack-config.mjs` climbs from itself — so it works from `packages/` and
-from `node_modules/` alike, and does not depend on the directory the build was
-launched from. Set `PACKAGE_BUILD_CONFIG` to point at the file explicitly if a
-consumer keeps it somewhere else.
+- **Every document a note produces needs a pack, and one that has none is a
+  finding** (#152). 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. Where the configuration declares no pack for one of them, that
+  document used to be dropped while the rest of the note compiled into a pack
+  that does exist — a build that succeeds and ships half of what was written.
+  The finding names the note, the class with no pack, and the class that did
+  compile, which is what distinguishes it from a note **nothing** claims: that
+  one is a `type:` to correct, this one a pack to declare.
+
+  It is asked **per note, not per type**, because documentation is: `Journals`
+  declines a doc-carrying note whose body is empty — an item with no prose gets
+  no doc — so a tree of deliberately description-less items loses nothing by
+  having no JournalEntry pack, and is told nothing. And it names no system, so a
+  type one system maps and another does not stays silent for the system that
+  declines it, per #79.
+
+**The configuration is found by walking up from the working directory, and from
+the installed package only if that finds nothing.** `engine/pack-config.mjs`
+climbs from `process.cwd()` first, so a build reads the tree it was run in —
+from the repository root, from `packages/`, from anywhere below, since the walk
+climbs. Climbing from the module itself is the fallback, for an invocation from
+outside any repository.
+
+The order matters in one shape: 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. Climbing
+from the module then landed on the _parent's_ configuration, and the build
+compiled the parent's content tree into the parent's `build/` and exited 0
+(#364). When both walks find a configuration and they disagree, the working
+directory's is read and the ignored one is named in a warning — that
+disagreement is also the cheapest signal that this tree is building on another
+checkout's `node_modules`. Run `npm ci` in the worktree to give it its own.
+
+Set `PACKAGE_BUILD_CONFIG` to point at the file explicitly if a consumer keeps
+it somewhere else; it skips both walks.
 
 **The configuration is resolved on first read, never at import.** Every module
 here can be imported — and `content-build --version` and `--help` answered — in a
@@ -388,6 +434,24 @@ exactly once, here, and read through `loadPackConfig()` everywhere. There is one
 resolved set at runtime; the compilers and the link-manifest emitter cannot come
 to disagree about which notes carry documentation.
 
+**Every note compiling into a system-bearing document carries documentation, and
+that includes actors** (#337). `docEntryTypes` is `itemTypes` plus the actor
+types the shipped subtype maps declare (`ACTOR_TYPES`, derived from them rather
+than listed again), plus `macro` and the map types. Only `doc` is outside it, for
+the reason that actually applies to it: its single document _is_ the prose.
+
+A being therefore has the same two addresses an item has — `<pkg>-<system>-being-<shortcode>`
+for the Actor and `<pkg>-none-docbeing-<shortcode>` for the page — where before
+it had only the first, and was the one system-bearing note a prose link could not
+name.
+
+**An actor keeps its prose inline as well, and that asymmetry is deliberate.** An
+item's description is an `@UUID` pointer into its journal, because one item is
+embedded across hundreds of beings and baking long prose into every copy bloats
+the compendium by the length of the text times the number of carriers. An actor
+is singular, so the same indirection costs a reader a click and saves nothing:
+`system.appearance` and `system.dossier` stay as rendered prose.
+
 The Item compiler **dispatches through that same resolved table**, via
 `engine/item-registry.mjs` (`itemTypes()` and `itemBuilder(type)`), so the types a
 consumer's notes are accepted for and the builders they compile with are one
@@ -438,12 +502,27 @@ systems:
   sohl: { compatibility: { verified: "0.9.0" } }
   hm3: { compatibility: { verified: "1.6.3" } }
 packs:
-  - { name: items-sohl, type: Item, system: sohl, default: true }
+  - { name: items-sohl, type: Item, system: sohl }
   - { name: items-hm3, type: Item, system: hm3 }
-  - { name: actors-sohl, type: Actor, system: sohl, default: true }
+  - { name: actors-sohl, type: Actor, system: sohl }
   - { name: actors-hm3, type: Actor, system: hm3 }
 ```
 
+**The `systems:` block is required here, not decorative.** A pack's `system:` is
+what its documents are stamped `_stats.systemId` and `systemVersion` from, and
+the version can only come from that block — or, for a package whose packs are
+all for its own system, from the package-wide stats. A pack naming a system that
+resolves to neither is refused at configuration time, naming the pack and the
+entry to add. It used to fall through and stamp `null` for both, which is the
+plausible lie #43 was about arriving by the one path the check did not cover:
+`harn-ensemble` shipped 2,513 compiled actors that way, out of a pack whose
+configuration says `system: sohl` on the line above.
+
+No `default: true` anywhere, because each system has exactly one pack of each
+type and a default is resolved per system. Marking one is still allowed and
+still means what it says — it designates that _system's_ default where a system
+has several packs of a type.
+
 A note carrying both a `sohl:` and an `hm3:` block then compiles **one document
 in each system**, each shaped by its own builders and stamped with its own
 system version. A note carrying only one block compiles only that system's
@@ -534,9 +613,46 @@ Both spellings are equal; the difference is only whether the type brings art.
 whitelist without a builder behind it.
 
 **The path is spelled the way a note spells it.** Registry art goes through the
-same `resolveImg` rule as a note's `img:`, so `icons/relic.svg` means _this_
-repository's asset root — `modules/sohl-relics/assets/icons/relic.svg` — and an
-already-served path (`systems/sohl/assets/icons/…`) passes through untouched.
+same `resolveImg` rule as a note's `img:`, so one spelling means one thing
+wherever it is written.
+
+#### An asset path's first segment says which package owns it
+
+Every authored asset path — a registry `img:`, a note's `img:`, an actor's
+`portrait:` — answers "which package holds this file?" in its **first segment**,
+and there are exactly three answers:
+
+| Authored path starts with | Owner                 | Emitted              |
+| ------------------------- | --------------------- | -------------------- |
+| `systems/`                | a separate **system** | unchanged            |
+| `modules/`                | a separate **module** | unchanged            |
+| anything else             | **this package**      | `<assetRoot>/<path>` |
+
+`assetRoot` is derived, never authored: it is
+`<packageKind>/<foundryPackage>/assets`, and it is the one place `systems/sohl`
+(or `modules/sohl-thalorna`) is ever spelled. So `icons/relic.svg` in a module's
+registry compiles to `modules/sohl-relics/assets/icons/relic.svg`, and the same
+string in the system's compiles to `systems/sohl/assets/icons/relic.svg`. An
+already-served `systems/sohl/assets/icons/…` passes through untouched — which is
+what lets a module pair a SoHL default with one of its own types.
+
+**"Anything else" is the rule, not a list of directories.** A package owns its
+whole `assets/` tree, so a directory this toolchain has never heard of is still
+that package's: art under `assets/artwork/` is addressed `artwork/deity.webp`
+and rooted exactly as `icons/…` and `images/…` are. An address naming no package
+at all — an absolute URL, a `data:` URI, a `/`-rooted path — passes through, on
+the same rule rather than as an exception.
+
+`worlds/` is deliberately not exempt: a package may not ship art out of a world,
+so prefixing such a path produces a plainly broken one rather than a plausible
+one that 404s in Foundry unreported.
+
+**`banner:` is a path that does not follow this rule.** It reaches no compiled
+document; it is a top-level key the Hugo theme reads, and the theme prefixes a
+relative value with `images/` and joins it onto `params.cdnBaseURL`. The two
+address different places — `img:` a file Foundry serves, `banner:` a file the
+CDN serves — so they are stated apart rather than reconciled. See the
+[content format specification](docs/content-format.md#banner-addresses-the-cdn-not-the-foundry-install).
 
 #### "Names no art" and "wants no art" are different (#218)
 
@@ -570,12 +686,20 @@ rather than two.
 > (`sohl/item-fields.mjs`, "the style of address the office carries"), so one
 > authored key fed two unrelated destinations that disagreed about what empty
 > means — and `title: null` stringified into the compiled document as the literal
-> `"null"`. That collision is gone: the field declares `topLevelMeans`, and the
-> top-level key is no longer a source for it (#218).
+> `"null"`. The field declares `topLevelMeans` now, so the top-level key is no
+> longer a source for it (#218).
+>
+> So `title: null` is a note declining to state a heading, and the site emitter's
+> `fm.title ?? name` falls back to `name.full`. `title: ""` publishes a
+> deliberately blank heading and is warned about on its own account — as the
+> page's heading, not as an art path.
 >
-> So `title: null` is now a note declining to state a heading, and the site
-> emitter's `fm.title ?? name` falls back to `name.full`. `title: ""` still
-> publishes a deliberately blank heading, and nothing warns about that yet.
+> **That warning reads the note's top level only.** The two spellings still name
+> unrelated quantities, so a `sohl.title` — the office's style of address — must
+> not answer for the page's heading. Twenty-eight `sohl-kethira-basic`
+> affiliations write `sohl.title: ""`, meaning an office with no style of
+> address, and every one of them was reported as publishing a blank heading
+> until the check honoured the declaration (#312).
 
 Because `""` used to mean "unset", a note still carrying that spelling has
 quietly changed meaning, and the frontmatter lint says so — for either art
@@ -712,6 +836,14 @@ state the same quantity, which is nearly everywhere: `subType` is the other
 declared item field spelled like a note-level key, and there the two agree by
 design.
 
+**The statement is symmetric, and the frontmatter linter reads it from the other
+side too.** If the two positions hold unrelated quantities, then the _in-block_
+position is not the note-level field either — so a check about a note-level field
+(the page's heading, an art path) reads past a block key the note's own type
+claims for something else. Declaring `topLevelMeans` settles both directions at
+once; it was read for the emitted field alone until #312, which is how an
+affiliation's office style came to answer for its page heading.
+
 **An exempted field is still authorable**, at the two positions that describe the
 document rather than the note:
 
@@ -949,6 +1081,44 @@ key it was probably meant to be, drawn from that type's own vocabulary:
 assets/content/Gear/Axe.md:14:5: error: "wieght" is not a `data:` property of a weapongear; the container is closed, so unlike a top-level key it is not passed through to the page. Did you mean "weight"?
 ```
 
+**A system block is closed too, and which blocks exist is the configuration's
+answer** (#58). A package is held to the blocks named after the systems it
+declares it ships for, read from the three places that already declare them:
+`systems:`, a pack's own `system:`, and `stats.systemId` where neither is
+written. So a package shipping for HM3 has its `hm3:` block checked and a
+package shipping for SoHL its `sohl:`. It used to be a constant, and the
+constant was `sohl`: an `hm3:` block was never read at all, so every key in it
+was discarded at compile without a word, while the block that _was_ checked was
+named after a system the package does not ship for.
+
+A pack's `system:` counts because it is already authoritative at compile — a
+note routed to a pack declaring one and carrying no such block fails the build —
+so a lint blind to it would refuse a note for want of a block it never checked.
+`harn-ensemble` declares its two systems that way and no other.
+
+**Each block is checked against its own system's vocabulary**, and that has two
+sources. A system's **`itemBuilders` registry** covers its item types: `skill` is
+one name over two data models, so a key SoHL's `skill` declares is not thereby a
+key HM3's declares, and a block that borrowed its neighbour's field names would
+accept the one mistake this check exists to report. The **note schemas** cover
+the rest — `being` above all, which is an actor type and sits in no item
+registry — and they belong to one system, SoHL, because that is the vocabulary
+`content-build` is built with.
+
+A type neither source names — `mysticalability` is SoHL's, `invocation` is
+HM3's — is a type that system says nothing about, and its block is left alone on
+such a note rather than reported wholesale. A package that names no system at all
+is system-agnostic on purpose: its packs are core document types carrying no
+system data, so it has no system block and none is invented for it.
+
+**A block whose vocabulary nothing states is said out loud.** A package
+declaring a system other than SoHL and no `itemBuilders` registry for it has
+nothing that can say what that block may carry, so the block goes unchecked — and
+`content-build lint` reports that once, naming the system and the registry to
+declare, because a check that quietly does nothing is indistinguishable from one
+that passed. `harn-ensemble` is the tree that gets it today: its `sohl:` block is
+checked, and its `hm3:` waits on `itemBuilders: [hm3, sohl]`.
+
 **`subType` stays at the top level**, and is closed in its own way: a type
 either declares a `subType` or does not, and a type that does declares its
 values. A `weapon` declares none — SoHL distinguishes a weapon's uses by strike
@@ -1342,6 +1512,28 @@ markdownlint honour them natively. The one exception is `CHANGELOG.md`, which
 `changeset version` regenerates in every repository here: linting it reports on
 the generator, so it is skipped by default.
 
+**A default that says when it is not in force.** Because a local config wins
+wholesale rather than merging, the conventions above otherwise hold by convention
+alone: a `prettier.config.mjs` that spreads `PRETTIER_BASE` without the `**/*.md`
+override reindents every note at 4, and a partial `.prettierrc` such as
+`{"tabWidth": 2}` silently discards `printWidth: 100`, `trailingComma` and the
+rest. So every `format` run first names, as warnings, each shared convention this
+repository resolves differently (#133):
+
+```text
+prettier.config.mjs: warning: markdown `tabWidth` is 4 here; the shared configuration says 2
+.prettierrc: warning: `printWidth` is not set here, so Prettier's own default applies; the shared configuration says 100
+```
+
+A repository with **no** Prettier config is warned too, and it is the sharper
+case: the shared conventions then reach this command and nothing else, so an
+editor's format-on-save and a bare `npx prettier --check .` apply Prettier's own
+defaults to the same tree and the two take turns rewriting the same lines. The
+fix is the one-line re-export below.
+
+None of this fails a run. A deliberate local choice still wins — it just stops
+being silent.
+
 Neither tool's file discovery is reimplemented, so `content-build format --check`
 and a bare `prettier --check .` report the same thing. A file Prettier cannot
 parse is a **finding**, with its position — not a crash that costs the report on
@@ -1485,6 +1677,17 @@ asked for — a build that downloads silently is not reproducible and fails
 strangely offline. The cache is keyed by version, so changing the pinned version
 is a miss rather than a silent overwrite.
 
+**A fetched catalogue is read one system at a time.** A dependency may ship a
+pack per system, and the two hold the same `(type, shortcode)` addresses with
+different data models — `skill:awar` is a real address in both vocabularies and
+means two different documents. So a pack declaring `system: hm3` resolves its
+embedded items against the dependency's `hm3` packs and its system-neutral ones,
+never against another system's, exactly as it already does for this repository's
+own packs. What each cached pack is comes from the dependency's manifest at
+fetch time, so a cache filled before this rule existed is treated as incomplete
+and `deps fetch` refills it — the alternative is a lookup that answers with the
+wrong system's document and reports nothing.
+
 **`--from` is for two packages changing together.** It fills the cache from a
 locally built artifact — a package zip or the directory it was built from — so a
 consumer can be built against a dependency that has not shipped. Without it,
@@ -2247,32 +2450,60 @@ JSDoc.
 
 ## Tests
 
-The package carries its own suite and its own vitest project, so it is
-verifiable without the repository that happens to host it:
+The package carries its own suite, so it is verifiable without any repository
+that consumes it:
 
 ```
-npm test -w @heroiclands/package-build     # from the SoHL repository root
-npm test                                   # from packages/content-build/
+npm test                                  # the whole suite
+npx vitest run tests/wikilinks.test.ts    # one file
 ```
 
-The SoHL repository's root `npm run test` names the very same project config, so
-one command still gates everything CI runs and neither entry point can drift
-into a different suite.
+**The suite is configured from a fixture, not from this repository's root.**
+`vitest.config.ts` points `PACKAGE_BUILD_CONFIG` at
+`tests/fixtures/repo/package-build.config.yaml`, whose adjacent `package.json`
+is shaped like a consumer's. The Foundry package id and the system version are
+derived from the manifest beside the configuration, and at the root that
+manifest is this toolchain's own — `@heroiclands/package-build`, which is
+neither a Foundry package id nor a game system version, so the derivations
+would assert nothing.
 
 The harness is deliberately austere: no global setup, no Foundry stubs, and no
 alias onto a consuming repository's source. `tests/suite-is-self-contained.test.ts`
-enforces that — a test in this suite that reached for `globalThis.game` or `@src`
-would pass in situ and fail the moment the package was installed from npm.
+enforces that — a test that reached for `globalThis.game`, imported `@src/…`, or
+resolved a path climbing out of the package would pass in situ and fail the
+moment the package was installed from npm. Before the extraction five files
+resolved `"../../.."` and asserted about whatever happened to be there, which
+was the system repository, because the package was vendored inside it (#1).
 
 `tests/dependencies-are-declared.test.ts` guards the same failure from the
-shipping side. Because this package is a workspace, npm hoists the root
-repository's `devDependencies` into the workspace root, so an import this
-package never declared still resolves here and fails nowhere but a consumer's
-install (#1557). The test walks every module named by the `files` field and
-holds each bare specifier to one of three cases — a Node builtin, this package
-addressing itself, or a declared `dependency` — and checks the converse: nothing
-shipped may import a `devDependency`, and no declared dependency may go
-unimported.
+shipping side. This package spent its first six changes as a workspace inside
+the Song of Heroic Lands repository, where npm hoisted the root's
+`devDependencies` into the workspace root: an import this package never declared
+still resolved, and failed nowhere but a consumer's install (#1557). The test
+walks every module named by the `files` field and holds each bare specifier to
+one of three cases — a Node builtin, this package addressing itself, or a
+declared `dependency` — and checks the converse: nothing shipped may import a
+`devDependency`, and no declared dependency may go unimported.
+
+`tests/import-needs-no-config.test.ts` is the third of the same family, and the
+one that keeps "resolved on first read, never at import" honest. It copies the
+files the package ships into a temporary directory outside this repository and
+imports each shipped module on its own, in a process whose environment has
+`PACKAGE_BUILD_CONFIG` deleted. Outside is load-bearing: the config walk climbs
+from the working directory and from the module's own directory, and the copy is
+both — so one left inside the tree could reach a configuration above it and
+prove nothing, which is why the first case asserts that none is reachable from
+the copy before the rest run. A module that hoisted a configured value to import
+time fails there, and only there.
+
+`tests/config-from-working-directory.test.ts` describes the resolution order
+itself (#364). It builds the shape no unit test can fake — a repository with the
+toolchain installed under it, and a second checkout nested inside that
+repository with its own configuration and no `node_modules` — and asserts which
+configuration a build run in each place reads. The nested case is the one that
+was wrong, and it is untestable any other way: the tell of a wrong-tree build is
+normally an unexpected zero diff, and the sweeps that provoke this shape expect
+zero differences, so only "which file was read" separates the outcomes.
 
 ## Releasing
 

package/README.md

@@ -208,6 +208,11 @@ packageBuild:
       run: [npx, cypress, run]
       open: [npx, cypress, open]
 
+    # Where that suite writes its results. Optional, and what it buys is the
+    # difference between "the suite ran and passed" and "the suite did not
+    # run" — a headless run that writes nothing here is reported as a failure.
+    results: [cypress/results]
+
     # What the fast loop can rebuild, in the order it must be built: the
     # bundler empties the stage, so it goes first. `recreate` marks a target
     # whose output Foundry reads once, at world launch.
@@ -483,6 +488,35 @@ repository can hold without rotting.
 A green sweep is what licenses moving `compatibility.verified` to that build. A
 red one is the early warning the sweep exists to produce.
 
+### A run that executed nothing is not a pass
+
+Because a sweep is evidence, the exit status of the suite is not enough on its
+own to call a run green. Every way of stopping a runner before it starts — a
+corrupt install, a missing browser, a killed process, an `npm ci` racing the
+run and taking `node_modules` with it — produces a run that executed nothing,
+and a harness that reports that as 0 makes the evidence unfalsifiable in the
+one direction that matters (#153).
+
+So the suite is bracketed rather than trusted:
+
+| Check                         | What it catches                                                                                            |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Before, the command resolves  | The runner is not installed. The error names it, before a container is stood up and a world seeded.        |
+| A runner is read through      | `npx cypress run` is checked for **`cypress`**, not `npx` — `npx` is never missing, so it answers nothing. |
+| After, the command still does | The runner went away mid-run. That is a run that cannot have finished, whatever it exited with.            |
+| After, results are newer      | The suite started and produced nothing. Requires `packageBuild.e2e.results`.                               |
+
+`results` names one path or a list of them, relative to the repository root.
+Existence is not the test — a directory the _previous_ run left behind exists,
+and reading that as evidence would make the check agree with exactly what it
+was built to catch. What counts is a file modified since the spawn.
+
+Two things it deliberately does not do. It only ever makes a verdict **worse**:
+a suite that failed keeps its own status, so there is no second path by which
+the harness can report a result that did not happen. And it does not apply to
+`open`, where a person decides what to execute and when to close the runner —
+"it wrote no results" describes that session rather than faulting it.
+
 ### Waiting for a world, not for a port
 
 Foundry answers on its port long before a world is serving. A suite started at
@@ -575,13 +609,18 @@ npm test
 ```
 
 Plain `vitest`, no setup file and no aliases: everything here is ESM over Node
-built-ins and three dependencies, and a harness that offered a Foundry global
-would let something reach for one.
+built-ins and what `dependencies` declares, and a harness that offered a Foundry
+global would let something reach for one. (This said "three dependencies" while
+it described the packaging half alone; absorbing the content half at 3.0.0
+brought the compendium, Markdown and SQL toolchains with it. The number is left
+out rather than restated, because the next dependency would make a restated one
+wrong again.)
 
 `tests/dependencies-are-declared.test.ts` is the guard an extraction most needs
 — every bare specifier in a shipped file must be a builtin, this package, or a
-declared `dependency`. Inside a workspace a missing declaration is invisible;
-installed from npm it fails on the first import.
+declared `dependency`. Inside a workspace, which this package was for its first
+six changes, a missing declaration is invisible; installed from npm it fails on
+the first import.
 
 ## Releasing
 

package/bin/content-build.mjs

@@ -79,7 +79,9 @@ import {
 } from "../engine/metadata-index.mjs";
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
-import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
+import { lintContentCharset } from "../engine/content-charset.mjs";
+import { lintContentIcons } from "../engine/content-icons.mjs";
+import { declaredSystems, lintFrontmatter, systemBlocksFor } from "../engine/frontmatter-lint.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     checkDeclaredFields,
@@ -105,7 +107,7 @@ import { HM3_ITEM_FIELDS } from "../hm3/item-fields.mjs";
 import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { schemaSubtypeOf } from "../engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
-import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
+import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
 import {
     authoredFrontmatter,
     emitContentIndex,
@@ -136,7 +138,7 @@ import {
     locateAddressFinding,
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
-import { itemPackJsonDirs } from "../engine/generate.mjs";
+import { emittedArtFor, itemPackJsonDirs } from "../engine/generate.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -787,6 +789,38 @@ function lintCommand() {
                         skipDirectories: config.skipDirectories,
                     }),
                 });
+                // Which system blocks this tree carries, derived from what it
+                // declares it ships for (#58). Read before the lint so the
+                // systems it will *not* check can be said out loud below.
+                // `schemaSystem` names whose vocabulary the `schemas` below
+                // are. They are `sohl/note-schemas.mjs`, imported here
+                // unconditionally, so this states a fact about this file rather
+                // than introducing one — and it is what lets a type no item
+                // registry declares, `being` above all, be checked at all.
+                const systemBlocks = systemBlocksFor(config, { schemaSystem: "sohl" });
+                const uncheckedSystems = declaredSystems(config).filter(
+                    (system) => !(system in systemBlocks),
+                );
+                if (uncheckedSystems.length) {
+                    // Said out loud for the reason the missing schema artifact
+                    // is: a check that quietly does nothing is indistinguishable
+                    // from one that passed, and the thing going unchecked here
+                    // is a closed region whose unknown keys the compiler drops
+                    // without a word. `harn-ensemble` is the tree this names —
+                    // two systems declared through its packs and an
+                    // `itemBuilders` registry for neither.
+                    log.info(
+                        `No \`itemBuilders\` registry declares the vocabulary of ` +
+                            `${uncheckedSystems.map((s) => `\`${s}\``).join(" or ")}, so ` +
+                            `${
+                                uncheckedSystems.length === 1 ?
+                                    "that system's block is"
+                                :   "those systems' blocks are"
+                            } unchecked — a key inside one is discarded at ` +
+                            `compile with no warning. Declare ` +
+                            `\`itemBuilders: [${declaredSystems(config).join(", ")}]\`.`,
+                    );
+                }
                 const frontmatter = lintFrontmatter(index, {
                     schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
                     // The closed frontmatter regions (#128). Passed in rather
@@ -799,6 +833,19 @@ function lintCommand() {
                     // the compile asks the map for whichever pack it is
                     // writing, and a companion is a pack it writes.
                     packs: config.packDirectories,
+                    // What art each type actually reaches its document through,
+                    // asked of the passes rather than listed here (#349). This
+                    // is the one place that decides what a tree is held to, so
+                    // it is where the derivation is handed over — the linter
+                    // states no list of iconless types of its own.
+                    emittedArt: emittedArtFor,
+                    // Handed over for the same reason the vocabulary is: the
+                    // linter checks the blocks it is given and names no system
+                    // itself. Until this it was given none, so every tree was
+                    // held to a `sohl:` whatever system it ships for — and an
+                    // `hm3:` block went unread, which is a key discarded at
+                    // compile in silence.
+                    systems: systemBlocks,
                     references: argv.references,
                 });
 
@@ -877,10 +924,33 @@ function lintCommand() {
                     }
                 }
 
+                // The charset the tree is held to, so a book can pick its face
+                // (#377). Run over the raw files rather than the parsed notes:
+                // the subject is every character authored, including the ones
+                // that stopped a note parsing at all.
+                const charset = lintContentCharset(root, {
+                    skipDirectories: config.skipDirectories,
+                });
+
+                // The names the charset check leaves room for (#378). An icon
+                // the registry does not declare renders as its own literal
+                // text, which is visible but easy to publish, so it is reported
+                // here rather than left for a reader to notice.
+                //
+                // The shipped registry, with no per-package override yet: an
+                // `icons:` configuration key is a change to the configuration
+                // contract and belongs with its own validation, rather than
+                // being read here before anything declares it.
+                const icons = lintContentIcons(root, {
+                    skipDirectories: config.skipDirectories,
+                });
+
                 const findings = [
                     ...addresses.findings,
                     ...frontmatter.findings,
                     ...schemaFindings,
+                    ...charset.findings,
+                    ...icons.findings,
                 ];
                 // Only an **error** fails the run. Every finding was an error
                 // until #142, so this changed nothing on the day it landed —
@@ -928,6 +998,13 @@ function lintCommand() {
  * which paths a repository skips is knowledge about that repository's layout,
  * and it stays there.
  *
+ * It is a default that **says when it is not in force**, though. Every run first
+ * reports, as warnings, each shared convention the repository's own
+ * configuration resolves differently — or that it declares no configuration at
+ * all, which guarantees an editor and a bare `npx prettier` disagree with this
+ * command about the same tree (#133). Nothing there fails the run: the point is
+ * that a local choice is deliberate rather than silent.
+ *
  * @returns {object} The yargs command module.
  */
 // eslint-disable-next-line
@@ -961,6 +1038,20 @@ function formatCommand() {
                     return;
                 }
                 const root = process.cwd();
+                // Before the per-file report, because it is the context for it:
+                // which rules this run applied, and whether anything else in
+                // the repository applies the same ones (#133). Warnings only —
+                // a consumer's config wins by design, so none of this touches
+                // the exit code.
+                const conventions = await checkPrettierConventions(root);
+                for (const finding of conventions.findings) emitDiagnostic(finding);
+                if (conventions.findings.length && conventions.configFile) {
+                    log.warn(
+                        `${conventions.findings.length} shared Prettier convention(s) are not ` +
+                            "what this repository resolves; a deliberate local choice wins on " +
+                            "purpose, so this is a warning and not a failure.",
+                    );
+                }
                 const { findings, checked, written } = await checkFormatting(root, {
                     paths: argv.paths,
                     write: argv.write,

package/config.mjs

@@ -126,7 +126,7 @@ const CONTAINER_KEYS = ["image", "name", "stages"];
  */
 const CONTAINER_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
 const CONTAINER_STAGE_KEYS = ["port", "world", "version"];
-const E2E_KEYS = ["stage", "suite", "build", "world", "gm", "documents"];
+const E2E_KEYS = ["stage", "suite", "results", "build", "world", "gm", "documents"];
 const E2E_SUITE_KEYS = ["run", "open"];
 const E2E_WORLD_KEYS = ["id", "title", "description"];
 const E2E_GM_KEYS = ["name", "password"];
@@ -557,6 +557,8 @@ function normalizeExceptions(value, field, where) {
  * @property {string} e2eStage       Which stage the suite runs against.
  * @property {Readonly<{run: readonly string[], open: readonly string[]|null}>|null} e2eSuite
  *   What to run against the served world; `null` when the repository has none.
+ * @property {readonly string[]} e2eResults  Where the suite writes its results,
+ *   so a run that wrote none is not mistaken for one that passed.
  * @property {Readonly<Record<string, Readonly<{script: string, recreate: boolean}>>>} e2eBuild
  *   Build targets the fast loop can produce, in declaration order.
  * @property {Readonly<Record<string, string>>} e2eWorld  Declared world identity.
@@ -798,6 +800,12 @@ export function resolvePackageBuildConfig(shared) {
                 "test"
             :   requireNonEmptyString(e2eInput.stage, "packageBuild.e2e.stage"),
         e2eSuite: normalizeE2ESuite(e2eInput.suite),
+        // Declaring nothing keeps the old contract — the suite's exit status is
+        // taken at its word. Declaring where results land is what lets the
+        // harness tell "the suite ran and passed" from "the suite did not run"
+        // (#153); a repository that wants that distinction has to say where to
+        // look for it, because the harness does not know what the suite is.
+        e2eResults: normalizeGlobs(e2eInput.results, [], "packageBuild.e2e.results"),
         e2eBuild,
         e2eWorld: normalizeStringMap(e2eInput.world, "packageBuild.e2e.world", E2E_WORLD_KEYS),
         e2eGm: normalizeStringMap(e2eInput.gm, "packageBuild.e2e.gm", E2E_GM_KEYS),