@heroiclands/package-build 22.12.2 → 22.13.0

package/types/engine/address.d.mts

@@ -1,14 +1,9 @@
 /**
- * A complete Address: four segments, and nothing else.
- *
- * `type` is the segment the canonical string carries, after the `doc<type>`
- * redirect. There is no fifth field recording the written form, because the
- * written form is a rendering rather than part of the value.
+ * A complete Address: four segments, with no memory of the authored form.
  *
  * @typedef {object} AddressTuple
  * @property {string} package - The owning **content** package.
- * @property {string} system - The system whose document this addresses, or
- *   `none`.
+ * @property {string} system - `note`, `none`, or a game system id.
  * @property {string} type - The type segment of the canonical Address.
  * @property {string} shortcode - The note's `shortcode`.
  */
@@ -33,29 +28,8 @@
  * @typedef {{reason: string, package?: string}} AddressProblem
  */
 /**
- * Every content type whose **prose compiles into a JournalEntry of its own**,
- * addressed by the virtual `doc<type>` qualifier.
- *
- * Every item type, every actor type, every map type, plus `macro` — a macro
- * note's body documents the script the note also compiles into a Macro, which
- * is the same shape as an item and its description: one note, two documents,
- * the prose living in the journals pack.
- *
- * **One set, read by the compilers and by the grammar alike.** The journals
- * pass decides what to compile from it, the link manifest decides what to
- * publish a `doc<type>` entry for, and the parser decides whether `doc<type>`
- * is a legal type segment. Held apart, the three drift into a manifest that
- * asserts documentation nothing compiled, a compiled entry no consumer can
- * address, or an authored `doc<type>` link that stops parsing. It is composed
- * exactly once, in `defineConfig`, and read from there — never recomposed at a
- * call site.
- *
- * `doc` notes are absent, for the reason that applies to them alone: a `doc`
- * note's single document *is* its prose, so there is no second document for a
- * `doc<type>` address to name.
- *
- * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration.
+ * The configured types whose prose compiles into a separate JournalEntry.
+ * The journal has a `note` Address with the authored type segment.
  *
  * @returns {ReadonlySet<string>} The configured doc-carrying types.
  */
@@ -69,30 +43,15 @@ export function docEntryTypes(): ReadonlySet<string>;
  *   `macro`; false for `doc`.
  */
 export function hasDocEntry(type: string): boolean;
+/** The segment of a note's own document. */
+export function ownDocumentSystem(type: any): string;
 /**
- * Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is
- * not one.
- *
- * A document and its documentation are two documents in two packs, so they need
- * two addresses. `skill-wpnc` is the item; `docskill-wpnc` is the JournalEntry
- * its prose compiled into, and `docmacro-autoattack` is the same arrangement
- * for a macro.
- *
- * The virtual form exists for a type that carries separate documentation
- * ({@link docEntryTypes} — the set the journals compiler and the link manifest
- * read too), **or** for one that routes to the items pack. The second clause
- * covers the open, unenumerated set: types that compile into items are not
- * enumerated anywhere, and a foreign package may publish an item type this
- * build has never heard of. Dropping it would silently unlink every `doc<type>`
- * address into such a package.
- *
- * A **real** type of the same name always wins: the virtual reading is only
- * consulted for a qualifier no authored note claims.
- *
- * @param {string} qualifier - The already-normalised type segment.
- * @param {Set<string>} types - Every type the content tree contains.
- * @returns {string|null} The underlying document type, or `null` when the
- *   qualifier is not a virtual one.
+ * Read a `doc<type>` input qualifier as the underlying authored type.
+ * A real type with that spelling takes precedence.
+ *
+ * @param {string} qualifier - The type segment from the input.
+ * @param {Set<string>} types - Types in the content tree.
+ * @returns {string|null} The underlying type, or `null`.
  */
 export function resolveItemDocType(qualifier: string, types: Set<string>): string | null;
 /**
@@ -164,29 +123,17 @@ export function isAddressTuple(value: unknown): boolean;
  */
 export function renderAddress(tuple: AddressTuple): string;
 /**
- * Whether the type an Address names is one this position accepts.
+ * Whether the canonical type an Address names is accepted at this position.
  *
- * The second of the two questions, and separate from the first because the
- * accepted **set** is a property of the position while the grammar is not.
- *
- * **An accepted type carries its documentation form with it.** A position
- * accepting `weapongear` accepts `docweapongear`, because the journal that
- * documents a weapon is the same thing to a position that wanted a weapon — and
- * a prose address of one *is* the journal, so refusing it would refuse the form
- * an author most often writes. It is the widening `defineConfig` applies to the
- * types a package may claim, applied here to the types a position may take.
- *
- * @param {AddressTuple} tuple - A parsed Address.
- * @param {Iterable<string>} allowed - The types this position accepts.
- * @returns {boolean} True when the Address names one of them.
+ * @param {AddressTuple} tuple - A complete Address.
+ * @param {Iterable<string>} allowed - Accepted types.
+ * @returns {boolean} Whether the type is accepted.
  */
 export function acceptsType(tuple: AddressTuple, allowed: Iterable<string>): boolean;
 /**
  * Apply the defaults to a partial reading, giving a complete Address.
  *
- * The three rules of the module note, applied in the order they depend on each
- * other: the package, then the system the type may fix, then the redirect the
- * system may force.
+ * Complete a parsed Address using the citing position's package and system.
  *
  * @param {{type: string, shortcode: string, package?: string, system?: string,
  *   itemDoc?: boolean}} read - A partial reading, as {@link readQualifier}
@@ -351,23 +298,10 @@ export const ADDRESS_SEPARATOR: string;
  * @type {number}
  */
 export const CANONICAL_KEY_SEGMENTS: number;
