@pagefront/lint-commerce 0.12.0 → 0.13.0

package/dist/rules/col-e-004.js

@@ -0,0 +1,19 @@
+import { UNKNOWN_RELEASE, unknownRelease } from "./release-schema.js";
+/**
+ * COL-E-004 — Unknown release.
+ * The collection-sheet counterpart of PDP-E-018 and ORG-E-004.
+ * Transcribed from commerce/spec/rules.md (normative); the check is
+ * shared (release-schema.ts).
+ *
+ * `appliesFrom` is "0.0.0": the rule judges the declared release
+ * itself, so it cannot be gated by it. It never fires on a sheet of a
+ * published release.
+ */
+export const colE004 = {
+    id: "COL-E-004",
+    ...UNKNOWN_RELEASE,
+    check: unknownRelease,
+    introduced: "release 0.5.0",
+    appliesFrom: "0.0.0",
+    specReference: "collection.md#the-envelope",
+};

package/dist/rules/col-e-005.d.ts

@@ -0,0 +1,16 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-E-005 — Referenced sheet URL off its edge's host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A collection sheet and the sheets it references in `hasPart` and
+ * `isPartOf` share a host (collection.md, "Identity"): a member's
+ * `pagefront:sheetUrl` is checked against the *canonical host*. The
+ * `brand` reference of a brand collection resolves under the brand edge
+ * of the organization linking contract, as PDP-E-006 checks it on a
+ * product sheet: against the host of the brand's `@id`. A hint with no
+ * host (a blank string among them) is treated as absent and skipped:
+ * a blank member hint is COL-W-002's finding. One finding per hint, at
+ * the `pagefront:sheetUrl` path.
+ */
+export declare const colE005: Rule;

package/dist/rules/col-e-005.js

@@ -0,0 +1,64 @@
+import { asRecord, matchedField, memberEntries } from "./col-shared.js";
+import { hostOf, renderHost } from "./sheet-url-host.js";
+/**
+ * COL-E-005 — Referenced sheet URL off its edge's host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A collection sheet and the sheets it references in `hasPart` and
+ * `isPartOf` share a host (collection.md, "Identity"): a member's
+ * `pagefront:sheetUrl` is checked against the *canonical host*. The
+ * `brand` reference of a brand collection resolves under the brand edge
+ * of the organization linking contract, as PDP-E-006 checks it on a
+ * product sheet: against the host of the brand's `@id`. A hint with no
+ * host (a blank string among them) is treated as absent and skipped:
+ * a blank member hint is COL-W-002's finding. One finding per hint, at
+ * the `pagefront:sheetUrl` path.
+ */
+export const colE005 = {
+    id: "COL-E-005",
+    title: "Referenced sheet URL off its edge's host",
+    severity: "error",
+    target: "$.data['hasPart','isPartOf','brand']",
+    check: (match, ctx) => {
+        const field = matchedField(match.path);
+        const hits = [];
+        if (field === "brand") {
+            const brand = asRecord(match.value);
+            if (brand === null)
+                return null;
+            // A value with no host (a blank string among them) is treated as absent.
+            const urlHost = hostOf(brand["pagefront:sheetUrl"]);
+            if (urlHost === null)
+                return null;
+            const idHost = hostOf(brand["@id"]);
+            if (urlHost === idHost)
+                return null;
+            return {
+                path: `${match.path}['pagefront:sheetUrl']`,
+                values: {
+                    sheetUrlHost: renderHost(urlHost),
+                    expected: `the brand's \`@id\` is on \`${renderHost(idHost)}\``,
+                },
+            };
+        }
+        const canonicalHost = hostOf(ctx.sheet.canonical_url);
+        for (const { entry, path } of memberEntries(match.value, match.path)) {
+            const urlHost = hostOf(entry["pagefront:sheetUrl"]);
+            if (urlHost === null || urlHost === canonicalHost)
+                continue;
+            hits.push({
+                path: `${path}['pagefront:sheetUrl']`,
+                values: {
+                    sheetUrlHost: renderHost(urlHost),
+                    expected: `the canonical page is on \`${renderHost(canonicalHost)}\``,
+                },
+            });
+        }
+        return hits;
+    },
+    messageTemplate: "Sheet URL at `{path}` is on host `{sheetUrlHost}`; {expected}.",
+    remediation: "Point `pagefront:sheetUrl` at the sheet on the host the edge requires: a member or parent sheet on the storefront host, a brand sheet on the host of the brand's `@id`. A consumer rejects a hint off that host and falls back to the entry's `url`.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#identity",
+};

