@heroiclands/package-build 0.6.1 → 3.0.0

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

@@ -0,0 +1,47 @@
+/**
+ * Whether a value is a well-formed shortcode.
+ *
+ * A blank value is **not** valid here. Blank is handled separately wherever a
+ * key is derived from a document's name, so this predicate answers only "is
+ * this an acceptable key", never "is this key present".
+ *
+ * @param {unknown} value - The candidate shortcode.
+ * @returns {boolean} `true` when it matches {@link SHORTCODE_PATTERN}.
+ */
+export function isValidShortcode(value: unknown): boolean;
+/**
+ * Lint every address in a content tree.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names the walk
+ *   ignores. Defaults to the configured list.
+ * @returns {{findings: Array<{file: string, line?: number, column?: number,
+ *   severity: "error"|"warning", message: string}>, notes: number,
+ *   keys: number}} The findings, and what was inspected to produce them.
+ */
+export function lintContentTree(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line?: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+    notes: number;
+    keys: number;
+};
+/**
+ * The shape every `shortcode` must match: ASCII letters and digits only.
+ *
+ * Case is deliberately **not** constrained: hundreds of authored shortcodes are
+ * mixed-case and collide with nothing, so tightening that is a separate
+ * decision from this one.
+ *
+ * A consuming system's *runtime* keeps its own copy of this pattern — it cannot
+ * import a build-time dependency into shipped code — and is expected to pin the
+ * two together with a test rather than trust that they still agree.
+ */
+export const SHORTCODE_PATTERN: RegExp;

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

@@ -0,0 +1,36 @@
+/**
+ * The **content** package: the distribution unit a note declares in its
+ * `package:` frontmatter. The pack compilers select their entries by it.
+ *
+ * Stable across compilation targets. If this content were ever compiled for a
+ * second game system, its notes would still declare `package: sohl` — only the
+ * Foundry package below would differ.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {string} The configured `contentPackage`.
+ */
+export function contentPackage(): string;
+/**
+ * The **Foundry package** this repository's packs are shipped in — the `id` in
+ * `assets/templates/system.template.json`, and the first segment of every
+ * compendium UUID the compilers emit.
+ *
+ * Distinct from {@link contentPackage}, and equal to it only by coincidence
+ * here: a note says `package: sohl` and its documents are addressed as
+ * `Compendium.sohl.<pack>.<Type>.<id>`. In `sohl-thalorna` the two differ
+ * (`thalorna` vs `sohl-thalorna`), which is why they are separate values rather
+ * than one — treating them as interchangeable is what #1498 was.
+ *
+ * Configured rather than read from the manifest so the link resolver stays
+ * filesystem-free and unit-testable. `assertPackageIdMatchesManifestFile` in
+ * `package-manifest.mjs` — called from `generatePacksJson`, before any entry is
+ * written — fails the build if this value and the manifest's `id` ever drift.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {string} The configured `foundryPackage`.
+ */
+export function foundryPackageId(): string;

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

@@ -0,0 +1,59 @@
+/**
+ * The URL segment for one content note.
+ *
+ * The name is **transliterated** before it is reduced, so an accented character
+ * is carried across rather than dropped — dropping is what turned `Nüsvōrroth`
+ * into `n-sv-rroth` and forced a hand-written slug. Ligatures expand the way a
+ * reader would spell them out: `þ`→`th`, `æ`→`ae`, `œ`→`oe`, `ß`→`ss`, `ij`→`ij`,
+ * `fi`→`fi`, and eth (`ð`) follows the Icelandic convention of a bare `d`.
+ *
+ * Two reductions are ours rather than the transliterator's:
+ *
+ * - **apostrophes are removed**, not treated as separators (`Armorer's Kit` →
+ *   `armorers-kit`), matching the URLs these pages already publish at;
+ * - **a fraction keeps its digits together** — a vulgar fraction expands to
+ *   `3/4`, and the solidus would otherwise split it into `3-4`, so a slash
+ *   *between digits* is closed up (`Kûrbúl ¾-Helm` → `kurbul-34-helm`).
+ *
+ * @param {string | undefined} name - The note's display name (`name.full`),
+ *   which a malformed note may not have at all.
+ * @returns {string} The URL segment (never empty).
+ * @throws {Error} When there is no name, or the name carries no URL-safe
+ *   characters — either way the note cannot be addressed, which is a content
+ *   error rather than something to paper over with a fallback.
+ */
+export function slugify(text: any): string;
+/**
+ * The URL segment a content note publishes at.
+ *
+ * {@link slugify} with the rule that a document *must* be addressable: a note
+ * that yields no slug is a content error, not something to paper over with a
+ * fallback, because the alternative is a page nobody can reach.
+ *
+ * @param {string | undefined} name - The note's display name (`name.full`),
+ *   which a malformed note may not have at all.
+ * @returns {string} The URL segment (never empty).
+ * @throws {Error} When there is no name, or the name carries no URL-safe
+ *   characters.
+ */
+export function contentSlug(name: string | undefined): string;
+/**
+ * Find pages that would publish to the same URL.
+ *
+ * Nothing constrains two notes in one section from sharing a name, and a
+ * collision silently overwrites one page with the other. This turns it into a
+ * build failure that names every claimant, so the fix is a more specific title.
+ * (The content tree has no collisions today.)
+ *
+ * @param {Array<{sec: string, slug: string, src: string}>} pages
+ * @returns {Array<{url: string, sources: string[]}>} One entry per collision, in
+ *   first-claim order; empty when every URL is unique.
+ */
+export function findSlugCollisions(pages: Array<{
+    sec: string;
+    slug: string;
+    src: string;
+}>): Array<{
+    url: string;
+    sources: string[];
+}>;

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

