@pagefront/lint-commerce 0.6.0 → 0.7.0

package/README.md

@@ -26,8 +26,8 @@ lint with their own catalogue, dispatched by sheet type.
 
 ## Catalogue
 
-Catalogue 0.9.0, targeting format 0.9: 35 product rules (`PDP-E-001` to
-`PDP-E-004`, `PDP-W-001` to `PDP-W-030`, `PDP-I-001`) and 7 organization
+Catalogue 0.10.0, targeting format 0.9: 38 product rules (`PDP-E-001` to
+`PDP-E-006`, `PDP-W-001` to `PDP-W-031`, `PDP-I-001`) and 7 organization
 rules (`ORG-E-001`, `ORG-W-001` to `ORG-W-006`), 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
@@ -53,6 +53,18 @@ section:
 - `PDP-W-030` — a `warranty` on an Offer, or a `pagefront:manufacturerWarranty`
   on the Product, carries neither `durationOfWarranty` nor `description`
 
+Added in 0.7.0 (catalogue 0.10.0), from the organization spec's
+["Linking contract"](https://themachineweb.org/pagefront/spec/commerce/organization#linking-contract-identity-only)
+section:
+
+- `PDP-E-005` — `pagefront:sheetUrl` on an Offer's `seller` is on a host
+  other than the product sheet's
+- `PDP-E-006` — `pagefront:sheetUrl` on `brand` is on a host other than
+  that of the brand's `@id`
+- `PDP-W-031` — an Offer's `seller` has an `@id` but no
+  `pagefront:sheetUrl`, and the Offer states no return or shipping terms
+  of its own
+
 ## API
 
 The public surface — everything importable from the package root, and

package/dist/catalogue.js

@@ -2,6 +2,8 @@ import { pdpE001 } from "./rules/pdp-e-001.js";
 import { pdpE002 } from "./rules/pdp-e-002.js";
 import { pdpE003 } from "./rules/pdp-e-003.js";
 import { pdpE004 } from "./rules/pdp-e-004.js";
+import { pdpE005 } from "./rules/pdp-e-005.js";
+import { pdpE006 } from "./rules/pdp-e-006.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";
@@ -32,6 +34,7 @@ import { pdpW027 } from "./rules/pdp-w-027.js";
 import { pdpW028 } from "./rules/pdp-w-028.js";
 import { pdpW029 } from "./rules/pdp-w-029.js";
 import { pdpW030 } from "./rules/pdp-w-030.js";
+import { pdpW031 } from "./rules/pdp-w-031.js";
 import { pdpI001 } from "./rules/pdp-i-001.js";
 /**
  * The commerce product-sheet rule catalogue — the executable form of
@@ -43,6 +46,6 @@ import { pdpI001 } from "./rules/pdp-i-001.js";
 export const commerceCatalogue = {
     vertical: "commerce",
     formatVersion: "0.9",
-    catalogueVersion: "0.9.0",
-    rules: [pdpE001, pdpE002, pdpE003, pdpE004, 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, pdpI001],
+    catalogueVersion: "0.10.0",
+    rules: [pdpE001, pdpE002, pdpE003, pdpE004, pdpE005, pdpE006, 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, pdpI001],
 };

package/dist/organization-catalogue.js

@@ -17,6 +17,6 @@ import { orgW006 } from "./rules/org-w-006.js";
 export const organizationCatalogue = {
     vertical: "commerce",
     formatVersion: "0.9",
-    catalogueVersion: "0.9.0",
+    catalogueVersion: "0.10.0",
     rules: [orgE001, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
 };

package/dist/product-schema.js

@@ -135,7 +135,13 @@ export const PRODUCT_SCHEMA = {
                     }
                 },
                 "brand": {
-                    "type": "object"
+                    "type": "object",
+                    "properties": {
+                        "pagefront:sheetUrl": {
+                            "type": "string",
+                            "format": "uri"
+                        }
+                    }
                 },
                 "description": {
                     "type": "string"
@@ -1053,6 +1059,10 @@ export const PRODUCT_SCHEMA = {
                         "email": {
                             "type": "string",
                             "format": "email"
+                        },
+                        "pagefront:sheetUrl": {
+                            "type": "string",
+                            "format": "uri"
                         }
                     },
                     "additionalProperties": true
@@ -1199,7 +1209,13 @@ export const PRODUCT_SCHEMA = {
                     "pattern": "^https?://schema\\.org/(NewCondition|UsedCondition|RefurbishedCondition|DamagedCondition)$"
                 },
                 "seller": {
-                    "type": "object"
+                    "type": "object",
+                    "properties": {
+                        "pagefront:sheetUrl": {
+                            "type": "string",
+                            "format": "uri"
+                        }
+                    }
                 },
                 "shippingDetails": {
                     "oneOf": [

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

@@ -0,0 +1,12 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-005 — Seller sheet URL off the product sheet's host.
+ * 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.
+ * 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.
+ */
+export declare const pdpE005: Rule;

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

@@ -0,0 +1,40 @@
+import { hostOf, renderHost } from "./sheet-url-host.js";
+/**
+ * PDP-E-005 — Seller sheet URL off the product sheet's host.
+ * 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.
+ * 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.
+ */
+export const pdpE005 = {
+    id: "PDP-E-005",
+    title: "Seller sheet URL off the product sheet's host",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match, ctx) => {
+        const offer = match.value;
+        if (typeof offer !== "object" || offer === null)
+            return null;
+        const seller = offer["seller"];
+        if (typeof seller !== "object" || seller === null || Array.isArray(seller))
+            return null;
+        const s = seller;
+        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)
+            return null;
+        return {
+            path: `${match.path}['seller']['pagefront:sheetUrl']`,
+            values: { sheetUrlHost: renderHost(urlHost), sheetHost: renderHost(sheetHost) },
+        };
+    },
+    messageTemplate: "Seller sheet URL at `{path}` is on host `{sheetUrlHost}`; the product sheet is on `{sheetHost}`.",
+    remediation: "Publish the seller's organization sheet on the storefront host.",
+    introduced: "v0.9",
+    specReference: "organization.md#linking-contract-identity-only",
+};

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

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-006 — Brand sheet URL off the brand's host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the data block's `brand` carries `pagefront:sheetUrl` whose
+ * host differs from the host of the brand's `@id`. A brand with no `@id`,
+ * or an `@id` without a host, fires too: there is no host for the URL to
+ * match. The finding sits at the `pagefront:sheetUrl` path.
+ */
+export declare const pdpE006: Rule;

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

