@heroiclands/package-build 7.0.0 → 8.0.0

package/types/engine/schema-check.d.mts

@@ -0,0 +1,176 @@
+/**
+ * A system's published field sets.
+ *
+ * @typedef {object} SchemaArtifact
+ * @property {number} version - {@link SCHEMA_ARTIFACT_VERSION}.
+ * @property {string} system - The system id the schemas belong to.
+ * @property {string} systemVersion - The system version they were read from.
+ * @property {Record<string, Record<string, {own: string[], inherited: string[]}>>} documents
+ *   Document type → subtype → its field paths, dotted for nested schema fields.
+ */
+/**
+ * Why `own` and `inherited` are recorded apart.
+ *
+ * A subtype's schema spreads its parent's — `MysticalAbilityDataModel` spreads
+ * `SohlItemDataModel`, which spreads the common one — so `notes`, `docHtml` and
+ * the rest arrive on every subtype. Those are the system's own runtime
+ * concerns, filled by the system rather than by a content builder, and a
+ * builder is not expected to emit them.
+ *
+ * Collapsing the two sets would make the *declared, not emitted* direction
+ * report every inherited field on every type: a wall of findings that are all
+ * correct and none actionable, which is the shape of report people learn to
+ * skip. So the two directions read different sets:
+ *
+ * | direction | read against | severity |
+ * | --- | --- | --- |
+ * | emitted, not declared | `own` ∪ `inherited` — the field must exist *somewhere* | error |
+ * | declared, not emitted | `own` only — what this subtype adds is what its builder answers for | report |
+ *
+ * @param {SchemaArtifact} artifact - The published schemas.
+ * @param {string} documentType - `Item`, `Actor`, …
+ * @param {string} subtype - The document subtype.
+ * @returns {{own: Set<string>, all: Set<string>}|null} The sets, or `null` when
+ *   the artifact declares no such subtype.
+ */
+export function declaredFields(artifact: SchemaArtifact, documentType: string, subtype: string): {
+    own: Set<string>;
+    all: Set<string>;
+} | null;
+/**
+ * Every `system` path a field declaration can emit.
+ *
+ * `buildFromFields` writes each field at its `to`, so the declaration is the
+ * emitted key set. A nested `to` (`charges.value`) is recorded whole, and its
+ * parents are recorded too: a schema declares `charges` as a `SchemaField` and
+ * the path beneath it separately, so a comparison that knew only the leaf would
+ * report the container as unemitted and the leaf as undeclared.
+ *
+ * @param {readonly {to: string}[]} fields - A type's field declaration.
+ * @returns {Set<string>} The paths, parents included.
+ */
+export function emittedFields(fields: readonly {
+    to: string;
+}[]): Set<string>;
+/**
+ * Compare one system's builders against one system's published schemas.
+ *
+ * Pure: field declarations in, findings out. The caller supplies both halves so
+ * that a system checking itself and a module checking against a vendored
+ * artifact run the identical comparison.
+ *
+ * @param {object} opts
+ * @param {Record<string, readonly {to: string}[]>} opts.builders - Type →
+ *   field declaration, as `ITEM_FIELDS` holds it.
+ * @param {SchemaArtifact} opts.artifact - The receiving system's schemas.
+ * @param {string} [opts.documentType="Item"] - Which document type the builders
+ *   compile into.
+ * @param {(type: string) => string} [opts.subtypeOf] - Maps a builder's type to
+ *   the document subtype it emits. Defaults to identity, which is what the
+ *   coincidence of names amounts to today (#79) — stated as a seam so that the
+ *   explicit map replaces a default rather than a hard-coded assumption.
+ * @returns {{undeclared: object[], unemitted: object[], skipped: string[]}}
+ *   `undeclared` fails a build; `unemitted` is reported; `skipped` names the
+ *   types the artifact says nothing about.
+ */
+export function compareFields({ builders, artifact, documentType, subtypeOf, }: {
+    builders: Record<string, readonly {
+        to: string;
+    }[]>;
+    artifact: SchemaArtifact;
+    documentType?: string | undefined;
+    subtypeOf?: ((type: string) => string) | undefined;
+}): {
+    undeclared: object[];
+    unemitted: object[];
+    skipped: string[];
+};
+/**
+ * The published schema this build should check itself against, or `null`.
+ *
+ * **Which system, and which version, are already settled.** `stats.systemId`
+ * and `stats.systemVersion` are derived rather than authored (#48) — a system
+ * package is its own system, and a module takes the one it requires — and the
+ * version is the `compatibility.verified` it pins. So the question "whose
+ * schema, at what version" has one answer here rather than a second set of
+ * configuration to disagree with the first.
+ *
+ * Two places to find it, because a system checks itself against source it owns
+ * while a module checks against a dependency it fetched:
+ *
+ * - **A system**: its own `schema.json`, generated from its `src/` and
+ *   committed beside it.
+ * - **A module**: the copy cached by `content-build deps fetch`, from the
+ *   archive of the version it pins — which is what makes the comparison happen
+ *   at `verified` rather than against whatever the system's `main` holds today.
+ *   That distinction is the whole of the `affiliation.subType` case.
+ *
+ * `null` where there is nothing to check against: a system-agnostic module
+ * stamps no system at all, and a system that has not adopted the artifact yet
+ * is simply unchecked. Neither is an error, and the caller says which it was.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {{artifact: SchemaArtifact, source: string}|null} The schema and
+ *   where it was read from.
+ */
+export function resolveSchemaArtifact(config: object): {
+    artifact: SchemaArtifact;
+    source: string;
+} | null;
+/**
+ * What an author is told about a field the target system does not define.
+ *
+ * Names the version, because the same field may be perfectly well defined on
+ * the system's `main` and simply unreleased — which is exactly the kethira case,
+ * and the difference between "you typed it wrong" and "you are ahead of your
+ * pin".
+ *
+ * @param {object} finding - One entry from `undeclared`.
+ * @returns {string} The message.
+ */
+export function undeclaredMessage(finding: object): string;
+/**
+ * What an author is told about a declared field no builder writes.
+ *
+ * Advisory rather than fatal: a field the system fills at runtime, or one added
+ * ahead of the content that will use it, is not a defect. Only fields the
+ * subtype declares *itself* are reported — see {@link declaredFields}.
+ *
+ * @param {object} finding - One entry from `unemitted`.
+ * @returns {string} The message.
+ */
+export function unemittedMessage(finding: object): string;
+/**
+ * The artifact version this module reads.
+ *
+ * A mismatch stops the check rather than resolving anyway: a schema read under
+ * the wrong shape would report confident nonsense in both directions, and a
+ * silently skipped check is the state #60 exists to leave.
+ *
+ * @type {number}
+ */
+export const SCHEMA_ARTIFACT_VERSION: number;
+/**
+ * A system's published field sets.
+ */
+export type SchemaArtifact = {
+    /**
+     * - {@link SCHEMA_ARTIFACT_VERSION}.
+     */
+    version: number;
+    /**
+     * - The system id the schemas belong to.
+     */
+    system: string;
+    /**
+     * - The system version they were read from.
+     */
+    systemVersion: string;
+    /**
+     *   Document type → subtype → its field paths, dotted for nested schema fields.
+     */
+    documents: Record<string, Record<string, {
+        own: string[];
+        inherited: string[];
+    }>>;
+};

