@heroiclands/package-build 22.0.0 → 22.0.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+- d049b3e: **A provenance record may state `ai`.** It says whether the file is
+  machine-generated, and like every provenance key it is optional — a record that
+  omits it is unchanged, and nothing reads it yet. It exists so a package can
+  record the fact where the fact belongs, rather than in a key that means
+  something else.
+  
+  **`attribution` is the person, not the tool.** It names whoever holds the rights
+  and is legally due the credit. Its description said a tool could go there, which
+  is what `ai` is for.
+
 ## 22.0.0
 
 ### Major 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

@@ -1465,8 +1465,9 @@ nothing about itself, compiles into no document, and publishes no page, so the
 | `asset` field | Source     | What it says                                                       |
 | ------------- | ---------- | ------------------------------------------------------------------ |
 | `path`        | the walk   | Where the file sits inside the emitting package's asset directory. |
-| `attribution` | provenance | Who made the file, or what tool generated it.                      |
+| `attribution` | provenance | The person holding the rights, to whom attribution is legally due. |
 | `source`      | provenance | Where it came from — a URL, or a sentence.                         |
+| `ai`          | provenance | Whether the file is machine-generated — `true` or `false`.         |
 | `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.       |
 | `notes`       | provenance | Anything else a person reading the attribution needs.              |
 
@@ -1490,10 +1491,10 @@ the two are distinct — they are equal in the system only by coincidence, and i
 
 ##### Where provenance comes from
 
-A `provenance.yaml` states `attribution`, `source`, `license` and `notes`, and
-nothing else: an unknown key is a finding rather than a silent drop, because
-`licence` beside `license` is otherwise an attribution record that looks
-complete and carries nothing.
+A `provenance.yaml` states the provenance fields in the table above, and nothing
+else: an unknown key is a finding rather than a silent drop, because `licence`
+beside `license` is otherwise an attribution record that looks complete and
+carries nothing.
 
 One address resolves its record in this order:
 
@@ -1507,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,16 +123,23 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "attribution",
         from: "provenance",
-        describe: "Who made the file, or what tool generated it.",
+        required: true,
+        describe: "The person holding the rights, to whom attribution is legally due.",
     }),
     Object.freeze({
         name: "source",
         from: "provenance",
         describe: "Where it came from — a URL, or a sentence.",
     }),
+    Object.freeze({
+        name: "ai",
+        from: "provenance",
+        describe: "Whether the file is machine-generated — `true` or `false`.",
+    }),
     Object.freeze({
         name: "license",
         from: "provenance",
+        required: true,
         describe: "The licence it is used under — an SPDX identifier, or terms.",
     }),
     Object.freeze({
@@ -154,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.
  *
@@ -213,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;
 }
 
@@ -234,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.0",
+    "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/packagebuild-metadata.jsonl

@@ -1,13 +1,13 @@
-{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","source":""},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-armorclothingbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","source":""},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-attributebnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","source":""},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-containerbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","source":""},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-devdocsbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","source":""},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-miscgearbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","source":""},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-mysticalabilitybnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","source":""},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-projectilebnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","source":""},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-rulesbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","source":""},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-skillbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","source":""},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-traumabnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","source":""},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-userguidebnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","source":""},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-weapongearbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","source":""},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","source":""},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-armorclothingbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","source":""},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-attributebnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","source":""},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-containerbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","source":""},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-devdocsbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","source":""},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-miscgearbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","source":""},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-mysticalabilitybnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","source":""},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-projectilebnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","source":""},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-rulesbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","source":""},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-skillbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","source":""},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-traumabnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","source":""},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-userguidebnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","source":""},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-weapongearbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","source":""},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}

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.
      */