@heroiclands/package-build 17.1.0 → 18.0.0

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

@@ -0,0 +1,185 @@
+/**
+ * Every `sql` fence in a markdown body, with the position each occupies.
+ *
+ * Positions are 0-based lines into the body as given, which is what a diagnostic
+ * about a directive needs (#17) and what the expander uses to splice results
+ * back in.
+ *
+ * @param {string} markdown - The note body, frontmatter already stripped.
+ * @returns {Array<{line: number, close: number, indent: string, query: string,
+ *   allowEmpty: boolean, sectionLevel: number, block: string}>} One entry per
+ *   fence, in document order.
+ */
+export function findSqlBlocks(markdown: string): Array<{
+    line: number;
+    close: number;
+    indent: string;
+    query: string;
+    allowEmpty: boolean;
+    sectionLevel: number;
+    block: string;
+}>;
+/**
+ * Open a DuckDB view over the content index.
+ *
+ * The records are written as JSON Lines to a temporary file and read with
+ * `read_json_auto`, rather than inserted row by row, because that is what makes
+ * the queries readable: DuckDB infers a `STRUCT` for every nested object, so a
+ * note's `sohl.weight` and `name.full` are addressed in a query exactly as they
+ * are authored in the note. A column-per-path table would force
+ * `"sohl.weight"` in quotes, and a JSON column would force `sohl->>'weight'`.
+ *
+ * `union_by_name` is what makes that work across a heterogeneous corpus: a
+ * `sohl:` block differs by note type, and the inferred struct is the union of
+ * every type's fields, with `NULL` where a record does not have one.
+ *
+ * `threads=1` so a result is byte-identical between runs. Rows tied under the
+ * authored `ORDER BY` then fall back to the index's own order, which is itself
+ * deterministic — the index is emitted sorted and byte-stable.
+ *
+ * ## A dependency is a schema
+ *
+ * A package that depends on another can tabulate what it depends on —
+ * `FROM sohl.notes` — because each declared dependency's published index is
+ * attached as a **schema** named after the package, with this package's own
+ * notes staying at the unqualified `notes`.
+ *
+ * It is `FROM` rather than a fence property naming a file, for two reasons. A
+ * path in authored content is a build artifact's name written into the corpus,
+ * so renaming the artifact means sweeping every note that cites it — the
+ * coupling #126 exists to undo. And *which dataset a query reads* is what
+ * `FROM` is for: the same rule that keeps `_ref` and `_section` ordinary SQL,
+ * visible where an author is already looking, rather than fence options.
+ *
+ * It costs no fetch. Every dependency's JSONL is already in the metadata cache
+ * when a compile starts, because resolving addresses across packages needs it.
+ *
+ * @param {object[]} records - Content-index records, as
+ *   {@link module:engine/content-index.collectContentIndex} returns them.
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - Directory for the temporary file.
+ * @param {Array<{id: string, file: string}>} [opts.dependencies] - Each
+ *   declared dependency's cached index, attached as a schema named `id`.
+ * @returns {Promise<{query: (sql: string) => Promise<object[]>,
+ *   close: () => Promise<void>}>} The open database.
+ */
+export function openNotesDatabase(records: object[], { dir, dependencies }?: {
+    dir?: string | undefined;
+    dependencies?: {
+        id: string;
+        file: string;
+    }[] | undefined;
+}): Promise<{
+    query: (sql: string) => Promise<object[]>;
+    close: () => Promise<void>;
+}>;
+/**
+ * Run one authored query and shape its result for the renderer.
+ *
+ * @param {object} db - From {@link openNotesDatabase}.
+ * @param {string} sql - The query, as authored.
+ * @returns {Promise<{columns: string[], rows: object[]}>} The rendered columns
+ *   — every selected alias except the underscore-prefixed ones — and the rows.
+ */
+export function runSqlQuery(db: object, sql: string): Promise<{
+    columns: string[];
+    rows: object[];
+}>;
+/**
+ * Render one query's result as markdown.
+ *
+ * A `_ref` alias makes the row's **first rendered column** a wikilink to that
+ * address; the reference is dropped when nothing can be linked, so a table never
+ * ships a link that does not resolve. A `_section` alias splits the result into
+ * a headed table per distinct value, in the order the rows arrive — so the
+ * authored `ORDER BY` decides the section order too, and one query replaces the
+ * forty near-identical blocks the language used to require.
+ *
+ * @param {{columns: string[], rows: object[]}} result - From
+ *   {@link runSqlQuery}.
+ * @param {object} [opts]
+ * @param {(ref: string) => boolean} [opts.linkable] - Whether an address can be
+ *   linked to; defaults to linking any non-empty `_ref`.
+ * @param {number} [opts.sectionLevel=2] - Heading level for `_section`.
+ * @returns {string} The markdown.
+ */
+export function renderSqlTable(result: {
+    columns: string[];
+    rows: object[];
+}, { linkable, sectionLevel }?: {
+    linkable?: ((ref: string) => boolean) | undefined;
+    sectionLevel?: number | undefined;
+}): string;
+/**
+ * Run every `sql` directive in a set of note bodies, ahead of expansion.
+ *
+ * **Why a separate pass.** DuckDB's API is asynchronous and
+ * {@link module:engine/content-tables.expandContentTables} is not — nor should
+ * it become so: two of its three callers are synchronous, and one of those,
+ * `renderPages`, is exported. Preparing the results first keeps every one of
+ * those signatures intact, and it is the shape #243 is heading for anyway —
+ * the corpus enumerated once, each pass reading the answer rather than
+ * deriving it again.
+ *
+ * A query that fails is recorded rather than thrown, so one bad directive costs
+ * its own table and not the whole build's report.
+ *
+ * @param {object} db - From {@link openNotesDatabase}.
+ * @param {Array<{source: string, markdown: string}>} sources - The bodies to
+ *   scan.
+ * @param {object} [opts]
+ * @param {(ref: string) => boolean} [opts.linkable] - Passed to
+ *   {@link renderSqlTable}.
+ * **Keyed by note, then by the directive's ordinal within it** — not by its
+ * line. The passes do not agree on what a body is: `walkMarkdownTree` trims it,
+ * while the link checker strips the frontmatter fence and leaves the newlines
+ * that followed, so the same directive sits on different lines in each. Its
+ * position in the sequence of fences is the same in both.
+ *
+ * @returns {Promise<Map<string, object[]>>} Note to results, in document order,
+ *   each carrying either a rendered `markdown` and its `rows`, or a `reason`.
+ */
+export function prepareSqlTables(db: object, sources: Array<{
+    source: string;
+    markdown: string;
+}>, { linkable }?: {
+    linkable?: ((ref: string) => boolean) | undefined;
+}): Promise<Map<string, object[]>>;
+/**
+ * Answer every `sql` directive in a content tree.
+ *
+ * The one entry point each pass uses, so the compiler, the link checker and the
+ * site build cannot disagree about what a table selects — the failure mode #243
+ * describes, where N passes each derive the corpus their own way.
+ *
+ * **Nothing is opened for a tree with no `sql` directive.** The corpus is still
+ * written entirely in the retiring language, so until a table is converted this
+ * costs one walk and no database at all — which is what lets every pass call it
+ * unconditionally.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - Resolved configuration, defaulting to ambient.
+ * @param {readonly string[]} [opts.skipDirectories] - The walk's scope.
+ * @param {object[]} [opts.records] - Index records the caller already derived.
+ *   A command that also builds a link index holds them already, and deriving
+ *   them twice is the duplicated-corpus failure #243 is closing.
+ * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
+ *   nothing when the tree has no such directive.
+ */
+export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records }?: {
+    config?: object | undefined;
+    skipDirectories?: readonly string[] | undefined;
+    records?: object[] | undefined;
+}): Promise<Map<string, object[]> | undefined>;
+/**
+ * Aliases the renderer reads rather than printing.
+ *
+ * `_ref` is the note a row points at, as the `type-shortcode` address a wikilink
+ * resolves — `address.slug` in the index. `_section` partitions the result into
+ * headed tables.
+ */
+export const RENDER_ALIASES: Readonly<{
+    ref: "_ref";
+    section: "_section";
+}>;

