@heroiclands/package-build 23.1.0 → 23.2.0

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

@@ -1,354 +0,0 @@
-/**
- * What a note declaring `draft:` is told, in one place.
- *
- * Written once and 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 did and what to write instead, rather than
- * which value to correct: no value makes declaring it right.
- *
- * @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 draftRetiredMessage(file?: string): string;
-/**
- * Refuse a note that declares `draft:` at all.
- *
- * Presence is the whole test. `draft: false` is as retired as `draft: true` —
- * it reads as "publish this note", which is what happens either way, and is
- * exactly the belief the message exists to correct.
- *
- * @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 the field.
- */
-export function assertNoDraftField(fm: object | null | undefined, { file, absPath }?: {
-    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.** 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. The form is retired, so the list has no reader.
- *
- * **`name.aliases` is a different field.** It lists alternate names in the
- * infobox and is deliberately unmentioned by this message. 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.** It is the note's
- * ordered alternate names and appears in the note infobox. It does not create
- * addresses or change how authored links resolve.
- *
- * 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;
-/**
- * What a note declaring `section:` 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 names what lands a section now rather than a value to correct: no value
- * makes declaring the field right.
- *
- * **What it did.** It named the section a `collection` note headed,
- * under the `collection` landing rule — the only reader it ever had, in the
- * second branch of `landingOf` (`engine/content-address.mjs`). That rule went
- * first, and the whole mechanism went with it: a section is a Hugo
- * directory the note format does not carry, so no note lands one and a page
- * that introduces a type is an ordinary note addressed `doc-<type>`. Nothing
- * else read the field, and no schema or vocabulary declared it, so left in
- * place it would be ignored in silence — the note saying one thing and the
- * build doing another.
- *
- * @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 sectionRetiredMessage(file?: string): string;
-/**
- * Refuse a note that declares `section:` at all.
- *
- * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
- * value reads as "this note heads a section and names none", a statement about
- * a rule that no longer exists.
- *
- * @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 the field.
- */
-export function assertNoSectionField(fm: object | null | undefined, { file, absPath }?: {
-    file?: string | undefined;
-    absPath?: string | undefined;
-}): void;
-/**
- * What a note writing a top-level `traits:` block is told.
- *
- * The message states the **mapping**, not just the destination, because three
- * of the keys reshaped as well as moved: the block nested its measurements
- * where the format flattens them. A bare "write `data:` instead" would send an
- * author to author `data.height: {m: 1.78}`, which is a declared key holding an
- * undeclared shape.
- *
- * @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 traitsRetiredMessage(file?: string): string;
-/**
- * Refuse a note that declares a top-level `traits:` block at all.
- *
- * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
- * `traits:` is still a note claiming a block that no longer exists.
- *
- * @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.
- * @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 the block.
- */
-export function assertNoTraitsField(fm: object | null | undefined, { file, absPath }?: {
-    file?: string | undefined;
-    absPath?: string | undefined;
-}): void;
-/**
- * A frontmatter key's position in a note's file, or nothing.
- *
- * {@link positionInFrontmatter} answers the same question from the file's
- * *text*; this reads the file to ask it. Kept apart from either caller because
- * both refusals need it and a second copy is a second thing to keep correct.
- *
- * @param {string|undefined} absPath - The note's file.
- * @param {string} key - The frontmatter key.
- * @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, { topLevel }?: {
-    topLevel?: boolean | undefined;
-}): {
-    line?: number;
-    column?: number;
-} | undefined;
-/**
- * What a note writing a renamed field is told, in one place.
- *
- * Shared by the compile-time report and the frontmatter lint, because an author
- * meets whichever runs first and they should read the same. It names the key to
- * write rather than a value to correct — no value makes the retired spelling
- * right — and it says the note compiles either way, so a reader knows this is a
- * rename to schedule rather than a build to unbreak.
- *
- * @param {string} retired - The spelling the note used.
- * @param {string} current - What to write instead.
- * @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 retiredAliasMessage(retired: string, current: string, file?: string): string;
-/**
- * What a note writing a field at its **legacy in-block position** is told.
- *
- * The same three-step retirement `retiredAliasMessage` announces, applied to a
- * *position* rather than a spelling. A field whose shared source moved
- * under `data:` keeps reading the key its block still carries, that read wins,
- * and it is reported here so a sweep has something to count down — without it,
- * moving a field into `data:` would be a flag day across every repository that
- * authors it.
- *
- * It names the block, because the key is `hm3.species` and not `species`: an
- * author told to move "`species`" has two regions to guess between.
- *
- * @param {string} block - The system block the key was written in.
- * @param {{name?: string, legacyKey?: string}} field - The declaration, which
- *   names both positions.
- * @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 legacyKeyMessage(block: string, field: {
-    name?: string;
-    legacyKey?: string;
-}, file?: string): string;
-/**
- * What a note writing a field at the **top-level key `data:` gathered it off**
- * is told.
- *
- * {@link legacyKeyMessage}'s counterpart for the other retiring position.
- * `portrait:` beside `img:` is the bare spelling of `data.portrait`, and both
- * are read for the same reason both in-block spellings are: a package moves its
- * corpus when it is ready, not on a flag day.
- *
- * It says nothing about which value is emitted, because that is not what an
- * author needs from it. The value is the same either way; what the finding
- * counts is one more note still on the old position.
- *
- * @param {{name?: string}} field - The declaration, which names the current
- *   position; the retiring one is derived from it.
- * @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 retiredTopLevelMessage(field: {
-    name?: string;
-}, file?: string): string;
-/**
- * Whether a note writes the retired spelling of a field, wherever it put it.
- *
- * Both regions are searched, because {@link sohlField} reads both: a note that
- * moved the key to the top level without renaming it has done half the
- * migration, and should be told so rather than passing in silence.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @param {string} current - The field's current name.
- * @param {object} [options] - Options.
- * @param {boolean} [options.inData=false] - Search the `data:` container
- *   instead. A `data:` field has exactly one home, so its retired spelling has
- *   exactly one too, and searching the block or the top level for it would
- *   answer about a key the container check has already refused.
- * @returns {boolean} Whether the retired spelling is declared.
- */
-export function declaresRetiredAlias(fm: object | null | undefined, current: string, { inData }?: {
-    inData?: boolean | undefined;
-}): boolean;
-/**
- * Read a field that has a retired spelling, the current name winning.
- *
- * This is the whole of the retirement window's behaviour, in one function, so
- * the compiler and the linter cannot disagree about which value a note carries.
- * Resolution within each spelling is {@link sohlField}'s — the `sohl:` block
- * first, then the note's top level — so a renamed field keeps working wherever
- * it was already written while the canonical home is the top level.
- *
- * A blank value counts as absent: `relations:` cleared in an editor means the
- * note records no standings there, and falling through to the retired spelling
- * is what an author part-way through the rename means by it.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @param {string} current - The field's current name.
- * @param {object} [options] - Options.
- * @param {boolean} [options.inData=false] - Read the `data:` container instead,
- *   which is where a `data:` field and its retired spelling are both written.
- *   Dotted names resolve inside it, so `appearance.eye_color` reads the way it
- *   is authored.
- * @returns {any} The value, or `undefined` when neither spelling carries one.
- */
-export function readAliasedField(fm: object | null | undefined, current: string, { inData }?: {
-    inData?: boolean | undefined;
-}): any;
-/**
- * The current field name a retired spelling was renamed to.
- *
- * Keyed by the **current** name, because that is what a type's schema declares
- * and what every reader asks for; the value is the spelling still honoured.
- * The table is therefore scoped by the schema without saying so twice: an alias
- * applies to a note only where that note's type declares the current field, so
- * `relation` is retired on an affiliation — which declares `relations` — and
- * remains an unknown key anywhere else.
- *
- * **`templatePriority`.** The number that decides which of several
- * competing templates the Create dialog offers was called `archetype`, and
- * `archetypes` — one letter apart — is a list of what *sort* a character is.
- * A priority and a taxonomy cannot be told apart by a plural `s`, so the
- * priority takes the name that says what it is. The specification already
- * called it `templatePriority` on two of its three sides.
- *
- * **`relations`.** The field holds a *map* of standings, one per
- * affiliation — its own description says so, and `resolveRelation` has always
- * read it that way. `relation` named the many as one, which every author had to
- * read past. Only `affiliation` declares the field, so the alias is reported
- * there and the old spelling stays an ordinary unknown key everywhere else.
- *
- * **`born`.** A birthday is a day that recurs; what a note records is the date
- * somebody was born, once. The two read alike while every value belonged to a
- * living person, and `born` is what the field has to be called beside `died`,
- * which a being now also states. It is the first alias whose field lives in
- * `data:` rather than in a system block, so the two readers below take
- * `inData`.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const RETIRED_FIELD_ALIASES: Readonly<Record<string, string>>;