@heroiclands/package-build 22.9.2 → 22.11.0

package/types/engine/wikilinks.d.mts

@@ -1,108 +1,3 @@
-/**
- * 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 sohl.utils.packs.docEntryTypes} — the set the journals compiler and
- * the link manifest read too), **or** for one that routes to the items pack.
- * The second clause is the older rule and stays: types that compile into items
- * are the open, unenumerated set, 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 text before the `/`.
- * @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.
- */
-export function resolveItemDocType(qualifier: string, types: Set<string>): string | null;
-/**
- * Read a link target as a **qualified** `type-shortcode` reference, or report
- * that it does not parse as one.
- *
- * Two separators are accepted, and they are **not** interchangeable in how
- * confidently they mark a target as qualified:
- *
- * - **`type-shortcode`** and its qualified forms — the canonical spelling.
- * Obsidian reads `/` inside a wikilink as a *path* and resolves it
- *   against the vault's folders, so a slash-qualified link is a broken link in
- *   the editor where the content is now authored.
- * - **`type/shortcode`** — the legacy form, still resolved so that a link
- *   written before the vault migrated does not silently die. A slash is
- *   *unconditionally* a qualifier: nothing else uses one, so an unknown type
- *   before it is reported rather than guessed at. The split is at the **last**
- *   slash, as it always was.
- *
- * **The grammar is strict, and omission runs left to right**:
- *
- * ```text
- * [[[[<package>-]<system>-]<type>-]<shortcode>]
- * ```
- *
- * So the written forms are exactly the suffixes of the canonical address —
- * `type-shortcode`, `system-type-shortcode`, `package-system-type-shortcode` —
- * and **`package-type-shortcode` is not one of them**. A link into another
- * package must therefore be fully qualified, which is the price of the segment
- * being positional rather than tagged.
- *
- * **Parsing is plain positional counting**, the same rule
- * {@link readCanonicalKey} follows, and it is sound for the same reason: every
- * segment matches `ADDRESS_SEGMENT_PATTERN` (enforced on shortcodes by
- * `content-lint.mjs`), so the hyphen is purely a
- * separator and the count alone determines every field. Verified across the
- * four content trees: 138,204 authored shortcodes, none carrying a separator.
- *
- * That replaced a first-hyphen split which let a shortcode contain a hyphen
- * (`trauma-self-pro` → `trauma` + `self-pro`). The tolerance predates the
- * charset rule and
- * outlived it; no tree has used it, and keeping it would make a three-segment
- * target ambiguous between a system and a hyphenated shortcode.
- *
- * **`sohl` is both a package and a system**, and positional counting is what
- * makes that harmless: three segments is `<system>-<type>-<shortcode>` whatever
- * the first segment could also have named, and four is the full form. Nothing
- * has to guess which sense was meant.
- *
- * **A partial address states what it states, and the rest is not invented.** An
- * omitted **system** is a *wildcard* — most links target items, which belong to
- * a system — so the caller matches on the segments supplied and requires
- * exactly one hit. An omitted **package** is instead *defaulted* to the citing
- * note's own, so an unqualified link resolves locally and only locally.
- *
- * @param {string} target - The link target, anchor already removed.
- * @param {Set<string>} types - Every type the content tree contains.
- * @param {Set<string>} [packages] - Every package an address may name. Omitted
- *   by callers that resolve within one package, where the form cannot occur.
- * @param {Set<string>} [noIndexPackages] - Packages declared `contentIndex:
- *   false` — a Foundry dependency only, with no fetched index. A fully
- *   qualified target naming one is refused with `no-content-index` before its
- *   type is even considered, since there is no index to resolve it against.
- * @returns {{type: string, shortcode: string, itemDoc: boolean,
- *   package?: string, system?: string, reason?: undefined}
- *   | {reason: "unknown-type"|"no-content-index", package?: string} | null}
- *   The resolved qualifier; a `reason` when the target is definitely qualified
- *   but names no known type or no fetched index; or `null` when it is not an
- *   address at all.
- */
-export function readQualifier(target: string, types: Set<string>, packages?: Set<string>, noIndexPackages?: Set<string>): {
-    type: string;
-    shortcode: string;
-    itemDoc: boolean;
-    package?: string;
-    system?: string;
-    reason?: undefined;
-} | {
-    reason: "unknown-type" | "no-content-index";
-    package?: string;
-} | null;
 /**
  * The deterministic JournalEntryPage id for one anchor: SHA-256 of
  * `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric
@@ -157,7 +52,7 @@ export function buildWikilinkIndex(docs: Array<{
     docPack?: string;
     none?: boolean;
     draft?: boolean;
-}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages }?: {
+}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages, referenceTargets, foreignReferences }?: {
     assets?: Map<string, object> | undefined;
     noIndexPackages?: Set<string> | undefined;
 }): {
@@ -232,16 +127,18 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
  * @param {object} index - From {@link buildWikilinkIndex}.
  * @param {unknown} ref - The reference, as authored.
  * @param {object} [hint] - `{type}`, where the caller knows what it expects.
- * @returns {{name?: string, uuid?: string, address?: string, subType?: string}|undefined}
+ * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string}|undefined}
  *   The target, or `undefined` where nothing answers.
  */
 export function resolveReference(index: object, ref: unknown, hint?: object): {
     name?: string;
     uuid?: string;
-    address?: string;
+    address?: import("./address.mjs").AddressTuple;
     subType?: string;
 } | undefined;
 import { ITEM_PACK } from "./ids.mjs";
 import { PACK_BY_TYPE } from "./ids.mjs";
 import { packForType } from "./ids.mjs";