@@ -0,0 +1,36 @@
+import { hostOf, renderHost } from "./sheet-url-host.js";
+/**
+ * PDP-E-006 — Brand sheet URL off the brand's host.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the data block's `brand` carries `pagefront:sheetUrl` whose
+ * host differs from the host of the brand's `@id`. A brand with no `@id`,
+ * or an `@id` without a host, fires too: there is no host for the URL to
+ * match. The finding sits at the `pagefront:sheetUrl` path.
+ */
+export const pdpE006 = {
+    id: "PDP-E-006",
+    title: "Brand sheet URL off the brand's host",
+    severity: "error",
+    target: "$.data.brand",
+    check: (match) => {
+        const brand = match.value;
+        if (typeof brand !== "object" || brand === null || Array.isArray(brand))
+            return null;
+        const b = brand;
+        if (b["pagefront:sheetUrl"] === undefined)
+            return null;
+        const urlHost = hostOf(b["pagefront:sheetUrl"]);
+        const idHost = hostOf(b["@id"]);
+        if (urlHost !== null && urlHost === idHost)
+            return null;
+        return {
+            path: `${match.path}['pagefront:sheetUrl']`,
+            values: { sheetUrlHost: renderHost(urlHost), idHost: renderHost(idHost) },
+        };
+    },
+    messageTemplate: "Brand sheet URL at `{path}` is on host `{sheetUrlHost}`; the brand's `@id` is on `{idHost}`.",
+    remediation: "Point `pagefront:sheetUrl` at the sheet the brand publishes on its own host, or remove it.",
+    introduced: "v0.9",
+    specReference: "organization.md#linking-contract-identity-only",
+};

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

