@heroiclands/package-build 17.1.0 → 18.0.0

package/types/hm3/actors.d.mts

@@ -0,0 +1,48 @@
+export class Hm3Actors extends SystemActorCompiler {
+    /**
+     * HM3's note-type → document-subtype map — the one declaration that says
+     * which block this pass reads, which notes it claims, and what each
+     * becomes. It is also what every embedded reference is translated through.
+     *
+     * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
+     */
+    static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
+    /**
+     * Build every embedded item an HM3 actor carries, from `hm3.items`.
+     *
+     * One list, not two: HM3 keeps a character's abilities in `system.abilities`
+     * rather than as embedded documents, so there is no attributes map to
+     * expand the way SoHL's pass expands `sohl.attributes`.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined items, by address.
+     * @param {string} actorId - The owning actor's id, seeding embedded ids.
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @returns {object[]} The embedded items.
+     */
+    buildEmbeddedItems(itemsMap: Map<string, object>, actorId: string, fm: object, ctx: string): object[];
+    /**
+     * Build one HM3 actor document from a `being` note.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined items, by address.
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} body - The note body, converted.
+     * @returns {object} The actor document, keyed for the pack.
+     */
+    buildActor(itemsMap: Map<string, object>, fm: object, body: string): object;
+    /**
+     * The document's `flags`: whatever the note authors, plus this system's
+     * template priority.
+     *
+     * The rule itself is {@link module:hm3/template-priority.templateFlags},
+     * because the Item pass writes the same flag from the same statement (#283)
+     * and two copies of it were one copy too many — this pass had the only one,
+     * and the Item pass had none.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} block - This pass's system block.
+     * @returns {object} The flags to emit.
+     */
+    actorFlags(fm: object, block: string): object;
+}
+import { SystemActorCompiler } from "../engine/actor-compiler.mjs";

package/types/hm3/default-item-art.d.mts

@@ -0,0 +1,42 @@
+/**
+ * The default art path for an HM3 item type, or throw when the type is unknown.
+ *
+ * Reading this from `item-builders.mjs` is what keeps the two lists one: that
+ * module cannot declare a type this map does not cover, because this throws and
+ * that module evaluates at import.
+ *
+ * @param {string} type - The note type.
+ * @returns {string} The default image path for it.
+ * @throws {Error} When no art is paired with the type.
+ */
+export function hm3DefaultItemArt(type: string): string;
+/**
+ * Default HM3 item artwork, keyed by the **note** type that compiles into it.
+ *
+ * The registry contract is fail-fast (see {@link module:engine/item-registry.itemArt}):
+ * a type whose entry pairs no art aborts the pack build for a note that carries
+ * no `img:` of its own, rather than shipping a mismatched icon. So every type
+ * `item-builders.mjs` declares has a row here.
+ *
+ * **Paths are fully resolved.** `resolveImg` rewrites a leading `icons/` or
+ * `images/` to the *consuming package's* asset root, which is not where these
+ * live: they are shipped by the HM3 system. Written as `systems/hm3/images/…`
+ * they pass through untouched and address the icons HM3's own compendiums
+ * already use, so an item compiled from a note looks like its hand-authored
+ * neighbours.
+ *
+ * **A one-to-many type gets one default**, because art is keyed by note type
+ * and a note type is what a registry entry addresses. `weapongear` compiles
+ * into a weapon or a missile and defaults to the sword either way; a note whose
+ * subject is a thrown spear says so with an `img:` of its own. Keying art by
+ * document subtype instead would mean a second lookup that could disagree with
+ * the registry's, and the note-level override already answers the case.
+ *
+ * @module
+ */
+/**
+ * Note type → the image an HM3 item of that type ships with.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const HM3_DEFAULT_ITEM_ART: Readonly<Record<string, string>>;

package/types/hm3/document-subtypes.d.mts

@@ -0,0 +1,24 @@
+/**
+ * The frontmatter key inside the `hm3:` block that resolves a one-to-many row.
+ *
+ * One key for all four rows, deliberately: an author who has learned it on a
+ * weapon has learned it on a trauma. It is the block's `type` property — the
+ * document type this system compiles the note into — which is what the content
+ * format has always called it.
+ *
+ * @type {string}
+ */
+export const HM3_TYPE_KEY: string;
+/**
+ * Every content type HM3 compiles into a Foundry document, and what it becomes.
+ *
+ * The Item rows are the nine types `item-builders.mjs` declares; the one Actor
+ * row is `being`, which HM3 splits into `character` and `creature`. Types this
+ * map does not name — `affiliation`, `affliction`, `attribute`,
+ * `concoction`, `mystery`, and every core type — compile into no HM3
+ * document at all, silently and correctly: HM3 has no form of them, and a
+ * finding on every such note would be the noise #79's rule exists to prevent.
+ *
+ * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
+ */
+export const HM3_DOCUMENT_SUBTYPES: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;

