@heroiclands/package-build 3.3.0 → 4.0.0

package/types/engine/base-compiler.d.mts

@@ -2,18 +2,17 @@
  * The tallies one pass accumulates while walking the tree.
  *
  * `declined` and `skippedOther` are deliberately separate numbers. A declined
- * note is one this build **refused** — it names a package this repository does
- * not compile — and it is an error; a skipped one legitimately belongs to
- * another pass, and there are thousands of those. Folding the first into the
- * second is what let a whole tree be filtered out in silence (#56).
+ * note is one this build **refused** — it declares a retired frontmatter field
+ * — and it is an error; a skipped one legitimately belongs to another pass, and
+ * there are thousands of those. Folding the first into the second is what let a
+ * whole tree be filtered out in silence (#56).
  *
  * @typedef {object} PassStats
  * @property {number} compiled - Notes that became a document.
- * @property {number} skippedDraft - Notes marked `draft: true`.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes refused because they declare another
- *   package. Counted as errors, never as skips.
+ * @property {number} declined - Notes refused because they declare a retired
+ *   frontmatter field. Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -310,20 +309,16 @@ export class BasePackCompiler {
  * The tallies one pass accumulates while walking the tree.
  *
  * `declined` and `skippedOther` are deliberately separate numbers. A declined
- * note is one this build **refused** — it names a package this repository does
- * not compile — and it is an error; a skipped one legitimately belongs to
- * another pass, and there are thousands of those. Folding the first into the
- * second is what let a whole tree be filtered out in silence (#56).
+ * note is one this build **refused** — it declares a retired frontmatter field
+ * — and it is an error; a skipped one legitimately belongs to another pass, and
+ * there are thousands of those. Folding the first into the second is what let a
+ * whole tree be filtered out in silence (#56).
  */
 export type PassStats = {
     /**
      * - Notes that became a document.
      */
     compiled: number;
-    /**
-     * - Notes marked `draft: true`.
-     */
-    skippedDraft: number;
     /**
      * - Notes with no `id`, where that is tolerated.
      */
@@ -333,8 +328,8 @@ export type PassStats = {
      */
     skippedOther: number;
     /**
-     * - Notes refused because they declare another
-     * package. Counted as errors, never as skips.
+     * - Notes refused because they declare a retired
+     * frontmatter field. Counted as errors, never as skips.
      */
     declined: number;
 };

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

@@ -12,8 +12,9 @@
  * `package:` frontmatter and the compilers kept the ones that matched. Every
  * content tree is single-package — each is single-sourced in the repository that
  * ships it — so the field restated this constant once per note while a value
- * that matched nothing filtered the whole tree out in silence. The field is
- * being retired; the value stays, here, where it is declared once.
+ * that matched nothing filtered the whole tree out in silence. That field is
+ * retired and declaring it now fails the build; this value stays, here, where
+ * it is declared once.
  *
  * Stable across compilation targets. If this content were ever compiled for a
  * second game system, it would still be published as `sohl` — only the Foundry

package/types/engine/helpers.d.mts

@@ -274,17 +274,15 @@ export function collectContentDocs(contentBase: string): Array<{
  * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
  * are resolved — so a generated cell may itself be a wikilink.
  *
- * A table searches only notes of the source note's own package, so a SoHL page
- * never tabulates setting-package content (and vice versa). Each candidate's
- * package is **derived** rather than read out of its frontmatter: `package:` is
- * optional, and comparing a declared value with an absent one would drop every
- * unswept — or every swept — note from the table (#56).
+ * A table searches the whole tree, which is one package's notes and nothing
+ * else — so there is no longer a package to scope on. It used to filter, back
+ * when a tree could hold several packages' notes and `package:` said which was
+ * which; that field is retired and the filter with it (#56).
  *
  * @param {string} body - The note's markdown body.
  * @param {object} ctx
  * @param {Array<object>} ctx.docs - From {@link collectContentDocs}.
  * @param {string} ctx.name - The note, for the error message.
- * @param {string} [ctx.pkg] - The source note's package.
  * @param {object} [ctx.fm] - The source note's frontmatter, which is what a
  *   query's `this` reads. Its entry in `docs` supplies the path as well.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,
@@ -297,10 +295,9 @@ export function collectContentDocs(contentBase: string): Array<{
  *   compile rather than shipping a table-shaped hole. The error carries
  *   `position`, the directive's own line.
  */
-export function expandNoteTables(body: string, { docs, name, pkg, fm, bodyLine }: {
+export function expandNoteTables(body: string, { docs, name, fm, bodyLine }: {
     docs: Array<object>;
     name: string;
-    pkg?: string | undefined;
     fm?: object | undefined;
     bodyLine?: number | undefined;
 }): {

package/types/engine/index.d.mts

@@ -6,6 +6,7 @@ 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 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/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

@@ -84,6 +84,16 @@ 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** (#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
+ * self-describing and makes sweeping the field out of a content tree
+ * output-preserving for a site as it already is for the packs.
+ *
  * @param {object} page - The page.
  * @param {object} options - `{ sections, readmeSections, decorate }`.
  * @returns {object} The frontmatter to write.