@heroiclands/package-build 11.1.0 → 14.0.0

package/CHANGELOG.md

@@ -1,5 +1,365 @@
 # @heroiclands/package-build
 
+## 14.0.0
+
+### Major Changes
+
+- a0a113b: **`publish.address.landing` is deleted.** `prefix` is the whole address scheme:
+  
+  ```yaml
+  publish:
+    address:
+      prefix: kb/ # default: "" — the package root
+  ```
+  
+  The key named which note addressed a whole section rather than a page within
+  one. #202 retired the second of its two rules and #204 retired the concept both
+  rules chose between — a section is a Hugo content directory the note format does
+  not carry, a page's address names no directory, and so no note lands one. What
+  survived was the key itself: resolved, refused-by-name for the retired value,
+  checked against a one-element vocabulary, frozen into the configuration, and
+  read by nobody. `LANDING_RULES` said so in its own doc comment — _"Inert since
+  #204."_
+  
+  **A configuration still declaring it is refused, at the line it is written on.**
+  Not reported as an unrecognized option, which names a spelling to correct and
+  leaves the author to work out that the mechanism is gone:
+  
+  ```text
+  package-build.config.yaml:14:9: error: package-build config:
+  `publish.address.landing` is a retired option — delete it. It named which note
+  addressed a whole section rather than a page within one, and there are no
+  sections to address: a section is a Hugo content directory the note format does
+  not carry, so no note lands one and every page is addressed
+  `<type>-<shortcode>`. Nothing replaces it.
+  ```
+  
+  Presence is the whole test, as it is for a retired frontmatter field: no value
+  makes declaring it right, so `readme` and the already-retired `collection` are
+  refused alike, by `RETIRED_ADDRESS_KEYS` — the configuration-side twin of
+  `engine/retired-fields.mjs`.
+  
+  **Why the key outlived its mechanism by one release.** `content-config.mjs` has
+  no warning channel — every finding goes through `fail()`, which throws — so
+  while both publishing consumers still declared the then-true `landing: readme`
+  the only options were to break them over a correct statement or to accept the
+  key in silence, and silent acceptance is what this codebase refuses everywhere
+  else. So it took the three steps `package:` took (#56): retire the value, have
+  consumers drop the key, delete the key. No consumer declares it now.
+  
+  **The plumbing goes with it.** `packageAddress` took an address scheme only to
+  validate the `landing` rule it then discarded — its own docstring already said
+  the `prefix` half never applied, because an address is `(type, shortcode)`, a
+  package-wide identity that takes no mount. It is now a function of the
+  frontmatter and nothing else, and `manifestContext` no longer carries a `scheme`
+  that nothing reads.
+  
+  | Removed                                                                                                                              | Where                        |
+  | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
+  | `LANDING_RULES`, `RETIRED_LANDING_RULES`                                                                                             | `content-config.mjs`         |
+  | `DEFAULT_ADDRESS_SCHEME.landing`, `ADDRESS_KEYS`' second entry, `normalizePublish`'s resolve-and-check, `AddressSchemeInput.landing` | `content-config.mjs`         |
+  | The `LANDING_RULES` re-export, `packageAddress`'s `{ scheme }` parameter and its landing check                                       | `engine/content-address.mjs` |
+  | `manifestContext`'s `scheme`, and the argument `collectManifestEntries` passed on with it                                            | `engine/manifest-emit.mjs`   |
+  
+  **Nothing a consumer emits moves.** Verified against pristine
+  `git archive origin/main` extractions of all three consumers, before and after:
+  `lint`, `links`, `manifest`, `package compile` and `site` produce **identical
+  console output, line for line**, and every emitted file is byte-identical —
+  31,197 files across the three trees, with only LevelDB's own timestamped `LOG`
+  differing. `sohl` stays green (2,988 manifest entries, 3,125 pack documents,
+  1,671 emitted pages); `sohl-thalorna` stays exactly as red as it was for its own
+  content gap (1,983 lint findings, 122 link findings); `sohl-kethira-basic` stays
+  green.
+  
+  Closes #215
+- 98ac362: **`subType: user-guide` is refused.** #206 renamed the `doc` subType
+  `user-guide` to `userguide` and held every `type` and `subType` to the address
+  charset, but shipped a **transitional acceptance** for the old spelling — a
+  warning naming the replacement rather than a refusal — because 43 `sohl` notes
+  authored it and no consumer can sweep ahead of the release that renames a value.
+  Every consumer tree has now swept: `sohl` **0**, `sohl-thalorna` **0**,
+  `sohl-kethira-basic` **0**, counted on a pristine extraction of each
+  `origin/main`. So the acceptance guards nothing, and this is the follow-up #207
+  named.
+  
+  `RETIRED_SUBTYPES`, `retiredSubType()` and `retiredSubTypeMessage()` are gone
+  from `engine/note-vocabulary.mjs`, along with the retired-spelling branch that
+  ran ahead of the charset check in `checkSubType`. Nothing replaces them:
+  `user-guide` now falls through to the **charset** check and is refused as an
+  error, for the reason that always applied — it contains a hyphen. That is why
+  the acceptance could be deleted rather than promoted to an error: the permanent
+  rule already covers the case, so no retirement-specific code outlived the sweep.
+  
+  **Breaking**, though the diff only removes code. A spelling that built at exit 0
+  one release ago now fails the build, and three exported symbols no longer exist.
+  A tree that has swept sees no change at all — which all three consumers have,
+  and each was verified unaffected.
+  
+  **The subType charset diagnostic is reworded.** It justified the rule by "the
+  hyphen separates the segments of an address", true of a `subType` when #206
+  shipped — `sectionOf` returned a `doc`'s subType, so the value was a URL path
+  segment — and not true since #204 retired sections. The rule stands on its own
+  footing instead: a subType is a vocabulary term the whole toolchain keys on, one
+  closed set away from being an address segment again, and a charset holding for a
+  type, a shortcode and a `contentPackage` but not for a subType would be a rule
+  nobody could state in a sentence. `typeCharsetMessage` is untouched — a type
+  genuinely is the first segment of every address.
+  
+  The same correction is applied to `assertVocabularyCharset`'s throw, which
+  carried the identical claim in a second place — _"A type and a subType are both
+  address segments"_ — where it would go unread until it fires, which is exactly
+  when it would be taken at face value. It now states the reason **per key**: the
+  address half for a type, the vocabulary-term half for a subType. The guard
+  itself is unchanged and stays where it is, running over `NOTE_VOCABULARY` as the
+  module loads.
+  
+  Closes #210
+
+### Minor Changes
+
+- 45b5bd0: **A section can say what it lists.** `site.sections` / `site.readmeSections`
+  take two more keys, `listType` and `listSubType`, and both reach the generated
+  `_index.md`:
+  
+  ```yaml
+  sections:
+    weapongear: { title: Weapons, listType: weapongear }
+    user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+  ```
+  
+  Since #204 a content page is written flat under the mount, so a declared
+  section's directory holds nothing but the landing this build writes for it and a
+  layout reading Hugo's `.Pages` finds no members. The membership survives in the
+  `site.sections` map and in nothing a theme can read — not on the page, not on
+  the landing, not in any URL — so every section landing served by a generic list
+  layout renders empty. `sohl` was unaffected only because its eleven catalog
+  layouts already query `site.RegularPages` by `Params.type`; a consumer rendering
+  through the shared theme has no layout of its own to edit. The landing now
+  states that query and the theme runs it
+  (HeroicLands/heroiclands-hugo-theme#50).
+  
+  **Two keys of their own, not `type` / `subType`.** On an `_index.md`, `type` is
+  Hugo's own layout selector: verified against Hugo 0.165, a section landing
+  carrying `type: doc` renders through `layouts/doc/list.html` rather than the
+  default list template — behaviour this build already relies on deliberately, for
+  the mount's own `landing`. Spelling the content type there would silently change
+  which template serves the landing.
+  
+  **Two keys added to the closed set, not an open passthrough.** `site.landing` is
+  passed through unvalidated because it is written once, for the mount, in one
+  landing template's own vocabulary; a section entry is written fourteen to twenty
+  times per build against a contract every package and every section shares.
+  Unbounded there, a mistyped `listTpye:` would publish into front matter, list
+  nothing, and report no error — which is the bug being fixed, moved one step
+  downstream where no build can see it. `normalizeSectionMeta` stays the one place
+  the vocabulary is bounded, and the writers still name no keys.
+  
+  **Both values are checked, because both ways of writing an inert declaration are
+  silent.** They name a content type and subType, so each must be an address
+  segment (`^[A-Za-z0-9]+$`), and a `listSubType` with no `listType` is refused —
+  a subType tells pages apart only within a type, so alone it names no query. The
+  charset check is the trap this came from: a section is named for a URL the site
+  chose and need not match the address (`/sohl/kb/user-guide/` is the section,
+  `userguide` the subType, #207), and copying the section's name in would match no
+  page at exit 0. All three refusals are located at the offending key:
+  
+  ```text
+  package-build.config.yaml:504:90: error: package-build config:
+  `site.sections.user-guide.listSubType` is `user-guide`, which is not
+  alphanumeric. …
+  ```
+  
+  **Additive.** A section that declares neither key emits exactly the bytes it
+  did before. Verified on a pristine `origin/main` extraction of `sohl`, the only
+  consumer running `content-build site` with declared sections: 1670 emitted files
+  byte-identical, and with the keys declared on two of its nineteen sections
+  exactly those two `_index.md` files change.
+  
+  Closes #212
+
+## 13.0.0
+
+### Major Changes
+
+- 0c2def0: A section is a Hugo directory concept, and the note format no longer carries one
+  (#204). Content pages emit **flat** under the mount, named by their address; the
+  `README.md` landing convention, `sectionOf`, the `<section>/` output routing, and
+  the "no section, so nowhere to file the page" refusal are all gone.
+  
+  **Why it goes.** Since #181 a page's URL _is_ its address,
+  `/<package>/<type>-<shortcode>/`, so a section appears in **no address at all**.
+  Its only remaining job was choosing the directory a page was written into, and
+  the only reason that mattered was Hugo's rule about what counts as a section —
+  `writeSectionLandings`'s own docstring said both of its jobs "exist because of
+  how Hugo decides what a section is". So the note format carried a filename
+  convention, a landing rule, a routing function and a refusal in order to satisfy
+  a rendering engine's directory semantics. #197 was the bill for that: `subType`
+  did double duty — a genre for an ordinary `doc`, a URL section for a `README` —
+  the two vocabularies collided, and it took #198, #200, #201 and a release to
+  settle by widening one of them rather than by removing the overload.
+  
+  **A page that introduces the notes of a type is now an ordinary note**, named by
+  convention and with no build path of its own: `type: doc`, `subType: reference`,
+  `shortcode: <type>`, addressed `doc-<type>`. The package's own front page already
+  worked this way (`homepage-root`, #182).
+  
+  | Surface                                | Before                                        | After                                             |
+  | -------------------------------------- | --------------------------------------------- | ------------------------------------------------- |
+  | A content page's file                  | `<mount>/<section>/<type>-<shortcode>.md`     | `<mount>/<type>-<shortcode>.md`                   |
+  | A content page's `url:`                | `/<package>/<type>-<shortcode>/`              | **unchanged**                                     |
+  | A `README.md` in the content tree      | its section's landing, addressed `<section>/` | an ordinary page, addressed `<type>-<shortcode>/` |
+  | A `doc` with no `subType`              | refused — "no section"                        | published, at `doc-<shortcode>/`                  |
+  | A `doc`'s `subType`                    | a genre, or a section address on a `README`   | a genre, closed to what the type declares         |
+  | `packageAddress(fm, { isReadme })`     | branched on the filename                      | a pure function of the frontmatter                |
+  | `sectionOf`                            | exported                                      | removed                                           |
+  | `declaredSections`                     | exported, fed the lint                        | removed — it had no other reader                  |
+  | `lintNote` / `lintFrontmatter` options | `landing`, `types`, `sections`                | removed                                           |
+  
+  **The closed-set check becomes meaningful again.** #206, released alongside this,
+  put a retired-spelling warning and an address-charset error ahead of it in
+  `checkSubType`; removing the section branch from underneath leaves three checks
+  in one order — retired spelling, then charset, then the genres the type declares
+  — with nothing widening the last of them. A `doc` note whose `subType` names a
+  content type is refused again, `README` or not.
+  
+  **`site.sections` is not retired — it is now the whole of what a section is.**
+  With no page filed into `<section>/`, nothing else makes
+  `/<package>/<prefix><section>/` exist at all, so `writeSectionLandings` stays and
+  its role changes from backfilling directories that pages created to _declaring_
+  the Hugo sections a site wants. Two consequences follow for a consuming site:
+  
+  - **Declare every section the site links to.** A card, menu entry or breadcrumb
+    pointing at an undeclared section is a 404.
+  - **A section landing lists no child pages.** Its directory holds only its own
+    `_index.md`, so a layout reading `.Pages` finds nothing; one that queries
+    `site.RegularPages` by `Params.type` is unaffected, and that is the shape a
+    content catalog wants anyway — it groups by what a page _is_, not by where its
+    file happened to be written.
+  
+  **`publish.address.landing` is inert, and still accepted.** Both publishing
+  consumers declare `landing: readme`, which stated something true when they wrote
+  it; refusing it now would break them over a correct statement, and silently
+  ignoring it would be worse. It selects nothing and is deleted once no
+  configuration writes it — the third step, and a separate change. The retired
+  `collection` value stays refused by name (#202).
+  
+  **Migration.** No note edit is required, and **no published URL moves** — an
+  address never contained a section. What a consuming site must check is its
+  layouts and its `site.sections`, per the two consequences above. Verified against
+  `sohl`, `sohl-thalorna` and `sohl-kethira-basic` at `origin/main`: `lint`,
+  `links`, `manifest` and `package compile` are byte-identical for all three (both
+  link manifests and every compiled pack document), and `sohl`'s emitted site is
+  byte-identical page for page, keyed by URL — all 1,606 addresses unchanged, 1,670
+  of 1,671 files identical. The one difference is a backfilled `kb/macro/_index.md`
+  that no longer exists, `macro` being the one section `sohl` did not declare;
+  nothing in its site or the shared theme links it.
+
+## 12.0.0
+
+### Major Changes
+
+- ab34b1c: Retire the `collection` landing rule, the `section:` frontmatter key it read,
+  and the `collection` doc subtype that selected it (#202). A section is landed by
+  the `README.md` in its directory, and that is now the only rule.
+  
+  **Why it goes.** Every publishing tree had already migrated: no note in `sohl`,
+  `sohl-thalorna` or `sohl-kethira-basic` declares `section:` or writes
+  `subType: collection`, and both publishing consumers configure `landing: readme`.
+  What was left was not merely unused but **unimplemented on one of the two sides
+  that must agree**. `engine/content-address.mjs` branched on the configured rule;
+  `engine/site-build.mjs` never read it — it derives `isReadme` from the basename
+  and treats a `README.md` as a landing whatever the configuration says. So under
+  `landing: collection` the link manifest and the emitted site would have disagreed
+  about where a page is, which is the single failure the shared address function
+  exists to prevent. With one rule they agree by construction.
+  
+  **`landing: collection` is refused, not merely unrecognized.** Reported as a bad
+  value it would read as a misspelling of the rule that survives, and an author
+  would correct the value rather than learn that the mechanism is gone. The
+  diagnostic names the key, says the rule is retired, says a section is landed by
+  its `README.md`, and says the `section:` key went with it — located to the line
+  and column in `package-build.config.yaml`, as every configuration finding is.
+  
+  **`section:` is refused the way `draft:`, `package:` and `aliases:` are.** It had
+  exactly one reader — the retired branch — and no schema or vocabulary declared
+  it, so nothing checked it: left in place it would be _ignored_, which reads to
+  its author as though it still works. It is now reported by `content-build lint`
+  and refused at compile, with the file, line and column.
+  
+  | Surface                          | Before                                | After                                  |
+  | -------------------------------- | ------------------------------------- | -------------------------------------- |
+  | `publish.address.landing`        | `readme` \| `collection`              | `readme` — the value is still accepted |
+  | `section:` in a note             | read under `collection`, else ignored | refused, at lint and at compile        |
+  | `subType: collection` on a `doc` | selected the rule                     | not a subtype the format declares      |
+  | `LANDING_RULES`                  | `["readme", "collection"]`            | `["readme"]`                           |
+  
+  **Migration.** Delete `landing: collection` from `publish.address` — or write
+  `landing: readme` — and make each section's landing the `README.md` in its
+  directory. Delete any `section:` a note still carries. A repository that already
+  configures `landing: readme` and writes no `section:` needs no change: `lint`,
+  `links` and `site` were verified byte-identical against `sohl`, `sohl-thalorna`
+  and `sohl-kethira-basic` at `origin/main`, including all 1,657 pages `sohl`
+  emits.
+  
+  **`publish.address.landing` itself survives, for now.** It is the key both
+  publishing consumers declare, and refusing a correct `landing: readme` would
+  break them over a statement that is still true. With one rule it selects nothing,
+  so it is a candidate for deletion once no configuration writes it — the third
+  step `package:` took (#56), and a separate change.
+
+### Minor Changes
+
+- ed06be0: Hold `type` and `subType` to the address charset, and rename a `doc`'s
+  `user-guide` subtype to `userguide` (#206).
+  
+  **The rule.** An address is `package-type-shortcode`, read back by counting
+  hyphen-separated segments, and that is sound for exactly one reason: no segment
+  may contain a hyphen. `ADDRESS_SEGMENT_PATTERN` (`^[A-Za-z0-9]+$`) stated it and
+  `SHORTCODE_PATTERN` aliased it, but only a **shortcode** was checked against it.
+  The other two values that reach an address were not: a `type` is the first
+  segment of every address, and a `doc`'s `subType` is the section it routes to —
+  a path segment of its own, and, under #204, a shortcode. Both are now held to
+  the same constant, read rather than restated; a third spelling of one rule is how
+  the disagreements found in #202 and #203 happened.
+  
+  **The diagnostic** is located where the value was written, in the standard form:
+  
+  ```text
+  assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a shortcode is held to. …
+  ```
+  
+  The charset is checked **ahead of** the closed-set check, which is what makes it
+  reach a type whose `subTypes` are declared but not yet enumerated (`being`) —
+  values nothing may otherwise claim to check.
+  
+  **`user-guide` became `userguide`**, the one declared value that broke the rule
+  and the only hyphenated `type` or `subType` in the vocabulary. A hyphenated
+  declaration can no longer be imported at all: the registry is checked against the
+  charset as `engine/note-vocabulary.mjs` loads.
+  
+  **The old spelling is accepted for one release, and says so.** A `doc` written
+  `subType: user-guide` is reported as a **warning** naming the note, the retired
+  value and its replacement, and the note still compiles:
+  
+  ```text
+  User_Guide/Actions.md:3:1: warning: `subType` "user-guide" is a retired spelling of "userguide" on a doc; write "userguide". …
+  ```
+  
+  _The ordering is the reverse of the usual, deliberately._ For a retired field the
+  sweep goes first; here it must go last. 43 `sohl` notes author `user-guide`
+  today, and declaring only the new spelling would invalidate all 43 with a release
+  they had no chance to sweep ahead of. So the acceptance ships first, consumers
+  rename, and a later change removes the acceptance — at which point the old
+  spelling falls through to the ordinary undeclared-value error with no code left
+  to remove. That later change is the breaking one; this one breaks nothing, which
+  is why it is a minor.
+  
+  **`type` gets no transitional path**, deliberately: no note in `sohl`,
+  `sohl-thalorna` or `sohl-kethira-basic` authors a hyphenated type, so an
+  acceptance would be dead code guarding a case that does not exist. Measured
+  against a pristine `origin/main` extraction of each tree, the only hyphenated
+  value of either key anywhere is the 43 `user-guide` notes.
+
 ## 11.1.0
 
 ### Minor Changes