package/types/hm3/index.d.mts

@@ -0,0 +1,7 @@
+export * as itemBuilders from "./item-builders.mjs";
+export * as itemFields from "./item-fields.mjs";
+export * as documentSubtypes from "./document-subtypes.mjs";
+export * as items from "./items.mjs";
+export * as actors from "./actors.mjs";
+export * as templatePriority from "./template-priority.mjs";
+export { HM3_DEFAULT_ITEM_ART, hm3DefaultItemArt } from "./default-item-art.mjs";

package/types/hm3/item-builders.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Every HM3 item type, paired with the builder for its `system` block, the
+ * default art for the type, and the frontmatter fields it declares.
+ *
+ * @type {Readonly<Record<string, Readonly<{system: (fm: object) => object, img: string, fields: readonly object[]}>>>}
+ */
+export const HM3_ITEM_BUILDERS: Readonly<Record<string, Readonly<{
+    system: (fm: object) => object;
+    img: string;
+    fields: readonly object[];
+}>>>;

package/types/hm3/item-fields.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Every HM3 item type's frontmatter vocabulary, in the order the `system` block
+ * emits it.
+ *
+ * The keys are **note** types, not HM3 document subtypes — `projectile`
+ * rather than `missilegear`, `mysticalability` rather than `psionic` — because
+ * a registry is addressed by what a note calls itself. What the document is
+ * called is the map's answer, and only the map's.
+ *
+ * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
+ */
+export const HM3_ITEM_FIELDS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;

package/types/hm3/items.d.mts

@@ -0,0 +1,23 @@
+export class Hm3Items extends SystemItemCompiler {
+    /**
+     * HM3's note-type → document-subtype map — the one declaration that says
+     * which block this pass reads, which notes it claims, and what each becomes
+     * (#58/#79).
+     *
+     * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
+     */
+    static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
+    /**
+     * The `system.*` field HM3 writes on an item from the note's prose.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {object} at - What the pass already knows about this note.
+     * @param {string} at.markdown - The note body, tables expanded and
+     *   wikilinks resolved.
+     * @returns {object} The shared `system` fields — `description`, or nothing.
+     */
+    commonSystem(fm: object, { markdown }: {
+        markdown: string;
+    }): object;
+}
+import { SystemItemCompiler } from "../engine/item-compiler.mjs";

package/types/hm3/template-priority.d.mts

@@ -0,0 +1,21 @@
+/**
+ * A document's `flags`: whatever the note authors, plus this system's template
+ * priority.
+ *
+ * A note that is not a template — or states nothing — writes nothing, rather
+ * than a `null` nothing reads.
+ *
+ * **Read through the shared resolver, not a field declaration** (#266). A
+ * `FieldSpec`'s shared source is a single position, and this value has five:
+ * `data:`, this block, the top level, and the retiring `archetype` spelling in
+ * the latter two. The resolver is the single implementation of what a note said,
+ * so the two systems cannot disagree about it. It is read against **this**
+ * block: the `sohl:` block is not a source for an HM3 document, so a tree that
+ * still states the priority there (`harn-ensemble`, on 2,502 notes) writes no
+ * HM3 flag until it sweeps to `data:`.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - This pass's system block.
+ * @returns {object} The flags to emit.
+ */
+export function templateFlags(fm: object, block: string): object;

package/types/manifest.d.mts

