@heroiclands/package-build 10.0.1 → 11.0.0

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

@@ -1,59 +1,22 @@
 /**
- * The URL segment for one content note.
+ * The URL-safe token a piece of prose reduces to.
  *
- * The name is **transliterated** before it is reduced, so an accented character
- * is carried across rather than dropped — dropping is what turned `Nüsvōrroth`
- * into `n-sv-rroth` and forced a hand-written slug. Ligatures expand the way a
- * reader would spell them out: `þ`→`th`, `æ`→`ae`, `œ`→`oe`, `ß`→`ss`, `ij`→`ij`,
- * `fi`→`fi`, and eth (`ð`) follows the Icelandic convention of a bare `d`.
+ * The text is **transliterated** before it is reduced, so an accented character
+ * is carried across rather than dropped. Ligatures expand the way a reader would
+ * spell them out: `þ`→`th`, `æ`→`ae`, `œ`→`oe`, `ß`→`ss`, `ij`→`ij`, `fi`→`fi`,
+ * and eth (`ð`) follows the Icelandic convention of a bare `d`.
  *
  * Two reductions are ours rather than the transliterator's:
  *
  * - **apostrophes are removed**, not treated as separators (`Armorer's Kit` →
- *   `armorers-kit`), matching the URLs these pages already publish at;
+ *   `armorers-kit`);
  * - **a fraction keeps its digits together** — a vulgar fraction expands to
  *   `3/4`, and the solidus would otherwise split it into `3-4`, so a slash
  *   *between digits* is closed up (`Kûrbúl ¾-Helm` → `kurbul-34-helm`).
  *
- * @param {string | undefined} name - The note's display name (`name.full`),
- *   which a malformed note may not have at all.
- * @returns {string} The URL segment (never empty).
- * @throws {Error} When there is no name, or the name carries no URL-safe
- *   characters — either way the note cannot be addressed, which is a content
- *   error rather than something to paper over with a fallback.
+ * @param {string | undefined} text - The prose to reduce.
+ * @returns {string} The token, or `""` when the text carries nothing URL-safe.
+ *   Empty is an ordinary answer here: nothing is addressed by a slug any more,
+ *   so an anchor that reduces to nothing is the caller's to judge.
  */
-export function slugify(text: any): string;
-/**
- * The URL segment a content note publishes at.
- *
- * {@link slugify} with the rule that a document *must* be addressable: a note
- * that yields no slug is a content error, not something to paper over with a
- * fallback, because the alternative is a page nobody can reach.
- *
- * @param {string | undefined} name - The note's display name (`name.full`),
- *   which a malformed note may not have at all.
- * @returns {string} The URL segment (never empty).
- * @throws {Error} When there is no name, or the name carries no URL-safe
- *   characters.
- */
-export function contentSlug(name: string | undefined): string;
-/**
- * Find pages that would publish to the same URL.
- *
- * Nothing constrains two notes in one section from sharing a name, and a
- * collision silently overwrites one page with the other. This turns it into a
- * build failure that names every claimant, so the fix is a more specific title.
- * (The content tree has no collisions today.)
- *
- * @param {Array<{sec: string, slug: string, src: string}>} pages
- * @returns {Array<{url: string, sources: string[]}>} One entry per collision, in
- *   first-claim order; empty when every URL is unique.
- */
-export function findSlugCollisions(pages: Array<{
-    sec: string;
-    slug: string;
-    src: string;
-}>): Array<{
-    url: string;
-    sources: string[];
-}>;
+export function slugify(text: string | undefined): string;

package/types/engine/diagnostics.d.mts

