@heroiclands/package-build 23.1.1 → 23.2.0

package/engine/standings.mjs

@@ -68,14 +68,12 @@ function mapping(value) {
 /**
  * The standings a being authored, in one shape whichever shape it wrote.
  *
- * The list form names bodies and no standings; the map form names both. Three
- * spellings reach here and every reader downstream takes the same entries, so
- * none of them asks which it was handed:
+ * Two spellings reach here and every reader downstream takes the same entries,
+ * so none of them asks which it was handed:
  *
  * - an **{@link AddressEntries}** — the map after the note boundary decoded its
  *   keys into typed Addresses, which is the shape every compile sees;
- * - a **plain map**, which is the shape a checker reading raw YAML sees;
- * - a **list**, which names bodies and says nothing about standing in them.
+ * - a **plain map**, which is the shape a checker reading raw YAML sees.
  *
  * An emptied map arrives from the property editor as `[]` and means what `{}`
  * means — this being authors no membership — so both read as no entries.
@@ -85,7 +83,7 @@ function mapping(value) {
  * Address is what a finding should name.
  *
  * @param {unknown} value - The authored `data.affiliations`.
- * @returns {{form: "absent"|"list"|"map"|"malformed",
+ * @returns {{form: "absent"|"map"|"malformed",
  *   entries: Array<{body: unknown, sourceKey: string|number, standing: unknown}>}}
  *   The form it was written in, and its entries.
  */
@@ -101,18 +99,9 @@ export function readStandings(value) {
             })),
         };
     }
