@heroiclands/package-build 22.0.1 → 22.0.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @heroiclands/package-build
 
+## 22.0.2
+
+### Patch Changes
+
+- 83fa58e: **A record states `attribution` and `license`, or it is a finding.** The nearest
+  provenance record is the whole answer and is never merged with the one above it,
+  so a key left out is not inherited — it is absent, and a record stating neither
+  would leave every file beneath it with no rights holder and no terms. `source`,
+  `ai` and `notes` stay optional, because blank is a truthful answer for each.
+
 ## 22.0.1
 
 ### Patch Changes

package/docs/api.md

@@ -567,13 +567,14 @@ The asset types — `icon`, `image` and `audio` — and the three roots they are
 
 The asset record: one line of the content index per addressable file. The record is emitted by the package holding the bytes, so its `path` is that package's path and each consumer joins its own root onto it — Foundry its data directory, the website its CDN prefix, the book its asset base.
 
-| Export                      | Signature                                                       | Returns                       | Use it when                                                                       |
-| --------------------------- | --------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
-| `ASSET_RECORD_FIELDS`       | `const ASSET_RECORD_FIELDS`                                     | `readonly AssetRecordField[]` | reading what an `asset` block carries, and where each field comes from            |
-| `PROVENANCE_KEYS`           | `const PROVENANCE_KEYS`                                         | `ReadonlySet<string>`         | validating a provenance file, whose keys are derived from the record's own fields |
-| `PROVENANCE_FILE`           | `const PROVENANCE_FILE`                                         | `string` — `provenance.yaml`  | naming the file a directory records provenance for its subtree in                 |
-| `PROVENANCE_SIDECAR_SUFFIX` | `const PROVENANCE_SIDECAR_SUFFIX`                               | `string` — `.yaml`            | naming a per-file record, which replaces an inherited one wholesale               |
-| `collectAssetRecords`       | `collectAssetRecords(assetsBase, { contentPackage, problems })` | `Array<Record<string, any>>`  | reading a package's asset roots into index records, without walking its notes     |
+| Export                      | Signature                                                       | Returns                       | Use it when                                                                                                                                             |
+| --------------------------- | --------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASSET_RECORD_FIELDS`       | `const ASSET_RECORD_FIELDS`                                     | `readonly AssetRecordField[]` | reading what an `asset` block carries, and where each field comes from                                                                                  |
+| `PROVENANCE_KEYS`           | `const PROVENANCE_KEYS`                                         | `ReadonlySet<string>`         | validating a provenance file, whose keys are derived from the record's own fields                                                                       |
+| `REQUIRED_PROVENANCE_KEYS`  | `const REQUIRED_PROVENANCE_KEYS`                                | `ReadonlySet<string>`         | the keys a provenance file must state — a record resolves wholesale, so one omitting them leaves every file it covers with no rights holder or no terms |
+| `PROVENANCE_FILE`           | `const PROVENANCE_FILE`                                         | `string` — `provenance.yaml`  | naming the file a directory records provenance for its subtree in                                                                                       |
+| `PROVENANCE_SIDECAR_SUFFIX` | `const PROVENANCE_SIDECAR_SUFFIX`                               | `string` — `.yaml`            | naming a per-file record, which replaces an inherited one wholesale                                                                                     |
+| `collectAssetRecords`       | `collectAssetRecords(assetsBase, { contentPackage, problems })` | `Array<Record<string, any>>`  | reading a package's asset roots into index records, without walking its notes                                                                           |
 
 ### `engine.packages`
 

package/docs/content-format.md

@@ -1508,6 +1508,17 @@ One address resolves its record in this order:
 3. Otherwise nothing, and the provenance fields are blank. A package that
    records no attribution is a fact to state, not a walk to fail.
 
+**The nearest record is the whole answer.** It is never merged with the one
+above it, so a record states every key it means to claim — which is what lets a
+reader open one file and know what the tree beneath it carries, instead of
+resolving a chain by hand.
+
+That is also why `attribution` and `license` are **required in any record that
+exists**: a key left out is not inherited from above, it is simply absent, so a
+record stating neither leaves every file it covers with no rights holder and no
+terms. Omitting one is a finding. `source`, `ai` and `notes` stay optional,
+because a blank is a truthful answer for each of them.
+
 #### A font is not an asset
 
 `assets/fonts` is not a root, and a font has no address.

package/engine/asset-index.mjs

@@ -88,6 +88,10 @@ export const PROVENANCE_SIDECAR_SUFFIX = ".yaml";
  * @property {string} name - The key inside `asset`.
  * @property {"walk"|"provenance"} from - Where the value comes from: the walk
  *   itself, or the provenance record resolved for the address.
+ * @property {boolean} [required] - Whether a provenance record that exists must
+ *   state this key. Omitting one is a finding rather than a blank, because a
+ *   record resolves wholesale: the nearest one is the whole answer, so a key it
+ *   leaves out is not inherited from above but simply absent.
  * @property {string} describe - One line, for the author-facing reference.
  */
 
@@ -119,6 +123,7 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "attribution",
         from: "provenance",
+        required: true,
         describe: "The person holding the rights, to whom attribution is legally due.",
     }),
     Object.freeze({
@@ -134,6 +139,7 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "license",
         from: "provenance",
+        required: true,
         describe: "The licence it is used under — an SPDX identifier, or terms.",
     }),
     Object.freeze({
@@ -159,6 +165,22 @@ export const PROVENANCE_KEYS = Object.freeze(
     ),
 );
 
+/**
+ * The keys a provenance file must state.
+ *
+ * Derived from {@link ASSET_RECORD_FIELDS} for the same reason the key set is:
+ * the rule and the record cannot disagree about which keys are required.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const REQUIRED_PROVENANCE_KEYS = Object.freeze(
+    new Set(
+        ASSET_RECORD_FIELDS.filter((field) => field.from === "provenance" && field.required).map(
+            (field) => field.name,
+        ),
+    ),
+);
+
 /**
  * Read one provenance file, reporting every key that is not a provenance key.
  *
@@ -218,6 +240,25 @@ function readProvenanceFile(file, findings) {
         }
         out[key] = value == null ? "" : String(value);
     }
+
+    // A record resolves wholesale — the nearest one is the whole answer, and no
+    // ancestor fills a key it leaves out. So an omitted `attribution` or
+    // `license` is not a value inherited from above; it is a file with no stated
+    // rights holder and no stated terms, which is the one thing a provenance
+    // record exists to prevent. Reported against the file rather than a line,
+    // because the fault is an absence and has no position.
+    for (const key of REQUIRED_PROVENANCE_KEYS) {
+        if (out[key]) continue;
+        findings.push({
+            file,
+            severity: "error",
+            message:
+                `a provenance record states \`${key}\`, and this one does not. ` +
+                "A record replaces rather than extends the one above it, so every " +
+                "file it covers would carry no " +
+                (key === "license" ? "licence" : key),
+        });
+    }
     return out;
 }
 