package/types/engine/subtype-registry.d.mts

@@ -0,0 +1,49 @@
+/**
+ * The map one system ships, by its id.
+ *
+ * @param {string|undefined} system - The system id (`"sohl"`, `"hm3"`).
+ * @returns {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined} Its
+ *   map, or `undefined` where this toolchain ships none for it.
+ */
+export function subtypeMapFor(system: string | undefined): import("./document-subtypes.mjs").DocumentSubtypeMap | undefined;
+/**
+ * The document subtype a note type compiles into for one system — the
+ * translation the *schema* check needs, and the reason it needs one.
+ *
+ * A schema artifact is keyed by document subtype; a field declaration is keyed
+ * by note type. Those were the same string until #78 renamed three of them, and
+ * a check that went on joining them by name simply stopped reporting on
+ * `armorgear` — a warning that vanishes is worse than one that fires, because
+ * nothing says it went.
+ *
+ * Falls back to the note type on a one-to-many row, where nothing but a note
+ * can say which subtype is meant and this has none: that is the answer the
+ * identity default already gave, and HM3's four such rows all name the note
+ * type among their subtypes.
+ *
+ * @param {string|undefined} system - The system whose schema is being checked.
+ * @param {string} type - The note type a field declaration is keyed by.
+ * @returns {string} The document subtype to look up.
+ */
+export function schemaSubtypeOf(system: string | undefined, type: string): string;
+/**
+ * The note-type → document-subtype maps this toolchain ships.
+ *
+ * Two, since `hm3/` landed (#139) — and it joined this list rather than the
+ * claim table growing a second copy of the same fact, which is what the list
+ * was for.
+ *
+ * The union is what makes the vocabulary wider than any one repository's
+ * configuration: `armorlocation` is a real content type because HM3 maps it,
+ * however a given repository is configured, so a tree full of them is a
+ * repository that has not finished configuring itself rather than an author who
+ * invented a word.
+ *
+ * `engine/` importing from `sohl/` is the arrangement `generate.mjs` already
+ * has — its `COMPILERS` table names the SoHL compilers by class — and for the
+ * same reason: the engine owns the *mechanism* that asks each system what it
+ * compiles, and the systems own the answers.
+ *
+ * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
+ */
+export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[];