package/dist/rules/col-shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers for the Commerce Collection Sheet rules
+ * (COL-E-001 … COL-W-006). Kept local to the collection rules: the
+ * member-entry walk and the kind enum are collection-catalogue
+ * vocabulary, not engine machinery.
+ */
+/** The closed enum of `pagefront:collectionKind`, in vocabulary order. */
+export declare const COLLECTION_KINDS: readonly ["category", "collection", "brand"];
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/** A string value that is present and not empty or whitespace-only. */
+export declare function nonBlank(value: unknown): value is string;
+/**
+ * The entries of a member array (`hasPart`, `isPartOf`,
+ * `itemListElement`) with their normalized paths. A matched value that
+ * is a single object is one entry at the match path; a non-object
+ * entry is skipped, since the schema types entries as objects.
+ */
+export declare function memberEntries(value: unknown, path: string): Array<{
+    entry: Record<string, unknown>;
+    path: string;
+}>;
+/** The entry's `name` for a message, or the fixed fallback. */
+export declare function entryName(entry: Record<string, unknown>): string;
+/** The field a match path ends in: `$['data']['hasPart']` → `hasPart`. */
+export declare function matchedField(path: string): string;

package/dist/rules/col-shared.js

@@ -0,0 +1,43 @@
+/**
+ * Shared helpers for the Commerce Collection Sheet rules
+ * (COL-E-001 … COL-W-006). Kept local to the collection rules: the
+ * member-entry walk and the kind enum are collection-catalogue
+ * vocabulary, not engine machinery.
+ */
+/** The closed enum of `pagefront:collectionKind`, in vocabulary order. */
+export const COLLECTION_KINDS = ["category", "collection", "brand"];
+export function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A string value that is present and not empty or whitespace-only. */
+export function nonBlank(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/**
+ * The entries of a member array (`hasPart`, `isPartOf`,
+ * `itemListElement`) with their normalized paths. A matched value that
+ * is a single object is one entry at the match path; a non-object
+ * entry is skipped, since the schema types entries as objects.
+ */
+export function memberEntries(value, path) {
+    const raw = Array.isArray(value)
+        ? value.map((entry, i) => ({ entry, path: `${path}[${i}]` }))
+        : [{ entry: value, path }];
+    const out = [];
+    for (const { entry, path: p } of raw) {
+        const record = asRecord(entry);
+        if (record !== null)
+            out.push({ entry: record, path: p });
+    }
+    return out;
+}
+/** The entry's `name` for a message, or the fixed fallback. */
+export function entryName(entry) {
+    return typeof entry["name"] === "string" ? entry["name"] : "(unnamed)";
+}
+/** The field a match path ends in: `$['data']['hasPart']` → `hasPart`. */
+export function matchedField(path) {
+    return /\['([^']+)'\]$/.exec(path)?.[1] ?? "";
+}

package/dist/rules/col-w-001.d.ts

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-W-001 — Empty `hasPart`.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An empty array is valid (a node whose assignments all live in its
+ * children, or that holds nothing); the warning asks for review, since
+ * an emission pipeline that lost the members produces the same shape.
+ * An absent `hasPart` is Layer 1's concern.
+ */
+export declare const colW001: Rule;

package/dist/rules/col-w-001.js