@@ -111,16 +111,29 @@ export function positionInBody(body: string, offset: number, { bodyLine, bodyCol
  * a line of prose — sending the reader to a position that is not the problem,
  * which is the one thing the located form exists to prevent.
  *
+ * The key match tolerates leading whitespace by default, so a nested key of the
+ * same name answers when no top-level one is present — which is usually what a
+ * reader wants, the key being unique in nearly every note. Pass `topLevel` where
+ * it is not: `aliases` is both a retired top-level field and a **permitted**
+ * `name.aliases` (#180), and a finding about the first must never open on the
+ * second, which would tell an author to delete a field they are allowed to
+ * write.
+ *
  * @param {string} raw - The file's full contents, frontmatter included.
  * @param {string} key - The top-level frontmatter key.
  * @param {string} [value] - When given, prefer the occurrence whose line also
  *   carries this text. A list-valued key (`aliases`) is reported at the entry
  *   that is wrong, not at the key that introduces it.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
+ *   an identically named nested key cannot answer for it.
  * @returns {{line?: number, column?: number}} Spreadable position fields, empty
  *   when the key cannot be located — dropped rather than guessed, as
  *   {@link formatDiagnostic} requires.
  */
-export function positionInFrontmatter(raw: string, key: string, value?: string): {
+export function positionInFrontmatter(raw: string, key: string, value?: string, { topLevel }?: {
+    topLevel?: boolean | undefined;
+}): {
     line?: number;
     column?: number;
 };

package/types/engine/helpers.d.mts

@@ -256,11 +256,11 @@ export function defaultStats(): object;
  * @param {object} [router] - The pack router. Supplied by the calling pass so
  *   the index and the compile agree about where each note landed; defaults to
  *   this repository's own.
- * @returns {{byShortcode: Map, byAlias: Map}} From `buildWikilinkIndex`.
+ * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
 export function buildContentLinkIndex(contentBase: string, router?: object): {
     byShortcode: Map<any, any>;
-    byAlias: Map<any, any>;
+    types: Set<any>;
 };
 /**
  * Converts the wikilinks in one note's markdown, reporting any that have no
@@ -280,7 +280,8 @@ export function buildContentLinkIndex(contentBase: string, router?: object): {
  *   entry. Position is carried by `{ file, bodyLine, bodyColumn, lineMap }`,
  *   the last from {@link expandNoteTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
- * @throws {Error} On an ambiguous alias or a dead qualified address. The error
+ * @throws {Error} On any link that does not resolve — an unlabelled one, a
+ *   target that is not an address, or an address nothing publishes. The error
  *   carries `file` and `position`, so a caller reports it in the same form
  *   rather than re-deriving one.
  */

package/types/engine/homepage.d.mts

@@ -1,3 +1,18 @@
+/**
+ * The file a homepage is written to, relative to the package's site root.
+ *
+ * Its **address**, flat at the package root, and stated in the page's own `url`
+ * — the same separation every other page has since #181, where the directory
+ * decides the Hugo section and the front matter decides the URL. Flat rather
+ * than inside a `homepage/` section directory, because a homepage is not one of
+ * a kind: a section holding exactly one page would publish a landing at
+ * `/<package>/kb/homepage/` that nothing links to and nobody wrote.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string} The destination filename, e.g. `homepage-root.md`.
+ * @throws {Error} When the note declares no shortcode, and so has no address.
+ */
+export function homepageDestination(fm: object): string;
 /**
  * Whether a note's frontmatter declares the homepage type.
  *
@@ -6,26 +21,38 @@
  */
 export function isHomepage(fm: object | null | undefined): boolean;
 /**
- * The address-bearing fields one note authors, in the order it authored them.
+ * What the address rule says about one note's top-level fields.
  *
- * Authoring order rather than declaration order, so a caller emitting one
- * diagnostic per finding emits them top to bottom down the file — the order a
- * reader and a compiler-output parser both expect.
+ * Two statements about the same thing, so they are made together: the field a
+ * homepage **owes** and the field it may **not** write.
  *
- * Presence is the whole test: `shortcode:` authored empty still says "this page
- * has an address of its own", and a value cannot make the claim true.
+ * The missing `shortcode` comes first, and is located at `type:` rather than at
+ * a key that is not there — the `homepage` value is what makes the field
+ * required, it is a real position in the file, and inventing a `1:1` for an
+ * absent key would put the author on the opening fence. The refused fields
+ * follow in the order the note authored them, so a caller emitting one
+ * diagnostic per finding walks down the file.
  *
- * Returned without a locator, because the two things that would supply one —
- * the raw note text and the position helper — belong to the caller. This
- * mirrors {@link module:engine/retired-fields}, whose retired-field messages
- * are likewise positioned by whoever reports them.
+ * Presence is the whole test for a refused field, and absence-or-blank for the
+ * required one: `shortcode:` authored empty is no address, and a value cannot
+ * make `id` mean something on a page that compiles to no document.
+ *
+ * Each finding carries the `locator` key to position it at, because the two
+ * things that would resolve one — the raw note text and the position helper —
+ * belong to the caller. This mirrors {@link module:engine/retired-fields},
+ * whose retired-field messages are likewise positioned by whoever reports them.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {Array<{key: string, message: string}>} One entry per field the note
- *   authored, empty for any note that is not a homepage.
+ * @returns {Array<{field: string, locator: {key: string, literal?: string},
+ *   message: string}>} One entry per finding, empty for any note that is not a
+ *   homepage and declares nothing wrong.
  */
 export function checkHomepageAddressFields(fm: object | null | undefined): Array<{
-    key: string;
+    field: string;
+    locator: {
+        key: string;
+        literal?: string;
+    };
     message: string;
 }>;
 /**
@@ -37,12 +64,16 @@ export function checkHomepageAddressFields(fm: object | null | undefined): Array
  * - _None_ and the package serves nothing at `/<package>/`. That is the failure
  *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
  *   homepage(s)` and exits 0.
- * - _Two_ and it serves a page nobody chose. Every homepage is written to the
- *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
- *   the package's front page is decided by the order the walk happened to reach
- *   the files in — by *filename*, on a type whose whole point is that it is
- *   routed by frontmatter. There is no "first wins" convention to fall back on,
- *   so nothing here can pick the right one.
+ * - _Two_ and it serves a page nobody chose. **This is a cardinality rule, and
+ *   since #182 it is only that.** It used to rest on the fixed destination
+ *   every homepage shared — the second overwrote the first — so the address
+ *   rule enforced it as a side effect. A homepage is written at its own address
+ *   now, so two of them publish two pages and collide over nothing; the
+ *   duplicate-address check catches only the pair that happen to share a
+ *   shortcode, and says nothing at all about a `homepage-root` beside a
+ *   `homepage-front`. Which of the two the redirect at `/<package>/` should
+ *   name is a question nothing here can answer, and both being reachable is
+ *   not an answer to it.
  *
  * Neither has a safe default, so neither is a warning. A warning is the right
  * severity for something a build can proceed past correctly, and a build that
@@ -106,25 +137,36 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
 /**
  * The frontmatter a homepage publishes with.
  *
- * The note's own, plus the two derived values every emitted page carries: the
- * resolved `title`, and the package the build derived — no note declares one
+ * The note's own, plus the derived values every emitted page carries: the
+ * resolved `title`, the package the build derived — no note declares one
  * (`package:` is retired, #56) and the theme's breadcrumb partial reads
- * `.Params.package`.
+ * `.Params.package` — and its **address**.
+ *
+ * The address is stated as `url` for the same reason every other page states
+ * one (#181): Hugo publishes a page where its file sits unless told otherwise,
+ * and a homepage's file sits at the package's site root. `slug` is written
+ * beside it because it is the last segment of that address and Hugo's own key
+ * for one; it decides nothing while `url` is present, but a page carrying only
+ * `url` would report a slug Hugo had inferred from the filename.
  *
  * An authored `aliases` is dropped for the same reason it is on every other
- * page: Obsidian reads it as names a reader might call the note, Hugo reads it
- * as URL redirects, and passing it through would publish a redirect stub at
- * each one.
+ * page: Hugo reads it as URL redirects, so passing it through would publish a
+ * redirect stub at each one. The field is retired (#180) and refused before a
+ * build reaches here, which makes this a guard rather than a working path.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
+ * @param {string} options.base - Where the package is served, with both
+ *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
+ * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm: object, { contentPackage, title }: {
+export function homepageFrontmatter(fm: object, { contentPackage, title, base }: {
     contentPackage: string;
     title: string;
+    base: string;
 }): object;
 /**
  * Every address a homepage carries, wherever it is written.
@@ -172,54 +214,48 @@ export const HOMEPAGE_TYPE: string;
  *
  * Empty on purpose, and declared rather than omitted: a type with no vocabulary
  * and a type that is unknown are different findings, and only the second is an
- * authoring error. The whole envelope is the two top-level keys `type` and an
- * optional `title`; there is no game-system data on a page that compiles to no
- * document.
+ * authoring error. The whole envelope is the top-level keys `type` and
+ * `shortcode`, plus an optional `title` or `name`; there is no game-system data
+ * on a page that compiles to no document.
  *
  * @type {readonly import("./field-spec.mjs").FieldSpec[]}
  */
 export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
 /**
- * Where a homepage is written, relative to the package's site root.
+ * The shortcode a package landing conventionally takes.
  *
- * Hugo's section landing, because the page *is* the package's landing: the
- * package root is a section and this is its index.
+ * A **convention, not a rule.** The address only has to be unique within the
+ * package, which `(type, shortcode)` already guarantees, and nothing here knows
+ * better than an author what their landing is called. What the constant buys is
+ * one spelling shared by the diagnostic, the documentation and the six trees —
+ * so `[[homepage-root|…]]` is the same link in every package.
  *
  * @type {string}
  */
-export const HOMEPAGE_DESTINATION: string;
+export const HOMEPAGE_SHORTCODE: string;
 /**
- * The top-level fields a homepage refuses, and what each one would decide (#53).
- *
- * A note's URL derives from `name.full` and its identity from
- * `(type, shortcode)`. The homepage is the one page for which neither holds: it
- * publishes at `/<package>/`, fixed by the package id. An author fluent in the
- * conventions writes them here expecting exactly what they do everywhere else,
- * and gets none of it.
- *
- * **They were never inert, which is why ignoring them was the wrong answer.** A
- * `shortcode` puts the note in the address index and in the `dataview` link
- * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
- * `homepage/<slug>/`, an address derived from `name.full` and published by
- * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
- * package root. A build that reports a live link to a 404 is worse than one
- * that says nothing. It also inflates `content-build lint`'s address tally, so
- * the lint and the link manifest disagree about what the package publishes.
- *
- * **A named class, not an allow-list, and that boundary is the decision.** The
- * documented envelope is `type` plus an optional `title`, and `landing`,
- * `description` and `banner` are legitimate beside them — but a homepage's
- * frontmatter is *emitted into the published page*
+ * The top-level field a homepage refuses, and what it would decide (#53).
+ *
+ * **One field, where there used to be three.** `name` and `shortcode` were
+ * refused because a page's URL derived from `name.full` while a homepage's
+ * destination was fixed, so the address a `shortcode` computed named a page the
+ * site build never wrote. A page's URL is its address now (#181) and a homepage
+ * publishes at its own, so both fields decide exactly what they decide
+ * everywhere else and are permitted (#182).
+ *
+ * `id` is untouched by that, and stays: it is the Foundry document id a
+ * compendium UUID is built from, and a homepage compiles into no document.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** A
+ * homepage's frontmatter is *emitted into the published page*
  * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
  * parameter this build has never heard of and has no standing to refuse.
  * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release. What is refused is the specific class that makes a
- * false claim about *where this page is*.
+ * package-build release.
  *
- * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
- * already drops it from every emitted page, with a reason of its own, so
- * authoring one is the same no-op it is on any other page rather than a wrong
- * belief about this one's address.
+ * `aliases` is deliberately not in the class: it is a **retired** field, refused
+ * on every note whatever its type (#180), so it is answered there rather than
+ * here.
  *
  * @type {ReadonlyMap<string, string>}
  */

package/types/engine/index.d.mts

@@ -28,7 +28,6 @@ export * as documentSubtypes from "./document-subtypes.mjs";
 export * as itemDocs from "./item-docs.mjs";
 export * as wikilinks from "./wikilinks.mjs";
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
-export * as aliasIndex from "./alias-index.mjs";
 export * as siteIndex from "./site-index.mjs";
 export * as baseCompiler from "./base-compiler.mjs";
 export * as journals from "./journals.mjs";

package/types/engine/note-vocabulary.d.mts

@@ -6,6 +6,35 @@
  * @returns {readonly string[]} The tags, in declaration order.
  */
 export function declaredTags(type: string, groups?: object): readonly string[];
+/**
+ * Whether a note carries a given tag, however the author wrote it.
+ *
+ * `tags:` is authored by hand and Obsidian is permissive about it: a single tag
+ * may be a scalar rather than a list, a value may carry the leading `#` it is
+ * written with in prose, and case and surrounding space are not significant.
+ * The spelling of the tag *itself* still is — a near miss is a near miss, and
+ * the frontmatter lint is what reports it; nothing here guesses.
+ *
+ * Reads `tags` and, as Dataview does, `tag` — the singular spelling Obsidian
+ * also accepts.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} tag - The tag to look for, in its declared spelling.
+ * @returns {boolean} Whether the note carries it.
+ */
+export function hasTag(fm: object | null | undefined, tag: string): boolean;
+/**
+ * Whether a note is tagged as an unfinished **draft** (#183).
+ *
+ * The one reader of {@link DRAFT_TAG}, so both builds ask the same question of
+ * the same field. Presentation only: a draft note is in the packs, in the
+ * manifest and on the site exactly as any other, and this decides nothing but
+ * whether a link into it renders marked.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the note carries the `draft` tag.
+ */
+export function isDraftNote(fm: object | null | undefined): boolean;
 /**
  * The `data:` keys a note type may carry.
  *
@@ -66,6 +95,20 @@ export function subTypes(type: string, vocabulary?: Readonly<Record<string, Type
  * fishing village is a `village` that is `fishing`, and the single-valued field
  * this replaced had to spell it `Fishing Village` as a value of its own.
  */
+/**
+ * The declared tag that marks a note as **unfinished** (#183).
+ *
+ * Named once and referenced from the declaration below, because a second
+ * spelling is how the two come apart: rename the tag in `DECLARED_TAGS` and a
+ * private copy elsewhere keeps matching the old word, silently.
+ *
+ * It is a **presentation** fact and nothing more. A draft note compiles,
+ * validates, publishes and resolves like any other; only a link *into* it
+ * renders marked. What it emphatically is not is the retired `draft:` field,
+ * whose entire effect was to move a note from published to unresolvable — see
+ * {@link draftRetiredMessage}.
+ */
+export const DRAFT_TAG: "draft";
 export const DECLARED_TAGS: Readonly<{
     /** What a place *is*. */
     placeKind: Readonly<{

package/types/engine/retired-fields.d.mts

@@ -35,6 +35,77 @@ export function assertNoDraftField(fm: object | null | undefined, { file, absPat
     file?: string | undefined;
     absPath?: string | undefined;
 }): void;
+/**
+ * What a note declaring a top-level `aliases:` is told, in one place.
+ *
+ * Shared by the compile-time refusal and the frontmatter lint, because an
+ * author meets whichever of the two runs first and they should read the same.
+ * It says what the field fed and what to write instead, rather than which value
+ * to correct: no value makes declaring it right.
+ *
+ * **What it did (#180).** It was the authored half of the alias index — the
+ * namespace a bare `[[Alias]]` was looked up in. Across the three content trees
+ * not one bare link resolved through it, while the collision rule that kept it
+ * unambiguous folded in every note's `name.full` and so dictated what a note
+ * could be named (#179). The form is retired, so the list has no reader.
+ *
+ * **`name.aliases` is a different field and is not retired.** It fed the same
+ * index, but unlike the top-level list it is being kept — reserved, unread,
+ * and deliberately unmentioned by this message, which would otherwise tell an
+ * author to delete a field they are allowed to write. See
+ * {@link assertNoAliasesField}.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function aliasesRetiredMessage(file?: string): string;
+/**
+ * Refuse a note that declares a top-level `aliases:`.
+ *
+ * Presence is the whole test. `aliases: []` is as retired as a populated one —
+ * it reads as "this note claims no other names", a statement about a namespace
+ * that no longer exists.
+ *
+ * **The nested `name.aliases` is deliberately not refused.** Both spellings fed
+ * the retired alias index, and both lost their reader with it, but only the
+ * top-level one is retired: `name.aliases` is **reserved**, held for a use that
+ * does not exist yet. So it is neither refused nor read — no index consults it,
+ * no rule validates its contents, nothing derives from it, and nothing emits
+ * it. It rides in the note as inert data, and a note carrying one compiles,
+ * resolves and emits exactly as if it were absent.
+ *
+ * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
+ * rather than resolving a dotted key: the top-level field is the whole subject,
+ * and reaching into `name` at all is the thing being avoided.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares a top-level `aliases`.
+ */
+export function assertNoAliasesField(fm: object | null | undefined, { file, absPath }?: {
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;
+/**
+ * Whether a note declares the retired top-level `aliases:`.
+ *
+ * A nested `name.aliases` is **not** this field and never answers true here —
+ * see {@link assertNoAliasesField} for why the two part company.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the retired field is declared.
+ */
+export function declaresRetiredAliasesField(fm: object | null | undefined): boolean;
 /**
  * A frontmatter key's position in a note's file, or nothing.
  *
@@ -47,11 +118,17 @@ export function assertNoDraftField(fm: object | null | undefined, { file, absPat
  * @param {string} [value] - When given, prefer the occurrence whose line also
  *   carries this text — so a finding about one entry of a block opens on that
  *   entry rather than on the key that introduces it.
+ * @param {object} [options] - Options, forwarded to
+ *   {@link positionInFrontmatter}.
+ * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
+ *   an identically named nested key cannot answer for it.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string): {
+export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string, { topLevel }?: {
+    topLevel?: boolean | undefined;
+}): {
     line?: number;
     column?: number;
 } | undefined;