@@ -0,0 +1,131 @@
+/**
+ * Parse one `dataview` block's query.
+ *
+ * @param {string} source - The query text (fences already stripped).
+ * @returns {{columns: Array<{header: string, expr: object}>, from: object|null,
+ *   where: object|null, sort: Array<{expr: object, descending: boolean}>,
+ *   limit: number|null}}
+ * @throws {Error} When the query is not a supported `TABLE` query — the message
+ *   names the offending clause, column, or token.
+ */
+export function parseDataviewQuery(source: string): {
+    columns: Array<{
+        header: string;
+        expr: object;
+    }>;
+    from: object | null;
+    where: object | null;
+    sort: Array<{
+        expr: object;
+        descending: boolean;
+    }>;
+    limit: number | null;
+};
+/**
+ * Resolve a dotted path against a content note. `file.*` names the note's place
+ * in the tree; everything else reads frontmatter, preferring a literal dotted
+ * key before walking the segments (the same precedence the pack compilers'
+ * `getFrontmatter` uses) — so **any** frontmatter property is addressable,
+ * however deeply nested.
+ *
+ * @param {ContentTableDoc} doc
+ * @param {string} path
+ * @returns {unknown} `null` when the note has no such field.
+ * @throws {Error} On an unknown `file.*` field, which would otherwise read as a
+ *   table that silently matches nothing.
+ */
+export function resolveField(doc: ContentTableDoc, path: string): unknown;
+/**
+ * Evaluate one parsed expression against a note.
+ *
+ * @param {object} node - From {@link parseDataviewQuery}.
+ * @param {ContentTableDoc} doc - The row being rendered.
+ * @param {ContentTableDoc} [self] - The note *containing* the query, which is
+ *   what `this` reads; absent means every `this.…` resolves to nothing.
+ * @returns {unknown}
+ */
+export function evaluate(node: object, doc: ContentTableDoc, self?: ContentTableDoc): unknown;
+/**
+ * The notes a query selects, in the order its `SORT` keys give. With no `SORT`
+ * the notes keep content-path order, and the note path (then its id) breaks any
+ * remaining tie, so the emitted table is byte-stable across builds regardless
+ * of directory-walk order.
+ *
+ * @param {object} spec - From {@link parseDataviewQuery}.
+ * @param {Array<ContentTableDoc>} docs
+ * @param {ContentTableDoc} [self] - The note containing the query (`this`).
+ * @returns {Array<ContentTableDoc>} The matching notes, sorted and limited.
+ */
+export function selectRows(spec: object, docs: Array<ContentTableDoc>, self?: ContentTableDoc): Array<ContentTableDoc>;
+/**
+ * Build the markdown table for one query.
+ *
+ * A `link(…)` cell — and the implicit `File` column — is emitted as a wikilink
+ * to the row's own note, which the caller's wikilink pass resolves; a note the
+ * caller reports as unlinkable (no shortcode, or a content directory that
+ * compiles into no pack) degrades to plain text. A column is right-aligned when
+ * every value it shows is numeric.
+ *
+ * @param {object} spec - From {@link parseDataviewQuery}.
+ * @param {Array<ContentTableDoc>} rows - From {@link selectRows}.
+ * @param {(doc: ContentTableDoc) => boolean} linkable - Can this note be linked to?
+ * @param {ContentTableDoc} [self] - The note containing the query (`this`).
+ * @returns {string} The markdown table (no trailing newline).
+ */
+export function renderContentTable(spec: object, rows: Array<ContentTableDoc>, linkable: (doc: ContentTableDoc) => boolean, self?: ContentTableDoc): string;
+/**
+ * Expand every fenced `dataview` block in a markdown body.
+ *
+ * A block that cannot be honoured — malformed or unsupported — is left in the
+ * body verbatim and reported in `errors`, so the failure is visible in the
+ * output as well as on the console. Every other code fence, and every code
+ * span, is left alone (that is how the syntax is documented).
+ *
+ * A query that matches **no** note is not an error: it renders as an empty
+ * table (headers only), which is what the author already sees in Obsidian, and
+ * a category with no content yet is a normal state of the corpus rather than a
+ * broken build.
+ *
+ * @param {string} markdown - The note body, frontmatter already stripped.
+ * @param {object} ctx
+ * @param {Array<ContentTableDoc>} ctx.docs - The searchable universe: every
+ *   content note the caller considers in scope.
+ * @param {(doc: ContentTableDoc) => boolean} [ctx.linkable] - Whether a note can
+ *   be linked to from a cell; defaults to never.
+ * @param {string} [ctx.source] - The note being expanded, for error reports.
+ * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
+ *   doc: what a query's `this` reads.
+ * @returns {{markdown: string, errors: Array<{source: string, directive: string,
+ *   reason: string, line: number}>, lineMap: Array<{line: number,
+ *   generated: boolean}>}} `lineMap` is parallel to the emitted lines and says
+ *   which authored line each came from, so a diagnostic about the expanded
+ *   body can name an authored position (#17). An `errors` entry carries the
+ *   0-based line of the directive that failed, for the same reason.
+ */
+export function expandContentTables(markdown: string, { docs, linkable, source, self }?: {
+    docs: Array<ContentTableDoc>;
+    linkable?: ((doc: ContentTableDoc) => boolean) | undefined;
+    source?: string | undefined;
+    self?: ContentTableDoc | undefined;
+}): {
+    markdown: string;
+    errors: Array<{
+        source: string;
+        directive: string;
+        reason: string;
+        line: number;
+    }>;
+    lineMap: Array<{
+        line: number;
+        generated: boolean;
+    }>;
+};
+/**
+ * One content note as a content build hands it to the expander: its parsed
+ * frontmatter plus its path below the content root, which backs the `file.*`
+ * fields.
+ */
+export type ContentTableDoc = {
+    fm: Record<string, any>;
+    path?: string;
+};

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