@@ -239,6 +280,9 @@ function inheritedProvenance(dir, root, cache, findings) {
     const own = path.join(dir, PROVENANCE_FILE);
     let answer;
     if (fs.existsSync(own)) {
+        // The nearest record is the whole answer. It is not merged with the one
+        // above it, so a record states every key it means to claim and a reader
+        // needs only the file in front of them to know what a file carries.
         answer = readProvenanceFile(own, findings);
     } else if (path.resolve(dir) === path.resolve(root)) {
         // The search stops at the type root: `assets/` above it is the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.0.1",
+    "version": "22.0.2",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/asset-index.d.mts

@@ -43,6 +43,10 @@ export const PROVENANCE_SIDECAR_SUFFIX: string;
  * @property {string} name - The key inside `asset`.
  * @property {"walk"|"provenance"} from - Where the value comes from: the walk
  *   itself, or the provenance record resolved for the address.
+ * @property {boolean} [required] - Whether a provenance record that exists must
+ *   state this key. Omitting one is a finding rather than a blank, because a
+ *   record resolves wholesale: the nearest one is the whole answer, so a key it
+ *   leaves out is not inherited from above but simply absent.
  * @property {string} describe - One line, for the author-facing reference.
  */
 /**
@@ -72,6 +76,15 @@ export const ASSET_RECORD_FIELDS: readonly AssetRecordField[];
  * @type {ReadonlySet<string>}
  */
 export const PROVENANCE_KEYS: ReadonlySet<string>;
+/**
+ * The keys a provenance file must state.
+ *
+ * Derived from {@link ASSET_RECORD_FIELDS} for the same reason the key set is:
+ * the rule and the record cannot disagree about which keys are required.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const REQUIRED_PROVENANCE_KEYS: ReadonlySet<string>;
 /**
  * One field of the `asset` block.
  */
@@ -85,6 +98,13 @@ export type AssetRecordField = {
      * itself, or the provenance record resolved for the address.
      */
     from: "walk" | "provenance";
+    /**
+     * - Whether a provenance record that exists must
+     * state this key. Omitting one is a finding rather than a blank, because a
+     * record resolves wholesale: the nearest one is the whole answer, so a key it
+     * leaves out is not inherited from above but simply absent.
+     */
+    required?: boolean | undefined;
     /**
      * - One line, for the author-facing reference.
      */