package/types/engine/system-block.d.mts

@@ -93,6 +93,27 @@ export function sharedProperty(fm: object, source: string, defaultValue?: any):
  * @returns {any} The value.
  */
 export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
+/**
+ * The key a field is authored at **inside** a system block — step 2.
+ *
+ * `legacyKey` when the field declares one, and `name` otherwise. The fallback
+ * is what makes this change invisible to every declaration written before it:
+ * a field whose shared source and in-block key are the same word says so once,
+ * as it always did.
+ *
+ * Named and exported rather than spelled inline because three readers ask the
+ * question and must agree — the resolver here, the frontmatter lint building
+ * the set of keys a block may carry, and the author-facing surfaces naming
+ * where a value was written.
+ *
+ * @param {{name?: string, legacyKey?: string}} field - The declaration.
+ * @returns {string|undefined} The in-block key, or `undefined` for a field that
+ *   is not authored at all.
+ */
+export function legacyKeyOf(field: {
+    name?: string;
+    legacyKey?: string;
+}): string | undefined;
 /**
  * Where a declared field's value came from.
  *
@@ -151,6 +172,24 @@ export function systemDataPaths(data: Record<string, unknown>, prefix?: string):
  * this is the difference between "the field is lost at load" and "the build
  * told you where".
  *
+ * **A declared *leaf* holds values, not fields.** A schema declares a path that
+ * has no children of its own for two ordinary reasons — a map with **dynamic
+ * keys** (`mystery.skillAptitudes` is skill selector → modifier) and a
+ * **TypedSchemaField** (`strikeModes`, discriminated by `type`) — and in both
+ * the contents are data an author wrote, not paths the schema names. Walking
+ * into one reports every entry as an undeclared field: one finding per skill
+ * aptitude, per strike mode, per standing.
+ *
+ * It stayed invisible while those maps were authored *outside* `<system>.system`
+ * and so were never walked. The moment the corpus moves them to the destination
+ * (#126) every one of them lights up — 62 findings on `sohl-thalorna` alone,
+ * none of them a defect.
+ *
+ * So descent is conditional on the schema declaring something *beneath* the
+ * path. `body.structure` declares `parts` and `zones`, so it is a real
+ * container and an undeclared `adjacent` under it is a real finding;
+ * `skillAptitudes` declares nothing beneath it, so what is beneath is a value.
+ *
  * @param {Record<string, unknown>} data - The authored `system` data.
  * @param {ReadonlySet<string>} declared - Every field path the schema declares
  *   for this subtype, inherited ones included.
@@ -265,7 +304,7 @@ export const BLOCK_DIRECTIVES: readonly string[];
 /**
  * Every key any system block may carry, whatever the system.
  *
- * A system adds its own on top — `archetype`, `kbcat` and the generators — and
+ * A system adds its own on top — `templatePriority`, `kbcat` and the generators — and
  * names them where it declares its vocabulary; see {@link unknownBlockKeys}.
  *
  * @type {ReadonlySet<string>}

package/types/engine/systems.d.mts

@@ -0,0 +1,106 @@
+/**
+ * Whether a value names a game system this toolchain knows.
+ *
+ * `none` is rejected: it is a real answer to "which system", but it is not a
+ * system, and a pack, a document-subtype map or a compiler table keyed by it
+ * would be keyed by nothing.
+ *
+ * @param {unknown} value - The candidate id.
+ * @returns {boolean} `true` when {@link SYSTEM_IDS} declares it.
+ */
+export function isSystemId(value: unknown): boolean;
+/**
+ * Whether a value is something the `<system>` segment may hold.
+ *
+ * The predicate an address parser wants: a declared system, or `none`.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @returns {boolean} `true` when {@link SYSTEM_SEGMENTS} declares it.
+ */
+export function isSystemSegment(value: unknown): boolean;
+/**
+ * What a caller writing an unknown system is told.
+ *
+ * Separate from {@link assertSystemSegment} so that a pass collecting findings
+ * can report the same sentence it would have thrown — the message is the part
+ * worth sharing, and a reporter that had to invent its own wording is how two
+ * halves of a build come to explain one rule two ways.
+ *
+ * The nullish case is called out by name because it is the likely mistake and
+ * the least legible failure: a YAML `null`, a `~`, or a key written with no
+ * value at all reaches here as `undefined`, and "expected one of sohl, hm3,
+ * none" would leave a reader hunting for the value they cannot see.
+ *
+ * @param {unknown} value - The offending value.
+ * @param {string} [where] - What carried it, for the message — a note path, a
+ *   configuration key, an address.
+ * @returns {string} The message, with no trailing period, in the style of the
+ *   other vocabulary messages.
+ */
+export function unknownSystemMessage(value: unknown, where?: string): string;
+/**
+ * Refuse a value the `<system>` segment may not hold.
+ *
+ * Throws rather than returning a finding, matching the nearest neighbour —
+ * `assertVocabularyCharset` in `engine/note-vocabulary.mjs`, and the
+ * `configFromData` validators — because every caller of this is validating a
+ * declaration rather than surveying content. A note's bad value belongs in a
+ * report; a build asking to route, address or compile an undeclared system has
+ * nowhere to continue to.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @param {string} [where] - What carried it, for the message.
+ * @returns {string} The value, unchanged, so a caller may validate inline.
+ * @throws {Error} Naming the value and the whole known vocabulary.
+ */
+export function assertSystemSegment(value: unknown, where?: string): string;
+/**
+ * Refuse a registry declaring an id that could not be an address segment.
+ *
+ * Run over {@link SYSTEM_SEGMENTS} as this module loads, so a declaration that
+ * breaks the charset cannot be imported, let alone shipped. Same reasoning as
+ * `assertVocabularyCharset`: a bad value in one note is one author's mistake,
+ * while a bad *declaration* puts an unreadable segment into every address that
+ * names the system.
+ *
+ * @param {Iterable<string>} segments - The declared ids, including `none`.
+ * @param {string} [where] - What declares them, for the message.
+ * @throws {Error} Naming every offending id at once — a reader fixing a list
+ *   wants the whole list.
+ */
+export function assertSystemCharset(segments: Iterable<string>, where?: string): void;
+/**
+ * The `<system>` segment of a note that belongs to no system.
+ *
+ * Most notes are that: a `doc`, a `place`, a `macro` or a map compiles into a
+ * JournalEntry, a Scene or a Macro, which Foundry defines and no game system
+ * does. `none` is the format's word for it, in the address and in the content
+ * index alike, so the two say "no system" the same way.
+ *
+ * @type {string}
+ */
+export const NO_SYSTEM: string;
+/**
+ * Every game system this toolchain compiles for.
+ *
+ * The registry, and the only place the list is written down. Adding a system
+ * is an edit to this set plus the map and compilers that make it real — a data
+ * change, not a search for every place a name was spelled.
+ *
+ * `none` is **not** a member: it marks the absence of a system, and a caller
+ * asking "is this a system" and a caller asking "is this a well-formed
+ * segment" want different answers. See {@link isSystemId} and
+ * {@link isSystemSegment}.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_IDS: ReadonlySet<string>;
+/**
+ * Everything the `<system>` segment of an address may say.
+ *
+ * The systems, plus {@link NO_SYSTEM}. Derived from the registry rather than
+ * listed again, so the two cannot drift.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_SEGMENTS: ReadonlySet<string>;

package/types/engine/web-wikilinks.d.mts

@@ -32,8 +32,10 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *
  * **Every target is an address**, parsed by {@link readQualifier} and looked up
  * case-insensitively in the KB-wide `ctx.index` (the canonical
- * `package-type-shortcode`, `type/shortcode`, and the site's own
- * `section/slug`), then in the vendored `ctx.foreign` manifests. A link written
+ * `package-system-type-shortcode`, `type/shortcode`, and the site's own
+ * `section/slug`), then in the vendored `ctx.foreign` manifests. A target is a
+ * *partial* address: an omitted package means this package, an omitted system
+ * is a wildcard, and exactly one match resolves — two are `ambiguous`. A link written
  * without a label addresses nothing at all and is reported as such (#180) —
  * there is no second namespace left for it to name.
  *

package/types/engine/wikilink-syntax.d.mts

@@ -77,11 +77,11 @@ export function unlabelledLinkMessage(target: string): string;
  *
  * **Both corrections, because the author cannot tell which applies.** An
  * address lands nowhere either because the shortcode is wrong or because the
- * package publishing it has no manifest vendored here, and the link itself
- * looks identical in the two cases.
+ * package publishing it is not a declared dependency — or is one whose index
+ * has not been fetched — and the link itself looks identical in every case.
  *
  * This used to be a **warning** in the checker and, in the site build, nothing
- * at all until every linkable package had vendored a manifest — on the
+ * at all until every linkable package's manifest was accounted for — on the
  * reasoning that a bare `[[Name]]` might be a placeholder for a note nobody had
  * written yet. That reasoning was a property of the bare form, which is retired
  * (#180); the intent behind it now has a real spelling, a `draft`-tagged note
@@ -101,6 +101,13 @@ export function unresolvedAddressMessage(target: string): string;
  * message names the claimants so the author can choose between them without
  * going looking.
  *
+ * **The correction is the canonical form**, all four segments (#59). Omission
+ * runs strictly left to right, so there is no `package-type-shortcode` to offer
+ * — naming a package means naming the system before the type. That used to be
+ * the correction here, back when a written target could state three segments at
+ * most; the grammar is positional now, and a three-segment target names a
+ * *system*, not a package.
+ *
  * @param {string} target - The address as authored.
  * @param {Iterable<string>} [packages] - The packages that publish it.
  * @returns {string} The message.

package/types/engine/wikilinks.d.mts

@@ -31,31 +31,58 @@ export function resolveItemDocType(qualifier: string, types: Set<string>): strin
  * Two separators are accepted, and they are **not** interchangeable in how
  * confidently they mark a target as qualified:
  *
- * - **`type-shortcode`** — the canonical form (#1398). Obsidian reads `/` inside
- *   a wikilink as a *path* and resolves it against the vault's folders, so a
- *   slash-qualified link is a broken link in the editor where the content is now
- *   authored. A hyphen qualifies **only when what precedes it is a known type**:
- *   note names contain hyphens too (`Grukar-ahk`), and a target that is one is
- *   reported as not an address rather than split at an arbitrary place. The
- *   split is at the **first** hyphen, so a shortcode may itself contain one
- *   (`trauma-self-pro` → `trauma` + `self-pro`).
+ * - **`type-shortcode`** and its qualified forms — the canonical spelling
+ *   (#1398). Obsidian reads `/` inside a wikilink as a *path* and resolves it
+ *   against the vault's folders, so a slash-qualified link is a broken link in
+ *   the editor where the content is now authored.
  * - **`type/shortcode`** — the legacy form, still resolved so that a link
  *   written before the vault migrated does not silently die. A slash is
  *   *unconditionally* a qualifier: nothing else uses one, so an unknown type
  *   before it is reported rather than guessed at. The split is at the **last**
  *   slash, as it always was.
  *
- * A leading **package** segment is optional and outermost: `sohl-skill-lang` is
- * `skill-lang` in the `sohl` package. It is read only when `packages` is given
- * and names the segment, and only when the remainder is itself a valid address,
- * so a note called "Grukar-ahk" is not mistaken for one (#1499).
+ * **The grammar is strict, and omission runs left to right** (#59):
+ *
+ * ```text
+ * [[[[<package>-]<system>-]<type>-]<shortcode>]
+ * ```
+ *
+ * So the written forms are exactly the suffixes of the canonical address —
+ * `type-shortcode`, `system-type-shortcode`, `package-system-type-shortcode` —
+ * and **`package-type-shortcode` is not one of them**. A link into another
+ * package must therefore be fully qualified, which is the price of the segment
+ * being positional rather than tagged.
+ *
+ * **Parsing is plain positional counting**, the same rule
+ * {@link readCanonicalKey} follows, and it is sound for the same reason: every
+ * segment is `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced on
+ * shortcodes by `content-lint.mjs` since #1397), so the hyphen is purely a
+ * separator and the count alone determines every field. Verified across the
+ * four content trees: 138,204 authored shortcodes, none carrying a separator.
+ *
+ * That replaced a first-hyphen split which let a shortcode contain a hyphen
+ * (`trauma-self-pro` → `trauma` + `self-pro`). The tolerance predates #1397 and
+ * outlived it; no tree has used it, and keeping it would make a three-segment
+ * target ambiguous between a system and a hyphenated shortcode.
+ *
+ * **`sohl` is both a package and a system**, and positional counting is what
+ * makes that harmless: three segments is `<system>-<type>-<shortcode>` whatever
+ * the first segment could also have named, and four is the full form. Nothing
+ * has to guess which sense was meant.
+ *
+ * **A partial address states what it states, and the rest is not invented.** An
+ * omitted **system** is a *wildcard* — most links target items, which belong to
+ * a system — so the caller matches on the segments supplied and requires
+ * exactly one hit. An omitted **package** is instead *defaulted* to the citing
+ * note's own, so an unqualified link resolves locally and only locally.
  *
  * @param {string} target - The link target, anchor already removed.
  * @param {Set<string>} types - Every type the content tree contains.
  * @param {Set<string>} [packages] - Every package an address may name. Omitted
  *   by callers that resolve within one package, where the form cannot occur.
  * @returns {{type: string, shortcode: string, itemDoc: boolean,
- *   package?: string, reason?: undefined} | {reason: "unknown-type"} | null}
+ *   package?: string, system?: string, reason?: undefined}
+ *   | {reason: "unknown-type"} | null}
  *   The resolved qualifier; a `reason` when the target is definitely qualified
  *   but names no known type; or `null` when it is not an address at all.
  */
