@heroiclands/package-build 3.4.0 → 5.0.0

package/types/engine/homepage.d.mts

@@ -0,0 +1,118 @@
+/**
+ * Whether a note's frontmatter declares the homepage type.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether it is a homepage note.
+ */
+export function isHomepage(fm: object | null | undefined): boolean;
+/**
+ * The title a homepage publishes under.
+ *
+ * The one defaulted value on the page, and it defaults to the package's own
+ * `packageBuild.manifest.title` — the name Foundry already shows for the
+ * package — so a homepage that adds nothing to it need not restate it. An
+ * authored `title` wins, because a front page is allowed to greet a reader
+ * differently from a package browser.
+ *
+ * Falls back to `contentPackage` last, so a package that has no manifest of its
+ * own still yields a titled page rather than a blank heading.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {object} config - The resolved configuration.
+ * @returns {string} The title.
+ */
+export function homepageTitle(fm: object | null | undefined, config: object): string;
+/**
+ * The frontmatter a homepage publishes with.
+ *
+ * The note's own, plus the two derived values every emitted page carries: the
+ * resolved `title`, and the package the build derived — no note declares one
+ * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * `.Params.package`.
+ *
+ * An authored `aliases` is dropped for the same reason it is on every other
+ * page: Obsidian reads it as names a reader might call the note, Hugo reads it
+ * as URL redirects, and passing it through would publish a redirect stub at
+ * each one.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package this build publishes.
+ * @param {string} options.title - The resolved title.
+ * @returns {object} The frontmatter to write.
+ */
+export function homepageFrontmatter(fm: object, { contentPackage, title }: {
+    contentPackage: string;
+    title: string;
+}): object;
+/**
+ * The package homepage — a note that compiles to a **page** rather than to a
+ * compendium document (#51).
+ *
+ * Every HeroicLands package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+ * and what a reader finds there is one markdown file in the content tree,
+ * written by a person: what the module is, which system it needs, how to install
+ * it, where its source lives. Nothing about it is derived.
+ *
+ * **Authored, not assembled.** An earlier sketch generated the page in tiers —
+ * identity and licence from the manifest, install URL from the release address,
+ * "requires" links from `relationships`, a card per configured section. It would
+ * have worked and needed almost no authoring, and it produces a page nobody
+ * chose the contents of. The things that matter most on these pages cannot be
+ * derived: that Kethira requires buying the book from Keléstia, what Thalorna's
+ * setting *is*, which of twenty sections a reader should start with. So the only
+ * thing defaulted here is the title, from `packageBuild.manifest.title`, so that
+ * the package's name is not written twice.
+ *
+ * **Dispatched by `type`, not by filename.** A fixed `homepage.md` the walker
+ * special-cased would be the anomaly: notes are routed by frontmatter, not by
+ * location, and `NOTE_SCHEMAS` already routes `doc`, `macro`, `being` and the
+ * map types. `homepage` is one more entry whose compile step emits a page. It is
+ * deliberately not `README.md`: `landing: readme` already means "a `README.md`
+ * is its section's landing page", and `sohl-thalorna/assets/content/README.md`
+ * is a developer explainer about the source tree — adopting that name would make
+ * Thalorna's public front page its build documentation.
+ *
+ * **Engine, not `sohl/`.** The `engine/` ÷ `sohl/` line separates *note-format*
+ * knowledge from *game-system* knowledge, and a homepage is note format: it
+ * carries no `system` block, mirrors no item builder, and would mean the same
+ * thing for a game system that is not SoHL. Reachability is the symptom that
+ * makes it obvious — `HarnMaster-3-FoundryVTT` declares no `itemBuilders`, so a
+ * type living in the SoHL registry would be unavailable to HM3 and to every HM3
+ * module, which is most of the packages that need a homepage and nothing else.
+ *
+ * **Its address is the package's, not the note's.** A homepage publishes at
+ * `/<contentPackage>/` because that is where the package is, so `name.full`,
+ * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
+ * module simply never reads them). It compiles into no document, so it carries
+ * no compendium UUID and appears in no pack and in no link-manifest entry.
+ *
+ * @module
+ */
+/**
+ * The note type that compiles to the package homepage.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_TYPE: string;
+/**
+ * What a homepage note may write under `sohl:` — nothing.
+ *
+ * Empty on purpose, and declared rather than omitted: a type with no vocabulary
+ * and a type that is unknown are different findings, and only the second is an
+ * authoring error. The whole envelope is the two top-level keys `type` and an
+ * optional `title`; there is no game-system data on a page that compiles to no
+ * document.
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
+/**
+ * Where a homepage is written, relative to the package's site root.
+ *
+ * Hugo's section landing, because the page *is* the package's landing: the
+ * package root is a section and this is its index.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_DESTINATION: string;

package/types/engine/index.d.mts

@@ -6,6 +6,9 @@ export * as packConfig from "./pack-config.mjs";
 export * as packRouter from "./pack-router.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
+export * as retiredFields from "./retired-fields.mjs";
+export * as homepage from "./homepage.mjs";
+export * as noteSchemas from "./note-schemas.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";

package/types/engine/manifest-emit.d.mts

@@ -37,14 +37,13 @@ export function entriesForNote(fm: object, name: string, address: string, body:
 /**
  * Every note this package publishes, as manifest entries.
  *
- * Drafts are excluded because the site does not publish them, and an entry for
- * an unpublished page is exactly the dead link the manifest exists to prevent.
- *
- * Every note in the tree is this package's note, whether or not it says so:
- * `package:` is optional and merely has to agree (#56). A note naming a
- * different package **throws** rather than being skipped — this build is not
- * authoritative for it, and skipping it silently is how a whole tree came to be
- * filtered out of a manifest that then claimed the package published nothing.
+ * Every note in the tree is this package's, so nothing here selects by package:
+ * the key's first segment is `contentPackage` (#56). A note still declaring the
+ * retired `package:` or `draft:` field **throws** rather than being skipped —
+ * skipping one silently is how a whole tree came to be filtered out of a
+ * manifest that then claimed the package published nothing, and it is what let
+ * a drafted note's inbound links look like links to a note that never existed
+ * (#69).
  *
  * A note that has no address is **reported, not guessed** — the finding carries
  * the file and the reason, so a caller can print it or fail on it. Inventing an

package/types/engine/note-package.d.mts

@@ -1,54 +1,49 @@
 /**
- * The package a note belongs to.
- *
- * Non-validating: the answer for a note that declares nothing, and for one that
- * declares the configured package, is the same value. A note declaring some
- * *other* package is answered literally here rather than corrected — the
- * compile pass reports that, once, through {@link assertNotePackage}.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {string} [configured] - The package this build compiles. Defaults to
- *   the configured `contentPackage`; passed explicitly by callers that already
- *   carry it in a context object, so a caller's configuration drives every read.
- * @returns {string} The package.
- */
-export function notePackage(fm: object | null | undefined, configured?: string): string;
-/**
- * A note's frontmatter as a generated table searches it — its package present
- * whether or not the note declares one.
+ * A note's frontmatter as a generated table searches it — its package present,
+ * though no note declares one.
  *
  * A `dataview` query resolves `package` out of frontmatter like any other
  * field, so a collection note that scopes itself with `WHERE … and package =
- * "sohl"` matches nothing once the field is deleted, and renders an **empty
- * table** in silence. Deriving the value here keeps the two spellings
- * equivalent, so a sweep that deletes the field is mechanical rather than a
- * trap (#56) — and a query that never mentions `package` is unaffected either
- * way.
+ * "sohl"` would match nothing now that the field is gone, and would render an
+ * **empty table** in silence. Supplying the derived value here is what kept the
+ * sweep mechanical rather than a trap (#56) — and a query that never mentions
+ * `package` is unaffected either way.
  *
- * The declared value is left alone when there is one, so nothing about an
- * unswept tree changes.
+ * The frontmatter is copied rather than written into: it is the note's own
+ * parsed object, shared with every other reader, and the derived package is a
+ * property of *this search*, not of the note.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
- * @param {string} [configured] - The package this build compiles.
- * @returns {object|null|undefined} The frontmatter itself when it declares a
- *   package, else a shallow copy carrying the derived one.
+ * @param {string} [configured] - The package this build compiles. Defaults to
+ *   the configured `contentPackage`; passed explicitly by callers that already
+ *   carry it in a context object, so a caller's configuration drives every read.
+ * @returns {object|null|undefined} A shallow copy carrying the derived package,
+ *   or whatever was passed when it is not frontmatter at all.
  */
 export function searchableFrontmatter(fm: object | null | undefined, configured?: string): object | null | undefined;
 /**
- * The package a note belongs to, refusing one that names another package.
+ * Refuse a note that declares `package:` at all.
  *
- * @param {object|null|undefined} fm - Parsed frontmatter.
+ * Presence is the whole test — a declaration that *agrees* with the
+ * configuration is as retired as one that disagrees, and an empty one
+ * (`package:`, which parses as `null`) is still the field.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
  * @param {object} [options] - Options.
  * @param {string} [options.file] - The note's path, named in the message. Omit
  *   it where the caller emits through a diagnostic, which puts the locator at
  *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
- * @returns {string} The package, which is always `configured`.
- * @throws {Error} When the note declares a different package.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
  */
