@heroiclands/package-build 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @heroiclands/package-build
 
+## 11.1.0
+
+### Minor Changes
+
+- 8906d7a: **A `README` landing's `subType` is checked against the sections the repository declares, not the genre list.**
+  
+  Two vocabularies were spelled with one key. For every note, `subType` is a
+  sub-kind of its type, checked against a closed list. For a `README` under
+  `publish.address.landing: readme` it is additionally the **URL section** —
+  `sectionOf` reads a `doc`'s `subType` as the segment the landing addresses — and
+  that is an open set the consuming repository names in `site.sections` /
+  `site.readmeSections`. `engine/frontmatter-lint.mjs` applied the closed reading
+  while `engine/content-address.mjs` applied the open one, so the two halves of the
+  toolchain disagreed about the same note: `content-build site` addressed and
+  published `Weapons/README.md` at `weapongear/`, and `content-build lint` refused
+  it because `doc` declares only `rules`, `user-guide` and `reference`. An item
+  section's landing was not expressible.
+  
+  The check now widens **for a landing only**, and only under `landing: readme`: a
+  `README` whose `subType` is its section may name any section the repository
+  declares, as well as any of its type's own genres — a genre is a section a `doc`
+  tree publishes under whether or not the repository describes it, so narrowing to
+  the configured set alone would refuse a correct `README`. An ordinary note's
+  `subType` stays closed to its type's genres, unchanged.
+  
+  **The guard survives**, checked against the set that actually decides where the
+  page goes:
+  
+  ```text
+  Weapons/README.md:4:1: error: `subType` "weapongeer" is the section this README
+  lands at, and nothing declares it: it is neither a section this repository
+  configures under `site.sections` / `site.readmeSections` (rules, user-guide,
+  weapongear, …) nor one of the subtypes doc declares (rules, user-guide,
+  reference). Did you mean "weapongear"?
+  ```
+  
+  Whether the value is an address is asked of `sectionOf` rather than by naming a
+  type, so the linter still knows no type names of its own; the section list is
+  read from the resolved configuration the site build renders those landings from,
+  through a new `declaredSections(config)`, so neither can name a section the other
+  does not.
+  
+  _Minor rather than patch_: `lintNote` and `lintFrontmatter` take two new
+  options (`landing`, `sections`) and `content-config.mjs` exports
+  `declaredSections`. Both options default to today's behaviour, so a caller that
+  passes neither — and a repository that declares no sections — is unaffected.
+  
+  Closes #197
+
+### Patch Changes
+
+- 68910b6: **A `README` landing may name any section that exists, not only a configured one.**
+  
+  #197 widened a landing's `subType` check by one term and it was the wrong one:
+  the sections the repository configures in `site.sections` /
+  `site.readmeSections`. That keys on configuration a consumer may legitimately not
+  have. `sohl-thalorna` has **no `site:` block at all** — it renders its site
+  through a local fork of the emitter — so `declaredSections` answered `[]`, the
+  accepted set collapsed back to the three `doc` genres, and five of its landings
+  were still refused for naming their own content type:
+  
+  ```text
+  assets/content/Characters/README.md:7:1: error: `subType` "being" is not one of the subtypes doc declares (rules, user-guide, reference)
+  ```
+  
+  A landing's `subType` is an **address**, so it is now checked against the
+  addresses that exist — the range of `sectionOf` over every note the format
+  permits, plus whatever the repository names:
+  
+  1. **Every content type the specification declares.** `sectionOf` returns
+     `fm.type` for a non-`doc` note, so `being`, `lore`, `scenario` and
+     `weapongear` are sections _by construction_, configured or not.
+  2. **The type's own subtypes** — `rules`, `user-guide`, `reference`.
+  3. **The configured sections**, which may name one that is neither: `sohl` has
+     `credits` and `dev-docs`.
+  
+  **The guard survives.** A misspelling is in none of the three, so it still fails,
+  and the near miss is drawn from the whole union. What is deliberately no longer
+  caught is a landing for a section that exists but is currently empty — which is
+  legitimate, and is why the set is the types the format _declares_ rather than
+  those _present in the tree_: `sohl` ships two such landings above tables that
+  stay empty until the first note of each type does.
+  
+  **The type list is the specification's, not the schema map's.** `NOTE_SCHEMAS`
+  declares 18 types and `docs/content-format.md` declares 23; `lore`, `place`,
+  `scenario`, `vehicle` and `armorlocation` are in the second only. Checking an
+  address against the schema map would refuse `Lore/README.md` for a reason that
+  is not about addresses, and would report one gap twice in two vocabularies.
+  Whether a note's fields can be checked is a different question, answered
+  elsewhere and reported on the notes themselves.
+  
+  `lintNote` / `lintFrontmatter` take a `types` option beside `sections`; both
+  default to empty, so a caller that passes neither is unaffected.
+  
+  Closes #200
+
 ## 11.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -1252,6 +1252,22 @@ publish:
   The two are alternatives rather than a pair that could both apply: each live
   content tree holds notes the other rule would move.
 
