@pagefront/lint-commerce 0.13.0 → 0.14.0

package/README.md

@@ -27,14 +27,14 @@ sheet type.
 
 ## Catalogue
 
-Catalogue 0.17.0, supporting commerce releases 0.5.0 (Product Sheet spec
+Catalogue 0.20.0, supporting commerce releases 0.5.0 (Product Sheet spec
 0.11.0, Organization Sheet spec 0.5.0, Collection Sheet spec 0.1.0), 0.4.0
 (Product Sheet spec 0.10.0, Organization Sheet spec 0.4.0) and 0.3.0, and the
-legacy draft line (format 0.9): 62 product rules (`PDP-E-001` to `PDP-E-021`, `PDP-W-001` to
-`PDP-W-040`, `PDP-I-001`), 11 organization rules (`ORG-E-001` to
-`ORG-E-004`, `ORG-W-001` to `ORG-W-007`) and 10 collection rules
+legacy draft line (format 0.9): 64 product rules (`PDP-E-001` to `PDP-E-022`, `PDP-W-001` to
+`PDP-W-041`, `PDP-I-001`), 12 organization rules (`ORG-E-001` to
+`ORG-E-004`, `ORG-W-001` to `ORG-W-008`) and 11 collection rules
 (`COL-E-001` to `COL-E-005`, `COL-W-001`, `COL-W-002`, `COL-W-004` to
-`COL-W-006`; `COL-W-003` is reserved), each defined in
+`COL-W-007`; `COL-W-003` is reserved), each defined in
 [`rules.md`](https://github.com/themachineweb/pagefront/blob/main/commerce/spec/rules.md)
 with its target, check, message and remediation. Every report carries the
 `catalogue_version` it was produced with.
@@ -209,6 +209,29 @@ with the Commerce Collection Sheet spec
   no such schema (at `/format_version`).
 - New export: `collectionCatalogue`. `SheetType` gains `"collection"`.
 
+Added in 0.14.0 (catalogue 0.20.0; catalogues 0.18.0 and 0.19.0 were never
+published on their own). Requires `@pagefront/lint-core` 0.4.0, unchanged.
+
+- `PDP-E-022` (applies from release 0.6.0) — "Unavailable offers
+  without a price" in the Product Sheet spec: a `checkoutPageURLTemplate` on
+  an Offer whose `availability` is `OutOfStock`, `SoldOut` or `Discontinued`.
+  From the same change, `PDP-W-016` is silent on such an Offer, which the
+  spec publishes without a price.
+- `PDP-W-041` (applies from release 0.6.0) — a purchase URL off the
+  canonical host: an Offer's `url`, or its `checkoutPageURLTemplate`
+  expanded with `quantity` set to 1, on another host than the canonical
+  host. The linter cannot see the seller's `pagefront:checkoutHosts`.
+- `ORG-W-008` (applies from release 0.6.0) — `pagefront:checkoutHosts`
+  without the `seller` role, and one finding per entry that is not a bare
+  host (not a string, empty, or carrying a scheme, a path or a port).
+- `COL-W-007` (applies from release 0.5.0) — a parent entry in `isPartOf`
+  without `pagefront:sheetUrl`, or with a blank one: the counterpart of
+  `COL-W-002` for a sheet's parents. A category's parents are category
+  sheets, so the producer that emitted the sheet knows their addresses.
+- The three rules gated to release 0.6.0 wait for that release: the bundled
+  release manifest has no 0.6.0 row yet, and a sheet declaring 0.6.0 fails
+  Layer 1 (`PDP-E-018`, `ORG-E-004`) until it lands.
+
 Changed in 0.12.1 (catalogue 0.16.1):
 
 - `PDP-E-017` adds a type hint. When a reference matches no option but a

package/dist/catalogue.js

@@ -20,6 +20,7 @@ import { pdpE018 } from "./rules/pdp-e-018.js";
 import { pdpE019 } from "./rules/pdp-e-019.js";
 import { pdpE020 } from "./rules/pdp-e-020.js";
 import { pdpE021 } from "./rules/pdp-e-021.js";
+import { pdpE022 } from "./rules/pdp-e-022.js";
 import { pdpW001 } from "./rules/pdp-w-001.js";
 import { pdpW002 } from "./rules/pdp-w-002.js";
 import { pdpW003 } from "./rules/pdp-w-003.js";
@@ -60,6 +61,7 @@ import { pdpW037 } from "./rules/pdp-w-037.js";
 import { pdpW038 } from "./rules/pdp-w-038.js";
 import { pdpW039 } from "./rules/pdp-w-039.js";
 import { pdpW040 } from "./rules/pdp-w-040.js";
+import { pdpW041 } from "./rules/pdp-w-041.js";
 import { pdpI001 } from "./rules/pdp-i-001.js";
 /**
  * The commerce product-sheet rule catalogue — the executable form of
@@ -71,6 +73,6 @@ import { pdpI001 } from "./rules/pdp-i-001.js";
 export const commerceCatalogue = {
     vertical: "commerce",
     releases: KNOWN_RELEASES,
-    catalogueVersion: "0.17.0",
-    rules: [pdpE001, pdpE002, pdpE003, pdpE004, pdpE005, pdpE006, pdpE007, pdpE008, pdpE009, pdpE010, pdpE011, pdpE012, pdpE013, pdpE014, pdpE015, pdpE016, pdpE017, pdpE018, pdpE019, pdpE020, pdpE021, pdpW001, pdpW002, pdpW003, pdpW004, pdpW005, pdpW006, pdpW007, pdpW008, pdpW009, pdpW010, pdpW011, pdpW012, pdpW013, pdpW014, pdpW015, pdpW016, pdpW017, pdpW018, pdpW019, pdpW020, pdpW021, pdpW022, pdpW023, pdpW024, pdpW025, pdpW026, pdpW027, pdpW028, pdpW029, pdpW030, pdpW031, pdpW032, pdpW033, pdpW034, pdpW035, pdpW036, pdpW037, pdpW038, pdpW039, pdpW040, pdpI001],
+    catalogueVersion: "0.20.0",
+    rules: [pdpE001, pdpE002, pdpE003, pdpE004, pdpE005, pdpE006, pdpE007, pdpE008, pdpE009, pdpE010, pdpE011, pdpE012, pdpE013, pdpE014, pdpE015, pdpE016, pdpE017, pdpE018, pdpE019, pdpE020, pdpE021, pdpE022, pdpW001, pdpW002, pdpW003, pdpW004, pdpW005, pdpW006, pdpW007, pdpW008, pdpW009, pdpW010, pdpW011, pdpW012, pdpW013, pdpW014, pdpW015, pdpW016, pdpW017, pdpW018, pdpW019, pdpW020, pdpW021, pdpW022, pdpW023, pdpW024, pdpW025, pdpW026, pdpW027, pdpW028, pdpW029, pdpW030, pdpW031, pdpW032, pdpW033, pdpW034, pdpW035, pdpW036, pdpW037, pdpW038, pdpW039, pdpW040, pdpW041, pdpI001],
 };

package/dist/collection-catalogue.js

@@ -9,6 +9,7 @@ import { colW002 } from "./rules/col-w-002.js";
 import { colW004 } from "./rules/col-w-004.js";
 import { colW005 } from "./rules/col-w-005.js";
 import { colW006 } from "./rules/col-w-006.js";
+import { colW007 } from "./rules/col-w-007.js";
 /**
  * The Commerce Collection Sheet rule catalogue — the executable form
  * of the "Commerce Collection Sheet rules" section of
@@ -25,6 +26,6 @@ import { colW006 } from "./rules/col-w-006.js";
 export const collectionCatalogue = {
     vertical: "commerce",
     releases: KNOWN_RELEASES,
-    catalogueVersion: "0.17.0",
-    rules: [colE001, colE002, colE003, colE004, colE005, colW001, colW002, colW004, colW005, colW006],
+    catalogueVersion: "0.20.0",
+    rules: [colE001, colE002, colE003, colE004, colE005, colW001, colW002, colW004, colW005, colW006, colW007],
 };

package/dist/organization-catalogue.js

@@ -10,6 +10,7 @@ import { orgW004 } from "./rules/org-w-004.js";
 import { orgW005 } from "./rules/org-w-005.js";
 import { orgW006 } from "./rules/org-w-006.js";
 import { orgW007 } from "./rules/org-w-007.js";
+import { orgW008 } from "./rules/org-w-008.js";
 /**
  * The Commerce Organization Sheet rule catalogue — the executable form
  * of the "Commerce Organization Sheet rules" section of
@@ -22,6 +23,6 @@ import { orgW007 } from "./rules/org-w-007.js";
 export const organizationCatalogue = {
     vertical: "commerce",
     releases: KNOWN_RELEASES,
-    catalogueVersion: "0.17.0",
-    rules: [orgE001, orgE002, orgE003, orgE004, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006, orgW007],
+    catalogueVersion: "0.20.0",
+    rules: [orgE001, orgE002, orgE003, orgE004, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006, orgW007, orgW008],
 };

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

@@ -0,0 +1,13 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * COL-W-007 — Parent entry without `pagefront:sheetUrl`.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A category's parents are category sheets and a collection's parent
+ * is a collection sheet, so the producer that emits the sheet has
+ * emitted its parents and knows their addresses. 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 colW007: Rule;

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

@@ -0,0 +1,32 @@
+import { entryName, memberEntries, nonBlank } from "./col-shared.js";
+/**
+ * COL-W-007 — Parent entry without `pagefront:sheetUrl`.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A category's parents are category sheets and a collection's parent
+ * is a collection sheet, so the producer that emits the sheet has
+ * emitted its parents and knows their addresses. 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 colW007 = {
+    id: "COL-W-007",
+    title: "Parent entry without pagefront:sheetUrl",
+    severity: "warning",
+    target: "$.data.isPartOf",
+    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: "Parent `{name}` at `{path}` carries no `pagefront:sheetUrl`; consumers must reach its sheet via `url` + `alternate`.",
+    remediation: "Emit the parent's sheet and add `pagefront:sheetUrl` with its address. A category's parents are category sheets, and a collection nests only in a collection that has a sheet.",
+    introduced: "catalogue 0.20.0",
+    appliesFrom: "0.5.0",
+    specReference: "collection.md#hierarchy",
+};

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

@@ -0,0 +1,15 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-W-008 — Checkout hosts without seller role, or not a bare host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * `pagefront:checkoutHosts` lists the hosts outside the canonical host
+ * on which the seller's offers are bought or checked out
+ * (organization.md, "Seller block"); it is admitted only where
+ * `commerceRole` includes `seller`, and each entry is a bare host name.
+ * One finding on the field when the role is absent, and one per entry
+ * that is not a bare host: a value that is not a string, is empty or
+ * whitespace-only, or carries a scheme, a path or a port. The entries
+ * are read as written; the rule compares them with nothing.
+ */
+export declare const orgW008: Rule;

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

@@ -0,0 +1,59 @@
+import { asRecord, commerceRoles } from "./org-shared.js";
+/**
+ * ORG-W-008 — Checkout hosts without seller role, or not a bare host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * `pagefront:checkoutHosts` lists the hosts outside the canonical host
+ * on which the seller's offers are bought or checked out
+ * (organization.md, "Seller block"); it is admitted only where
+ * `commerceRole` includes `seller`, and each entry is a bare host name.
+ * One finding on the field when the role is absent, and one per entry
+ * that is not a bare host: a value that is not a string, is empty or
+ * whitespace-only, or carries a scheme, a path or a port. The entries
+ * are read as written; the rule compares them with nothing.
+ */
+export const orgW008 = {
+    id: "ORG-W-008",
+    title: "Checkout hosts without seller role, or not a bare host",
+    severity: "warning",
+    target: "$.data",
+    check: (match) => {
+        const data = asRecord(match.value);
+        if (data === null || !Object.prototype.hasOwnProperty.call(data, "pagefront:checkoutHosts"))
+            return null;
+        const field = `${match.path}['pagefront:checkoutHosts']`;
+        const hits = [];
+        if (!commerceRoles(data).includes("seller")) {
+            hits.push({ path: field, values: { problem: "the sheet does not declare the `seller` role" } });
+        }
+        const hosts = data["pagefront:checkoutHosts"];
+        if (Array.isArray(hosts)) {
+            hosts.forEach((entry, i) => {
+                const problem = notBareHost(entry);
+                if (problem !== null)
+                    hits.push({ path: `${field}[${i}]`, values: { problem } });
+            });
+        }
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "`pagefront:checkoutHosts` at `{path}`: {problem}.",
+    remediation: "List bare host names only (`checkout.merchant.example`), and only on the seller's own sheet, one whose `pagefront:commerceRole` includes `seller`; otherwise remove the field.",
+    introduced: "release 0.6.0",
+    appliesFrom: "0.6.0",
+    specReference: "organization.md#seller-block-seller",
+};
+/** Why `entry` is not a bare host, or `null` when it is one. */
+function notBareHost(entry) {
+    if (typeof entry !== "string")
+        return `entry ${JSON.stringify(entry)} is not a string`;
+    if (entry.trim() === "")
+        return "an entry is empty or whitespace-only";
+    const shown = `entry \`${entry}\``;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(entry))
+        return `${shown} carries a scheme`;
+    if (entry.includes("/"))
+        return `${shown} carries a path`;
+    if (entry.includes(":"))
+        return `${shown} carries a port`;
+    return null;
+}

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

@@ -0,0 +1,13 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-022 — Checkout template on an unavailable offer.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer whose `availability` is OutOfStock, SoldOut or Discontinued
+ * cannot be bought now, so it MUST NOT carry `checkoutPageURLTemplate`
+ * ("Unavailable offers without a price"); `url` stays, since the page
+ * is where a shopper asks to be notified. Fires whether or not the
+ * offer states a price. Applies from release 0.6.0, whose Product Sheet
+ * spec 0.12.0 introduces the requirement.
+ */
+export declare const pdpE022: Rule;

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

@@ -0,0 +1,33 @@
+import { asObject } from "./configurator-pricing.js";
+import { isUnavailable } from "./unavailable-offer.js";
+/**
+ * PDP-E-022 — Checkout template on an unavailable offer.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer whose `availability` is OutOfStock, SoldOut or Discontinued
+ * cannot be bought now, so it MUST NOT carry `checkoutPageURLTemplate`
+ * ("Unavailable offers without a price"); `url` stays, since the page
+ * is where a shopper asks to be notified. Fires whether or not the
+ * offer states a price. Applies from release 0.6.0, whose Product Sheet
+ * spec 0.12.0 introduces the requirement.
+ */
+export const pdpE022 = {
+    id: "PDP-E-022",
+    title: "Checkout template on an unavailable offer",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = asObject(match.value);
+        if (offer === null || !Object.prototype.hasOwnProperty.call(offer, "checkoutPageURLTemplate"))
+            return null;
+        if (!isUnavailable(offer))
+            return null;
+        return { path: `${match.path}['checkoutPageURLTemplate']`, values: { availability: String(offer["availability"]) } };
+    },
+    messageTemplate: "Checkout template at `{path}` sits on an Offer whose `availability` is `{availability}`, which cannot be bought now.",
+    remediation: "Remove the template; keep `url`, the page where a shopper can ask to be notified.",
+    introduced: "release 0.6.0",
+    // The requirement is introduced by release 0.6.0 (Product Sheet spec 0.12.0).
+    appliesFrom: "0.6.0",
+    specReference: "product.md#tax-inclusion",
+};