@@ -0,0 +1,21 @@
+/**
+ * COL-W-001 — Empty `hasPart`.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An empty array is valid (a node whose assignments all live in its
+ * children, or that holds nothing); the warning asks for review, since
+ * an emission pipeline that lost the members produces the same shape.
+ * An absent `hasPart` is Layer 1's concern.
+ */
+export const colW001 = {
+    id: "COL-W-001",
+    title: "Empty hasPart",
+    severity: "warning",
+    target: "$.data.hasPart",
+    check: (match) => (Array.isArray(match.value) && match.value.length === 0 ? {} : null),
+    messageTemplate: "`hasPart` at `{path}` is empty: the set declares no direct members.",
+    remediation: "Confirm the set has no direct members (its products all live in subcategories, or it holds nothing). If the storefront assigns products or subcategories to this node, list them.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#members",
+};

package/dist/rules/col-w-002.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-W-002 — Member entry without `pagefront:sheetUrl`.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * The hint is recommended on every member entry: a producer that emits
+ * both sheets knows the URL, and without it a consumer reaches the
+ * member sheet through its page. The hint is an optimisation that MAY
+ * be stale; the rule asks for its presence and never checks that it
+ * resolves. One finding per entry, at the entry's path.
+ */
+export declare const colW002: Rule;

package/dist/rules/col-w-002.js

@@ -0,0 +1,31 @@
+import { entryName, memberEntries, nonBlank } from "./col-shared.js";
+/**
+ * COL-W-002 — Member entry without `pagefront:sheetUrl`.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * The hint is recommended on every member entry: a producer that emits
+ * both sheets knows the URL, and without it a consumer reaches the
+ * member sheet through its page. The hint is an optimisation that MAY
+ * be stale; the rule asks for its presence and never checks that it
+ * resolves. One finding per entry, at the entry's path.
+ */
+export const colW002 = {
+    id: "COL-W-002",
+    title: "Member entry without pagefront:sheetUrl",
+    severity: "warning",
+    target: "$.data.hasPart",
+    check: (match) => {
+        const hits = [];
+        for (const { entry, path } of memberEntries(match.value, match.path)) {
+            if (nonBlank(entry["pagefront:sheetUrl"]))
+                continue;
+            hits.push({ path, values: { name: entryName(entry) } });
+        }
+        return hits;
+    },
+    messageTemplate: "Member `{name}` at `{path}` carries no `pagefront:sheetUrl`; consumers must reach its sheet via `url` + `alternate`.",
+    remediation: "Add `pagefront:sheetUrl` with the member's sheet URL when you emit that sheet. If the member has no sheet, the entry is complete as it stands.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#members",
+};

package/dist/rules/col-w-004.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-W-004 — Brand reference and brand kind disagree.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A `brand` collection is keyed on a `Brand` node and carries `brand`;
+ * a `category` or `collection` is not. Either half missing is the
+ * kind-without-content / content-without-kind pattern the organization
+ * catalogue checks for roles (ORG-W-001 … ORG-W-004). The finding sits
+ * at the data block either way.
+ */
+export declare const colW004: Rule;

package/dist/rules/col-w-004.js

@@ -0,0 +1,37 @@
+import { asRecord } from "./col-shared.js";
+/**
+ * COL-W-004 — Brand reference and brand kind disagree.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A `brand` collection is keyed on a `Brand` node and carries `brand`;
+ * a `category` or `collection` is not. Either half missing is the
+ * kind-without-content / content-without-kind pattern the organization
+ * catalogue checks for roles (ORG-W-001 … ORG-W-004). The finding sits
+ * at the data block either way.
+ */
+export const colW004 = {
+    id: "COL-W-004",
+    title: "Brand reference and brand kind disagree",
+    severity: "warning",
+    target: "$.data",
+    check: (match) => {
+        const data = asRecord(match.value);
+        if (data === null)
+            return null;
+        const kind = data["pagefront:collectionKind"];
+        const brand = data["brand"];
+        const hasBrand = brand !== undefined && brand !== null;
+        if (kind === "brand" && !hasBrand) {
+            return { values: { problem: "declares `pagefront:collectionKind` `brand` but carries no `brand`" } };
+        }
+        if (kind !== "brand" && hasBrand && typeof kind === "string") {
+            return { values: { problem: `carries \`brand\` but declares \`pagefront:collectionKind\` \`${kind}\`` } };
+        }
+        return null;
+    },
+    messageTemplate: "Collection at `{path}` {problem}.",
+    remediation: "On a brand collection, add `brand`, the reference to the `Brand` node the set is keyed on (`@type`, `@id` and `pagefront:sheetUrl`). On a category or a collection, remove `brand`, or declare the kind `brand` if the set is the products sold under one label.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#kind-discriminator-pagefrontcollectionkind",
+};