@@ -0,0 +1,12 @@
+/**
+ * Count the Markdown notes below a content tree.
+ *
+ * Only notes count. The per-pack folder manifests are not content, so a tree
+ * holding nothing but manifests counts zero — which is correct, because it
+ * compiles zero documents. Dot directories are skipped so stale editor caches
+ * cannot make an empty tree look populated.
+ *
+ * @param {string} root - Absolute path to the content tree.
+ * @returns {number} The number of `.md` notes, or 0 when the tree is absent.
+ */
+export function countContentNotes(root: string): number;

package/types/engine/diagnostics.d.mts

@@ -0,0 +1,152 @@
+/**
+ * The `file:line:column` locator, with whatever is known.
+ *
+ * The path is relativized against the working directory — during a build that
+ * is the consuming repository's root, so the result is both shorter to read
+ * and what an editor resolves a relative diagnostic against. A path outside
+ * the tree stays absolute, since a `../../..` locator helps nobody.
+ *
+ * @param {object} at
+ * @param {string} [at.file] - Absolute or relative path to the source file.
+ * @param {number} [at.line] - 1-based line.
+ * @param {number} [at.column] - 1-based column. Ignored without a line.
+ * @returns {string} The locator, or `""` when not even a file is known.
+ */
+export function formatLocator({ file, line, column }?: {
+    file?: string | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+}): string;
+/**
+ * One diagnostic, as a parseable line.
+ *
+ * @param {object} d
+ * @param {string} [d.file] - Source file the diagnostic is about.
+ * @param {number} [d.line] - 1-based line.
+ * @param {number} [d.column] - 1-based column.
+ * @param {"warning"|"error"} d.severity - Which of the two levels this is.
+ * @param {string} d.message - What is wrong, in one sentence.
+ * @returns {string} `file:line:column: severity: message`, with any unknown
+ *   leading field omitted.
+ */
+export function formatDiagnostic({ file, line, column, severity, message }: {
+    file?: string | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    severity: "warning" | "error";
+    message: string;
+}): string;
+/**
+ * Prints one diagnostic on the console, unprefixed.
+ *
+ * **Both severities go to stderr**, which is what keeps findings clear of the
+ * progress and summary prose a build writes to stdout. That is Node's doing,
+ * not a choice made here: `console.warn` is an alias for `console.error` and
+ * writes to `process.stderr`, so the two branches below differ only in which
+ * severity word the line carries, never in the stream.
+ *
+ * Saying otherwise has already cost something — an earlier version of this
+ * comment claimed warnings went to stdout, and a consumer wrote a whole
+ * local wrapper to obtain the stderr routing it already had. Anything relying
+ * on the separation should split on the `severity` field, not on the stream.
+ *
+ * This deliberately sidesteps `loglevel`, for the reason given in the module
+ * docs.
+ *
+ * @param {object} d - As {@link formatDiagnostic}.
+ * @returns {void}
+ */
+export function emitDiagnostic(d: object): void;
+/**
+ * Where a character offset within a note's **body** falls in its **file**.
+ *
+ * Three corrections separate the two, and each is applied only where it is
+ * true:
+ *
+ * 1. _The frontmatter._ A body offset is not a file line until the lines
+ *    before the body are added — `bodyLine`.
+ * 2. _The trimmed first line._ `parseMarkdownFile` trims the body, so its
+ *    first line may have lost indentation the file still has. `bodyColumn`
+ *    restores it, and only on that line.
+ * 3. _Generated text._ A body is scanned **after** its content tables expand,
+ *    so an offset may fall in text no one authored. `lineMap` maps each
+ *    scanned line back to the line it came from; a generated line reports the
+ *    directive that produced it and **no column**, since there is no authored
+ *    character to point at.
+ *
+ * @param {string} body - The text the offset indexes into.
+ * @param {number} offset - 0-based character offset within `body`.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - 1-based file line of the body's line 0.
+ * @param {number} [opts.bodyColumn=1] - 1-based file column of the body's
+ *   first character.
+ * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - Per
+ *   scanned line, the 0-based body line it came from. From
+ *   {@link expandContentTables}.
+ * @returns {{line: number, column: number|undefined, generated: boolean}}
+ */
+export function positionInBody(body: string, offset: number, { bodyLine, bodyColumn, lineMap }?: {
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+    lineMap?: {
+        line: number;
+        generated: boolean;
+    }[] | undefined;
+}): {
+    line: number;
+    column: number | undefined;
+    generated: boolean;
+};
+/**
+ * Where a **frontmatter key** is declared in a note's file.
+ *
+ * {@link positionInBody} answers the same question for the body, and the two
+ * are separate because the body is what the compilers scan while frontmatter is
+ * what the linters read — a key sits *before* the body, so a body offset can
+ * never reach it.
+ *
+ * The search is deliberately scoped to the frontmatter block rather than run
+ * over the whole file. A bare search for the key would match the first place
+ * the word appears anywhere, which for a key like `name` or `type` is routinely
+ * a line of prose — sending the reader to a position that is not the problem,
+ * which is the one thing the located form exists to prevent.
+ *
+ * @param {string} raw - The file's full contents, frontmatter included.
+ * @param {string} key - The top-level frontmatter key.
+ * @param {string} [value] - When given, prefer the occurrence whose line also
+ *   carries this text. A list-valued key (`aliases`) is reported at the entry
+ *   that is wrong, not at the key that introduces it.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when the key cannot be located — dropped rather than guessed, as
+ *   {@link formatDiagnostic} requires.
+ */
+export function positionInFrontmatter(raw: string, key: string, value?: string): {
+    line?: number;
+    column?: number;
+};
+/**
+ * Where a literal sits in a text, so a finding about it can be opened.
+ *
+ * {@link positionInBody} maps an offset within a parsed note body, and
+ * {@link positionInFrontmatter} finds a key in the fence. This is the plainer
+ * case: a finding about a string the reader can see in a file that is neither —
+ * a manifest, a lockfile, a config.
+ *
+ * `@heroiclands/package-build` carries the same arithmetic for the files *it*
+ * reads. That is a duplicate worth naming: unlike the diagnostic *format* or a
+ * validation *rule*, "which line and column is this substring on" has exactly
+ * one correct answer and cannot drift into disagreement. The tidier arrangement
+ * is for that package to re-export this one — the dependency runs that way — and
+ * it should, next time either is touched.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} needle - The literal to locate.
+ * @param {number} [occurrence] - Which occurrence, 1-based. Repeats of one
+ *   literal are otherwise indistinguishable.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when the literal is not there — dropped rather than guessed.
+ */
+export function positionOfLiteral(text: string, needle: string, occurrence?: number): {
+    line?: number;
+    column?: number;
+};