package/dist/rules/pdp-w-016.d.ts

@@ -5,5 +5,9 @@ import type { Rule } from "@pagefront/lint-core";
  *
  * Bespoke cross-field check: `availability` and `priceCurrency` present,
  * but no `price`, no `priceSpecification`, no `pagefront:priceOnRequest`.
+ * Silent when `availability` is OutOfStock, SoldOut or Discontinued: an
+ * offer the page shows as unavailable is published without a price
+ * ("Unavailable offers without a price"), so the missing price is no
+ * sign of an extraction failure.
  */
 export declare const pdpW016: Rule;

package/dist/rules/pdp-w-016.js

@@ -1,9 +1,14 @@
+import { isUnavailable } from "./unavailable-offer.js";
 /**
  * PDP-W-016 — Possibly-missed price.
  * Transcribed from commerce/spec/rules.md (normative).
  *
  * Bespoke cross-field check: `availability` and `priceCurrency` present,
  * but no `price`, no `priceSpecification`, no `pagefront:priceOnRequest`.
+ * Silent when `availability` is OutOfStock, SoldOut or Discontinued: an
+ * offer the page shows as unavailable is published without a price
+ * ("Unavailable offers without a price"), so the missing price is no
+ * sign of an extraction failure.
  */
 export const pdpW016 = {
     id: "PDP-W-016",
@@ -15,6 +20,8 @@ export const pdpW016 = {
         if (typeof offer !== "object" || offer === null)
             return null;
         const o = offer;
+        if (isUnavailable(o))
+            return null;
         return o["availability"] !== undefined &&
             o["priceCurrency"] !== undefined &&
             o["price"] === undefined &&

package/dist/rules/pdp-w-041.d.ts

@@ -0,0 +1,15 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-041 — Purchase URL off the canonical host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A purchase URL is an Offer's `url`, or its `checkoutPageURLTemplate`
+ * expanded with `quantity` set to 1 ("Where to buy", "Purchase host").
+ * Fires once for each whose host differs from the canonical host, the
+ * host of the envelope `canonical_url`. A `url` with no host is
+ * PDP-E-021's concern and a template that does not expand to an
+ * absolute https URL is PDP-E-019's; both are skipped here. The seller
+ * sheet's `pagefront:checkoutHosts`, which can declare the host, is out
+ * of the linter's sight: it never fetches. Applies from release 0.6.0.
+ */
+export declare const pdpW041: Rule;

package/dist/rules/pdp-w-041.js

@@ -0,0 +1,53 @@
+import { asObject, own } from "./configurator-pricing.js";
+import { checkoutTemplateProblem, expandTemplate } from "./checkout-template.js";
+import { hostOf, renderHost } from "./sheet-url-host.js";
+/**
+ * PDP-W-041 — Purchase URL off the canonical host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A purchase URL is an Offer's `url`, or its `checkoutPageURLTemplate`
+ * expanded with `quantity` set to 1 ("Where to buy", "Purchase host").
+ * Fires once for each whose host differs from the canonical host, the
+ * host of the envelope `canonical_url`. A `url` with no host is
+ * PDP-E-021's concern and a template that does not expand to an
+ * absolute https URL is PDP-E-019's; both are skipped here. The seller
+ * sheet's `pagefront:checkoutHosts`, which can declare the host, is out
+ * of the linter's sight: it never fetches. Applies from release 0.6.0.
+ */
+export const pdpW041 = {
+    id: "PDP-W-041",
+    title: "Purchase URL off the canonical host",
+    severity: "warning",
+    target: "$.data.offers[*]",
+    check: (match, ctx) => {
+        const offer = asObject(match.value);
+        if (offer === null)
+            return null;
+        const canonicalHost = hostOf(ctx.sheet.canonical_url);
+        const hits = [];
+        const urlHost = hostOf(own(offer, "url"));
+        if (urlHost !== null && urlHost !== canonicalHost) {
+            hits.push({
+                path: `${match.path}['url']`,
+                values: { purchaseHost: urlHost, host: renderHost(canonicalHost) },
+            });
+        }
+        const template = own(offer, "checkoutPageURLTemplate");
+        if (typeof template === "string" && checkoutTemplateProblem(template) === null) {
+            const templateHost = hostOf(expandTemplate(template, { quantity: "1" }));
+            if (templateHost !== null && templateHost !== canonicalHost) {
+                hits.push({
+                    path: `${match.path}['checkoutPageURLTemplate']`,
+                    values: { purchaseHost: templateHost, host: renderHost(canonicalHost) },
+                });
+            }
+        }
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "Purchase URL at `{path}` is on host `{purchaseHost}`; the canonical page is on `{host}`.",
+    remediation: "Move the purchase to the canonical host, or declare the host in `pagefront:checkoutHosts` on the seller's organization sheet.",
+    introduced: "release 0.6.0",
+    // The purchase-host rule is introduced by release 0.6.0 (Product Sheet spec 0.12.0).
+    appliesFrom: "0.6.0",
+    specReference: "product.md#where-to-buy",
+};

package/dist/rules/unavailable-offer.d.ts

@@ -0,0 +1,2 @@
+/** True when the offer's `availability` is one of the three unavailable values. */
+export declare function isUnavailable(offer: Record<string, unknown>): boolean;

package/dist/rules/unavailable-offer.js

@@ -0,0 +1,13 @@
+/**
+ * Shared helper for the rules that read an Offer's availability as
+ * "cannot be bought now" (product.md, "Unavailable offers without a
+ * price"): OutOfStock, SoldOut and Discontinued, in the http or https
+ * form the schema accepts. The other availability values describe an
+ * item that can still be bought.
+ */
+const UNAVAILABLE = /^https?:\/\/schema\.org\/(OutOfStock|SoldOut|Discontinued)$/;
+/** True when the offer's `availability` is one of the three unavailable values. */
+export function isUnavailable(offer) {
+    const availability = offer["availability"];
+    return typeof availability === "string" && UNAVAILABLE.test(availability);
+}

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * (test/linter-version.test.mjs) fails when they diverge. Regenerate
  * on version bump.
  */
-export declare const PACKAGE_VERSION = "0.13.0";
+export declare const PACKAGE_VERSION = "0.14.0";

package/dist/version.js

@@ -5,4 +5,4 @@
  * (test/linter-version.test.mjs) fails when they diverge. Regenerate
  * on version bump.
  */
-export const PACKAGE_VERSION = "0.13.0";
+export const PACKAGE_VERSION = "0.14.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagefront/lint-commerce",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Pagefront commerce linter: the commerce rule catalogue and CLI, on the @pagefront/lint-core engine.",
   "license": "Apache-2.0",
   "repository": {