@heroiclands/package-build 22.12.2 → 22.13.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @heroiclands/package-build
 
+## 22.13.0
+
+### Minor Changes
+
+**Content links**
+
+- Ordinary wikilinks open readable notes by default; image embeds and art fields resolve systemless assets.
+- Readable notes use `note` addresses, while explicit game systems select Actors and Items and `none` selects systemless targets.
+
+**Editor navigation**
+
+- Install `@heroiclands/content-language-server` for content note search and navigation in an editor.
+
+## 22.12.3
+
+### Patch Changes
+
+- Content authors can find notes by name, alias, tag, shortcode, or Address and follow references from an LSP-capable editor.
+- Editor reference search works without ripgrep installed.
+
 ## 22.12.2
 
 ### Patch Changes

package/README.md

@@ -14,6 +14,9 @@ The content half is documented separately in **[CONTENT.md](CONTENT.md)** — th
 note format, the pack pipeline, and the configuration contract a content tree
 declares itself with.
 
+Editor navigation for content projects is provided by
+[`@heroiclands/content-language-server`](https://github.com/HeroicLands/content-language-server).
+
 ## Install
 
 ```

package/docs/api.md

@@ -596,16 +596,17 @@ The map from each place, drawn for the site: `content-build site` draws the map
 
 The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.
 
-| Export                 | Signature                              | Returns                         | Use it when                                                                                  |
-| ---------------------- | -------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- |
-| `NO_SYSTEM`            | `const NO_SYSTEM`                      | —                               | naming the `<system>` segment of a note that belongs to no game system                       |
-| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating every game system this toolchain compiles for                                    |
-| `SYSTEM_SEGMENTS`      | `const SYSTEM_SEGMENTS`                | —                               | enumerating everything the `<system>` address segment may say — the systems plus `NO_SYSTEM` |
-| `isSystemId`           | `isSystemId(value)`                    | `boolean`                       | checking whether a value names a game system this toolchain knows (`none` is rejected)       |
-| `isSystemSegment`      | `isSystemSegment(value)`               | `boolean`                       | checking whether a value is something the `<system>` address segment may hold                |
-| `unknownSystemMessage` | `unknownSystemMessage(value, where)`   | `string`                        | building the message for a caller that wrote an unknown system                               |
-| `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                      |
-| `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment                     |
+| Export                 | Signature                              | Returns                         | Use it when                                                                            |
+| ---------------------- | -------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| `NO_SYSTEM`            | `const NO_SYSTEM`                      | —                               | naming a systemless asset or Foundry document                                          |
+| `NOTE_SYSTEM`          | `const NOTE_SYSTEM`                    | —                               | naming readable note content across web, book and Foundry                              |
+| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating every game system this toolchain compiles for                              |
+| `SYSTEM_SEGMENTS`      | `const SYSTEM_SEGMENTS`                | —                               | enumerating the game systems, `note` and `none`                                        |
+| `isSystemId`           | `isSystemId(value)`                    | `boolean`                       | checking whether a value names a game system this toolchain knows (`none` is rejected) |
+| `isSystemSegment`      | `isSystemSegment(value)`               | `boolean`                       | checking whether a value is something the `<system>` address segment may hold          |
+| `unknownSystemMessage` | `unknownSystemMessage(value, where)`   | `string`                        | building the message for a caller that wrote an unknown system                         |
+| `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                |
+| `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment               |
 
 ### `engine.calendars`
 
@@ -675,7 +676,7 @@ Where a content note publishes on the web. One rule, in one place, because two b
 | `addressSlug`            | `function addressSlug(fm)`                            | {string} The address segment, e.g.                                                                                                                                                                      | The single path segment a note is addressed by: `type-shortcode`.                                     |
 | `packageAddress`         | `function packageAddress(fm)`                         | {string} The package-relative address, with a trailing slash and no leading one.                                                                                                                        | A note's address: `<type>-<shortcode>/`, e.g.                                                         |
 | `canonicalKey`           | `function canonicalKey(pkg, system, type, shortcode)` | {string} `package-system-type-shortcode`, lowercased.                                                                                                                                                   | The **canonical** address of a note: fully qualified, one spelling per document, and globally unique. |
-| `blockSystem`            | `function blockSystem(keyPath)`                       | {string} The system id, or `none`.                                                                                                                                                                      | Which system a frontmatter key path is written under.                                                 |
+| `blockSystem`            | `function blockSystem(keyPath)`                       | {string} The game system id, or `note`.                                                                                                                                                                 | Which system a frontmatter key path is written under.                                                 |
 | `expandAddress`          | `function expandAddress(read, where)`                 | {string} The canonical `package-system-type-shortcode`.                                                                                                                                                 | Expand a written address to the one canonical address it names.                                       |
 | `CANONICAL_KEY_SEGMENTS` | `const CANONICAL_KEY_SEGMENTS`                        | —                                                                                                                                                                                                       | How many segments a canonical key has, and therefore how many the reader below counts.                |
 | `readCanonicalKey`       | `function readCanonicalKey(key)`                      | {{package: string, system: string, type: string, shortcode: string} \|null\|undefined} The parts; `null` when there is a string that is not in canonical form; `undefined` when there is no key at all. | Reads a canonical key back into its parts.                                                            |
@@ -1062,12 +1063,12 @@ Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLa
 
 **Item docs** — an item's prose compiled as a JournalEntry, with the item keeping only a pointer to it. An item note's body describes what the thing _is_. That is documentation, and documentation belongs in the journals pack, so each item note compiles into a JournalEntry and the item's `system.docHtml` becomes nothing but a `@UUID` link to that entry's first page — the description-as-pointer convention, which {@link sohl.utils.descriptionLinkTarget} recognises and Display Description follows.
 
-| Export           | Signature                                                       | Returns                                                                                          | Use it when                                                                                                                 |
-| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| `docEntryTypes`  | `function docEntryTypes()`                                      | {ReadonlySet<string>} The configured doc-carrying types.                                         | Every content type whose **prose compiles into a JournalEntry of its own**, addressed by the virtual `doc<type>` qualifier. |
-| `hasDocEntry`    | `function hasDocEntry(type)`                                    | {boolean} True for an item type, for `macro` and for a map type; false for `doc` and for actors. | Whether a content note's type is one whose prose becomes a JournalEntry of its own.                                         |
-| `itemDocEntryId` | `function itemDocEntryId(itemId)`                               | {string} A 16-character Foundry id.                                                              | The id of the JournalEntry a note's prose compiles into — an item's, or a macro's.                                          |
-| `itemDocPointer` | `function itemDocPointer(packageId, itemId, name, firstPageId)` | {string} The pointer to store in `system.docHtml`.                                               | The description an item carries in place of its prose: a `@UUID` link to the first page of its item doc, and nothing else.  |
+| Export           | Signature                                                       | Returns                                                                                          | Use it when                                                                                                                |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `docEntryTypes`  | `function docEntryTypes()`                                      | {ReadonlySet<string>} The configured doc-carrying types.                                         | Every content type whose **prose compiles into a JournalEntry of its own**, addressed by `note` with the authored type.    |
+| `hasDocEntry`    | `function hasDocEntry(type)`                                    | {boolean} True for an item type, for `macro` and for a map type; false for `doc` and for actors. | Whether a content note's type is one whose prose becomes a JournalEntry of its own.                                        |
+| `itemDocEntryId` | `function itemDocEntryId(itemId)`                               | {string} A 16-character Foundry id.                                                              | The id of the JournalEntry a note's prose compiles into — an item's, or a macro's.                                         |
+| `itemDocPointer` | `function itemDocPointer(packageId, itemId, name, firstPageId)` | {string} The pointer to store in `system.docHtml`.                                               | The description an item carries in place of its prose: a `@UUID` link to the first page of its item doc, and nothing else. |
 
 - `itemTypes` — re-exported: Every content type that compiles into an item — and therefore into an item doc.
 
@@ -1077,7 +1078,7 @@ Wikilink resolution for the pack compilers. Content notes link to one another wi
 
 | Export               | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                                                    | Use it when                                                                                                                                                                |
 | -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is not one.                                                                                      |
+| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads an accepted `doc<type>` input alias as its authored type.                                                                                                            |
 | `readQualifier`      | `function readQualifier(target, types, packages, noIndexPackages)`      | {{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. | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
 | `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                                                   | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
 | `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                     | Builds the link-resolution tables for a content tree.                                                                                                                      |

package/docs/commands.md

@@ -1,6 +1,6 @@
 # Command reference
 
-`@heroiclands/package-build` ships two binaries. `package-build` is the
+`@heroiclands/package-build` ships two build binaries. `package-build` is the
 packaging half — clean, stage, check, package, deploy, run a Foundry
 container, drive the end-to-end suite. `content-build` is the content half —
 compile a note tree into compendium packs, check it, publish it as a site or a
@@ -21,7 +21,7 @@ says so under **OPTIONS** rather than omitting the section.
 
 **Every finding is `file:line:column: severity: message`**, the path starting
 the line — the diagnostic contract this package's own build tooling emits and
-that both binaries' content-side commands use for anything found in a
+that both build binaries' content-side commands use for anything found in a
 specific file. A field that cannot be known is dropped rather than guessed:
 `file:line:` when the column means nothing, `file:` when only the file is
 known. See [Diagnostics](diagnostics.md) for the full contract.

package/docs/content-format.md

@@ -96,7 +96,7 @@ column regardless.
 
 **Embedded models link to documentation in an infobox.** The model Address
 continues to identify the native Item used for compilation. Its displayed link
-uses that same package, type and Shortcode under `none`, which names the
+uses that same package, type and Shortcode under `note`, which names the
 corresponding documentation journal. A model with no published documentation
 keeps its known name as plain text; the infobox does not substitute an Actor or
 Item link.
@@ -1268,85 +1268,78 @@ below.
 <package>-<system>-<note_type>-<shortcode>
 ```
 
-Read it from the right: the last segment is always the shortcode, the one before
-it always the note type, the one before that always the system, and the first the
-package. Nothing is positional-by-guess — a segment means what its position says
-it means.
+The final segment is the shortcode, preceded by the note type, the system and
+the package. Each segment has one position. The system says which kind of target
+is named:
 
-The `<system>` segment is `none` for a note that belongs to no system, which is
-most of them: `harnadventures-none-being-grod`. A note that exists only for one
-system names it.
+| system        | target                                                                      |
+| ------------- | --------------------------------------------------------------------------- |
+| `note`        | Readable note content: a web page, a book entry, or a Foundry JournalEntry. |
+| `none`        | A systemless target such as an asset, Folder, Macro or Scene.               |
+| `sohl`, `hm3` | A game system's Actor or Item document.                                     |
+
+A note can publish more than one Address. A `being` note, for example, publishes
+`thalorna-note-being-bctrncml` for its readable content and
+`thalorna-sohl-being-bctrncml` for its SoHL Actor. An item note follows the same
+pattern for its page and Item. The type segment remains the authored note type
+in each Address.
 
 #### Shorter forms
 
-The full address is the unambiguous form, and almost nothing uses it — 92 of
-12,056 links in the current trees. The rest rely on shorter forms, each dropping
-segments from the left:
+Authors may omit segments from the left. The complete Address states all four:
 
 | form                            | expands to                                               |
 | ------------------------------- | -------------------------------------------------------- |
 | `package-system-type-shortcode` | itself                                                   |
 | `system-type-shortcode`         | `<this package>-system-type-shortcode`                   |
-| `type-shortcode`                | `<this package>-<this block's system>-type-shortcode`    |
-| `shortcode`                     | as above, with the type from the field's own declaration |
+| `type-shortcode`                | `<this package>-<this position's system>-type-shortcode` |
+| `shortcode`                     | as above, with the type from the field's declaration     |
 
-There is no `package-type-shortcode`: the forms are exactly the **suffixes** of
-the canonical address, so naming another package means naming its system too.
-`kethira-place-tashal` is three segments, which reads as system `kethira`, and
-fails.
+There is no `package-type-shortcode` form. A reference to another package states
+its system as well as its package.
 
 #### Authored references and generated references
 
-Authored notes may use any permitted suffix. Builds leave those source bytes
-unchanged. Generated content indexes, SQL records, site frontmatter and generated
-Wikilinks contain full `package-system-type-shortcode` Addresses. For example,
-`data.parents: [north]` in the `thalorna` package emits
-`data.parents: [thalorna-none-place-north]`.
+Authored notes may use any permitted suffix. Builds leave source bytes unchanged.
+Generated content indexes, SQL records, site frontmatter and generated
+Wikilinks contain complete Addresses. For example, `data.parents: [north]` in
+`thalorna` emits `data.parents: [thalorna-note-place-north]`.
 
-SQL queries compare Address-valued fields to full Addresses. A note's `shortcode`
-is a distinct identity component, so it is not equal to an Address stored in
-`data.parents`, `data.domains` or a governance rank's `lore`. Use the target's
-complete identity for that comparison, including its package, system and type.
-A stub has no published page address; its note identity still contains those
-components and its Shortcode.
+SQL queries compare Address-valued fields to complete Addresses. A note's
+`shortcode` is a distinct identity component, so it is not equal to an Address
+stored in `data.parents`, `data.domains` or a governance rank's `lore`. Use the
+target's complete identity for that comparison. A stub has no published page
+address; its note identity still contains the package, system, type and shortcode.
 
-The toolchain holds parsed Address properties as complete tuples internally.
-Address-keyed relation maps hold typed targets and standing values. Only generated
-output serializes these properties to Address strings. Runtime Shortcodes,
-Foundry UUIDs, file paths and URLs keep their own representations.
+The toolchain holds parsed Addresses as complete tuples internally. Address-keyed
+relation maps hold typed targets and standing values. Only generated output
+serializes these properties to Address strings. Runtime Shortcodes, Foundry
+UUIDs, file paths and URLs keep their own representations.
 
 An Address-valued `data:` field must name a target in this package or a declared
-dependency index. `content-build lint` reports a missing target as an error at
-the value or map key that names it. A stub counts as a target for data even
-though it publishes no page. Art slots use their own missing-art warning and
-document fallback.
+dependency index. `content-build lint` reports a missing target at the value or
+map key that names it. A stub counts as a target for data even though it
+publishes no page. Art slots use their own missing-art warning and document
+fallback.
 
 #### An omitted segment defaults from where the link is written
 
-It is **not** a wildcard and resolution is not a search. Every short form expands
-to exactly one canonical address before anything is looked up, so a lookup either
-finds one entry or none — there is no candidate set, and a cross-package
-ambiguity is impossible by construction.
-
-- **package** omitted → the current package. A short address therefore names
-  _this_ package and never falls through to a dependency; reaching another one is
-  the fully qualified form's job.
-- **system** omitted → **the system block the link is written under**. Anywhere
-  under `sohl:` is `sohl`; anywhere under `hm3:` is `hm3`; **anywhere else** —
-  top-level frontmatter, `data:`, and body prose — is `none`. The enclosing block
-  decides at any depth, so `sohl.items[3].model` and `sohl.system.body.structure`
-  default alike; the field has no say.
-
-**Under `none`, a system-bearing type addresses its documentation.** A note's
-`none` address _is_ its `doc<type>` journal — the Item is the one with a system —
-so a prose `[[affiliation-sirvadar|Sirvadar]]` names the page, which is what
-prose almost always means. A prose link that means the **Item** states the
-system: `[[sohl-affiliation-sirvadar|…]]`.
-
-Only a type whose own document carries a system is redirected this way. A
-`macro` and the map types have documentation journals too, but their own
-documents are core ones already at `none`, so `macro-autoattack` names the Macro
-and `docmacro-autoattack` its journal — two live addresses.
+An omitted segment is a default, not a wildcard. Every short form expands to one
+complete Address before lookup.
+
+- **Package:** the current package. A short address never falls through to a
+  dependency.
+- **System in `[[link|text]]`:** `note`, for every note type. Use an explicit
+  game system to name its Actor or Item, or `none` to name a systemless target.
+- **System in `![[link|text]]`:** `none`. An embed names an image or icon asset;
+  it also supplies `image` as the type of a bare shortcode.
+- **System in frontmatter:** a system block such as `sohl:` or `hm3:` supplies
+  its game system. Other Address fields default to `note`, except fields
+  declared for images, icons or folders, which default to `none`.
+
+For example, `[[macro-autoattack|Automated Attack]]` names the readable macro
+note, while `[[none-macro-autoattack|Automated Attack]]` names the Foundry Macro.
+`![[icon-anvil|Anvil]]` names the systemless icon asset.
 
 **A complete Address is lowercase throughout.** Every segment — package,
 system, type and shortcode alike — contains only lowercase ASCII letters and
@@ -1572,7 +1565,7 @@ A **`Wikilink`** is how body prose names something:
 The brackets, the `#<anchor>` and the `|<text>` label are the Wikilink's own.
 What sits inside them is an `Address` like any other — read by the same grammar,
 written at any of its lengths, and taking each omitted segment from where the
-link is written, which for body prose is this package and system `none`. So
+link is written, which for body prose is this package and system `note`. So
 nothing about resolution belongs to the bracketed form: a wikilink and a
 frontmatter field ask the same question of the same value, and the findings above
 are the answers either of them gets.
@@ -2054,10 +2047,10 @@ system a note might write. A package shipping for a second system declares
 `system:` on a pack of each class it compiles.
 
 That includes actors. A being producing its Actor and nothing else would be
-the one system-bearing note with no address at `none`, leaving a prose link
+a system-bearing note with readable content, giving a prose link
 naming it nowhere to land. It carries a documentation journal like every other
 such note, addressed
-`<package>-none-docbeing-<shortcode>` beside the Actor's
+`<package>-note-being-<shortcode>` beside the Actor's
 `<package>-<system>-being-<shortcode>`.
 
 **A being keeps its prose inline as well.** `system.appearance` and
@@ -4065,7 +4058,7 @@ await CONFIG.SOHL.class.Utility.currentCombatantAttack();
 
 Three rules follow, and each is deliberate. The anchor names the **page**, not
 the heading text, so the heading may be worded freely and
-`[[docmacro-autoattack#script]]` still opens exactly this page. The fence must
+`[[macro-autoattack#script]]` still opens exactly this page. The fence must
 be **tagged** — an untagged fence is a code sample whose language nobody stated,
 and treating it as executable would make an illustrative snippet the macro. And
 only the **first** tagged fence counts, so a note may document its macro
@@ -4141,8 +4134,8 @@ persists in the pack.
 **Each address names the note's own document.** That is the same rule `pack:`
 follows, so there is one answer and not two. A note that compiles into _two_
 documents — an item and the JournalEntry its prose became — puts the second in a
-bundle only when the bundle names it by its own `doc…` address:
-`miscgear-bowlcer` is the item, `docmiscgear-bowlcer` its description page.
+bundle when the bundle names its `note` Address:
+`sohl-miscgear-bowlcer` is the Item, `miscgear-bowlcer` its description page.
 
 **An address that resolves to nothing fails the build.** A `folder` address is
 refused with a message of its own: a folder materialises in every pack holding

package/docs/getting-started.md

@@ -132,9 +132,8 @@ repository.
 npm install --save-dev @heroiclands/package-build
 ```
 
-That installs two binaries into `node_modules/.bin`: `package-build`, the
-packaging half, and `content-build`, the content half. Every command below is
-one of those two. Run them through `npx`, or wire them into npm scripts as
+That installs `package-build`, the packaging half, and `content-build`, the
+content half, into `node_modules/.bin`. Run them through `npx`, or wire them into npm scripts as
 [`project-setup.md`](project-setup.md) describes.
 
 **How it worked:** `npx package-build --version` prints the installed version.