@@ -0,0 +1,12 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-031 — Seller reference not locatable.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when an offer's `seller` carries `@id` but no
+ * `pagefront:sheetUrl`, and the offer carries neither
+ * `hasMerchantReturnPolicy` nor `shippingDetails`: the terms it would
+ * inherit sit on a seller sheet no consumer can locate. The finding
+ * sits at the `seller` path.
+ */
+export declare const pdpW031: Rule;

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

@@ -0,0 +1,35 @@
+/**
+ * PDP-W-031 — Seller reference not locatable.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when an offer's `seller` carries `@id` but no
+ * `pagefront:sheetUrl`, and the offer carries neither
+ * `hasMerchantReturnPolicy` nor `shippingDetails`: the terms it would
+ * inherit sit on a seller sheet no consumer can locate. The finding
+ * sits at the `seller` path.
+ */
+export const pdpW031 = {
+    id: "PDP-W-031",
+    title: "Seller reference not locatable",
+    severity: "warning",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = match.value;
+        if (typeof offer !== "object" || offer === null)
+            return null;
+        const o = offer;
+        const seller = o["seller"];
+        if (typeof seller !== "object" || seller === null || Array.isArray(seller))
+            return null;
+        const s = seller;
+        if (s["@id"] === undefined || s["pagefront:sheetUrl"] !== undefined)
+            return null;
+        if (o["hasMerchantReturnPolicy"] !== undefined || o["shippingDetails"] !== undefined)
+            return null;
+        return { path: `${match.path}['seller']` };
+    },
+    messageTemplate: "Seller at `{path}` has an `@id` but no `pagefront:sheetUrl`, and the Offer states no return or shipping terms of its own.",
+    remediation: "Add `pagefront:sheetUrl` to the seller reference, or state the terms on the Offer.",
+    introduced: "v0.9",
+    specReference: "organization.md#linking-contract-identity-only",
+};

package/dist/rules/sheet-url-host.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared helper for the organization-reference rules (PDP-E-005,
+ * PDP-E-006, PDP-W-031): the *host* of a value per the catalogue's
+ * Definitions section — the host a WHATWG URL parser yields (lowercased,
+ * default port dropped) for a full absolute URL, or `null` when the
+ * value is not a full absolute URL, does not parse, or parses with an
+ * empty host (`urn:…`).
+ */
+export declare function hostOf(value: unknown): string | null;
+/** The rendered form of a host placeholder: the host, or `(none)`. */
+export declare const renderHost: (host: string | null) => string;

package/dist/rules/sheet-url-host.js

@@ -0,0 +1,22 @@
+import { isFullAbsoluteUrl } from "@pagefront/lint-core";
+/**
+ * Shared helper for the organization-reference rules (PDP-E-005,
+ * PDP-E-006, PDP-W-031): the *host* of a value per the catalogue's
+ * Definitions section — the host a WHATWG URL parser yields (lowercased,
+ * default port dropped) for a full absolute URL, or `null` when the
+ * value is not a full absolute URL, does not parse, or parses with an
+ * empty host (`urn:…`).
+ */
+export function hostOf(value) {
+    if (!isFullAbsoluteUrl(value))
+        return null;
+    try {
+        const host = new URL(value).host;
+        return host === "" ? null : host;
+    }
+    catch {
+        return null;
+    }
+}
+/** The rendered form of a host placeholder: the host, or `(none)`. */
+export const renderHost = (host) => host ?? "(none)";