@@ -18,7 +18,7 @@ export function normalizeRepoUrl(repository: string | {
     url?: string;
 }): string;
 /**
- * The four addresses a Foundry manifest advertises.
+ * The addresses a Foundry manifest advertises.
  *
  * `manifest` deliberately points at **`releases/latest`** rather than at this
  * version: it is the URL an *installed* package re-fetches to discover that a
@@ -42,6 +42,27 @@ export function releaseUrls({ repoUrl, version, artifact }: {
     manifest: string;
     download: string;
 };
+/**
+ * Where this release publishes its content index (#239).
+ *
+ * **Pinned to this version, like `download` and unlike `manifest`.** A
+ * consumer reaches this URL by reading the dependency's manifest, so the
+ * manifest it read and the index it then fetches describe the same release —
+ * which is the whole point of publishing them together. A `releases/latest`
+ * index would silently pair a pinned manifest with a moving index, and the
+ * mismatch would surface as a cross-package link that resolved yesterday.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.version - The version being built.
+ * @param {string} opts.contentPackage - The content package name.
+ * @returns {string} The version-pinned asset URL.
+ */
+export function metadataUrl({ repoUrl, version, contentPackage }: {
+    repoUrl: string;
+    version: string;
+    contentPackage: string;
+}): string;
 /**
  * The manifest's `packs`, derived from the one pack list the build already has.
  *

package/types/release.d.mts

@@ -13,19 +13,24 @@
  * @param {string} [opts.outDir] - Where the release assets are written.
  * @param {"system"|"module"} [opts.artifact] - Which artifact is shipped.
  *   Determines both asset names.
- * @returns {Promise<{zip: string, manifest: string, bytes: number,
- *   version: string}>} The two paths written, the archive's size, and the
- *   version the manifest declares.
+ * @param {string} [opts.metadataDir] - Where the build writes its content
+ *   index, consulted when the advertised file was not staged.
+ * @returns {Promise<{zip: string, manifest: string, metadata?: string,
+ *   bytes: number, version: string}>} The paths written, the archive's size,
+ *   and the version the manifest declares. `metadata` is absent when the
+ *   manifest advertises no content index.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
-export function packRelease({ stageDir, outDir, artifact, }?: {
+export function packRelease({ stageDir, outDir, artifact, metadataDir, }?: {
     stageDir?: string | undefined;
     outDir?: string | undefined;
     artifact?: "module" | "system" | undefined;
+    metadataDir?: string | undefined;
 }): Promise<{
     zip: string;
     manifest: string;
+    metadata?: string;
     bytes: number;
     version: string;
 }>;

package/types/sohl/actors.d.mts

@@ -1,80 +1,13 @@
-export class Actors extends BasePackCompiler {
+export class Actors extends SystemActorCompiler {
     /**
-     * The note-type → document-subtype map this pass compiles against.
-     *
-     * Stated by the class rather than reached for through the module import, so
-     * every subtype decision the pass makes — the actor's own, and each
-     * embedded item reference's — reads one declaration that a subclass
-     * compiling for another system can replace. That is also what lets the
-     * non-identity behaviour be exercised without introducing a non-identity
-     * row into SoHL's own map, which is #78's job and moves compiled bytes.
+     * SoHL's note-type → document-subtype map — the one declaration that says
+     * which block this pass reads, which notes it claims, and what each
+     * becomes (#79). It is also what every embedded reference is translated
+     * through, which is why a subclass replaces one thing and not two.
      *
      * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
      */
     static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
