@heroiclands/package-build 22.9.2 → 22.10.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @heroiclands/package-build
 
+## 22.10.0
+
+### Minor Changes
+
+**Affiliations** — a `seat`, a `parents` list, a `domains` list and a `relations`
+map written under `data:` now reach the compiled item, so an affiliation carries
+the place its authority sits in, the bodies it answers to, the places it holds
+sway over and its standing toward other societies. Every affiliation shipped
+these empty whatever its note said, so a setting's compiled packs change without
+a word of its content changing, and anything reading those fields — a sheet, a
+chat card, a rules outcome — begins seeing them. Every other field the format
+maps out of `data:` is read from there too: a gear item's weight, worth,
+craftsmanship and durability, an affliction's and a trauma's timed phases, and a
+mystery's charges and skill aptitudes. Writing one at its destination still wins.
+
+**Addresses** — a field that points at another note names it by _address_,
+written at whatever length says what it means: a note in another package in
+full, one in this package by its shortcode alone, with the compiled document
+carrying the shortcode the game reads either way. A value naming the wrong kind
+of thing now says so, instead of compiling into a reference that resolves to
+nothing — a `seat` or a `domains` entry that is not a place, a `parents` entry or
+a `relations` key that is not an affiliation, a border's or a route's `to` that
+is not a place.
+
+**Art** — `icon`, `tokenIcon`, `bgImage` and `banner` each accept an `icon` or an
+`image` address, whichever one they default to, so a deity's profile art can be a
+full illustration rather than a game icon. Any other type, an `audio` address
+among them, is now an error naming what the slot accepts rather than a silent
+fall back to the document's default art.
+
+**Shortcodes** — `assocSkillCode`, `assocAffiliationCode` and `parentSkillCode`
+name another item by its bare shortcode, resolved among one actor's own embedded
+items, where a qualified value can never resolve. Such a value is now refused
+with that reason rather than reported as a dead reference, and no authored value
+in any tree carries one today.
+
+**The specification** names three different things where it had one word: an
+
+- Published references identify their complete package and document; authored abbreviations remain accepted and source notes stay unchanged.
+- Documentation references open their journals, and native character species text stays independent of shared species lore.
+- Content authors receive errors at malformed references and references naming an unsupported kind of note.
+- Economy references require an explicit type and accept only affiliations or lore.
+
+### Patch Changes
+
+**Places**
+
+- A border or a route naming a place in another package is written as a _full
+  address_; a bare shortcode names a place in the package being built.
+
 ## 22.9.2
 
 ### Patch Changes

package/CONTENT.md

@@ -16,6 +16,23 @@ It ships a command line as well as a library — see
 npm install -D @heroiclands/package-build
 ```
 
+## Content references
+
+Notes may abbreviate Addresses according to the defaults of their field and
+system block. Builds preserve the authored files and write full Addresses to
+generated content under `build/`. A reference under `data:` or in body prose
+uses `none` as its system; a system-bearing target at `none` names its
+documentation. A reference to an Item or Actor states its system explicitly.
+
+Published SQL records use these complete identities too. Compare Address fields
+with full Addresses, not a target's bare Shortcode. A stub's identity remains
+available from its package, type and Shortcode even though it has no page address.
+See the [content format](docs/content-format.md#addresses) for defaults, accepted
+forms and examples.
+
+Shared `data.species` names species lore. HârnMaster's native `hm3.system.species`
+is independent character-sheet text; a shared lore reference does not populate it.
+
 ## Configure
 
 A consuming repository declares one `package-build.config.yaml` at its root:
@@ -1411,6 +1428,22 @@ taken from the content-format specification. It is note-format knowledge rather
 than any system's: `data:` holds what is true of the thing, and what a system
 makes of that value is declared in that system's own half.
 
+An Address field declares `kind: "address"`; an Address list declares
+`kind: "list"` and `entryKind: "address"`. A keyed map keeps `kind: "map"`
+and declares `keyKind`: `"address"` for affiliation relations, `"shortcode"`
+for skill aptitudes. Aptitude keys also accept `subType:<skill-subtype>`.
+`ref` supplies an omitted type and `accepts` states the permitted types;
+these are independent declarations. Heterogeneous fields such as `economy`
+and bundle `contents` require an explicit type. `economy` accepts only
+`affiliation` and `lore` Addresses.
+
+The frontmatter lint checks these values and locates malformed entries without
+requiring their targets to exist. `parseAddress(value, defaults, { declared:
+true })` applies the shared grammar to a declared Address, validates every
+segment, and returns a complete tuple or a reason. This mode leaves package
+membership to resolution. The lint receives the builder's package separately
+from target lookup, including when reference resolution is disabled.
+
 **There is deliberately no third rule** requiring every note to repeat its own
 `type-shortcode` address in `aliases:`. It would serve one reader — Obsidian, so
 `[[type-shortcode]]` resolves in the editor — and no build reads it: both

package/bin/content-build.mjs

@@ -213,7 +213,9 @@ prefix.apply(log, {
  */
 function reportFailure(err) {
     const message = err instanceof Error ? err.message : String(err);
-    if (/** @type {{located?: boolean}} */ (err)?.located) console.error(message);
+    if (err?.file && err?.keyPath)
+        emitDiagnostic({ file: err.file, ...(err.position ?? {}), severity: "error", message });
+    else if (/** @type {{located?: boolean}} */ (err)?.located) console.error(message);
     else log.error(message);
 }
 

package/docs/api.md

@@ -134,6 +134,7 @@ The per-system frontmatter block: how one note feeds more than one game system t
 | `blockProperty`             | `blockProperty(fm, block, key, defaultValue)` | the value                              | reading a property a system block may override, else the shared top-level one                 |
 | `legacyKeyOf`               | `legacyKeyOf(field)`                          | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
 | `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                   | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