-export function assertNotePackage(fm: object | null | undefined, { file, configured }?: {
+export function assertNoDeclaredPackage(fm: object | null | undefined, { file, absPath, configured }?: {
     file?: string | undefined;
+    absPath?: string | undefined;
     configured?: string | undefined;
-}): string;
+}): void;

package/types/engine/note-schemas.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+export const ENGINE_NOTE_SCHEMAS: Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>;

package/types/engine/pack-router.d.mts

@@ -46,9 +46,9 @@ export class PackRoutingError extends Error {
 /**
  * The frontmatter field a note declares its pack in.
  *
- * Deliberately close to the retiring `package:` and deliberately not the same
+ * Deliberately close to the retired `package:` and deliberately not the same
  * word: `package:` said which *distribution* owned a note — now the
- * repository's `contentPackage` (#56) — while `pack:` says which *compendium*
- * receives its document.
+ * repository's `contentPackage`, and no longer authorable (#56) — while `pack:`
+ * says which *compendium* receives its document.
  */
 export const PACK_FIELD: "pack";

package/types/engine/retired-fields.d.mts

@@ -0,0 +1,54 @@
+/**
+ * What a note declaring `draft:` is told, in one place.
+ *
+ * Written once and shared by the compile-time refusal and the frontmatter lint,
+ * because an author meets whichever of the two runs first and they should read
+ * the same. It says what the field did and what to write instead, rather than
+ * which value to correct: no value makes declaring it right.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function draftRetiredMessage(file?: string): string;
+/**
+ * Refuse a note that declares `draft:` at all.
+ *
+ * Presence is the whole test. `draft: false` is as retired as `draft: true` —
+ * it reads as "publish this note", which is what happens either way, and is
+ * exactly the belief the message exists to correct.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
+ */
+export function assertNoDraftField(fm: object | null | undefined, { file, absPath }?: {
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;
+/**
+ * A frontmatter key's position in a note's file, or nothing.
+ *
+ * {@link positionInFrontmatter} answers the same question from the file's
+ * *text*; this reads the file to ask it. Kept apart from either caller because
+ * both refusals need it and a second copy is a second thing to keep correct.
+ *
+ * @param {string|undefined} absPath - The note's file.
+ * @param {string} key - The top-level frontmatter key.
+ * @returns {{line?: number, column?: number}|undefined} Spreadable position
+ *   fields, dropped rather than guessed when the file cannot be read or the key
+ *   cannot be found — as `formatDiagnostic` requires.
+ */
+export function locateFrontmatterKey(absPath: string | undefined, key: string): {
+    line?: number;
+    column?: number;
+} | undefined;

package/types/engine/site-build.d.mts

@@ -41,6 +41,43 @@ export function collectTreePages(tree: object, ctx: object): {
     pages: object[];
     fmLinkFindings: object[];
 };
+/**
+ * The package's homepage notes — the authored page at `/<contentPackage>/`.
+ *
+ * A separate walk from {@link collectContentPages} rather than a branch inside
+ * it, because in homepage-only mode it is the **whole** of the site build: the
+ * content tree is never read for pages at all, so the licensing constraint two
+ * packages ship under is a property of the code path rather than of a
+ * configuration that happens to be empty (#55).
+ *
+ * Returned as a list rather than as the one note there should be. Requiring
+ * exactly one is #52's, and it is a separate decision — this reports what it
+ * found so a count is visible either way.
+ *
+ * @param {string} contentBase - Absolute path to the content tree.
+ * @param {object} ctx - `{ skipDirectories }`.
+ * @returns {{pages: object[]}} The homepage notes, in walk order.
+ */
+export function collectHomepages(contentBase: string, ctx: object): {
+    pages: object[];
+};
+/**
+ * Writes each homepage at the package's own root.
+ *
+ * Its own writer, deliberately small. A homepage is authored markdown published
+ * verbatim — no table expansion, no section landing, and (until #54) no link
+ * resolution — so routing it through {@link renderPages} would buy it a pipeline
+ * it has no input for, and would make homepage-only mode depend on the index,
+ * the foreign manifests and the table universe that mode exists to not build.
+ *
+ * @param {string} outRoot - The package's site root — the configured `site.out`,
+ *   one level above the content mount.
+ * @param {readonly object[]} pages - From {@link collectHomepages}.
+ * @param {object} config - The resolved configuration, for the package name and
+ *   the default title.
+ * @returns {number} How many pages were written.
+ */
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -63,6 +100,17 @@ export function collectTreePages(tree: object, ctx: object): {
  * @returns {object} The gate results and, when they pass, the built index.
  */
 export function siteGates(pages: object[], findings: object, { manifestDir }: object): object;
+/**
+ * The gate result of a build that ran none of them.
+ *
+ * Homepage-only publishes one authored page and resolves nothing, so every gate
+ * here is about a surface that mode does not have. The shape is returned all the
+ * same, because a caller reads the same fields whichever mode ran and a `null`
+ * would make each of them a special case.
+ *
+ * @returns {object} An all-clear gate result.
+ */
+export function emptyGates(): object;
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates: any): boolean;
 /**
@@ -84,10 +132,10 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * redirect stub at each name. They are dropped, and this build emits no
  * redirects of its own.
  *
- * A content page carries the package the build **derived**, whether or not the
- * note declared one (#65). `package:` became optional in 3.3.0, so a swept tree
- * declares none — and the note's frontmatter alone would then publish a page
- * that does not say which package it belongs to. The emitted page is what a
+ * A content page carries the package the build **derived** (#65). No note
+ * declares one — `package:` is retired (#56) — so the note's frontmatter alone
+ * would publish a page that does not say which package it belongs to. The
+ * emitted page is what a
  * theme reads: `breadcrumbs.html` builds its middle crumb from
  * `.Params.package`, so without it that crumb degrades from a linked, labelled
  * section to a bare type slug. Writing the derived value keeps a page

package/types/sohl/note-schemas.d.mts

@@ -2,6 +2,12 @@
  * Every content type this package compiles, and what a note of that type may
  * write.
  *
+ * The engine's own types are merged in first, so a SoHL tree is checked against
+ * one vocabulary rather than two. They are declared there rather than here
+ * because they are note-format knowledge — a `homepage` carries no `system`
+ * block and would mean the same thing for a game system that is not SoHL — and
+ * because a package declaring no `itemBuilders` never reaches this file (#51).
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const NOTE_SCHEMAS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;