-export { ITEM_PACK, PACK_BY_TYPE, packForType };
+import { readQualifier } from "./address.mjs";
+import { resolveItemDocType } from "./address.mjs";
+export { ITEM_PACK, PACK_BY_TYPE, packForType, readQualifier, resolveItemDocType };

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

@@ -7,6 +7,11 @@
  * 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.
  *
+ * Each field names both of its authored positions, as
+ * {@link module:hm3/actors} does and for the same reason: `name` is the shared
+ * source the content format's mapping tables state, and `legacyKey` is the key
+ * the `hm3:` block still carries.
+ *
  * @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/sohl/infobox.d.mts

@@ -2,11 +2,10 @@
  * What one entry of `sohl.items` names.
  *
  * An entry addresses its item three ways and every tree uses all three: a
- * `model` address whose last two hyphen-separated segments are always
- * `<type>-<shortcode>`, explicit `type` / `shortcode` keys, or a locally
- * authored item stating its type with the shortcode inside its own `system`
- * block. One decode covers all of them, so nothing downstream has to know
- * which form a note happened to use.
+ * `model` address, explicit `type` / `shortcode` keys, or a locally authored
+ * item stating its type with the shortcode inside its own `system` block. One
+ * decode covers all of them, so nothing downstream has to know which form a
+ * note happened to use.
  *
  * @param {object} entry - One `sohl.items` entry.
  * @returns {{type: string, shortcode: string, name: string, system: object}|undefined}
@@ -83,6 +82,8 @@ export function projectileSections(fm: object, ctx: object): object[];
  * @returns {[string, object][]} Mode name → the mode.
  */
 export function strikeModes(declared: unknown): [string, object][];
+/** An affiliation presents skill documentation while retaining native Item identity. */
+export function affiliationSections(fm: any, ctx: any): object[];
 /** What this system's box is called. @type {string} */
 export const SOHL_INFOBOX_TITLE: string;
 /**

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

@@ -2,6 +2,14 @@
  * Every item type's frontmatter vocabulary, in the order the `system` block
  * emits it.
  *
+ * **A field whose shared source is a path into `data:` names both positions.**
+ * `name` is the source the content format's mapping tables state — `data.seat`,
+ * `data.weight` — and `legacyKey` is the key the system block still carries, which
+ * wins while a tree writes it. Naming only the source would move the in-block
+ * read to a key spelled `data.seat`, which nothing authors; naming only the key
+ * leaves the container the specification points at unread, and the field then
+ * compiles its default over an authored value with nothing said.
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const ITEM_FIELDS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;