-    if (Array.isArray(value)) {
-        // An empty list is an emptied map, not a membership stated as a list.
-        if (value.length === 0) return { form: "map", entries: [] };
-        return {
-            form: "list",
-            entries: value.map((body, position) => ({
-                body,
-                sourceKey: position,
-                standing: undefined,
-            })),
-        };
-    }
+    // An emptied map arrives from the property editor as `[]`; any other list
+    // is malformed.
+    if (Array.isArray(value) && value.length === 0) return { form: "map", entries: [] };
     if (!mapping(value) || isAddressTuple(value)) return { form: "malformed", entries: [] };
     return {
         form: "map",
@@ -270,7 +259,7 @@ export function standingLead(standing, digest) {
  * Five questions, and the last three are what keying the entry by its body
  * buys:
  *
- * 1. the value is a map keyed by Address (or the list this window still takes);
+ * 1. the value is a map keyed by Address;
  * 2. every key names an affiliation that resolves, once;
  * 3. the entry states a standing at all — what a stated standing holds is the
  *    inner-key check's, read from {@link STANDING_FIELDS};
@@ -278,7 +267,7 @@ export function standingLead(standing, digest) {
  * 5. an `office` is a key of that body's `governance.offices`.
  *
  * Both of the last two are read from the named body's own frontmatter as the
- * lint runs, so a renamed rung or a renamed post fails on every being pointing
+ * lint runs, so a rung or a post that does not exist fails on every being pointing
  * at it rather than on a list somebody has to remember to edit.
  *
  * @param {object} note - The note.
@@ -301,18 +290,14 @@ export function checkStandings(note, { index } = {}) {
 
     const findings = [];
     const seen = new Map();
-    // The list form names bodies and has nowhere to put a standing. Its entries
-    // are still held to being affiliations that resolve, so a tree part-way
-    // through the sweep keeps the check it had.
-    const isKey = form === "map";
     for (const { body, sourceKey, standing } of entries) {
         const path = ["data", "affiliations", sourceKey];
         const resolved = resolveBody(note, index, body);
-        findings.push(...bodyFindings(note, body, path, isKey, resolved));
+        findings.push(...bodyFindings(note, body, path, true, resolved));
         if (resolved.address) {
             if (seen.has(resolved.address)) {
                 findings.push({
-                    ...position(note, path, isKey),
+                    ...position(note, path, true),
                     message:
                         `\`data.affiliations\` names ${resolved.address} twice, as ` +
                         `${JSON.stringify(String(seen.get(resolved.address)))} and ` +
@@ -322,7 +307,6 @@ export function checkStandings(note, { index } = {}) {
             }
             seen.set(resolved.address, sourceKey);
         }
-        if (!isKey) continue;
         const named = resolved.address ?? String(body);
         // An entry with nothing after its key, and an emptied map arriving from
         // the property editor as `[]`, say exactly what an authored `{}` says:

package/engine/system-block.mjs

@@ -37,68 +37,25 @@
  *
  * This is the load-bearing part, and the reason the whole module exists.
  * `sohl.system.portrait` and `hm3.system.bioImage` both default from one shared
- * top-level property — and they are two *real* fields with different names. The
- * two Actor schemas one `being` note has to feed share **no field name at all**,
- * so a rule that matched on spelling would not be a rule with exceptions; it
- * would be a rule that never fires.
+ * property — and they are two *real* fields with different names. The two Actor
+ * schemas one `being` note has to feed share **no field name at all**, so a rule
+ * that matched on spelling would not be a rule with exceptions; it would be a
+ * rule that never fires.
  *
  * So each field declares where its shared value comes from, and the resolution
  * order for a system `S` is:
  *
  * 1. `S.system.<to>` — authored directly, wins outright;
- * 2. `S.<legacyKey>` — the legacy in-block position the corpus still writes,
- *    kept until the corpus moves it;
- * 3. the shared top-level property the field **declares** as its source, which
- *    may be a dotted path (`data.portrait`) rather than a sibling key;
- * 3b. for a `data.` source, the bare top-level key that container gathered it
- *    off — the retiring *shared* position, derived rather than declared;
+ * 2. `S.<name>` — the field's own name, written in the block. A field whose
+ *    `name` is a path into `data:` has no in-block position, because its home
+ *    is the container;
+ * 3. the shared property the field **declares** as its source, which may be a
+ *    dotted path (`data.portrait`) rather than a sibling key;
  * 4. the field's own default.
  *
- * ## Steps 2 and 3 are two declarations, because they are two positions
- *
- * They are not one: keying both on `name` holds only while the
- * shared source and the in-block key were the same word. `data:` ended
- * that — a shared source is now a path *into* a container, so `data.species`
- * and `species` are two spellings of two different places, and no single value
- * of `name` reached both. `name: "species"` read `hm3.species` and could not
- * see `data.species`; `name: "data.species"` read the shared source and could
- * not see `hm3.species`. Each yielded the field's **default** wherever only the
- * other position was authored — silently, since the field compiles and the
- * document is emitted with the value simply gone.
- *
- * That made every move into `data:` a flag day. Each of this package's other
- * retirements — `package:`, `image`, `archetype`, `relation` — works because
- * *both spellings are read while the corpus moves*, and one property could not
- * offer that here.
- *
- * So a field declares `legacyKey` beside `name`: the key it is authored at
- * inside the block, which step 2 reads and which **falls back to `name`** when
- * absent, so every declaration written before this resolves unchanged. A field
- * that declares one is mid-sweep by construction, which is what
- * {@link module:engine/field-spec.readsLegacyKey} reports on.
- *
- * ## Step 3 has a retiring position too, and it is derived
- *
- * `legacyKey` retires the *in-block* position, and for a while that looked like
- * the whole of what `data:` left behind. It is not. The facts `data:` holds
- * were not invented by it — the sweep **gathered** them out of the note's open top
- * level, where `portrait:` sat beside `img:` and `shortcode:` — so a field that
- * declares `data.portrait` has two shared spellings to read, not one, and
- * reading only the current one is the same silent miss `legacyKey` exists to
- * prevent. It is worse here, because the caller's `?? default` cannot tell a
- * value that is absent from one that is merely unreachable: 646 `sohl-thalorna`
- * beings shipped the generic person icon over an authored path, and no tree
- * that still writes the top-level spelling — `sohl`'s own bestiary does —
- * looked any different from one that names no art at all.
- *
- * So step 3b reads it, and unlike `legacyKey` it is **derived**: the retiring
- * spelling of `data.<key>` is `<key>`, mechanically, because that is precisely
- * what the move did. A second declaration would be a second place for the same
- * fact to be stated, and the retirement it describes is one rule rather than a
- * per-field decision. {@link retiredTopLevelKey} is that derivation, and it
- * answers for `data.` sources alone — `protection.blunt` is a path into a
- * container notes have always written at the top level, never a `blunt:` that
- * moved.
+ * A key written at a position that is not on this list is not read. For a
+ * field whose home is `data:`, the frontmatter lint reports the key at the
+ * position it was written.
  *
  * ## A name that collides across the two vocabularies skips step 3
  *
@@ -108,28 +65,23 @@
  * all. They do not always. An `affiliation` item's `system.title` is the style
  * of address an office carries — "Ajaw", "Warden"; a note's top-level `title`
  * is refused outright by the closed top-level vocabulary, which has no `title`
- * entry. Nothing relates them, and step 3 fed the first from the second anyway.
- *
- * It was not a harmless coincidence either, because step 3 answers **without**
- * applying `field.default` — only step 2 does — so an authored `title: null`
- * reached the field's coercion unguarded and shipped as the literal string
- * `"null"` in fifteen documents.
+ * entry. Nothing relates them. Step 3 answers **without** applying
+ * `field.default`, so an authored `title: null` would reach the field's
+ * coercion unguarded.
  *
  * So a field may declare `topLevelMeans`: why the note's top-level key of this
  * name is not this field's source — declared wherever that key's spelling
  * means something else at the note level, or the closed top-level vocabulary
- * refuses it outright. Declaring it removes the whole shared level — step 3
- * and the retiring 3b alike, since both read the note's top level and the
- * objection is to that level, not to a spelling — leaving the two positions
- * that describe the document rather than the note. It is deliberately
- * a per-field opt-out rather than a change to the order — step 3 is right
+ * refuses it outright. Declaring it removes the shared level (step 3), leaving
+ * the positions that describe the document rather than the note. It is a
+ * per-field opt-out rather than a change to the order — step 3 is right
  * wherever the two levels state the same quantity, which is nearly everywhere —
  * and its value is the reason rather than a bare flag, so the collision is
  * legible where the field is declared. See {@link module:engine/field-spec.FieldSpec}.
  *
  * `sohlField()` — read `fm.sohl[key]`, fall back to `fm[key]` — is the
- * degenerate case where source and destination happen to share a name. It stops
- * being the general rule; {@link blockField} is what remains of it.
+ * degenerate case where source and destination happen to share a name. It is
+ * not the general rule; {@link blockField} is what remains of it.
  *
  * ## Nothing here knows a game system
  *
@@ -365,17 +317,14 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
 }
 
 /**
- * A system override followed by a shared `data:` value followed by the
- * retiring top-level spelling `data:` gathered it off, reporting which one
+ * A system override followed by a shared `data:` value, reporting which one
  * answered.
  *
  * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
  * universal `data:` key — `pack` and `packFolder`, declared for every note
  * type rather than per type, so neither is a `FieldSpec` that resolver takes.
  * The order is the same shape: a system's own override, then the shared
- * `data:` position, then the bare top-level key a tree authored before
- * `data:` existed. The top-level value stays readable while a tree still on
- * it moves its authored fields.
+ * `data:` position.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.
@@ -389,8 +338,6 @@ export function resolveDataProperty(fm, block, key, defaultValue = undefined) {
     if (declared !== undefined && declared !== null) return { value: declared, from: "block" };
     const shared = isMapping(fm?.data) ? fm.data[key] : undefined;
     if (shared !== undefined && shared !== null) return { value: shared, from: "shared" };
-    const legacy = isMapping(fm) ? fm[key] : undefined;
-    if (legacy !== undefined && legacy !== null) return { value: legacy, from: "topLevel" };
     return { value: defaultValue, from: "default" };
 }
 
@@ -408,27 +355,6 @@ export function blockDataProperty(fm, block, key, defaultValue = undefined) {
     return resolveDataProperty(fm, block, key, defaultValue).value;
 }
 
-/**
- * The key a field is authored at **inside** a system block — step 2.
- *
- * `legacyKey` when the field declares one, and `name` otherwise. The fallback
- * is what makes this change invisible to every declaration written before it:
- * a field whose shared source and in-block key are the same word says so once,
- * as it always did.
- *
- * Named and exported rather than spelled inline because three readers ask the
- * question and must agree — the resolver here, the frontmatter lint building
- * the set of keys a block may carry, and the author-facing surfaces naming
- * where a value was written.
- *
- * @param {{name?: string, legacyKey?: string}} field - The declaration.
- * @returns {string|undefined} The in-block key, or `undefined` for a field that
- *   is not authored at all.
- */
-export function legacyKeyOf(field) {
-    return field?.legacyKey ?? field?.name;
-}
-
 /**
  * The `data:` container's prefix, as a shared source spells it.
  *
@@ -437,31 +363,20 @@ export function legacyKeyOf(field) {
 const DATA_PREFIX = "data.";
 
 /**
- * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
- *
- * The retiring spelling of `data.portrait` is not a second declaration anyone
- * has to write — it is `portrait`, mechanically, and the same holds for every
- * other key the container gathered. Deriving it is what keeps the two spellings
- * of one field from disagreeing the way two declarations would.
- *
- * **Only a `data.` source has one.** `protection.blunt` and `impact.die` are
- * paths into containers a note has always written at the top level; they were
- * never `blunt:` or `die:`, and reading those would invent a position rather
- * than remember one.
+ * The key a field is authored at **inside** a system block — step 2.
  *
- * A field declaring {@link module:engine/field-spec.FieldSpec `topLevelMeans`}
- * has no shared position at all, retiring or otherwise — the resolver checks
- * that before asking.
+ * The field's `name`, except that a name which is a path into `data:` has no
+ * in-block position. Named and exported because the resolver and the
+ * frontmatter lint, which builds the set of keys a block may carry, must agree.
  *
  * @param {{name?: string}} field - The declaration.
- * @returns {string|undefined} The retiring top-level path, or `undefined` for a
- *   field whose shared source never lived there.
+ * @returns {string|undefined} The in-block key, or `undefined` for a field that
+ *   is not authored in the block.
  */
-export function retiredTopLevelKey(field) {
+export function inBlockKey(field) {
     const name = field?.name;
-    if (typeof name !== "string" || !name.startsWith(DATA_PREFIX)) return undefined;
-    const rest = name.slice(DATA_PREFIX.length);
-    return rest === "" ? undefined : rest;
+    if (typeof name !== "string" || name.startsWith(DATA_PREFIX)) return undefined;
+    return name;
 }
 
 /**
@@ -492,7 +407,7 @@ export function authoredKey(name) {
  * can distinguish a value an author wrote from one a default supplied, which
  * the value alone never says.
  *
- * @typedef {"system"|"block"|"shared"|"topLevel"|"default"|"value"} FieldSource
+ * @typedef {"system"|"block"|"shared"|"default"|"value"} FieldSource
  */
 
 /**
@@ -529,19 +444,16 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
         if (own !== undefined) return { value: own, from: "system" };
     }
 
-    // 2. The legacy in-block position, keyed on `legacyKey` — the shared
-    //    source is a path into `data:` and the in-block key is a bare word, so
-    //    the two are declared separately. Every note in every tree
-    //    writes here today, and will until the corpus moves them; dropping it would
-    //    be a corpus migration disguised as a mechanism change.
+    // 2. The field's own name, written in the block. A name that is a path
+    //    into `data:` has no in-block position: its home is the container.
     const declared = systemBlock(fm, block);
-    const legacyKey = legacyKeyOf(field);
-    if (declared && legacyKey) {
-        if (legacyKey in declared) {
-            const value = declared[legacyKey];
+    const key = inBlockKey(field);
+    if (declared && key !== undefined) {
+        if (key in declared) {
+            const value = declared[key];
             return { value: value ?? field.default, from: "block" };
         }
-        const nested = getFrontmatter(declared, legacyKey, undefined);
+        const nested = getFrontmatter(declared, key, undefined);
         if (nested !== undefined) return { value: nested, from: "block" };
     }
 
@@ -551,20 +463,6 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
     if (field.topLevelMeans === undefined) {
         const shared = getFrontmatter(fm, field.name, undefined);
         if (shared !== undefined) return { value: shared, from: "shared" };
-
-        // 3b. The bare top-level key the `data:` source was gathered off — the
-        //     retiring *shared* position, exactly as `legacyKey` is the
-        //     retiring *in-block* one. Without it a field declaring
-        //     `data.portrait` cannot see the `portrait:` every tree still
-        //     writes, and the miss arrives at the caller's `?? default` as an
-        //     ordinary absence: 646 `sohl-thalorna` beings compiled the generic
-        //     person icon over an authored path, deterministically and with
-        //     nothing said.
-        const retiring = retiredTopLevelKey(field);
-        if (retiring !== undefined) {
-            const legacy = getFrontmatter(fm, retiring, undefined);
-            if (legacy !== undefined) return { value: legacy, from: "topLevel" };
-        }
     }
 
     // 4. The field's own default.

package/engine/system-vocabulary.mjs

@@ -2,6 +2,12 @@
  * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
  * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
  *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 

package/engine/walk-files.mjs

@@ -0,0 +1,69 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The repository walk shared by the prose checks.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Directories never walked, whatever the ignore files say.
+ *
+ * `node_modules` is in every consumer's `.gitignore` and would be excluded
+ * anyway; skipping it in the walk rather than per file is the difference
+ * between a check that takes a second and one that stats a hundred thousand
+ * files to be told each is ignored. `.git` is in nobody's `.gitignore`, so it
+ * has to be named.
+ */
+const NEVER_WALK = Object.freeze(new Set([".git", "node_modules"]));
+
+/**
+ * Every file under a root, minus the directories nothing should walk.
+ *
+ * @param {string} root - Absolute path to walk.
+ * @param {object} [hooks]
+ * @param {(dir: string) => void} [hooks.enter] - Called with each directory
+ *   before its entries are read.
+ * @param {(abs: string, isDirectory: boolean) => boolean} [hooks.skip] -
+ *   Whether to leave a path out; a skipped directory is not entered.
+ * @returns {string[]} Absolute file paths, in directory order.
+ */
+export function walkFiles(root, hooks = {}) {
+    const out = [];
+    /** @param {string} dir - Directory to descend into. */
+    const descend = (dir) => {
+        hooks.enter?.(dir);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            // A directory that vanished or cannot be read is not a finding
+            // about prose; leave it to whatever owns it.
+            return;
+        }
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!NEVER_WALK.has(entry.name) && !hooks.skip?.(abs, true)) descend(abs);
+            } else if (entry.isFile() && !hooks.skip?.(abs, false)) {
+                out.push(abs);
+            }
+        }
+    };
+    descend(root);
+    return out;
+}

package/engine/web-wikilinks.mjs

@@ -416,9 +416,8 @@ export function resolveWebWikilinks(body, ctx) {
         const label = authoredLabel({ display });
 
         // **Every link carries a label**. Without one there is nothing
-        // to resolve against — the alias namespace a bare `[[Text]]` named is
-        // retired — and nothing to show either, a shortcode being an address
-        // rather than prose. Reported before the same-page form, because the
+        // to resolve against, and nothing to show either, a shortcode being an
+        // address rather than prose. Reported before the same-page form, because the
         // rule is about how the link is *written*: `[[#slug]]` needs the pipe
         // exactly as `[[skill-clmb]]` does.
         if (!parsed.labelled) {
@@ -531,6 +530,26 @@ export function resolveWebWikilinks(body, ctx) {
             read && !read.reason && read.package === ctx.contentPackage ?
                 `${read.type}/${read.shortcode}`.toLowerCase()
             :   rawKey;
+        // A capital in the shortcode is refused, never lowercased. The
+        // lowercase spelling is looked up only to name it in the finding.
+        if (read?.reason === "shortcode-not-lowercase") {
+            const lower = read.lowercase;
+            const declared =
+                lookupRead(ctx.index, lower, ctx.contentPackage) ??
+                (ctx.foreign && lower.package ?
+                    lookupRead(ctx.foreign, lower, ctx.contentPackage)
+                :   undefined);
+            return report(
+                all,
+                {
+                    target,
+                    reason: "shortcode-not-lowercase",
+                    shortcode: read.shortcode,
+                    ...(declared ? { declared: lower.shortcode } : {}),
+                },
+                label ?? target,
+            );
+        }
         const reason =
             ctx.collide?.has(collideKey) ? "ambiguous"
                 // "It parsed as an address" is a property of the parse, not of
@@ -538,6 +557,7 @@ export function resolveWebWikilinks(body, ctx) {
             : read && !read.reason ? "unresolved"
             : read?.reason === "unknown-type" ? "unknown-type"
             : read?.reason === "no-content-index" ? "no-content-index"
+            : read?.reason === "not-lowercase" ? "not-lowercase"
                 // Every link is an address, and this is not one. Distinct from
                 // a dead address, because the fix is different: a name has to
                 // become an address, not be corrected.

package/engine/wikilink-syntax.mjs

@@ -40,8 +40,8 @@ import { parseAddress, isAddressTuple, splitAnchor } from "./address.mjs";
  *
  * The one rule about a link's *shape* that both resolvers share also lives here
  * — **a link carries a label** ({@link unlabelledLinkMessage}) — because the
- * two used to state it in their own words and the author met whichever ran
- * first.
+ * two state it through one message and the author reads the same words
+ * whichever ran first.
  *
  * For the same reason, so does the **vocabulary of link findings**
  * ({@link LINK_FINDING_REASONS}) and the message each one reports through
@@ -145,15 +145,10 @@ export function authoredLabel({ display }) {
  * the form to write rather than a value to correct: there is no value that
  * makes an unlabelled link resolve.
  *
- * **Why there is nothing left for a bare link to mean**. The pipe used
- * to select between two namespaces — address and alias — and the alias one was
- * empty in practice: across 8,305 wikilinks in three content trees, not one
- * bare `[[Alias]]` resolved to a note. What the index it looked up in *did* do
- * was fold every note's `name.full` into itself, which forbade two notes of a
- * type from sharing a display name. So the namespace is gone, every
- * link is an address, and an address needs the pipe that says so.
+ * **A bare link has nothing to mean.** Every link is an address, and an
+ * address needs the pipe that says so.
  *
- * The **link part may still be an anchor**: `[[#slug|Text]]` addresses a
+ * The **link part may be an anchor**: `[[#slug|Text]]` addresses a
  * section of the page it is written on. It is the label that is required, not
  * a target.
  *
@@ -164,7 +159,7 @@ export function unlabelledLinkMessage(target) {
     return (
         `wikilink [[${target}]] carries no label, so it addresses nothing — ` +
         `write [[type-shortcode|Text]]. Every link is an address; the bare ` +
-        `[[Name]] form named an alias, and the alias namespace is retired`
+        `[[Name]] form addresses nothing`
     );
 }
 
@@ -181,6 +176,8 @@ export function unlabelledLinkMessage(target) {
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.
  * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `shortcode-not-lowercase` — the shortcode segment carries a capital. A
+ *   shortcode is lowercase, and the link is refused rather than lowercased.
  * - `unknown-type` — definitely qualified, but names no type this build knows.
  * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.
@@ -199,6 +196,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "unlabelled",
         "not-an-address",
         "not-lowercase",
+        "shortcode-not-lowercase",
         "unknown-type",
         "not-an-asset",
         "unresolved",
@@ -240,13 +238,9 @@ export function isEventAnchor(hit, anchor) {
  * package publishing it is not a declared dependency — or is one whose index
  * has not been fetched — and the link itself looks identical in every case.
  *
- * As a **warning** in the checker and, in the site build, nothing
- * at all until every linkable package's manifest was accounted for — on the
- * reasoning that a bare `[[Name]]` might be a placeholder for a note nobody had
- * written yet. That reasoning was a property of the bare form, which is retired;
- * the intent behind it now has a real spelling, a `draft`-tagged note
- * that exists and resolves and renders marked. So an address naming no
- * note is a typo or an omission, both want fixing, and all three builds say so.
+ * An address naming no note is a typo or an omission: the intent of a
+ * placeholder for a note nobody has written yet is spelled as a `draft`-tagged
+ * note that exists, resolves and renders marked. Both want fixing, and all three builds say so.
  *
  * @param {string} target - The address as authored, named in the message.
  * @returns {string} The message, unpunctuated at the end as a finding is.
@@ -327,11 +321,24 @@ export function ambiguousAddressMessage(target, packages = []) {
  * @param {string} [finding.type] - For `not-an-asset`, the type the address
  *   named.
  * @param {string} [finding.stub] - For `stub`, where the stub is.
+ * @param {string} [finding.shortcode] - For `shortcode-not-lowercase`, the
+ *   shortcode as written.
+ * @param {string} [finding.declared] - For `shortcode-not-lowercase`, the
+ *   lowercase spelling, when it is a declared shortcode.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type, stub }) {
+export function linkFindingMessage({
+    reason,
+    target,
+    packages,
+    anchor,
+    type,
+    stub,
+    shortcode,
+    declared,
+}) {
     switch (reason) {
         case "unlabelled":
             return unlabelledLinkMessage(target);
@@ -345,8 +352,12 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
         case "not-lowercase":
             return (
                 `address [[${target}]] capitalises a package, system or type ` +
-                `segment — those three are lowercase, and only the shortcode ` +
-                `keeps its case`
+                `segment — every segment of an address is lowercase`
+            );
+        case "shortcode-not-lowercase":
+            return (
+                `address [[${target}]] shortcode \`${shortcode ?? target}\` must be ` +
+                `lowercase${declared ? `; the declared shortcode is \`${declared}\`` : ""}`
             );
         case "unknown-type":
             return `address [[${target}]] names no known content type`;