package/dist/rules/col-w-005.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-W-005 — Parent of another kind.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A category's parents are categories (the tree), and a collection
+ * never sits in the tree: its parent, when it has one, is a collection.
+ * The rule reads the kind the `isPartOf` entry declares and is quiet on
+ * an entry that declares none, since it never fetches the parent sheet.
+ * One finding per offending entry, at the entry's path.
+ */
+export declare const colW005: Rule;

package/dist/rules/col-w-005.js

@@ -0,0 +1,41 @@
+import { asRecord, entryName, memberEntries } from "./col-shared.js";
+/**
+ * COL-W-005 — Parent of another kind.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A category's parents are categories (the tree), and a collection
+ * never sits in the tree: its parent, when it has one, is a collection.
+ * The rule reads the kind the `isPartOf` entry declares and is quiet on
+ * an entry that declares none, since it never fetches the parent sheet.
+ * One finding per offending entry, at the entry's path.
+ */
+export const colW005 = {
+    id: "COL-W-005",
+    title: "Parent of another kind",
+    severity: "warning",
+    target: "$.data",
+    check: (match) => {
+        const data = asRecord(match.value);
+        if (data === null)
+            return null;
+        const kind = data["pagefront:collectionKind"];
+        if (kind !== "category" && kind !== "collection")
+            return null;
+        const hits = [];
+        for (const { entry, path } of memberEntries(data["isPartOf"], `${match.path}['isPartOf']`)) {
+            const parentKind = entry["pagefront:collectionKind"];
+            if (typeof parentKind !== "string")
+                continue;
+            const offends = kind === "category" ? parentKind !== "category" : parentKind === "category";
+            if (!offends)
+                continue;
+            hits.push({ path, values: { kind, name: entryName(entry), parentKind } });
+        }
+        return hits;
+    },
+    messageTemplate: "This `{kind}` sheet names parent `{name}` at `{path}`, whose entry declares kind `{parentKind}`.",
+    remediation: "A category's `isPartOf` entries are categories: the tree is made of categories only. A collection nests in a collection and never in a category. Correct the parent's declared kind, or move the set to the kind its parent implies.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#kind-discriminator-pagefrontcollectionkind",
+};

package/dist/rules/col-w-006.d.ts

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-W-006 — Duplicate member.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * `hasPart` is the set's direct membership, read as exhaustive; the
+ * same `@id` twice is a duplicated tile or a merge error. The first
+ * occurrence stands; every later one fires, at its own path, naming the
+ * index of the first.
+ */
+export declare const colW006: Rule;

package/dist/rules/col-w-006.js