+**Under `readme`, a landing's `subType` is an address rather than a genre.** The
+segment the `README` lands at is what `sectionOf` reads — for a `doc`, its
+`subType` — so `Weapons/README.md` writes `subType: weapongear` and publishes at
+`weapongear/`. `content-build lint` checks that value against the sections that
+can exist, which is three sets: every **content type** the format declares
+(`sectionOf` returns a non-`doc` note's own type, so `being` and `weapongear` are
+sections by construction), the **subtypes the type declares** (`rules`,
+`user-guide`, `reference`), and any section named in
+[`site.sections` / `site.readmeSections`](#what-a-section-may-declare). A
+misspelt one is still refused, by name and against all three, with the near miss
+suggested. This applies to a `README` only: every other note's `subType` stays
+closed to the values its type declares.
+
+Configuring the section is **not** a prerequisite — `site.sections` is framing,
+and a package that renders its own site need declare no `site:` block at all.
+
 A note the scheme yields no address for — one carrying no `shortcode`, a `doc`
 with no subtype (so no section to be filed under), a collection note naming no
 section — is **reported and omitted**, never guessed. The command

package/bin/content-build.mjs

@@ -72,6 +72,10 @@ import {
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
+// The sections this repository declares — the open set a `README` landing's
+// `subType` names (#197). Read from the resolved configuration the site build
+// renders those landings from, so neither can name a section the other does not.
+import { declaredSections } from "../content-config.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     checkDeclaredFields,
@@ -736,6 +740,22 @@ function lintCommand() {
                     // decides which vocabulary a tree is held to.
                     vocabulary: NOTE_VOCABULARY,
                     references: argv.references,
+                    // How this repository addresses a section landing, and the
+                    // sections that can exist — the open vocabulary a
+                    // `README`'s `subType` is read against (#197, #200).
+                    // Passed in for the same reason the schemas are: the
+                    // linter checks a note against what it is handed.
+                    //
+                    // The types come from the **specification**, not from
+                    // `schemas`: a landing's `subType` is an address, and a
+                    // type the format declares is a section whether or not
+                    // this build carries a schema to check its notes' fields
+                    // with. Reading `schemas` here would refuse `Lore/README.md`
+                    // for a reason that is not about addresses, and report one
+                    // gap twice in two vocabularies.
+                    landing: config.publish.address.landing,
+                    types: [...loadContentFormat().types.keys()],
+                    sections: declaredSections(config),
                 });
 
                 // What the builders emit, against what the receiving system

package/content-config.mjs

@@ -210,6 +210,34 @@ export function publishesContentPages(config) {
     return config.publish.site === "content";
 }
 
+/**
+ * Every URL section this repository names, in declaration order (#197).
+ *
+ * A section is *declared* by describing it: `site.sections` for one whose
+ * landing this build generates, `site.readmeSections` for one whose landing is
+ * a `README`. Between them they are the open set of addresses a repository
+ * says it publishes under — which is what a `README` landing's `subType` names,
+ * since `sectionOf` reads that field as the section rather than as a genre.
+ *
+ * Read from the same two maps the site build renders each landing from, so the
+ * set a note is checked against and the set a landing is written from cannot
+ * come to disagree. A repository that describes no section declares none, and
+ * the answer is empty rather than a guess assembled from the tree.
+ *
+ * @param {{site: {sections: object, readmeSections: object}}} config - A
+ *   resolved configuration.
+ * @returns {readonly string[]} The section names, deduplicated.
+ */
+export function declaredSections(config) {
+    const site = config?.site ?? {};
+    return Object.freeze([
+        ...new Set([
+            ...Object.keys(site.sections ?? {}),
+            ...Object.keys(site.readmeSections ?? {}),
+        ]),
+    ]);
+}
+
 /**
  * @typedef {"systems" | "modules"} PackageKind
  */

package/engine/frontmatter-lint.mjs

@@ -55,7 +55,10 @@
  * @module
  */
 
+import path from "node:path";
+
 import { authoredFields } from "./field-spec.mjs";
+import { DEFAULT_ADDRESS_SCHEME, sectionOf } from "./content-address.mjs";
 import { resolveFieldValue, SYSTEM_BLOCK_KEYS, unknownBlockKeys } from "./system-block.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
@@ -313,22 +316,83 @@ function checkDataContainer(note, { type, fields }) {
     return findings;
 }
 
+/**
+ * Whether this note's `subType` names the **section it lands at** rather than a
+ * sub-kind of its type (#197).
+ *
+ * Under `landing: readme` a `README.md` addresses its whole section, and the
+ * segment is what `sectionOf` reads — for a `doc`, its `subType`. So that one
+ * field is spelled once and read twice: as a genre on an ordinary note, and as
+ * an address on a landing. The two vocabularies are not the same set, and the
+ * closed one cannot answer for the open one.
+ *
+ * Asked of {@link sectionOf} rather than by naming a type, because which types
+ * route by their `subType` is address knowledge and this module deliberately
+ * knows no type names of its own.
+ *
+ * @param {object} note - The note.
+ * @param {string} landing - The repository's landing rule.
+ * @returns {boolean} Whether the value is an address.
+ */
+function subTypeIsSection(note, landing) {
+    if (landing !== "readme") return false;
+    const file = typeof note.file === "string" ? note.file : "";
+    if (path.basename(file).toLowerCase() !== "readme.md") return false;
+    const fm = note.fm ?? {};
+    return typeof fm.subType === "string" && sectionOf(fm) === fm.subType;
+}
+
 /**
  * Check a note's top-level `subType` against the values its type declares
- * (#128).
+ * (#128), or — for a `README` landing — against the sections that can exist
+ * (#197, #200).
  *
  * `subType` stays at the top level — it is what each system's map reads to
  * derive a document type, so it describes the note rather than the subject —
  * but it is not open like the rest of that region: a type either declares a
  * `subType` or does not, and a type that does declares its values.
  *
+ * **A landing page's is an address, and an address is checked against the
+ * addresses that exist.** A `README` under `landing: readme` addresses its
+ * section through this field, and a section is `weapongear` or `being` as
+ * readily as it is `rules`. What can legitimately appear there is the range of
+ * {@link sectionOf} over every note the format permits, plus whatever the
+ * repository names:
+ *
+ * 1. **Every declared content type.** `sectionOf` returns `fm.type` for a
+ *    non-`doc` note, so `being`, `lore` and `weapongear` are sections *by
+ *    construction*, configured or not.
+ * 2. **The type's own subtypes** — `rules`, `user-guide`, `reference` for a
+ *    `doc`, since a `doc` routes by its subtype.
+ * 3. **The configured sections**, which may name one that is neither: `sohl`
+ *    configures `credits` and `dev-docs`.
+ *
+ * Checking only (3) was #197's fix and keyed on configuration a consumer may
+ * legitimately not have: `sohl-thalorna` has no `site:` block at all, so five
+ * of its landings were refused for naming their own content type (#200).
+ *
+ * **The guard survives.** A misspelling is none of the three, so it still
+ * fails, with the near miss drawn from the whole union. What is deliberately no
+ * longer caught is a landing for a section that exists but is empty — which is
+ * legitimate, and is why the set is the types the format *declares* rather than
+ * the types *present in the tree*: `sohl` ships two such landings above tables
+ * that stay empty until the first note of each type does.
+ *
  * @param {object} note - The note.
  * @param {object} opts
  * @param {string} opts.type - The note's type, for the message.
  * @param {object} opts.entry - The type's vocabulary entry.
+ * @param {boolean} [opts.asSection] - Whether the value is a section address —
+ *   see {@link subTypeIsSection}.
+ * @param {readonly string[]} [opts.types] - The content types the format
+ *   declares. Empty leaves a landing checked against its genres and the
+ *   configured sections alone.
+ * @param {readonly string[]} [opts.sections] - The sections the repository
+ *   configures. Empty when it configures none, which is ordinary rather than a
+ *   defect.
  * @returns {object[]} Findings.
  */
-function checkSubType(note, { type, entry }) {
+function checkSubType(note, { type, entry, asSection = false, types = [], sections = [] }) {
     const fm = note.fm ?? {};
     if (!Object.hasOwn(fm, "subType") || fm.subType == null || fm.subType === "") return [];
 
@@ -353,6 +417,28 @@ function checkSubType(note, { type, entry }) {
     // the value is nobody's to check yet.
     if (values == null || values.includes(value)) return [];
 
+    if (asSection) {
+        if (types.includes(value) || sections.includes(value)) return [];
+        const guess = nearest(value, [...types, ...values, ...sections]);
+        return [
+            {
+                file: note.file,
+                ...at,
+                severity: "error",
+                message:
+                    `\`subType\` "${value}" is the section this README lands ` +
+                    `at, and nothing declares it. A section is a content type ` +
+                    `(${types.join(", ")}), a subtype ${type} declares ` +
+                    `(${values.join(", ")})` +
+                    (sections.length ?
+                        `, or a section configured under \`site.sections\` / ` +
+                        `\`site.readmeSections\` (${sections.join(", ")})`
+                    :   "") +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
+            },
+        ];
+    }
+
     const guess = nearest(value, values);
     return [
         {
@@ -435,9 +521,33 @@ function checkTags(note, { type }) {
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {string} [opts.landing] - The repository's landing rule, from
+ *   `publish.address.landing`. It decides which note addresses a whole section,
+ *   and so whether a `subType` is a genre or an address (#197).
+ * @param {readonly string[]} [opts.types] - The content types the format
+ *   declares — the sections that exist by construction (#200). Read from
+ *   `docs/content-format.md` rather than from `schemas`, because the two answer
+ *   different questions: whether an address is real, and whether this build can
+ *   check a note's fields. A type the specification declares and no schema
+ *   covers is a real section, and its notes are reported on their own account.
+ * @param {readonly string[]} [opts.sections] - The sections the repository
+ *   configures, from `declaredSections`. Supplied by the caller for the same
+ *   reason `vocabulary` is: this module checks a note against what it is
+ *   handed.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_SYSTEM_BLOCKS }) {
+export function lintNote(
+    note,
+    {
+        schemas,
+        index,
+        vocabulary,
+        systems = DEFAULT_SYSTEM_BLOCKS,
+        landing = DEFAULT_ADDRESS_SCHEME.landing,
+        types = [],
+        sections = [],
+    },
+) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
@@ -534,7 +644,15 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
     const entry = vocabulary?.[type];
     if (entry) {
         findings.push(...checkDataContainer(note, { type, fields: entry.data ?? [] }));
-        findings.push(...checkSubType(note, { type, entry }));
+        findings.push(
+            ...checkSubType(note, {
+                type,
+                entry,
+                asSection: subTypeIsSection(note, landing),
+                types,
+                sections,
+            }),
+        );
     }
 
     const fields = authoredFields(schema);
@@ -691,10 +809,19 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
  * @param {boolean} [opts.references=true] - Whether to check references.
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {string} [opts.landing] - The repository's landing rule; see
+ *   {@link lintNote}.
+ * @param {readonly string[]} [opts.types] - The content types the format
+ *   declares; see {@link lintNote}.
+ * @param {readonly string[]} [opts.sections] - The sections the repository
+ *   configures; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index, { schemas, vocabulary, references = true, systems }) {
+export function lintFrontmatter(
+    index,
+    { schemas, vocabulary, references = true, systems, landing, types, sections },
+) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -708,6 +835,9 @@ export function lintFrontmatter(index, { schemas, vocabulary, references = true,
                 vocabulary,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
+                ...(landing ? { landing } : {}),
+                ...(types ? { types } : {}),
+                ...(sections ? { sections } : {}),
             }),
         );
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "11.0.0",
+    "version": "11.1.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -14,6 +14,30 @@ export function publishesContentPages(config: {
         site: SiteMode;
     };
 }): boolean;
+/**
+ * Every URL section this repository names, in declaration order (#197).
+ *
+ * A section is *declared* by describing it: `site.sections` for one whose
+ * landing this build generates, `site.readmeSections` for one whose landing is
+ * a `README`. Between them they are the open set of addresses a repository
+ * says it publishes under — which is what a `README` landing's `subType` names,
+ * since `sectionOf` reads that field as the section rather than as a genre.
+ *
+ * Read from the same two maps the site build renders each landing from, so the
+ * set a note is checked against and the set a landing is written from cannot
+ * come to disagree. A repository that describes no section declares none, and
+ * the answer is empty rather than a guess assembled from the tree.
+ *
+ * @param {{site: {sections: object, readmeSections: object}}} config - A
+ *   resolved configuration.
+ * @returns {readonly string[]} The section names, deduplicated.
+ */
+export function declaredSections(config: {
+    site: {
+        sections: object;
+        readmeSections: object;
+    };
+}): readonly string[];
 /**
  * Validate and normalize a content configuration.
  *

package/types/engine/frontmatter-lint.d.mts

@@ -29,9 +29,22 @@ export function matchesKind(value: unknown, kind: string): boolean;
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {string} [opts.landing] - The repository's landing rule, from
+ *   `publish.address.landing`. It decides which note addresses a whole section,
+ *   and so whether a `subType` is a genre or an address (#197).
+ * @param {readonly string[]} [opts.types] - The content types the format
+ *   declares — the sections that exist by construction (#200). Read from
+ *   `docs/content-format.md` rather than from `schemas`, because the two answer
+ *   different questions: whether an address is real, and whether this build can
+ *   check a note's fields. A type the specification declares and no schema
+ *   covers is a real section, and its notes are reported on their own account.
+ * @param {readonly string[]} [opts.sections] - The sections the repository
+ *   configures, from `declaredSections`. Supplied by the caller for the same
+ *   reason `vocabulary` is: this module checks a note against what it is
+ *   handed.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, systems }: {
+export function lintNote(note: object, { schemas, index, vocabulary, systems, landing, types, sections, }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
@@ -39,6 +52,9 @@ export function lintNote(note: object, { schemas, index, vocabulary, systems }:
         known?: readonly string[];
         fieldVocabulary?: boolean;
     }>> | undefined;
+    landing?: string | undefined;
+    types?: readonly string[] | undefined;
+    sections?: readonly string[] | undefined;
 }): object[];
 /**
  * Check every note in a built index against its type's schema.
@@ -51,10 +67,16 @@ export function lintNote(note: object, { schemas, index, vocabulary, systems }:
  * @param {boolean} [opts.references=true] - Whether to check references.
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {string} [opts.landing] - The repository's landing rule; see
+ *   {@link lintNote}.
+ * @param {readonly string[]} [opts.types] - The content types the format
+ *   declares; see {@link lintNote}.
+ * @param {readonly string[]} [opts.sections] - The sections the repository
+ *   configures; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems, landing, types, sections }: {
     schemas: Record<string, readonly object[]>;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
@@ -62,6 +84,9 @@ export function lintFrontmatter(index: object, { schemas, vocabulary, references
         known?: readonly string[];
         fieldVocabulary?: boolean;
     }>> | undefined;
+    landing?: string | undefined;
+    types?: readonly string[] | undefined;
+    sections?: readonly string[] | undefined;
 }): {
     findings: object[];
     notes: number;