+/** The accepted `doc<type>` input prefix for readable note links. */
+export const ITEM_DOC_PREFIX: "doc";
 /**
- * The qualifier prefix that addresses a note's **documentation** rather than
- * the note's own document: `docskill-wpnc` is the JournalEntry that
- * `skill-wpnc`'s prose compiled into.
- *
- * Every doc-carrying type has a `doc<type>` counterpart, formed by prefix and
- * never enumerated, so the prefix itself is the whole of that vocabulary.
- *
- * @type {string}
- */
-export const ITEM_DOC_PREFIX: string;
-/**
- * A complete Address: four segments, and nothing else.
- *
- * `type` is the segment the canonical string carries, after the `doc<type>`
- * redirect. There is no fifth field recording the written form, because the
- * written form is a rendering rather than part of the value.
+ * A complete Address: four segments, with no memory of the authored form.
  */
 export type AddressTuple = {
     /**
@@ -375,8 +309,7 @@ export type AddressTuple = {
      */
     package: string;
     /**
-     * - The system whose document this addresses, or
-     * `none`.
+     * - `note`, `none`, or a game system id.
      */
     system: string;
     /**

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

@@ -69,12 +69,9 @@ export function packageAddress(fm: object): string;
  *
  * The **enclosing system block** decides, at any depth within it, and nothing
  * else does: `sohl.items[3].model` and `sohl.system.body.structure` are both
- * `sohl` because both sit under `sohl:`. Everywhere else is {@link NO_SYSTEM} —
- * top-level frontmatter, the shared `data:` container, and body prose, which has
- * no key path at all and passes `undefined`.
- *
- * It is the block rather than the field, so an `Address` field needs no opinion
- * about systems and no per-field table has to be kept in step with the schema.
+ * `sohl` because both sit under `sohl:`. Everywhere else takes
+ * {@link NOTE_SYSTEM}; fields declared for assets or folders supply their own
+ * `none` default at the field parser.
  *
  * The first segment must **be** a declared system, not merely look like one:
  * `sohlish.items` is a key called `sohlish`, and `notes.sohl.thing` names no

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

@@ -39,12 +39,8 @@ export function anchorsOf(body: string): Set<string>;
  * before, since the walk read the file and it then read it again for the raw
  * text.
  *
- * The index mirrors what both builds construct, including the two addresses a
- * doc-carrying note answers to: `type/shortcode` for the document, and
- * `doc<type>/shortcode` for the JournalEntry its prose compiles into. Once a
- * manifest publishes `doc<type>` entries that prefix is a *known type*, and the
- * virtual reading that used to answer for it no longer fires — a real type owns
- * its own name — so the note is indexed under both.
+ * The index holds each compiled document under its complete Address. Readable
+ * content uses `note`, and system documents use their declared system.
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]

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

@@ -30,6 +30,7 @@ export const STRUCTURED_ADDRESSES: readonly ({
     shape: string;
     type: string;
     accepts: string[];
+    system: string;
     noteType?: undefined;
 } | {
     noteType: string;
@@ -37,5 +38,6 @@ export const STRUCTURED_ADDRESSES: readonly ({
     shape: string;
     type: string;
     accepts: string[];
+    system?: undefined;
 })[];
 export { AddressEntries, encodeAddresses, cloneAddressState } from "./address-values.mjs";

package/types/engine/systems.d.mts

@@ -80,6 +80,8 @@ export function assertSystemCharset(segments: Iterable<string>, where?: string):
  * @type {string}
  */
 export const NO_SYSTEM: string;
+/** The Address segment for a note's readable content. */
+export const NOTE_SYSTEM: "note";
 /**
  * Every game system this toolchain compiles for.
  *