-    constructor({ itemsSourceDirs, foreignSourceDirs, ...options }: {
-        [x: string]: any;
-        itemsSourceDirs?: never[] | undefined;
-        foreignSourceDirs?: never[] | undefined;
-    });
-    /** @type {readonly string[]} */
-    itemsSourceDirs: readonly string[];
-    foreignSourceDirs: any;
-    itemsMap: Map<string, object> | undefined;
-    /** @inheritdoc */
-    reportDetail(stats: any): void;
-    /**
-     * The Foundry Item subtype an embedded reference's `type` addresses.
-     *
-     * **The reference is in the note vocabulary; the address is in the
-     * document's** (#140). A being writes `(type, shortcode)` with the type an
-     * author authors, while {@link itemAddress} keys the predefined items by
-     * the subtype each compiled document carries — so exactly one of the two
-     * sides has to translate, and it is this one. The system's map is a
-     * function from note type to subtype by construction; the reverse is not,
-     * and a compiled document records nothing about the note that produced it,
-     * so there is no honest way to key the addresses the other way round.
-     *
-     * The two vocabularies are the same string in every SoHL row today, which
-     * is why looking a reference up verbatim worked. The first non-identity row
-     * (#78: `armor` → `armorgear`) ends that, and a reference resolving to
-     * nothing must be a finding rather than an item quietly missing from the
-     * compiled actor.
-     *
-     * @param {string} type - The type the reference names.
-     * @returns {import("../engine/document-subtypes.mjs").ReferencedSubtype}
-     *   The subtype, or why the reference names none.
-     */
-    embeddedSubtype(type: string): import("../engine/document-subtypes.mjs").ReferencedSubtype;
-    /**
-     * Resolve one embedded item from a `(type, shortcode?, overlay)`
-     * descriptor. If `shortcode` is given, the predefined item is fetched
-     * from `itemsMap` and the overlay deep-merged on top. If absent, the
-     * descriptor must carry enough fields to stand alone. The embedded
-     * item's `_id` is regenerated deterministically from
-     * `(actorId, subType, shortcode, indexKey)` so re-exports are stable —
-     * from the **document subtype**, so that renaming a note type (#78) leaves
-     * every embedded id exactly where it was.
-     * Returns null if the descriptor cannot be resolved.
-     *
-     * @param {Map<string, object>} itemsMap - The predefined items, by address.
-     * @param {string} actorId - The owning actor's id, seeding embedded ids.
-     * @param {string} type - The **note** type the reference names.
-     * @param {string|null} shortcode - The referenced item's shortcode, or
-     *   `null` for a stand-alone entry.
-     * @param {object} [overlay] - The entry's remaining properties.
-     * @param {string} indexKey - Distinguishes two references to one item.
-     * @param {string} ctx - Diagnostic context (the actor's label).
-     * @param {object} [at] - Where to locate a finding.
-     * @param {string} [at.fmKey] - The frontmatter key the reference sits
-     *   under, so an unresolved one is reported at the reference rather than
-     *   at the note.
-     * @returns {object|null} The embedded item, or null when it resolved to
-     *   nothing — always with a finding emitted.
-     */
-    resolveEmbedded(itemsMap: Map<string, object>, actorId: string, type: string, shortcode: string | null, overlay?: object, indexKey: string, ctx: string, { fmKey }?: {
-        fmKey?: string | undefined;
-    }): object | null;
     /**
      * Build all embedded items for an actor: one per `sohl.attributes`
      * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
@@ -114,7 +47,7 @@ export class Actors extends BasePackCompiler {
         _id: any;
         system: {
             shortcode: any;
-            archetype: number | null;
+            templatePriority: number | null;
             portrait: string;
             appearance: string;
             dossier: string;
@@ -145,4 +78,4 @@ export class Actors extends BasePackCompiler {
         _key: string;
     };
 }
-import { BasePackCompiler } from "../engine/base-compiler.mjs";
+import { SystemActorCompiler } from "../engine/actor-compiler.mjs";

package/types/sohl/being-info.d.mts

@@ -33,30 +33,6 @@ export function deriveBeingInfo(sohl: object | null | undefined, index: Map<stri
     name?: string;
     url?: string;
 }>): object | null | undefined;
-/**
- * **A being's info-block fields**, derived from the items it embeds.
- *
- * A `being` note carries its embedded documents as `sohl.items` — a flat list
- * of `{ shortcode, type, system? }` — but the shared theme's sidebar reads
- * *resolved* shapes: a `skills` map, `gear` grouped by kind, and `spells` /
- * `talents` split out of the mystical abilities. This is the translation
- * between the two, and it is SoHL data-model knowledge: which item type is a
- * skill, where a mastery level lives, what distinguishes a spell from a talent.
- *
- * **It lives here because it was living in two places.** Both
- * `Song-of-Heroic-Lands-FoundryVTT` and `sohl-thalorna` carried a copy, and the
- * copies drifted: SoHL's caller still gated the derivation on `character` and
- * `creature`, the two types #1580 merged into `being`, so it had matched
- * nothing since the merge and all 95 of its being pages published with empty
- * sidebar sections (SoHL#1696). thalorna's copy checked `being` and was right.
- * Nothing failed in either repository; the pages built and shipped.
- *
- * {@link isBeing} exists for that reason. The bug was not in the derivation —
- * it was in each caller's idea of what a being *is*, written out per repository
- * where it could rot independently. One definition, imported.
- *
- * @module
- */
 /**
  * The note `type` whose pages carry a being info block.
  *
@@ -69,9 +45,14 @@ export const BEING_TYPE: "being";
 /**
  * The sidebar group each gear item type is displayed under.
  *
- * Presentation naming, not data-model naming: the model says `weapongear`, the
- * sidebar heading says "weapons". Kept as one table so a new gear type is added
- * in a single place rather than in each consumer's site build.
+ * Presentation naming, not data-model naming: the note type says `weapongear`,
+ * the sidebar heading says "weapons". Kept as one table so a new gear type is
+ * added in a single place rather than in each consumer's site build.
+ *
+ * Keyed by **note** type, which is what a being's embedded `(type, shortcode)`
+ * references spell — and since #78 three of those are no longer the document
+ * subtype they compile into. A reference still on a renamed spelling is
+ * normalised at the lookup below rather than given a second row here.
  *
  * @type {Readonly<Record<string, string>>}
  */

