@heroiclands/package-build 23.1.1 → 23.2.1

package/markdownlint-config.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The shared markdownlint rules, as a markdownlint-cli2 options module.
+ * The shared markdownlint rules, as a `.markdownlint-cli2.mjs` options module.
  *
  * `package-build markdown` applies these without a consumer declaring
  * anything; this is for an editor's markdownlint extension, and for a consumer

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.1.1",
+    "version": "23.2.1",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -145,13 +145,16 @@
         "flesch": "^2.0.1",
         "glob": "^13.0.6",
         "gray-matter": "^4.0.3",
-        "handlebars": "^4.7.9",
+        "handlebars": "^4.7.10",
+        "ignore": "^7.0.12",
+        "jsonc-parser": "^3.3.1",
         "loglevel": "^1.9.2",
         "loglevel-plugin-prefix": "^0.8.4",
         "markdown-it": "^15.0.0",
         "markdown-it-deflist": "^4.0.0",
         "markdown-it-footnote": "^4.0.0",
-        "markdownlint-cli2": "^0.23.3",
+        "markdownlint": "^0.41.1",
+        "minimatch": "^10.2.6",
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
         "remark-frontmatter": "^5.0.0",

package/release.mjs

@@ -120,17 +120,18 @@ async function appendTree(archive, root, date) {
  *   Determines both asset names.
  * @param {string} [opts.metadataDir] - Where the build writes its content
  *   index, consulted when the advertised file was not staged.
- * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
+ * @param {boolean} [opts.pdf] - Whether to build the books that ship beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   schema?: string, pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, pdfs: string[], pdfFindings: object[], pdfSkipped: string|null,
  *   bytes: number, version: string}>} The paths written, what the book build
  *   found, the archive's size, and the version the manifest declares.
  *   `metadata` is absent when the manifest advertises no content index,