@@ -64,6 +91,7 @@ export function readQualifier(target: string, types: Set<string>, packages?: Set
     shortcode: string;
     itemDoc: boolean;
     package?: string;
+    system?: string;
     reason?: undefined;
 } | {
     reason: "unknown-type";

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

@@ -0,0 +1,107 @@
+/**
+ * The shared rule set, as an ESLint flat configuration.
+ *
+ * **Deliberately narrow, for the same reason the markdown and stylesheet rule
+ * sets are** — Prettier already owns YAML's whitespace, quoting and line
+ * breaks, including inside a frontmatter fence, so a rule about any of those
+ * would either duplicate the formatter or fight it. What is left is the class
+ * the formatter cannot see: text that parses to something other than what it
+ * looks like.
+ *
+ * - **A parse error is reported, not swallowed.** A duplicate key, a tab used
+ *   as indentation, a mapping whose items start at different columns: the YAML
+ *   parser detects all three and `parseMarkdownFile` discards all three.
+ * - `no-empty-mapping-value` — `folder:` and `folder: null` parse identically
+ *   and read as opposites: one is a decision, the other is a key somebody began
+ *   and did not finish. YAML cannot tell them apart, so the distinction has to
+ *   be made where the text still exists. A key with a block under it is not
+ *   empty, which is what separates 65 unfinished keys in `sohl-thalorna` from
+ *   the tens of thousands that are ordinary containers.
+ * - `no-irregular-whitespace` — a non-breaking space in a key or an unquoted
+ *   scalar is invisible in every editor and changes the value.
+ * - `no-empty-key`, `no-empty-document` — a fence or a file that parses to
+ *   nothing at all.
+ *
+ * **GitHub workflows are exempt from `no-empty-mapping-value`**, because an
+ * empty value is the language there: `on:` `push:` and `workflow_dispatch:`
+ * carry their meaning by being present, and writing `push: null` to satisfy a
+ * linter would be worse YAML, not better.
+ *
+ * @param {object} plugin - The `eslint-plugin-yml` module.
+ * @returns {object[]} A complete flat config, for `overrideConfig`.
+ */
+export function yamlLintConfig(plugin: object): object[];
+/**
+ * The files to lint: every YAML file git would consider, and no other.
+ *
+ * `--cached --others --exclude-standard` is tracked files plus untracked ones
+ * that are not ignored, which is the same set `gitignore: true` gives the
+ * markdown linter — and it matters more than it sounds. Asking ESLint for
+ * `**\/*.md` in `Song-of-Heroic-Lands-FoundryVTT` offers it 60,792 files, almost
+ * all of them inside `nogit/` and `.claude/worktrees/`; this offers 1,888, in
+ * 20ms. Untracked-but-not-ignored is included so a note gets linted while it is
+ * being written, not only once it has been staged.
+ *
+ * `-z` because git otherwise quotes any path outside ASCII, and these trees are
+ * full of them.
+ *
+ * @param {string} root - Repository root.
+ * @param {readonly string[]} [globs] - Path globs, defaulting to
+ *   {@link YAML_GLOBS}.
+ * @returns {string[]} Repository-relative paths.
+ */
+export function candidateFiles(root: string, globs?: readonly string[]): string[];
+/**
+ * Lint a repository's YAML against the shared rule set.
+ *
+ * ESLint is run through its Node API with `overrideConfigFile: true`, which
+ * stops it looking for an `eslint.config.js` at all. That is what lets this ship
+ * as a command rather than as a configuration a consumer has to adopt: a
+ * repository needs no ESLint of its own, and one that *has* an ESLint — as
+ * `Song-of-Heroic-Lands-FoundryVTT` does, for `src/` — keeps it untouched and
+ * unconsulted.
+ *
+ * @param {string} root - Repository to lint.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.paths] - Globs to lint instead of every
+ *   YAML file git would consider.
+ * @param {object} [opts.plugin] - The `eslint-plugin-yml` module, for tests.
+ * @param {Function} [opts.ESLint] - The `ESLint` class, for tests.
+ * @returns {Promise<{findings: object[], checked: number}>} The findings, and
+ *   how many files were linted.
+ */
+export function lintYaml(root: string, opts?: {
+    paths?: readonly string[] | undefined;
+    plugin?: object | undefined;
+    ESLint?: Function | undefined;
+}): Promise<{
+    findings: object[];
+    checked: number;
+}>;
+/** File extensions that carry YAML, either wholly or in a frontmatter fence. */
+export const YAML_GLOBS: readonly string[];
+/**
+ * Present a markdown file to ESLint as the YAML it begins with.
+ *
+ * An ESLint *processor* carves virtual files out of a container file — the
+ * mechanism `eslint-plugin-markdown` uses for fenced code blocks. Frontmatter is
+ * the easy case of it: the block is always at the top of the file, so mapping a
+ * finding back to the file it came from is a constant `+1` for the opening
+ * `---`, with no offset table to keep.
+ *
+ * The virtual file is named `0.yaml` so the flat config's `**` + `*.yaml`
+ * patterns select it; ESLint addresses it as `<the note>.md/0.yaml`.
+ *
+ * @type {{meta: object, supportsAutofix: boolean,
+ *   preprocess: (text: string) => Array<{text: string, filename: string}>,
+ *   postprocess: (messages: object[][]) => object[]}}
+ */
+export const frontmatterProcessor: {
+    meta: object;
+    supportsAutofix: boolean;
+    preprocess: (text: string) => Array<{
+        text: string;
+        filename: string;
+    }>;
+    postprocess: (messages: object[][]) => object[];
+};