@heroiclands/package-build 22.4.4 → 22.4.5

package/docs/commands.md

@@ -261,7 +261,8 @@ package-build: `packageKind: documentation` ships no Foundry package, so there i
 
 **NAME**
 
-`package-build site-root` — write the deployment's `_headers`.
+`package-build site-root` — write the deployment's `_headers`, and index the
+site for search.
 
 **SYNOPSIS**
 
@@ -294,6 +295,29 @@ it.
 The rules are scoped to those hostnames, so a site deployed under a domain of
 its own stays indexable.
 
+With `_headers` written, the rendered site is indexed for search. Pagefind
+reads every page under `<out>/<contentPackage>/` and writes the index into
+`<out>/<contentPackage>/pagefind/`, so it is deployed with the pages and served
+at `/<contentPackage>/pagefind/`; the theme loads `pagefind.js` from there,
+relative to the site's base URL, and the browser bundle derives the prefix from
+its own address, so nothing about the prefix is configured on either side. What
+is indexed is the body of every page and the homepage; the theme marks its own
+chrome — header, footer, breadcrumbs, infobox, the related-pages card —
+`data-pagefind-ignore`, and carries `data-pagefind-filter` attributes for a
+page's `type` and `package`, so a search can be narrowed to one kind of page.
+This command's part is only to run the indexer over whatever the theme
+rendered.
+
+The indexer is the `pagefind` package this toolchain depends on, which installs
+the binary for the platform as an optional dependency; nothing goes on a
+`PATH`. Every failure of the step is an error located at the rendered site —
+`build/site/<contentPackage>: error: search index: …` — and a binary that is
+not installed names the platform package `npm ci` installs.
+
+[`site.search: false`](configuration.md#site) skips the step, and removes a
+`pagefind/` an earlier build left beside the pages, so a site that wants no
+search deploys none.
+
 **OPTIONS**
 
 `--out <dir>` — the directory that is deployed. Defaults to `build/site`.
@@ -302,13 +326,20 @@ its own stays indexable.
 
 1 when `<out>/<contentPackage>/` holds no rendered site, which means the site
 build has not run and writing root files would publish a deployment with nothing
-under the prefix. Otherwise 0.
+under the prefix; 1 when the index cannot be built. Otherwise 0.
 
 **EXAMPLES**
 
 ```
 $ package-build site-root
 ✅ Wrote build/site/_headers.
+✅ Indexed 412 pages for search into build/site/thalorna/pagefind/.
+```
+
+```
+$ package-build site-root
+✅ Wrote build/site/_headers.
+Search is off (`site.search: false`), so no index was written.
 ```
 
 **SEE ALSO**
@@ -1829,6 +1860,155 @@ demo-book: error: the document tree named by `pdf.document` cannot be read
 `content-build site`, `content-build package <action> [pack] [entry]`,
 [Diagnostics](diagnostics.md), [Configuration](configuration.md).
 
+### `content-build map`
+
+**NAME**
+
+Draw the containment tree, the map from a place, or the whole route graph.
+
+**SYNOPSIS**
+
+```
+content-build map --tree [--root <shortcode>] [--engine dot|twopi|neato] [--rankdir TB|LR|BT|RL]
+                  [--nodesep <inches>] [--ranksep <inches>] [--no-polities]
+content-build map --from <shortcode>.. | --from all
+content-build map --travel
+content-build map [...] [--scale <factor>] [--base <url>] [--out <dir>]
+```
+
+**DESCRIPTION**
+
+Draws what the place notes state. Every drawing is read from the content
+index — this package's records and every declared dependency's fetched
+index — so a consumer's map draws its dependencies' places beside its own
+and no note is opened except to locate a finding. Everything lands under
+`build/map/`, always the `.dot` beside the `.svg`, so a drawing can be
+re-rendered, diffed or read without the index. GraphViz draws: `dot` (or
+`twopi`, `neato`) for the tree, `neato` for the other two. It is a
+build-time tool of this command alone; when the engine a run needs is not
+installed the command says so, names what to install, and stops. A build
+that asks for maps as one step of a larger job — a site build — writes
+the `.dot` files, emits one warning and skips the renderings rather than
+failing.
+
+The three drawings, any of which may be asked for in one run:
+
+**`--tree`** — the author's check. The containment tree from `data.parents`,
+edges running child → parent, clustered by continent — a `region` parented
+directly on the `world` note — with the places reaching no continent
+floating outside every cluster. Node shape, colour and size are by
+`subType` (a gold double circle for the world, a blue box for a region, a
+small green ellipse for a settlement, a purple diamond for a site, a teal
+hexagon for a feature, an orange house for a structure), and a legend
+drawn from the same style table sits on every drawing. A `polity`
+affiliation is drawn as a grey dashed cylinder beside every region note in
+its own directory. Anomalies are highlighted and reported as findings: a
+place with **no parent** and a **placeholder for a parent shortcode no
+place declares** are filled red (errors); a place on a **cycle** is
+outlined red (an error); a place with **more than one parent**, a region
+with **no `packFolder`** and a polity whose directory holds **no region
+note** are warnings. The world note has no parent by nature and is not a
+finding. Writes `tree.svg` for the whole world and `tree-<shortcode>.svg`
+for each continent; with `--root`, the subtree beneath that one place as
+`tree-<shortcode>.svg` — every place whose `parents` chain reaches it by
+any path — and no findings.
+
+**`--from <shortcode>`** — the map from a place, `from-<shortcode>.svg`.
+Pre-modern maps were itineraries: partial, centred on their maker, exact
+about the next stage and vague about the tenth. A place's `borders` and
+`routes` are exactly that, so the reader's map is one map per place, from
+that place. The place sits at the centre, **north up, east right**. Every
+neighbour it states — or that states it, since a border or a route is one
+fact stated from each end — sits at the angle of its bearing and on the
+ring of its days, with an edge labelled by the bearing and days; a border
+is a dashed edge, and where several modes reach one place the label lists
+each. Beyond each neighbour, every place a second hop reaches is drawn
+dimmer at the composed bearing where the two hops agree — the same bearing
+or adjacent ones, added as vectors weighted by their days — on the ring of
+their total; where the hops disagree the place is omitted rather than
+guessed at. Nodes sharing a ring and a bearing are fanned apart. `all`
+draws the map from every place that states or is named in a border or a
+route. Positions are computed by the command and pinned, so `neato` only
+draws; nothing on the page is a solver's decision.
+
+_The rings._ One faint dashed circle per marker of the days scale up to
+the horizon of 90 days — `1 2 3 5 10 20 30 45 60 90` — each labelled at
+its top, spaced logarithmically so that equal ratios of days are equal
+steps of radius: a day to two days is the same step as five to ten, and a
+day's ride and a month's voyage both fit on one page. A neighbour with a
+route sits on the ring of its shortest route's days. A neighbour reached by
+a border alone sits on the innermost ring, because a frontier states no
+distance. One more circle, the rim, lies a log step beyond the horizon:
+a place farther than 90 days, and a second hop whose days are unknown
+because either hop was a border, are a name at the rim carrying its days
+or `?` — beyond what the notes state, the map states nothing more.
+
+_Two scales._ The generated map from a place is the default regional map:
+every place gets one at build time, from its `borders` and `routes`. An
+authored `regionalmap` note is an artefact of the setting — a road book, a
+sailor's chart, a tax survey, partial and from somewhere, whose prose says
+whose it is — and never the survey. The two are two sources of the same
+thing on a place's page.
+
+**`--travel`** — the whole route graph, `travel.svg`, for the author: one
+undirected edge per pair of places, a border dashed, each route asking
+`neato` for a length on the same log scale as the rings so the god's-eye
+view and the itinerary agree about what a day and a month look like; the
+engine solves the positions.
+
+Every node's label is the place's `name.full` and its tooltip the canonical
+address. With `--base`, every name is also a link — GraphViz writes an
+`<a href>` around it — to the page at `<base><slug>/` for this package's
+places and to the URL the fetched index resolved for a dependency's, so a
+page can inline the SVG. Without it the names are plain text.
+
+**OPTIONS**
+
+| Option       | Type    | Default      | Description                                                                                                                                    |
+| ------------ | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--tree`     | boolean | `false`      | Draw the containment tree: `tree.svg`, one `tree-<shortcode>.svg` per continent, and the findings.                                             |
+| `--root`     | string  | —            | With `--tree`, draw the subtree beneath this place as `tree-<shortcode>.svg` and report nothing.                                               |
+| `--from`     | string  | —            | Draw the map from this place as `from-<shortcode>.svg`; repeatable, or `all` for every place with a border or a route.                         |
+| `--travel`   | boolean | `false`      | Draw the whole route graph as `travel.svg`.                                                                                                    |
+| `--engine`   | choice  | `dot`        | The tree's layout engine — `dot`, `twopi` (radial, rooted on the world or the `--root`) or `neato`. The other two drawings are always `neato`. |
+| `--rankdir`  | choice  | `TB`         | The tree's rank direction — `TB`, `LR`, `BT` or `RL`; `dot` engine only.                                                                       |
+| `--nodesep`  | number  | by `--scale` | The tree's GraphViz `nodesep`, in inches.                                                                                                      |
+| `--ranksep`  | number  | by engine    | The tree's GraphViz `ranksep`, in inches.                                                                                                      |
+| `--scale`    | number  | `1`          | Multiply every node's width, height, font size and border weight, the legend's included.                                                       |
+| `--polities` | boolean | `true`       | Draw polities beside their regions in the tree. `--no-polities` drops them.                                                                    |
+| `--base`     | string  | —            | The site base this package's pages are served under, ending in a slash; given, every name is a link to its page.                               |
+| `--out`      | string  | `build/map`  | Directory to write into, relative to the working directory.                                                                                    |
+
+**EXIT STATUS**
+
+1 when no drawing is asked for, when a `--from` or `--root` names no
+place, when the GraphViz engine a drawing needs is not installed, when a
+dependency's index cannot be read, when a note the index cannot record is
+met, on any error finding from `--tree` (a place with no parent, a parent
+that does not resolve, a cycle), or on any other thrown error. Otherwise 0
+— the warnings are reported and never fail the command.
+
+**EXAMPLES**
+
+```
+$ content-build map --tree
+assets/content/Regions/Sea.md:16:5: warning: place "innersea" has more than one parent (northc, southc), which is legal for a sea between continents or a region split between two, and worth a look otherwise
+assets/content/Regions/Marches/Lost_Fort.md:9:14: error: place "lostfort" names parent "marchs", which does not resolve to any place in this package or a fetched index
+[…] 394 place(s) → 7 drawing(s) under build/map
+
+$ content-build map --from dunharargn --base /thalorna/
+[…] 394 place(s) → 1 drawing(s) under build/map
+
+$ content-build map --travel
+[…] GraphViz's `neato` is not installed, and `content-build map` draws with it; install GraphViz (`brew install graphviz` on macOS, `apt-get install graphviz` on Debian or Ubuntu) and run the command again
+```
+
+**SEE ALSO**
+
+`content-build lint [root]` (which checks `borders` and `routes` from both
+ends), `content-build deps fetch`, `content-build content-index [root]`,
+[Content format](content-format.md), [Diagnostics](diagnostics.md).
+
 ### `content-build reachability <dir> [file]`
 
 **NAME**

package/docs/configuration.md

@@ -769,6 +769,7 @@ Any other key under `docs.itemFields` is refused:
 | `site.passOptions` | object   | `{}`                                        |
 | `site.notfound`    | object   | `null`                                      |
 | `site.hugo`        | object   | `{}`                                        |
+| `site.search`      | boolean  | `true`                                      |
 
 How much of a package reaches the web at all is **not** here — it is
 [`publish.site`](#publish). `site` is framing: which named pass bundle
@@ -818,7 +819,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo, search).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -932,6 +933,23 @@ the block cannot grow into a second configuration file:
 
 > ``package-build config: `site.hugo.baseURL` is derived from package.json `homepage` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
 
+`site.search` is whether the rendered site carries a search index. On by
+default: `package-build site-root` runs Pagefind over the rendered pages after
+it writes `_headers`, and the index lands beside them as
+`build/site/<contentPackage>/pagefind/`, served at `/<contentPackage>/pagefind/`
+with the rest of the site. The theme loads it relative to the site's base URL
+and renders the search box; what is indexed is the body of every page, with the
+theme's own chrome marked out. `false` skips the step and removes an index an
+earlier build left, so a site that wants no search deploys none. See
+[`package-build site-root`](commands.md#package-build-site-root).
+
+```yaml
+site:
+  search: false
+```
+
+> ``package-build config: `site.search` must be a boolean.``
+
 ### The generated Hugo configuration
 
 `content-build site` writes `build/hugo/hugo.toml` on every run. Every value

package/docs/content-format.md

@@ -3081,12 +3081,111 @@ three maps, and none of those maps needs to know it is a keep.
 - structure: A single building or habitation — halls, keeps, temples, inns, towers.
 - feature: A place significant by its terrain — forests, rivers, falls, passes, fords.
 
-| `data` property | Values       | Description                                                                  |
-| --------------- | ------------ | ---------------------------------------------------------------------------- |
-| `demonym`       | `string`     | What a person from this place is called — a Vylarian                         |
-| `lore`          | `WikiLink[]` | Lore concerning this place — its peoples, its law, its calendar, its history |
-| `parents`       | `WikiLink[]` | Enclosing places within which this place is located                          |
-| `population`    | `number`     | Approximate population (precision 2 significant digits)                      |
+| `data` property | Values                                              | Description                                                                  |
+| --------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `demonym`       | `string`                                            | What a person from this place is called — a Vylarian                         |
+| `lore`          | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
+| `parents`       | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
+| `population`    | `number`                                            | Approximate population (precision 2 significant digits)                      |
+| `borders`       | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
+| `routes`        | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
+
+#### Where a place is, in relation to other places
+
+`parents` states what a place is **within**. Two more properties state what
+it is **next to** and what it is **reachable from**, as data rather than as
+prose, so that two notes describing one frontier cannot quietly disagree about
+which side of it each is on:
+
+```yaml
+data:
+  borders: # places sharing a frontier
+    - { to: dunharargn, bearing: NE } # both required
+    - { to: bethuargn, bearing: W }
+  routes: # journeys from this place's centre
+    - { to: steinmark, bearing: SW, mode: land, days: 3, terrain: [road, mountains] }
+    - { to: denizara, bearing: W, mode: ship, days: 5 }
+    - { to: kethramir, bearing: E, mode: land, days: 30, terrain: [dunes], leagues: 90 }
+```
+
+- `to` — required; the `shortcode` of a `place` note in this package or in a
+  declared dependency's index. A shortcode, not an address.
+- `bearing` — required; where the neighbour or the destination lies from here.
+- `mode` — required on a route; how the journey is travelled.
+- `days` — required on a route; a marker meaning "about this, under normal
+  conditions", from the scale below. Any other value is an error.
+- `terrain` — optional on a route; the terrains crossed, in travel order, from
+  the registry below. Each terrain names the modes that cross it, so open sea
+  on a land route — or a road on a ship route — is an error.
+- `leagues` — optional on a route; a distance, only where the note states one.
+
+**Regions border; settlements are days apart.** A frontier is a fact about two
+regions, and a journey is a fact about two places a traveller sets out from and
+arrives at. A pair appears in `routes` once per `mode` — a port and its
+neighbour may be three days by land and one by ship — and in `borders` once.
+**A place never borders its own parent or child**: containment is `parents`,
+and restating it as adjacency makes the two contradict each other.
+
+**Both ends state the relation, and `content-build lint` checks that they
+agree.** A border at `NE` from one side is a border at `SW` from the other; a
+route stated by land in three days from one side is stated by land in three
+days from the other, at the opposite bearing. A neighbour that states nothing
+back is a warning naming both notes — the pair is half-written, not wrong. A
+neighbour that states a different bearing, a different `days` or a different
+`mode` is an error, because one of the two notes is wrong and a reader cannot
+tell which. Every `to` must resolve to a place, every value must come from its
+closed set, and each finding is located at the entry that states it.
+
+| `bearing` value | where the other place lies |
+| --------------- | -------------------------- |
+| `N`             | north                      |
+| `NE`            | north-east                 |
+| `E`             | east                       |
+| `SE`            | south-east                 |
+| `S`             | south                      |
+| `SW`            | south-west                 |
+| `W`             | west                       |
+| `NW`            | north-west                 |
+
+| `mode` value | travelled                    |
+| ------------ | ---------------------------- |
+| `land`       | on foot, mounted, or by cart |
+| `boat`       | on a river or a lake         |
+| `ship`       | on open sea                  |
+
+| `days` value | meaning                                      |
+| ------------ | -------------------------------------------- |
+| `1`          | a day                                        |
+| `2`          | two days                                     |
+| `3`          | three days                                   |
+| `5`          | about five days                              |
+| `10`         | a ten-day week                               |
+| `20`         | two ten-day weeks                            |
+| `30`         | three ten-day weeks                          |
+| `45`         | a month and a half                           |
+| `60`         | two months                                   |
+| `90`         | a season                                     |
+| `180`        | many months                                  |
+| `360`        | who knows — a journey nobody reckons in days |
+
+| `terrain` value | crossed by         |
+| --------------- | ------------------ |
+| `road`          | land               |
+| `track`         | land               |
+| `plain`         | land               |
+| `steppe`        | land               |
+| `hills`         | land               |
+| `mountains`     | land               |
+| `forest`        | land               |
+| `jungle`        | land               |
+| `marsh`         | land               |
+| `dunes`         | land               |
+| `desert`        | land               |
+| `ice`           | land               |
+| `coast`         | land, boat or ship |
+| `open-sea`      | ship               |
+| `river`         | boat               |
+| `lake`          | boat               |
 
 **A place declares only what is true of ground.** Four properties were removed
 because they were true of something else, and each removal has a home to go to.

package/docs/diagnostics.md

@@ -242,6 +242,7 @@ over one would teach people to stop reading the report.
 | `content-build markdown [paths..]`               | it reports any markdownlint finding                                                                                                                                                                                                                                |
 | `content-build site`                             | any gate finding (no homepage, a wikilink in frontmatter, an address that cannot be derived, an unusable or unaddressable foreign manifest, a conflicting address) or any table or wikilink error while writing pages — the run stops at the first gate that fires |
 | `content-build pdf`                              | it could not build the book for a reason other than a deliberate no-op — never on a reported finding by itself                                                                                                                                                     |
+| `content-build map`                              | `--tree` reports an `error`-severity finding (a place with no parent, a parent that does not resolve, a cycle), a named place is not one, the GraphViz engine a drawing needs is not installed, or the corpus cannot be indexed — never on a warning               |
 | `content-build docs item-fields --check`         | the generated page differs from what is committed                                                                                                                                                                                                                  |
 | `content-build package compile`                  | pack JSON generation reported any `error`-severity finding (checked, and the compile refused, before any pack is written), or a compiled pack fails its Scene/Level integrity check                                                                                |
 | `content-build deps fetch`                       | the fetch itself throws — it emits no diagnostics                                                                                                                                                                                                                  |

package/docs/project-setup.md

@@ -263,12 +263,13 @@ package carries this group:
 `build:site-content` writes the whole Hugo source tree under `build/hugo/` —
 the generated `hugo.toml` and the content mount — with `content-build site`;
 `build:site-html` runs Hugo over it, rendering into `build/site/<contentPackage>/`;
-`build:site-root` writes the deployment's `_headers` beside
-that; and `serve:site` does the first and then `hugo server` for a live
-preview. The repository carries no Hugo configuration of its own: `hugo.toml`
-is generated on every run from `package.json`, `package-build.config.yaml`,
-the installed `@heroiclands/hugo-theme` and the navigation `deps fetch`
-cached, and the only file to add is `@heroiclands/hugo-theme` under
+`build:site-root` writes the deployment's `_headers` beside that and indexes
+the rendered pages for search into `build/site/<contentPackage>/pagefind/`;
+and `serve:site` does the first and then `hugo server` for a live preview.
+The repository carries no Hugo configuration of its own: `hugo.toml` is
+generated on every run from `package.json`, `package-build.config.yaml`, the
+installed `@heroiclands/hugo-theme` and the navigation `deps fetch` cached,
+and the only file to add is `@heroiclands/hugo-theme` under
 `devDependencies`. Hugo itself is a separate install — the extended edition,
 on the developer's `PATH` and the runner's.
 

package/engine/frontmatter-lint.mjs

@@ -1403,17 +1403,27 @@ export function lintNote(
     // to recognise it would be worse than not checking.
     const entry = vocabulary?.[current];
     if (entry) {
+        const fields = dataFields(current, vocabulary) ?? [];
         findings.push(
             ...checkDataContainer(note, {
                 type,
                 // Read through `dataFields`, so the keys **every** type accepts
                 // are part of what this type declares rather than a second list
                 // the container check would have to be told about.
-                fields: dataFields(current, vocabulary) ?? [],
+                fields,
                 packs,
             }),
         );
         findings.push(...checkSubType(note, { type, entry }));
+        // A field that declares a check of its own, beyond its shape. Handed
+        // the index the reference check resolves through, so a value naming
+        // another note reads that note — local or in a fetched index — the
+        // way a wikilink would. The linter names no such field itself; the
+        // vocabulary does, beside the field.
+        for (const field of fields) {
+            if (typeof field.check !== "function") continue;
+            findings.push(...field.check(note, { index }));
+        }
     }
 
     const fields = authoredFields(schema);

package/engine/index.mjs

@@ -84,6 +84,24 @@ export * as noteSchemas from "./note-schemas.mjs";
 /** The closed frontmatter regions: the `data:` container and each type's `subType`. */
 export * as noteVocabulary from "./note-vocabulary.mjs";
 
+/** What a place is next to and reachable from: the closed sets, and the checks. */
+export * as placeRelations from "./place-relations.mjs";
+
+/** The places a map is drawn from, read from the content index, and what `parents` says about them. */
+export * as mapPlaces from "./map-places.mjs";
+
+/** The geometry of the map from a place: bearings to angles, days to rings, hops composed. */
+export * as mapLayout from "./map-layout.mjs";
+
+/** The three drawings of `content-build map`, as DOT. */
+export * as mapDot from "./map-dot.mjs";
+
+/** GraphViz, as the map command finds and runs it. */
+export * as mapGraphviz from "./map-graphviz.mjs";
+
+/** `content-build map`: the drawings, written under `build/map/`. */
+export * as mapBuild from "./map-build.mjs";
+
 /** The closed registry of system ids, and the `none` that stands for no system. */
 export * as systems from "./systems.mjs";