@@ -0,0 +1,37 @@
+import { memberEntries, nonBlank } from "./col-shared.js";
+/**
+ * COL-W-006 — Duplicate member.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * `hasPart` is the set's direct membership, read as exhaustive; the
+ * same `@id` twice is a duplicated tile or a merge error. The first
+ * occurrence stands; every later one fires, at its own path, naming the
+ * index of the first.
+ */
+export const colW006 = {
+    id: "COL-W-006",
+    title: "Duplicate member",
+    severity: "warning",
+    target: "$.data.hasPart",
+    check: (match) => {
+        const seen = new Map();
+        const hits = [];
+        for (const { entry, path } of memberEntries(match.value, match.path)) {
+            const id = entry["@id"];
+            if (!nonBlank(id))
+                continue;
+            const first = seen.get(id);
+            if (first === undefined) {
+                seen.set(id, path);
+                continue;
+            }
+            hits.push({ path, values: { id, first } });
+        }
+        return hits;
+    },
+    messageTemplate: "Member `{id}` at `{path}` repeats the entry at `{first}`.",
+    remediation: "Keep one entry per member. A product assigned to the set once appears once; a product in several sets appears once in each of them.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#members",
+};

package/dist/rules/org-w-007.d.ts

@@ -0,0 +1,15 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-W-007 — Catalogue entry off the sheet's host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * `hasOfferCatalog` is the catalogue entry point: its entries reference
+ * Commerce Collection Sheets on the organization sheet's own host
+ * (organization.md, "Catalogue entry point"). An entry whose
+ * `pagefront:sheetUrl` is on another host leads a consumer off the
+ * publisher's storefront, where the collection sheets it would find
+ * are not this publisher's statement. A hint with no host is treated as
+ * absent and skipped. One finding per entry, at the `pagefront:sheetUrl`
+ * path.
+ */
+export declare const orgW007: Rule;

package/dist/rules/org-w-007.js

@@ -0,0 +1,47 @@
+import { asRecord } from "./org-shared.js";
+import { hostOf, renderHost } from "./sheet-url-host.js";
+/**
+ * ORG-W-007 — Catalogue entry off the sheet's host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * `hasOfferCatalog` is the catalogue entry point: its entries reference
+ * Commerce Collection Sheets on the organization sheet's own host
+ * (organization.md, "Catalogue entry point"). An entry whose
+ * `pagefront:sheetUrl` is on another host leads a consumer off the
+ * publisher's storefront, where the collection sheets it would find
+ * are not this publisher's statement. A hint with no host is treated as
+ * absent and skipped. One finding per entry, at the `pagefront:sheetUrl`
+ * path.
+ */
+export const orgW007 = {
+    id: "ORG-W-007",
+    title: "Catalogue entry off the sheet's host",
+    severity: "warning",
+    target: "$.data.hasOfferCatalog",
+    check: (match, ctx) => {
+        const catalog = asRecord(match.value);
+        if (catalog === null || !Array.isArray(catalog["itemListElement"]))
+            return null;
+        const canonicalHost = hostOf(ctx.sheet.canonical_url);
+        const hits = [];
+        catalog["itemListElement"].forEach((item, i) => {
+            const entry = asRecord(item);
+            if (entry === null)
+                return;
+            // A value with no host (a blank string among them) is treated as absent.
+            const urlHost = hostOf(entry["pagefront:sheetUrl"]);
+            if (urlHost === null || urlHost === canonicalHost)
+                return;
+            hits.push({
+                path: `${match.path}['itemListElement'][${i}]['pagefront:sheetUrl']`,
+                values: { sheetUrlHost: renderHost(urlHost), host: renderHost(canonicalHost) },
+            });
+        });
+        return hits;
+    },
+    messageTemplate: "Catalogue entry sheet URL at `{path}` is on host `{sheetUrlHost}`; the canonical page is on `{host}`.",
+    remediation: "Point `pagefront:sheetUrl` at the collection sheet on this organization sheet's own host. A root in another language is reached through `pagefront:availableLanguages` on the root sheet, never through a second host here.",
+    introduced: "release 0.5.0",
+    appliesFrom: "0.5.0",
+    specReference: "organization.md#catalogue-entry-point-any-role",
+};

package/dist/rules/pdp-e-005.d.ts

@@ -4,7 +4,9 @@ import type { Rule } from "@pagefront/lint-core";
  * Transcribed from commerce/spec/rules.md (normative).
  *
  * Fires when an offer's `seller` carries `pagefront:sheetUrl` whose host