package/types/engine/schema-extract.d.mts

@@ -0,0 +1,61 @@
+/**
+ * The `subtype: ClassName` entries of a registry object literal.
+ *
+ * @param {ts.SourceFile} src - The parsed file holding the registry.
+ * @param {string} name - The registry binding, e.g. `itemModels`.
+ * @returns {Map<string, string>} Subtype to DataModel class name.
+ */
+export function registryOf(src: ts.SourceFile, name: string): Map<string, string>;
+/**
+ * The `tsconfig.json` path aliases, read rather than restated.
+ *
+ * A TypeScript repository may import every DataModel through `@src/…`, so a
+ * resolver that understood only relative specifiers would find none of them.
+ * Reading the mapping means adding an alias there does not silently make a
+ * subtype unreadable here.
+ *
+ * Absent for a JavaScript repository, which is not an error — it simply has no
+ * aliases to resolve.
+ *
+ * @param {string} rootDir - The repository root.
+ * @returns {[string, string][]} Prefix to directory, longest prefix first.
+ */
+export function pathAliases(rootDir: string): [string, string][];
+/**
+ * Resolve one subtype's schema into own and inherited field paths.
+ *
+ * @param {object} opts - Resolution inputs.
+ * @param {string} opts.file - The file naming the class (registry or importer).
+ * @param {string} opts.className - The DataModel class.
+ * @param {[string, string][]} opts.aliases - From {@link pathAliases}.
+ * @param {Map<string, ts.SourceFile>} opts.cache - The per-run parse memo.
+ * @param {string} opts.rootDir - For readable error paths.
+ * @returns {{own: string[], inherited: string[]}}
+ */
+export function fieldsForClass({ file, className, aliases, cache, rootDir }: {
+    file: string;
+    className: string;
+    aliases: [string, string][];
+    cache: Map<string, ts.SourceFile>;
+    rootDir: string;
+}): {
+    own: string[];
+    inherited: string[];
+};
+/**
+ * Build the whole artifact from a package's source.
+ *
+ * @param {object} opts - Inputs.
+ * @param {string} opts.rootDir - The repository root.
+ * @param {object[]} opts.registries - `{documentType, from, registry}` entries.
+ * @param {string} opts.packageId - The Foundry package id.
+ * @param {string} opts.version - The package version.
+ * @returns {object} The artifact `schema-check.mjs` reads.
+ */
+export function buildSchemaArtifact({ rootDir, registries, packageId, version, }: {
+    rootDir: string;
+    registries: object[];
+    packageId: string;
+    version: string;
+}): object;
+import ts from "typescript";