package/types/sohl/default-item-art.d.mts

@@ -1,5 +1,6 @@
 /**
- * The default art path for an item `type`, or throw when the type is unknown —
+ * The default art path for an item **document subtype**, or throw when it is
+ * unknown —
  * the build's fail-fast contract, so an unrecognized type is never silently
  * defaulted (aborting the pack build rather than shipping a mismatched icon).
  *
@@ -7,8 +8,9 @@
  * {@link DEFAULT_ITEM_ART} directly and fall back to Foundry's default instead
  * of calling this — see `SohlItem.getDefaultArtwork`.
  *
- * @param {string} type - the item type.
- * @returns {string} the default image path for that type.
+ * @param {string} type - The SoHL Item document subtype — `armorgear`, not the
+ *   `armor` note type that compiles into one.
+ * @returns {string} the default image path for that subtype.
  */
 export function defaultItemArt(type: string): string;
 export namespace DEFAULT_ITEM_ART {

package/types/sohl/items.d.mts

@@ -1,40 +1,25 @@
-export class Items extends BasePackCompiler {
+export class Items extends SystemItemCompiler {
     /**
-     * How many of each item type this pass wrote, for the summary. Every type
-     * is present from the start so the tally reads as a census of the
-     * whitelist rather than of what happened to compile.
+     * SoHL's note-type → document-subtype map — the one declaration that says
+     * which block this pass reads, which notes it claims, and what each becomes
+     * (#58/#79).
      *
-     * @type {Record<string, number>}
+     * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
      */
-    counts: Record<string, number>;
+    static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
     /**
-     * The Foundry Item subtype a note compiles into.
-     *
-     * **Looked up, not inferred.** For every type this system declares, the
-     * emitted subtype is the map's, so the note vocabulary and the document
-     * vocabulary are two separately-stated things rather than one string
-     * written twice (#79).
-     *
-     * **A type the map does not name belongs to the consumer**, and its
-     * registry entry is the declaration: a repository shipping an item type of
-     * its own writes it once, in the `itemBuilders` table of its
-     * `package-build.config.yaml`, and that key is what the document is a
-     * subtype of. That is an authored statement in the consumer's own
-     * configuration, not a coincidence inside this package's source — and
-     * refusing it here would silently drop every document of a type SoHL has
-     * no opinion about (#7/#1563).
+     * The `system.*` fields SoHL writes on every item, whatever its type:
+     * shortcode, templatePriority, actionDefs, notes, docHtml.
      *
      * @param {object} fm - The note's frontmatter.
-     * @returns {string} The document's `type`.
+     * @param {object} at - What the pass already knows about this note.
+     * @param {string} at.description - The pointer to the note's item doc.
+     * @param {string} at.label - Human-readable context for error messages.
+     * @returns {object} The shared `system` fields.
      */
-    itemSubtype(fm: object): string;
-    /** An item is named by its own type in the log, not by "item". */
-    noteLabel(fm: any): any;
-    /** @inheritdoc */
-    onCompiled(fm: any): void;
-    /** @inheritdoc */
-    reportCompiled(stats: any): void;
-    /** @inheritdoc */
-    reportDetail(stats: any): void;
+    commonSystem(fm: object, { description, label }: {
+        description: string;
+        label: string;
+    }): object;
 }
-import { BasePackCompiler } from "../engine/base-compiler.mjs";
+import { SystemItemCompiler } from "../engine/item-compiler.mjs";

package/engine/foreign-manifests.mjs

@@ -1,126 +0,0 @@
-/*
- * 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
- */
-
-/**
- * Whether a vendored manifest can still be *addressed*, as distinct from read.
- *
- * A consuming build vendors each foreign package's link manifest and resolves
- * cross-package links through it. The lookup is by canonical key, so it needs
- * both sides to agree on the key's shape: when they agree the link resolves,
- * and when they drift apart the lookup cannot match on *any* input — while the
- * page still reads correctly, because an unresolved wikilink falls through to
- * its own display text. That is how a v3 key change left one repository reading
- * 2,367 entries through a lookup that could never hit one of them (#1499).
- *
- * Bridging the lookup is not enough on its own: it fails silently again the next
- * time either side moves. So the shapes are *checked* rather than merely
- * converted, and a manifest that yields no addressable key at all fails the
- * build. A lookup that cannot match anything reports nothing, which is the one
- * failure a dead-link check can never catch.
- *
- * This guards {@link kbManifest}'s own key format, which is why it lives beside
- * it rather than in whichever consumer happens to load a manifest.
- *
- * @module
- */
-
-import fs from "node:fs";
-import path from "node:path";
-
-import { formatDiagnostic, positionOfLiteral } from "./diagnostics.mjs";
-import { readCanonicalKey } from "./kb-manifest.mjs";
-
-/**
- * Every foreign package whose manifest entries a build cannot address.
- *
- * A package is reported only when it contributes entries and **none** of them
- * yields a readable canonical key — the total, silent failure described above.
- * Partial drift is deliberately not reported here: it resolves something, and
- * whatever it fails to resolve surfaces as an ordinary dead address, pointed at
- * the note that cites it. A package contributing no entries at all is likewise
- * not a finding; a pack-only package publishes no addressable pages by design
- * (#1516), and one being brought up publishes nothing yet.
- *
- * @param {Map<string, {package?: string}>} foreignIndex - `foreign.index` as
- *   returned by `loadForeignManifests`, keyed by canonical key.
- * @returns {Array<{package: string, entries: number, sampleKey: string}>} One
- *   finding per drifted package, in the order the index first names each.
- */
-export function unaddressableForeignPackages(foreignIndex) {
-    const byPackage = new Map();
-    for (const [key, value] of foreignIndex ?? new Map()) {
-        // The package is read from the entry rather than the key, since the key
-        // is the very thing under suspicion — deriving it from a shape that may
-        // not parse would report the finding against `undefined`.
-        const pkg = value?.package;
-        if (!pkg) continue;
-        const seen = byPackage.get(pkg) ?? {
-            entries: 0,
-            readable: 0,
-            sampleKey: key,
-        };
-        seen.entries += 1;
-        if (readCanonicalKey(key)) seen.readable += 1;
-        byPackage.set(pkg, seen);
-    }
-
-    const findings = [];
-    for (const [pkg, seen] of byPackage) {
-        if (seen.entries > 0 && seen.readable === 0) {
-            findings.push({
-                package: pkg,
-                entries: seen.entries,
-                sampleKey: seen.sampleKey,
-            });
-        }
-    }
-    return findings;
-}
-
-/**
- * One finding, in the standard `file:line:column: severity: message` form.
- *
- * The position is recovered by locating the offending key in the manifest text:
- * the finding is about a literal the reader can see in the file, so its position
- * is implicit rather than absent. When the file cannot be read, or the key is
- * not in it, the locator degrades to the file alone — a dropped field, never a
- * guessed `1:1` that would send the reader to the top of a 500 KB manifest for a
- * finding that is not there.
- *
- * @param {{package: string, entries: number, sampleKey: string}} finding - One
- *   finding from {@link unaddressableForeignPackages}.
- * @param {string} manifestDir - The directory the manifests were loaded from.
- * @returns {string} The formatted diagnostic, path first on the line.
- */
-export function formatUnaddressableFinding(finding, manifestDir) {
-    const file = path.join(manifestDir, `${finding.package}.json`);
-    let at = {};
-    try {
-        at = positionOfLiteral(fs.readFileSync(file, "utf8"), `"${finding.sampleKey}"`);
-    } catch {
-        // Unreadable here is not itself the finding — `loadForeignManifests`
-        // already reports that as a stale manifest. The file is simply all that
-        // is known about where this one is.
-    }
-    return formatDiagnostic({
-        file,
-        ...at,
-        severity: "error",
-        message:
-            "no key in this manifest is a canonical " +
-            `\`package-type-shortcode\` address (${finding.entries} ` +
-            `${finding.entries === 1 ? "entry" : "entries"}, none addressable; ` +
-            `first is \`${finding.sampleKey}\`) — every cross-package link to ` +
-            `${finding.package} would resolve to nothing, silently`,
-    });
-}