+| `authoredKey`               | `authoredKey(name)`                           | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
 | `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`           | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
 | `systemDataPaths`           | `systemDataPaths(data, prefix)`               | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
 | `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`     | `string[]`                             | finding authored paths a system's published schema does not declare                           |
@@ -459,6 +460,7 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 
 | Export            | Signature                       | Returns             | Use it when                                                                                                          |
 | ----------------- | ------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `RELATION_TYPE`   | `const RELATION_TYPE`           | `string`            | the type a `to` names — the default its `<type>` segment takes and the whole of its accepted set                     |
 | `BEARINGS`        | `const BEARINGS`                | `readonly string[]` | the eight compass bearings, clockwise from `N`                                                                       |
 | `ROUTE_MODES`     | `const ROUTE_MODES`             | `readonly string[]` | the modes a route is travelled by — `land`, `boat`, `ship`                                                           |
 | `TRAVEL_DAYS`     | `const TRAVEL_DAYS`             | `readonly number[]` | the days markers a route may state, each meaning "about this, under normal conditions"                               |
@@ -488,12 +490,13 @@ What lies within a place, who holds it, and what an affiliation holds — read o
 
 Whether a world's population figures agree from the region down — the polities and regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `content-build lint` runs all four as warnings.
 
-| Export                  | Signature                                | Returns             | Use it when                                                                                                  |
-| ----------------------- | ---------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `POPULATION_TOLERANCE`  | `const POPULATION_TOLERANCE`             | `number`            | how far a figure written to two significant digits may round below what it contains before that is a finding |
-| `POPULATION_RULES`      | `const POPULATION_RULES`                 | `readonly object[]` | the rules in order, each its `name` — the prefix its findings carry — and what it `describe`s                |
-| `checkPopulation`       | `checkPopulation(note, { index })`       | `object[]`          | linting a place's `population` — over-held land, an over-full region, and an oversized settlement            |
-| `checkCitedPopulations` | `checkCitedPopulations(note, { index })` | `object[]`          | linting a `doc` note's cited figures, each located at the `~figure` that states it                           |
+| Export                  | Signature                                | Returns                | Use it when                                                                                                  |
+| ----------------------- | ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `POPULATION_TOLERANCE`  | `const POPULATION_TOLERANCE`             | `number`               | how far a figure written to two significant digits may round below what it contains before that is a finding |
+| `POPULATION_RULES`      | `const POPULATION_RULES`                 | `readonly object[]`    | the rules in order, each its `name` — the prefix its findings carry — and what it `describe`s                |
+| `checkPopulation`       | `checkPopulation(note, { index })`       | `object[]`             | linting a place's `population` — over-held land, an over-full region, and an oversized settlement            |
+| `checkCitedPopulations` | `checkCitedPopulations(note, { index })` | `object[]`             | linting a `doc` note's cited figures, each located at the `~figure` that states it                           |
+| `foreignNode`           | `foreignNode(canonical, entry)`          | `PopulationNode\|null` | reading a fetched index entry into a node, or `null` for one that names neither a place nor an affiliation   |
 
 ### `engine.marketClass`
 
@@ -1087,6 +1090,7 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | -------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | `WIKILINK`                 | `const WIKILINK`                                           | —                                                               | A wikilink, as authored.                                                        |
 | `parseWikilink`            | `function parseWikilink(rawInner)`                         | {ParsedWikilink} The parts, each trimmed.                       | Split a wikilink's interior into its parts.                                     |
+| `readWikilink`             | `function readWikilink(inner, context)`                    | Typed target or literal target with diagnostic source.          | Parse a link target using complete builder Address context.                     |
 | `authoredLabel`            | `authoredLabel({ display })`                               | {string\|null} The label, or `null` when there is none to show. | The label an author actually supplied, or `null` when they supplied none.       |
 | `unlabelledLinkMessage`    | `function unlabelledLinkMessage(target)`                   | {string} The message, unpunctuated at the end as a finding is.  | What an author writing an unlabelled link is told, in one place.                |
 | `LINK_FINDING_REASONS`     | `const LINK_FINDING_REASONS`                               | —                                                               | Every way a link can fail, named once for all three resolvers.                  |