package/types/engine/field-reference.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Render the per-type item frontmatter reference.
+ *
+ * @param {object} [options] - Rendering options.
+ * @param {string} [options.title] - The page's H1.
+ * @param {string[]} [options.preamble] - Lines placed after the H1, before the
+ *   first type. Written by the consumer, since only it knows what its page
+ *   should link to.
+ * @param {string} [options.generatedBy] - What a reader should re-run to
+ *   regenerate the page, named in the do-not-edit banner.
+ * @param {object} [options.config] - Resolved configuration. Defaults to the
+ *   consumer's own.
+ * @returns {string} The complete markdown page.
+ */
+export function renderItemFieldReference({ title, preamble, generatedBy, config, }?: {
+    title?: string | undefined;
+    preamble?: string[] | undefined;
+    generatedBy?: string | undefined;
+    config?: object | undefined;
+}): string;

package/types/engine/field-spec.d.mts

@@ -0,0 +1,181 @@
+/**
+ * Write `value` at a dotted path, creating the intermediate objects.
+ *
+ * Insertion order is the emitted JSON's key order, so a declaration's order is
+ * the compiled document's order — which is what lets a field list replace a
+ * hand-written object literal without changing a single byte of output.
+ *
+ * @param {object} target - The object to write into (mutated).
+ * @param {string} dotted - Path, e.g. `"locations.flexible"`.
+ * @param {any} value - The value to set.
+ * @returns {object} `target`, for chaining.
+ */
+export function setPath(target: object, dotted: string, value: any): object;
+/**
+ * Read one declared field out of a note's frontmatter.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {object} fm - The note's frontmatter.
+ * @returns {any} The value to emit.
+ */
+export function readField(field: FieldSpec, fm: object): any;
+/**
+ * Turn a field declaration into the builder it declares.
+ *
+ * @param {readonly FieldSpec[]} fields - The declaration, in emission order.
+ * @returns {(fm: object) => object} A `system`-block builder.
+ */
+export function buildFromFields(fields: readonly FieldSpec[]): (fm: object) => object;
+/**
+ * The fields of a declaration an author actually writes.
+ *
+ * Constants and derived values are part of the emitted document but not part of
+ * the vocabulary, so every author-facing surface — the reference generator, a
+ * frontmatter linter, an unknown-key check — wants this list rather than the
+ * whole declaration.
+ *
+ * @param {readonly FieldSpec[]} fields - The declaration.
+ * @returns {FieldSpec[]} Only the fields with a frontmatter `name`.
+ */
+export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
+/**
+ * @typedef {object} FieldSpec
+ * @property {string} to - Dotted path in the emitted `system` block.
+ * @property {string} [name] - Frontmatter key under `sohl:`, dotted for a
+ *   nested one (`impact.die`). Absent means the value is not authored — see
+ *   `value`.
+ * @property {string} [shape] - Human-readable shape, for documentation. Comes
+ *   paired with `read` from one of the coercion constants below.
+ * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
+ *   How the raw frontmatter value becomes the emitted one. Identity if absent.
+ * @property {any} [default] - Emitted when the note does not carry the field.
+ * @property {boolean} [required] - Whether a note must carry it. A required
+ *   field's `read` is expected to throw when it is missing.
+ * @property {"string"|"number"|"boolean"|"list"|"map"} [kind] - The value's
+ *   shape, for the frontmatter linter (#19). Distinct from `shape`, which is
+ *   prose for a reader, and from `read`, which is what the compiler does: a
+ *   field may declare `kind` without changing a byte of what it emits, and
+ *   several do — `weight` is coerced leniently but is still a number, and
+ *   `weight: heavy` is an authoring mistake worth reporting where it was made.
+ *   Absent means the lint makes no claim about the value.
+ * @property {string} [ref] - The content type a value addresses by shortcode,
+ *   for the linter's dead-reference check. Only for references to a **note**:
+ *   `bodyLocationCode` names a part inside a being's own body structure, not a
+ *   note, so it declares none.
+ * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
+ *   the constant, or a function deriving it from the frontmatter.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/** Whatever the author wrote, unconverted. */
+export const AS_AUTHORED: Readonly<{
+    shape: "as authored";
+}>;
+/** Coerced with `String()`. */
+export const STRING: Readonly<{
+    shape: "string";
+    kind: "string";
+    read: (raw: any) => string;
+}>;
+/** Coerced with `Number()`, with a non-numeric or absent value reading `0`. */
+export const NUMBER: Readonly<{
+    shape: "number";
+    kind: "number";
+    read: (raw: any) => number;
+}>;
+/** Coerced with `Boolean()`. */
+export const BOOLEAN: Readonly<{
+    shape: "boolean";
+    kind: "boolean";
+    read: (raw: any) => boolean;
+}>;
+/**
+ * A number whose *absence* is meaningful: unset or blank ships `null`, and any
+ * other value goes through `Number()` unguarded (so a non-numeric one is
+ * `NaN`, not a silent `0` — an authoring mistake worth seeing).
+ */
+export const NULLABLE_NUMBER: Readonly<{
+    shape: "number or unset";
+    kind: "number";
+    read: (raw: any) => number | null;
+}>;
+/**
+ * A number whose absence is meaningful, but whose *value* is guarded: unset
+ * ships `null`, anything else reads as a number defaulting to `0`.
+ */
+export const NULLABLE_COUNT: Readonly<{
+    shape: "number or unset";
+    kind: "number";
+    read: (raw: any) => number | null;
+}>;
+/** Anything falsy — including a cleared `""` — ships `null`. */
+export const BLANK_IS_NULL: Readonly<{
+    shape: "as authored, blank is unset";
+    read: (raw: any) => any;
+}>;
+/** Anything falsy — including a cleared `""` — falls back to the default. */
+export const BLANK_IS_DEFAULT: Readonly<{
+    shape: "as authored, blank is the default";
+    read: (raw: any, { field }: {
+        field: any;
+    }) => any;
+}>;
+export type FieldSpec = {
+    /**
+     * - Dotted path in the emitted `system` block.
+     */
+    to: string;
+    /**
+     * - Frontmatter key under `sohl:`, dotted for a
+     * nested one (`impact.die`). Absent means the value is not authored — see
+     * `value`.
+     */
+    name?: string | undefined;
+    /**
+     * - Human-readable shape, for documentation. Comes
+     * paired with `read` from one of the coercion constants below.
+     */
+    shape?: string | undefined;
+    /**
+     * -
+     * How the raw frontmatter value becomes the emitted one. Identity if absent.
+     */
+    read?: ((raw: any, ctx: {
+        fm: object;
+        field: FieldSpec;
+    }) => any) | undefined;
+    /**
+     * - Emitted when the note does not carry the field.
+     */
+    default?: any;
+    /**
+     * - Whether a note must carry it. A required
+     * field's `read` is expected to throw when it is missing.
+     */
+    required?: boolean | undefined;
+    /**
+     * - The value's
+     * shape, for the frontmatter linter (#19). Distinct from `shape`, which is
+     * prose for a reader, and from `read`, which is what the compiler does: a
+     * field may declare `kind` without changing a byte of what it emits, and
+     * several do — `weight` is coerced leniently but is still a number, and
+     * `weight: heavy` is an authoring mistake worth reporting where it was made.
+     * Absent means the lint makes no claim about the value.
+     */
+    kind?: "string" | "number" | "boolean" | "map" | "list" | undefined;
+    /**
+     * - The content type a value addresses by shortcode,
+     * for the linter's dead-reference check. Only for references to a **note**:
+     * `bodyLocationCode` names a part inside a being's own body structure, not a
+     * note, so it declares none.
+     */
+    ref?: string | undefined;
+    /**
+     * - For a field with no `name`:
+     * the constant, or a function deriving it from the frontmatter.
+     */
+    value?: any | ((fm: object) => any);
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};