- * differs from the host of the sheet's own `sheet_url`, or has no host.
+ * differs from the canonical host, or has no host. The canonical host is
+ * the host of the envelope `canonical_url`, the page the sheet describes
+ * (the catalogue's Definitions); the optional `sheet_url` plays no part.
  * The seller's `@id` plays no part: the linking contract lets it be
  * minted on another domain the organization controls. The finding sits
  * at the `pagefront:sheetUrl` path.

package/dist/rules/pdp-e-005.js

@@ -4,7 +4,9 @@ import { hostOf, renderHost } from "./sheet-url-host.js";
  * Transcribed from commerce/spec/rules.md (normative).
  *
  * Fires when an offer's `seller` carries `pagefront:sheetUrl` whose host
- * differs from the host of the sheet's own `sheet_url`, or has no host.
+ * differs from the canonical host, or has no host. The canonical host is
+ * the host of the envelope `canonical_url`, the page the sheet describes
+ * (the catalogue's Definitions); the optional `sheet_url` plays no part.
  * The seller's `@id` plays no part: the linking contract lets it be
  * minted on another domain the organization controls. The finding sits
  * at the `pagefront:sheetUrl` path.
@@ -25,15 +27,15 @@ export const pdpE005 = {
         if (s["pagefront:sheetUrl"] === undefined)
             return null;
         const urlHost = hostOf(s["pagefront:sheetUrl"]);
-        const sheetHost = hostOf(ctx.sheet.sheet_url);
-        if (urlHost !== null && urlHost === sheetHost)
+        const canonicalHost = hostOf(ctx.sheet.canonical_url);
+        if (urlHost !== null && urlHost === canonicalHost)
             return null;
         return {
             path: `${match.path}['seller']['pagefront:sheetUrl']`,
-            values: { sheetUrlHost: renderHost(urlHost), sheetHost: renderHost(sheetHost) },
+            values: { sheetUrlHost: renderHost(urlHost), host: renderHost(canonicalHost) },
         };
     },
-    messageTemplate: "Seller sheet URL at `{path}` is on host `{sheetUrlHost}`; the product sheet is on `{sheetHost}`.",
+    messageTemplate: "Seller sheet URL at `{path}` is on host `{sheetUrlHost}`; the canonical page is on `{host}`.",
     remediation: "Publish the seller's organization sheet on the storefront host.",
     introduced: "v0.9",
     appliesFrom: "0.3.0",

package/dist/rules/pdp-e-017.js

@@ -1,4 +1,13 @@
 import { asObject, own, pricedConfiguratorId, pricingBlock, seg } from "./configurator-pricing.js";
+function isScalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/** The declared option that equals `value` after string conversion, if any. */
+function sameTextOption(value, declared) {
+    if (!isScalar(value))
+        return undefined;
+    return declared.find((v) => isScalar(v) && String(v) === String(value));
+}
 function declaredDimensions(configurator) {
     const out = new Map();
     const dimensions = configurator["dimensions"];
@@ -22,15 +31,34 @@ function unresolved(pairs, path, dimensions) {
     for (const [dimension, value] of Object.entries(asObject(pairs) ?? {})) {
         const option = JSON.stringify(value);
         const declared = dimensions.get(dimension);
-        let problem = null;
+        const at = `${path}${seg(dimension)}`;
         if (declared === undefined) {
-            problem = `the configurator declares no dimension \`${dimension}\``;
+            const problem = `the configurator declares no dimension \`${dimension}\``;
+            hits.push({ path: at, values: { dimension, option, problem } });
         }
         else if (declared.values !== null && !declared.values.some((v) => v === value)) {
-            problem = `\`${dimension}\` lists no option \`${option}\``;
-        }
-        if (problem !== null) {
-            hits.push({ path: `${path}${seg(dimension)}`, values: { dimension, option, problem } });
+            const near = sameTextOption(value, declared.values);
+            if (near === undefined) {
+                const problem = `\`${dimension}\` lists no option \`${option}\``;
+                hits.push({ path: at, values: { dimension, option, problem } });
+            }
+            else {
+                const declaredOption = JSON.stringify(near);
+                const referenceType = typeof value;
+                const declaredType = typeof near;
+                const problem = `it references \`${option}\` (${referenceType}); dimension \`${dimension}\` declares \`${declaredOption}\` (${declaredType})`;
+                hits.push({
+                    path: at,
+                    values: {
+                        dimension,
+                        option,
+                        problem,
+                        reference_type: referenceType,
+                        declared_option: declaredOption,
+                        declared_type: declaredType,
+                    },
+                });
+            }
         }
     }
     return hits;

package/dist/rules/pdp-e-019.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "@pagefront/lint-core";
+export declare const pdpE019: Rule;

package/dist/rules/pdp-e-019.js

@@ -0,0 +1,50 @@
+import { asObject, own } from "./configurator-pricing.js";
+import { checkoutTemplateProblem } from "./checkout-template.js";
+/**
+ * PDP-E-019 — Invalid checkout template.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer's `checkoutPageURLTemplate` must be a string, a valid RFC 6570
+ * template, name no variable other than `quantity`, the one variable the
+ * Product Sheet spec defines ("Where to buy"), and expand with `quantity`
+ * set to 1 to an absolute https URL (an empty template fails). One
+ * finding per Offer, the first of those checks in that order. Applies
+ * from release 0.5.0, whose Product Sheet spec 0.11.0 introduces the
+ * requirement.
+ */
+function listVariables(variables) {
+    const quoted = variables.map((v) => `\`${v}\``);
+    if (quoted.length === 1)
+        return `the variable ${quoted[0]}`;
+    return `the variables ${quoted.slice(0, -1).join(", ")} and ${quoted[quoted.length - 1]}`;
+}
+export const pdpE019 = {
+    id: "PDP-E-019",
+    title: "Invalid checkout template",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = asObject(match.value);
+        if (offer === null || !Object.prototype.hasOwnProperty.call(offer, "checkoutPageURLTemplate"))
+            return null;
+        const problem = checkoutTemplateProblem(own(offer, "checkoutPageURLTemplate"));
+        if (problem === null)
+            return null;
+        const text = problem.kind === "not-string"
+            ? "is not a string"
+            : problem.kind === "invalid"
+                ? `is not a valid RFC 6570 template: ${problem.detail}`
+                : problem.kind === "undefined-variables"
+                    ? `names ${listVariables(problem.variables)}, which Pagefront does not define; the one defined variable is \`quantity\``
+                    : problem.expansion === ""
+                        ? "is empty"
+                        : `expands with \`quantity\` set to 1 to \`${problem.expansion}\`, which is not an absolute https URL`;
+        return { path: `${match.path}['checkoutPageURLTemplate']`, values: { problem: text } };
+    },
+    messageTemplate: "Checkout template at `{path}` {problem}.",
+    remediation: "Use only `quantity` and write the template so that it expands to an absolute `https` URL, or remove the template.",
+    introduced: "release 0.5.0",
+    // The requirement is introduced by release 0.5.0 (Product Sheet spec 0.11.0).
+    appliesFrom: "0.5.0",
+    specReference: "product.md#where-to-buy",
+};

package/dist/rules/pdp-e-020.d.ts

@@ -0,0 +1,13 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-020 — Checkout template without a region.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer that carries `checkoutPageURLTemplate` declares the market the
+ * checkout serves with `areaServed` or `eligibleRegion` ("Where to buy").
+ * A region property that is empty or whitespace-only counts as absent.
+ * The template's own validity is PDP-E-019's concern. Applies from
+ * release 0.5.0, whose Product Sheet spec 0.11.0 introduces the
+ * requirement.
+ */
+export declare const pdpE020: Rule;