- *   `schema` is absent when the stage carries no `schema.json`, and `pdf` is
- *   absent when no book was written. `pdfSkipped` is `null` when a book was
- *   built, and otherwise the reason none was — itself `null` when the book
- *   builder could not be loaded, which is reported through `pdfFindings`.
+ *   `schema` is absent when the stage carries no `schema.json`, and `pdfs` is
+ *   every book's PDF that was written, in declared order. `pdfSkipped` is
+ *   `null` when a book was built, and otherwise the reason none was — itself
+ *   `null` when the book builder could not be loaded or a book failed, which
+ *   is reported through `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -190,23 +191,24 @@ export async function packRelease({
     const book =
         pdf ?
             await packReleasePdf({ out, version: manifest.version })
-        :   { pdf: null, findings: [], reason: "the release was asked not to build one" };
+        :   { pdfs: [], findings: [], reason: "the release was asked not to build one" };
 
     return {
         zip: zipPath,
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
         ...(schema ? { schema } : {}),
-        ...(book.pdf ? { pdf: book.pdf } : {}),
+        pdfs: book.pdfs,
         pdfFindings: book.findings,
-        pdfSkipped: book.pdf ? null : book.reason,
+        pdfSkipped: book.pdfs.length ? null : book.reason,
         bytes: archive.pointer(),
         version: manifest.version,
     };
 }
 
 /**
- * Build the book that ships beside the archive.
+ * Build the books that ship beside the archive — every one `pdf.books`
+ * declares.
  *
  * **Imported when it is used, not when this module is.** The book build pulls
  * in a markdown parser, DuckDB and the whole content engine; `release.mjs`
@@ -223,8 +225,9 @@ export async function packRelease({
  * @param {object} opts - Options.
  * @param {string} opts.out - The release directory.
  * @param {string} opts.version - The version the manifest declares.
- * @returns {Promise<{pdf: string|null, findings: object[], reason: string|null}>}
- *   What was built, and what was found on the way.
+ * @returns {Promise<{pdfs: string[], findings: object[], reason: string|null}>}
+ *   Each book's PDF that was built, in declared order, and what was found on
+ *   the way.
  */
 async function packReleasePdf({ out, version }) {
     let buildPdf;
@@ -232,7 +235,7 @@ async function packReleasePdf({ out, version }) {
         ({ buildPdf } = await import("./engine/pdf-build.mjs"));
     } catch (err) {
         return {
-            pdf: null,
+            pdfs: [],
             findings: [
                 {
                     severity: "warning",
@@ -243,7 +246,11 @@ async function packReleasePdf({ out, version }) {
         };
     }
     const result = await buildPdf({ out, version });
-    return { pdf: result.pdf, findings: result.findings, reason: result.reason };
+    return {
+        pdfs: result.books.map((book) => book.pdf).filter((pdf) => pdf),
+        findings: result.findings,
+        reason: result.reason,
+    };
 }
 
 /**

package/sohl/actors.mjs

@@ -42,10 +42,11 @@
  * **A membership is derived, never authored here.** `data.affiliations` names
  * the bodies a being belongs to and the standing it holds in each, and each
  * entry becomes one embedded affiliation item: the entry's `rank` is that
- * item's `system.level` and its `office` is `system.office`. A standing is a
- * fact about the setting rather than about one system — it does not become true
- * because SoHL is installed — so the system block states none of it, and a
- * sheet and a page cannot come to disagree.
+ * item's `system.level`, its `office` is `system.office`, and the first of its
+ * `societies` is `system.society`, the one society the SoHL item carries. A
+ * standing is a fact about the setting rather than about one system — it does
+ * not become true because SoHL is installed — so the system block states none
+ * of it, and a sheet and a page cannot come to disagree.
  *
  * Not a standalone script — exports the `Actors` compiler class, imported and
  * driven by `engine/generate.mjs`. Must run after the items passes, since it
@@ -155,18 +156,7 @@ export class Actors extends SystemActorCompiler {
                     this.errorCount++;
                     return;
                 }
-                const { model, shortcode, type, ...rest } = entry;
-                if (shortcode !== undefined) {
-                    this.noteError(
-                        `${ctx}: sohl.items[${index}] carries a top-level ` +
-                            `\`shortcode\` — that key is retired. Name the item ` +
-                            `this entry copies with \`model:\` (an address, e.g. ` +
-                            `\`${type ?? "skill"}-${shortcode}\`), and use ` +
-                            `\`system.shortcode\` for this item's own identity.`,
-                    );
-                    this.errorCount++;
-                    return;
-                }
+                const { model, type, ...rest } = entry;
                 const read = model === undefined ? null : this.readModel(model, index, ctx);
                 if (model !== undefined && !read) return;
                 if (read && type !== undefined) {
@@ -216,7 +206,8 @@ export class Actors extends SystemActorCompiler {
      * The body's own compiled item is the model, so a membership carries
      * whatever that body declares — its subtype, its common skills, its
      * standings toward others — and the being adds only what is true of *this*
-     * membership: the rung it stands on and the post it holds.
+     * membership: the rung it stands on, the post it holds, and the society it
+     * is held in.
      *
      * A being naming a body that compiles to no item is a finding rather than a
      * silently dropped membership: the note says the being belongs somewhere,
@@ -236,9 +227,12 @@ export class Actors extends SystemActorCompiler {
             if (!shortcode) continue;
             const level = Number(standing?.rank);
             const office = typeof standing?.office === "string" ? standing.office.trim() : "";
+            const [first] = Array.isArray(standing?.societies) ? standing.societies : [];
+            const society = typeof first === "string" ? first.trim() : "";
             const system = {
                 ...(Number.isFinite(level) ? { level } : {}),
                 ...(office ? { office } : {}),
+                ...(society ? { society } : {}),
             };
             const embedded = this.resolveEmbedded(
                 itemsMap,
@@ -335,16 +329,12 @@ export class Actors extends SystemActorCompiler {
             // identity (the dedup/override key of the Create-dialog picker).
             shortcode: fm.shortcode || "",
             // Required nullable number: a priority, or `null` for a being that
-            // is not a template (the archetype contract). `system.archetype`
-            // is the legacy spelling; the emitted key moves
-            // with the schema, since an undeclared `system` key is discarded at
-            // construction without a warning.
+            // is not a template (the archetype contract).
             templatePriority: systemTemplatePriority(fm, ctx),
             // `system.portrait` is **not** written here. A picture of the
             // subject is a picture, so a being's portrait is the lead image of
-            // its `{#appearance}` section — which is the markup below — and the
-            // key that used to declare one is not a key. With no authored
-            // source left, the field keeps the schema's own initial.
+            // its `{#appearance}` section — which is the markup below. With no
+            // authored source, the field keeps the schema's own initial.
             appearance: renderSection(body || "", "appearance"),
             // One document says it once. `dossier` is the field that carries
             // an unsettled entry's notice, and `appearance` carries none —
@@ -399,9 +389,8 @@ export class Actors extends SystemActorCompiler {
             folder,
             sort: 0,
             ownership: { default: 0 },
-            // Whatever the note authors, and nothing else. The priority used to
-            // be spliced in here as `flags.sohl.docArchetype`; it is a schema
-            // field now and sits in `system`.
+            // Whatever the note authors, and nothing else. The template
+            // priority is a schema field and sits in `system`.
             flags: blockProperty(fm, SYSTEM, "flags", {}),
             _stats: this.stats,
             _key: `!actors!${id}`,

package/sohl/default-item-art.mjs

@@ -46,9 +46,9 @@
  * **The keys are SoHL *document* subtypes, not markdown note types.** The
  * runtime reads this with `itemData.type`, which is a Foundry Item subtype, and
  * that is the vocabulary a compendium document carries. The two vocabularies
- * would be the same string but for three renamed note types (`armorgear` →
- * `armor`, and its two siblings), and this map stayed on the document side
- * because that is the side the runtime cannot translate: `sohl/item-builders.mjs`
+ * are the same string but for three note types (`armor` and its two siblings,
+ * whose document subtypes are `armorgear` and its siblings), and this map stays
+ * on the document side because that is the side the runtime cannot translate: `sohl/item-builders.mjs`
  * asks SoHL's own note-type → subtype map before it looks art up here, so the
  * build translates once and no second copy of those three rows exists.
  */

package/sohl/document-subtypes.mjs

@@ -28,20 +28,6 @@
  * silently. Sixteen lines of data are the price of the two vocabularies being
  * separately stated.
  *
- * **Three rows are no longer the identity, and that is what the map was for.**
- * `armor`, `concoction` and `projectile` were renamed from the `…gear`
- * spellings that named SoHL's *document* subtype rather than the thing the note
- * is about; the subtypes themselves did not move, so those three rows now
- * say two different words where they used to say one twice. Landing the rename
- * cost exactly what having the map first promised it would: a data change on
- * three lines here, and no mechanism change anywhere.
- *
- * The old spellings are still read — {@link RENAMED_TYPES} normalises them
- * before this map is consulted — so a tree that has not swept its 30,741
- * embedded `(type, shortcode)` references compiles byte-identically. `weapon`
- * is deliberately **not** among them: both systems call that document a
- * `weapongear`, so the name says nothing SoHL-specific and is left alone.
- *
  * **What this map is not.** It says which document a note becomes, never what
  * that document contains: the `system` block comes from the item registry's
  * builders (`item-builders.mjs`), and an item's own `system.subType` field —
@@ -58,8 +44,7 @@ import { defineDocumentSubtypes } from "../engine/document-subtypes.mjs";
  * becomes.
  *
  * The Item rows are the thirteen types the item registry declares; the one
- * Actor row is `being`, which was two types (`character` and `creature`)
- * compiling to the same actor before they were retired. Types this
+ * Actor row is `being`. Types this
  * map does not name — `doc`, `macro`, the three map types — compile into
  * documents that carry no system subtype at all, so they have no row and never
  * needed one.

package/sohl/infobox.mjs

@@ -62,7 +62,6 @@ import {
     humanizeValue,
     systemRowsSection,
 } from "../engine/infobox.mjs";
-import { currentType } from "../engine/ids.mjs";
 import { subTypes } from "../engine/note-vocabulary.mjs";
 import { systemBlock, systemData } from "../engine/system-block.mjs";
 import { readCanonicalKey } from "../engine/content-address.mjs";
@@ -205,7 +204,7 @@ function modelAddress(model) {
     const target = parseAddress(
         model,
         { package: contentPackage(), system: "sohl", types: MODEL_TYPES },
-        { declared: true, legacyShortcodeCase: true },
+        { declared: true },
     );
     return target.reason ? undefined : target;
 }
@@ -240,7 +239,7 @@ export function decodeItem(entry) {
     if (!type) return undefined;
     return {
         ...(address ? { address } : {}),
-        type: currentType(type),
+        type: type,
         shortcode,
         name: typeof entry.name === "string" ? entry.name : "",
         system,

package/sohl/item-builders.mjs

@@ -18,13 +18,10 @@
  * There is one list, not two. This repository hands {@link ITEM_BUILDERS} to
  * the build as `itemBuilders` in `package-build.config.yaml`, and `itemTypes()`
  * — the whitelist — is derived from that table's own keys, so a type cannot be
- * whitelisted for compilation without a builder to compile it. Split, the
- * whitelist and the builder table were maintained by hand and had already
- * drifted: `trait` — a **retired** item type, absent from
- * `documentTypes.Item` and reported by world migration as unrecognized — was
- * still advertised as compilable, so a `type: trait` note passed the gate and
- * then died on `BUILDERS[type] is not a function`, swallowed as a per-file
- * error.
+ * whitelisted for compilation without a builder to compile it. Kept apart, a
+ * whitelist naming a type absent from `documentTypes.Item` would let a note of
+ * that type pass the gate and then die on `BUILDERS[type] is not a function`,
+ * swallowed as a per-file error.
  *
  * **The builders are generated, not written.** Each type's `system` builder
  * comes from its field declaration in `item-fields.mjs` by way of
@@ -58,7 +55,7 @@ import { ITEM_FIELDS } from "./item-fields.mjs";
  *
  * Reading {@link defaultItemArt} here is what makes the two lists one: this
  * module cannot name a type the art map does not cover, because that function
- * throws and this module evaluates at import. A drift that a test used to catch
+ * throws and this module evaluates at import. A drift between the lists
  * is unrepresentable.
  *
  * **The art map is keyed by the document subtype**, which the runtime reads

package/sohl/item-fields.mjs

@@ -246,7 +246,7 @@ const STRIKE_MODES = Object.freeze({
  * @returns {number} The die size, `0` when the projectile declares none.
  */
 function impactDie(fm) {
-    return Number(sohlSystemField(fm, "impactBase.die", 0, { legacyKey: "impact.die" })) || 0;
+    return Number(sohlSystemField(fm, "impactBase.die", 0, { name: "impact.die" })) || 0;
 }
 
 /** A strike mode discriminated by `type`, mandatory on a combat technique. */
@@ -281,7 +281,6 @@ const GEAR_COMMON = Object.freeze([
     },
     {
         name: "data.weight",
-        legacyKey: "weight",
         to: "weightBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -290,7 +289,6 @@ const GEAR_COMMON = Object.freeze([
     },
     {
         name: "data.value",
-        legacyKey: "value",
         to: "valueBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -299,7 +297,6 @@ const GEAR_COMMON = Object.freeze([
     },
     {
         name: "data.quality",
-        legacyKey: "quality",
         to: "qualityBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -308,7 +305,6 @@ const GEAR_COMMON = Object.freeze([
     },
     {
         name: "data.durability",
-        legacyKey: "durability",
         to: "durabilityBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -352,13 +348,9 @@ export const COMBAT_TECHNIQUE_STRIKE_MODE = Object.freeze({
  * Every item type's frontmatter vocabulary, in the order the `system` block
  * emits it.
  *
- * **A field whose shared source is a path into `data:` names both positions.**
- * `name` is the source the content format's mapping tables state — `data.seat`,
- * `data.weight` — and `legacyKey` is the key the system block still carries, which
- * wins while a tree writes it. Naming only the source would move the in-block
- * read to a key spelled `data.seat`, which nothing authors; naming only the key
- * leaves the container the specification points at unread, and the field then
- * compiles its default over an authored value with nothing said.
+ * **A field whose shared source is a path into `data:` is authored there and
+ * nowhere else.** `name` is the source the content format's mapping tables
+ * state — `data.seat`, `data.weight`.
  *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
@@ -418,7 +410,6 @@ export const ITEM_FIELDS = Object.freeze({
             // Plural because the field holds a map of many standings, one per
             // affiliation — the singular reads as a misnomer.
             name: "data.relations",
-            legacyKey: "relations",
             to: "relations",
             ...RELATION,
             address: AFFILIATION_KEYS,
@@ -430,7 +421,6 @@ export const ITEM_FIELDS = Object.freeze({
             // A list, because an affiliation may sit under more than one at
             // once — an arcane tradition within an order, say.
             name: "data.parents",
-            legacyKey: "parents",
             to: "parents",
             ...ADDRESS_LIST,
             address: AFFILIATION_ITEMS,
@@ -442,7 +432,6 @@ export const ITEM_FIELDS = Object.freeze({
             // subTypes, while a seat covers a polity, a guild, an order and a
             // faith alike.
             name: "data.seat",
-            legacyKey: "seat",
             to: "seat",
             ...BLANK_IS_NULL,
             address: PLACE_VALUE,
@@ -487,7 +476,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.contagionIndex",
-            legacyKey: "contagionIndex",
             to: "contagionIndexBase",
             ...NUMBER,
             default: 0,
@@ -495,7 +483,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.transmission",
-            legacyKey: "transmission",
             to: "transmission",
             ...AS_AUTHORED,
             default: "none",
@@ -518,7 +505,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.outcomeTraumas",
-            legacyKey: "outcomeTraumas",
             to: "outcomeTraumas",
             ...BLANK_IS_NULL,
             default: null,
@@ -526,7 +512,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.outcome",
-            legacyKey: "outcome",
             to: "outcome",
             ...BLANK_IS_DEFAULT,
             default: "cured",
@@ -551,7 +536,6 @@ export const ITEM_FIELDS = Object.freeze({
         // the whole content of the declaration.
         {
             name: "data.onsetDurationFormula",
-            legacyKey: "onsetDurationFormula",
             to: "onsetDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -560,7 +544,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.onsetDurationBase",
-            legacyKey: "onsetDurationBase",
             to: "onsetDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -569,7 +552,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.healingCheckDurationFormula",
-            legacyKey: "healingCheckDurationFormula",
             to: "healingCheckDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -578,7 +560,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.healingCheckDurationBase",
-            legacyKey: "healingCheckDurationBase",
             to: "healingCheckDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -587,7 +568,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.resolutionDurationFormula",
-            legacyKey: "resolutionDurationFormula",
             to: "resolutionDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -596,7 +576,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.resolutionDurationBase",
-            legacyKey: "resolutionDurationBase",
             to: "resolutionDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -831,7 +810,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.skillAptitudes",
-            legacyKey: "skillAptitudes",
             to: "skillAptitudes",
             ...SKILL_APTITUDES,
             default: {},
@@ -839,7 +817,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.charges",
-            legacyKey: "charges",
             to: "charges",
             ...CHARGES,
             default: { value: null, max: null },
@@ -896,7 +873,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.charges",
-            legacyKey: "charges",
             to: "charges",
             ...CHARGES,
             default: { value: null, max: null },
@@ -1089,7 +1065,6 @@ export const ITEM_FIELDS = Object.freeze({
         // that sets it bleeds, and one that leaves it unset does not.
         {
             name: "data.healingCheckDurationFormula",
-            legacyKey: "healingCheckDurationFormula",
             to: "healingCheckDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -1098,7 +1073,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.healingCheckDurationBase",
-            legacyKey: "healingCheckDurationBase",
             to: "healingCheckDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -1107,7 +1081,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.bloodLossAdvanceDurationFormula",
-            legacyKey: "bloodLossAdvanceDurationFormula",
             to: "bloodLossAdvanceDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -1116,7 +1089,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.bloodLossAdvanceDurationBase",
-            legacyKey: "bloodLossAdvanceDurationBase",
             to: "bloodLossAdvanceDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -1125,7 +1097,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.courseDurationFormula",
-            legacyKey: "courseDurationFormula",
             to: "courseDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -1134,7 +1105,6 @@ export const ITEM_FIELDS = Object.freeze({
         },
         {
             name: "data.courseDurationBase",
-            legacyKey: "courseDurationBase",
             to: "courseDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -1177,7 +1147,7 @@ export const ITEM_FIELDS = Object.freeze({
             to: "strikeModes",
             ...STRIKE_MODES,
             default: [],
-            describe: "The ways the weapon can be used to strike.",
+            describe: "The ways the weapon can strike.",
         },
     ]),
 });

package/sohl/items.mjs

@@ -88,10 +88,6 @@ export class Items extends SystemItemCompiler {
             shortcode: fm.shortcode,
             // Required nullable number: a priority, or `null` for a document
             // that is not a template (the archetype contract).
-            // `system.archetype` is the legacy spelling; the receiving
-            // schema declares only the new name, so the emitted key moves with
-            // it — an undeclared `system` key is discarded at construction
-            // without a warning.
             templatePriority: systemTemplatePriority(fm, label),
             actionDefs: [],
             notes: "",

package/sohl/kb-passes.mjs

@@ -51,9 +51,9 @@ import log from "loglevel";
  * code spans rather than refuse to build.
  *
  * **Configuring one that cannot be used is a defect, and it fails the build.**
- * A missing file, a malformed one, a permissions error and a path typo used to
+ * A missing file, a malformed one, a permissions error and a path typo would
  * be indistinguishable from each other *and* from a correctly configured build
- * with no symbols: a bare `catch` returned `{}` for all five. Nothing then
+ * with no symbols, were a bare `catch` to return `{}` for all of them. Nothing then
  * compares an emitted page against what its source asked for, so the first
  * observer of a broken map was a reader who clicked nothing, because every
  * `{@link}` on the published site had quietly become a code span.
@@ -112,7 +112,7 @@ function readSymbolMap(file, repoRoot) {
 
     // Reported because a map that loaded and a map that loaded empty are
     // otherwise indistinguishable without reading the emitted HTML — and an
-    // empty one degrades every tag exactly as a missing one used to.
+    // empty one degrades every tag exactly as a missing one does.
     log.info(`resolved ${Object.keys(parsed).length} API symbols from ${file}`);
     return parsed;
 }