@heroiclands/package-build 20.3.1 → 20.4.0

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

@@ -5,7 +5,7 @@
  * note is one this build **refused** — it declares a retired frontmatter field
  * — and it is an error; a skipped one legitimately belongs to another pass, and
  * there are thousands of those. Folding the first into the second is what let a
- * whole tree be filtered out in silence (#56).
+ * whole tree be filtered out in silence.
  *
  * @typedef {object} PassStats
  * @property {number} compiled - Notes that became a document.
@@ -13,7 +13,7 @@
  * @property {number} skippedOther - Notes this pass does not claim.
  * @property {number} declined - Notes this pack **refused** — one declaring a
  *   retired frontmatter field, or one routed to a system pack whose system it
- *   says nothing about (#58). Counted as errors, never as skips.
+ *   says nothing about. Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -51,7 +51,7 @@ export class BasePackCompiler {
      * its generated tables expanded and its wikilinks converted.
      *
      * False for a pass whose output must be exactly what the author typed —
-     * the macros pass, whose `command` is executable source (#1514). A pass
+     * the macros pass, whose `command` is executable source. A pass
      * that says so also skips building the content-wide link index it would
      * never read.
      *
@@ -67,7 +67,7 @@ export class BasePackCompiler {
      * passes wrote — so an Actor pass must run after every Item pass, and it
      * says so here.
      *
-     * The generator derives the compile order from this (#73), so the order
+     * The generator derives the compile order from this, so the order
      * `packs:` declares is presentation only — it is the manifest's `packs`
      * array as well, and a consumer orders that for a reader. A pass that
      * reads another's output states the dependency once, in the class that
@@ -82,7 +82,7 @@ export class BasePackCompiler {
     static readsPackOutputOf: readonly string[];
     /**
      * Whether this pass's document **is** a system's data, and therefore takes
-     * only notes that carry that system's block (#58).
+     * only notes that carry that system's block.
      *
      * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
      * and an `actors-sohl` from one tree — and the note-side half of that is
@@ -112,7 +112,7 @@ export class BasePackCompiler {
      * legal on every note whatever its type, because
      * `BLOCK_DOCUMENT_PROPERTIES` maps it onto `document.img` — so a note whose
      * document has no such property authors it, validates, compiles, and loses
-     * the value with nothing said. That is #349: `Parrot` in `sohl-thalorna`
+     * the value with nothing said: `Parrot` in `sohl-thalorna`
      * had declared `img:` since long before the art rule existed and compiled
      * `img: null` exactly as a note declaring nothing does. Naming the fields
      * here is what lets the lint tell an inert key from a live one.
@@ -134,7 +134,7 @@ export class BasePackCompiler {
      *   never descends into. Required: see {@link assertStatedScope}.
      * @param {(address: string|null) => string|null} [options.folderResolver] -
      *   Resolves a `packFolder` — a folder note's address — to the Foundry
-     *   folder id it materialises as in this pack (#255, #257).
+     *   folder id it materialises as in this pack.
      * @param {string} [options.packName] - The pack this pass writes.
      * @param {string} [options.docType] - The Foundry document type it holds.
      * @param {{resolve: Function}} [options.router] - The pack router. Omit it
@@ -163,7 +163,7 @@ export class BasePackCompiler {
     /** @type {number} */
     errorCount: number;
     /**
-     * Emitted-`system` findings, one per `documentType|subtype|field` (#155).
+     * Emitted-`system` findings, one per `documentType|subtype|field`.
      *
      * A key the compiler writes is on **every** document of a subtype, so
      * reporting it where it is found would print the same sentence 3,126 times
@@ -222,7 +222,7 @@ export class BasePackCompiler {
     packSystem: any;
     corpus: any;
     /**
-     * The `_stats` block every entry this pass emits is stamped with (#48).
+     * The `_stats` block every entry this pass emits is stamped with.
      *
      * Per pack rather than per package, because a module may ship the same
      * content for two systems — `harn-ensemble` has an `actors-hm3` pack and an
@@ -252,8 +252,7 @@ export class BasePackCompiler {
      * routed *here* and carries nothing for this pack's system is an authoring
      * mistake with a hollow document at the end of it, not a note that belongs
      * to another pass. Skipping it quietly is how a whole tree compiles to
-     * documents nobody can use — the failure mode #1502 and #56 are both
-     * instances of.
+     * documents nobody can use.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True when the note may be compiled here; `false` when
@@ -266,7 +265,7 @@ export class BasePackCompiler {
     eligibleFor(fm: object): boolean;
     /**
      * A refusal only this pass can make, because its subject is the note's
-     * **type** (#330).
+     * **type**.
      *
      * The `assertNo*Field` family above it in the walk is type-agnostic by
      * construction: it runs before `selects`, so that a note declaring a
@@ -291,7 +290,7 @@ export class BasePackCompiler {
      * Whether this pass claims a note. **Required.**
      *
      * Called only for a note this build compiles — every note in the tree
-     * belongs to the configured content package (#56) — so a subclass decides
+     * belongs to the configured content package — so a subclass decides
      * on `type` alone.
      *
      * @param {object} fm - The note's frontmatter.
@@ -368,8 +367,7 @@ export class BasePackCompiler {
         column?: number;
     }): void;
     /**
-     * Report every `<system>.system` key the receiving subtype does not declare
-     * (#58).
+     * Report every `<system>.system` key the receiving subtype does not declare.
      *
      * An **error**, not a warning: Foundry drops an unknown `system` key at
      * construction without a word, so the alternative is a document shipped
@@ -390,7 +388,7 @@ export class BasePackCompiler {
     reportUndeclaredSystemData(fm: object, block: string, documentType: string, subType: string): number;
     /**
      * Record every `system` key the *compiled document* carries that the
-     * receiving subtype does not declare (#155).
+     * receiving subtype does not declare.
      *
      * The sibling of {@link BasePackCompiler#reportUndeclaredSystemData}, and
      * the half that sees what no declaration states. A compiler writes keys of
@@ -434,7 +432,7 @@ export class BasePackCompiler {
     /**
      * Emit the collected emitted-`system` findings, once each.
      *
-     * An **error**, for the reason #60 made its sibling one: the value is gone
+     * An **error**, for the reason its sibling is one: the value is gone
      * at load and the build says nothing, and severity that varied by *which
      * part of the build wrote the key* would make the less fixable half the
      * quieter one. What varies is the message, which says whose fix it is —
@@ -529,7 +527,7 @@ export class BasePackCompiler {
  * note is one this build **refused** — it declares a retired frontmatter field
  * — and it is an error; a skipped one legitimately belongs to another pass, and
  * there are thousands of those. Folding the first into the second is what let a
- * whole tree be filtered out in silence (#56).
+ * whole tree be filtered out in silence.
  */
 export type PassStats = {
     /**
@@ -547,7 +545,7 @@ export type PassStats = {
     /**
      * - Notes this pack **refused** — one declaring a
      * retired frontmatter field, or one routed to a system pack whose system it
-     * says nothing about (#58). Counted as errors, never as skips.
+     * says nothing about. Counted as errors, never as skips.
      */
     declined: number;
 };

package/types/engine/bundle-notes.d.mts

@@ -35,7 +35,7 @@ export function bareAddress(value: unknown): string | null;
  * `### type: bundle` table puts it — the closed container, so a misspelled
  * `content` is a finding rather than a silently empty Adventure. It is accepted
  * at the top level too, exactly as a folder note's `parent` is: an author
- * following #259's own example rather than the specification should get a
+ * following the shipped example rather than the specification should get a
  * bundle, not a silent default.
  *
  * **Order is the author's**, and it is kept: an Adventure's `SetField` attaches
@@ -124,9 +124,9 @@ export function buildAdventure({ id, name, img, description, caption, folder, fl
  * world's collection already holds that `_id`, then creates or updates each.
  * Afterwards the documents live independently and the Adventure has no further
  * role. **It is an installer** — a set of document *copies* packaged for
- * one-shot import (#259).
+ * one-shot import.
  *
- * That is the whole difference from a folder (#256), which is a live grouping
+ * That is the whole difference from a folder, which is a live grouping
  * **by reference** that persists in the pack. A bundle carries copies and
  * exists to be imported once, so the two are not variations on one idea.
  *

package/types/engine/bundles.d.mts

@@ -8,7 +8,7 @@
  * the first.
  *
  * A **folder** document is skipped. It is emitted into every pack that holds
- * something filed in it (#257), so it is not one pack's document and has no
+ * something filed in it, so it is not one pack's document and has no
  * single note behind it; a bundle that wants folders is a question this pass
  * refuses rather than guesses at — see {@link Bundles#resolveAddress}.
  *

package/types/engine/code-fences.d.mts

@@ -94,12 +94,12 @@ export function matchAllOutsideCode(markdown: string, pattern: RegExp, options?:
  * **Which runs count as code is {@link codeRegions}' rule, not a second copy of
  * it.** The knowledgebase build carried its own regex once, and it was weaker in
  * two ways that both corrupted the one page whose subject *is* link syntax — so
- * its examples were exactly the input a looser rule mangles (SoHL#1665). A
+ * its examples are exactly the input a looser rule mangles. A
  * single-backtick span was allowed to cross newlines, so one odd backtick paired
  * with another paragraphs away and every span after it paired wrongly: prose was
  * masked as code while real spans were left exposed. And only three-backtick
  * fences were recognised, so a four-backtick example holding a three-backtick
- * block — the documented "fences of any length" case (#1505) — leaked its
+ * block — the documented "fences of any length" case — leaked its
  * contents.
  *
  * @param {string} body - The markdown body.
@@ -114,7 +114,7 @@ export function protectCode(body: string, transform: (masked: string) => string)
  * written. Every build-time rewriter that pattern-matches a body therefore has
  * to know where code is — otherwise a source listing that happens to contain
  * the rewriter's syntax is silently corrupted. Wikilink conversion met this as
- * `[[0]]` inside a fence being turned into a link (#1505), and it depended on
+ * `[[0]]` inside a fence being turned into a link, and it depended on
  * the surrounding literal's shape (`[[1,2],[3,4]]` survived), so the corruption
  * looked arbitrary.
  *

package/types/engine/compendiums.d.mts

@@ -6,7 +6,7 @@
  * @param {object} opts
  * @param {object} [opts.config]         The resolved build configuration, which
  *     the two path arguments below default from. Supplying one is how a caller
- *     compiles a package other than this repository's (#1508).
+ *     compiles a package other than this repository's.
  * @param {string[]} [opts.sourcePacks]  Every pack compiled from the content
  *     tree, in compile order. Defaults to the configured pack directories.
  * @param {string} [opts.stageDest]      Directory the LevelDB packs are built
@@ -15,10 +15,10 @@
  * @throws {Error} If pack JSON generation reported any error. Packs compiled
  *     from incomplete or empty JSON ship blank or short compendiums, and the
  *     omission is invisible until a player looks for content that is not there
- *     (#1502) — so this is fatal, not a warning, and the caller is expected to
+ * — so this is fatal, not a warning, and the caller is expected to
  *     turn it into a failing exit code.
  * @throws {Error} If a compiled pack ships a Scene that has lost its embedded
- *     Level (#1538). Fatal for the same reason: Foundry reads a missing Level
+ *     Level. Fatal for the same reason: Foundry reads a missing Level
  *     record as "no levels" and persists that on the next world launch, so the
  *     map image is gone before anyone notices it was ever at risk. See
  *     {@link verifyPackSceneLevels}.

package/types/engine/compile-corpus.d.mts

@@ -4,7 +4,7 @@
  * @param {object} opts - Options.
  * @param {string} opts.contentBase - Root of the content tree.
  * @param {readonly string[]} opts.skipDirectories - The scope, stated by the
- *   caller as every corpus read requires (#243).
+ *   caller as every corpus read requires.
  * @param {object} opts.router - The pack router this compile resolved. Shared
  *   by every pass, which is what makes one link index correct for all of them.
  * @param {object} [opts.config] - The resolved configuration.

package/types/engine/content-address.d.mts

@@ -6,7 +6,7 @@
  * key's **last two segments** — which is what makes a manifest entry's `path`
  * derivable from the key it is filed under rather than transported beside it.
  *
- * It was once the key's whole tail, and #59 ended that: the key gained a
+ * It is not the key's whole tail: the key carries a
  * `<system>` segment, so its tail is now `system-type-shortcode` and a slug is
  * the tail with that segment dropped. The behaviour here is unchanged, and
  * deliberately — a page has no system to name (see the module note above), so
@@ -50,9 +50,9 @@ export function addressSlug(fm: object): string;
  *
  * **It is a pure function of the frontmatter**, and takes no options. Nothing
  * about the file the note was read from reaches it: the `README.md` convention
- * that made one note address a whole section is retired with the section itself
- * (#204), so every note is addressed alike and there is one rule and no branch.
- * It took an address scheme until #215, to validate a `landing` rule it then
+ * that made one note address a whole section is retired with the section itself,
+ * so every note is addressed alike and there is one rule and no branch.
+ * It takes no address scheme; the `landing` rule it once validated is
  * discarded; with that key retired, `prefix` was the only thing left in the
  * scheme and the paragraph above is the reason it never applied.
  *
@@ -85,9 +85,9 @@ export function packageAddress(fm: object): string;
  * merge is a real conflict rather than an artefact of two packages sharing a
  * namespace. `(type, shortcode)` alone is unique only *within* a package, and
  * two independently authored packages reaching for the same short string is a
- * matter of time (#1499).
+ * matter of time.
  *
- * **The system segment (#59).** A package may ship content for more than one
+ * **The system segment.** A package may ship content for more than one
  * system, and one note then compiles into a document per system — an actor in
  * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
  * land on one key, so the address cannot name either of them. `harn-ensemble`
@@ -137,7 +137,7 @@ export function blockSystem(keyPath?: string): string;
 /**
  * Expand a written address to the one canonical address it names.
  *
- * **An omitted segment defaults from where the link is written** (#336) — it is
+ * **An omitted segment defaults from where the link is written** — it is
  * not a wildcard, and resolution is not a search. Package omitted means the
  * citing note's own; system omitted means {@link blockSystem} of the key path it
  * was written under. So every short form has exactly one expansion, computed
@@ -186,8 +186,8 @@ export function expandAddress(read: {
  * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
  * so the hyphen is purely a separator and the count alone determines every
  * field. That is enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
- * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * the data: shortcodes by `content-lint.mjs`, `contentPackage` by
+ * `defineConfig`, and types are bare words. Were any of them free to
  * carry a hyphen, no amount of counting would recover the fields and the reader
  * would need a vocabulary to match against instead.
  *
@@ -251,7 +251,7 @@ export function packageRelative(url: string, base: string): string;
 export function resolvePackageUrl(rel: string, base: string): string;
 /**
  * The Foundry `_id` of the document a note compiles into, derived from its
- * canonical address (#270).
+ * canonical address.
  *
  * A note used to author this — an opaque 16-character string, one per note,
  * that said nothing its address did not and that no check guaranteed. The
@@ -278,7 +278,7 @@ export function resolvePackageUrl(rel: string, base: string): string;
  * @returns {string} A 16-character Foundry id.
  */
 export function documentId(pkg: string, system: string, type: string, shortcode: string): string;
-/** The knowledgebase's mount within this package's site (#1470). */
+/** The knowledgebase's mount within this package's site. */
 export const KB_PREFIX: "kb/";
 /**
  * How many segments a canonical key has, and therefore how many the reader

package/types/engine/content-format-check.d.mts

@@ -22,7 +22,7 @@ export function declaredPaths(artifact: object): Set<string>;
  *
  * A shared row names no type, so it is placed rather than typed: "in the shared
  * mappings" instead of "on a `weapongear`". Reading `on a \`the shared
- * mappings\`` would be the alternative, and a diagnostic is prose (#275).
+ * mappings\`` would be the alternative, and a diagnostic is prose.
  *
  * @param {object} finding - `{system, systemVersion, noteType, source, target, shared}`.
  * @returns {string} The message.
@@ -79,16 +79,16 @@ export function measureNote(note: object, format: import("./content-format.mjs")
 /**
  * Measure a corpus, and count what it finds by class.
  *
- * The counts are the point as much as the findings: #127 promotes a class to
- * fatal when its count reaches zero, so a run that prints them is the epic's
- * progress bar.
+ * The counts are the point as much as the findings: a class is promoted to
+ * fatal when its count reaches zero, so a run that prints them is the
+ * migration's progress bar.
  *
  * @param {Iterable<object>} notes - `{file, raw, fm}` for each authored note.
  * @param {import("./content-format.mjs").ContentFormat} format - The parsed
  *   specification.
  * @param {object} [opts]
  * @param {boolean} [opts.strict=false] - Report the findings as errors rather
- *   than warnings. #127 turns this on one slice at a time.
+ *   than warnings. Turned on one slice at a time.
  * @returns {{findings: object[], notes: number, byClass: Record<string, number>}}
  */
 export function measureCorpus(notes: Iterable<object>, format: import("./content-format.mjs").ContentFormat, { strict }?: {
@@ -107,7 +107,7 @@ export function measureCorpus(notes: Iterable<object>, format: import("./content
 export function fieldDriftMessage({ noteType, source, target, name, to }: object): string;
 /**
  * Check the specification's per-type tables against the field declarations that
- * compile them (#136).
+ * compile them.
  *
  * @param {object} opts
  * @param {import("./content-format.mjs").ContentFormat} opts.format - The

package/types/engine/content-format.d.mts

@@ -52,7 +52,7 @@ export const CONTENT_FORMAT_PATH: string;
  *   `the shared mappings` for a row of the shared tables — see `shared`.
  * @property {boolean} [shared] - Whether the row came from a **shared** mapping
  *   table, which stands before the first `### type:` heading and states what
- *   every type maps identically (#275). Absent on a per-type row, so the two
+ *   every type maps identically. Absent on a per-type row, so the two
  *   never mix: only a per-type row has a field declaration to be checked
  *   against.
  * @property {string} system - The system column it sits under, from the header.
@@ -121,7 +121,7 @@ export type MappingClaim = {
     /**
      * - Whether the row came from a **shared** mapping
      * table, which stands before the first `### type:` heading and states what
-     * every type maps identically (#275). Absent on a per-type row, so the two
+     * every type maps identically. Absent on a per-type row, so the two
      * never mix: only a per-type row has a field declaration to be checked
      * against.
      */

package/types/engine/content-html.d.mts

@@ -0,0 +1,78 @@
+/**
+ * What a note carrying raw HTML is told.
+ *
+ * It names the tag, because a file with several is fixed one at a time, and it
+ * says why rather than only what: an author who does not know the book cannot
+ * render it will read the finding as pedantry about a tag that plainly works.
+ *
+ * @param {string} tag - The matched markup, as written.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function htmlMessage(tag: string): string;
+/**
+ * Every raw HTML tag in one note's body.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>} One finding per tag, in source
+ *   order.
+ */
+export function checkHtml(body: string, file: string, { bodyLine, bodyColumn }?: {
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+}): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "warning";
+    message: string;
+}>;
+/**
+ * Walk a content tree and report raw HTML in every note's prose.
+ *
+ * The frontmatter fence is taken off first, so what is scanned is the body and
+ * the positions are still the file's. A file with no frontmatter is scanned
+ * whole: it is not a note, but a stray `.md` in the tree carrying markup is the
+ * same problem for the same reason.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>, files: number}} The findings, and
+ *   how many files were read.
+ */
+export function lintContentHtml(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line: number;
+        column: number;
+        severity: "warning";
+        message: string;
+    }>;
+    files: number;
+};
+/**
+ * A raw HTML tag, opening, closing or self-closing.
+ *
+ * The name must start a tag for the match to begin, which is what keeps
+ * markdown's own angle brackets out of it: an autolink is `<https://…>`, and
+ * `https` is followed by `:` rather than whitespace or `>`, so the pattern
+ * stops. A comparison written in prose — `a < b` — has no name after the
+ * bracket at all.
+ *
+ * Attributes are consumed as "anything but a bracket", deliberately loosely: a
+ * finding names the tag, and a pattern that tried to parse attribute syntax
+ * would be a second HTML parser with its own bugs, in a module whose whole
+ * point is that nothing here should be parsing HTML.
+ *
+ * @type {RegExp}
+ */
+export const HTML_TAG: RegExp;