@pagefront/lint-commerce 0.6.0 → 0.8.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.11.0, targeting format 0.9: 48 product rules (`PDP-E-001` to
+`PDP-E-012`, `PDP-W-001` to `PDP-W-035`, `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,46 @@ 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
+
+Added in 0.8.0 (catalogue 0.11.0), from the product spec's
+["Configurator pricing and price bands"](https://themachineweb.org/pagefront/spec/commerce/product#configurator-pricing-and-price-bands)
+section. Configurator pricing moved from `pagefront:configurator` into the
+offer's `pagefront:configuratorPricing`; a sheet carrying prices inside the
+configurator now fails Layer 1.
+
+- `PDP-E-001` now also covers the pricing block's `configurator`
+  reference, which must equal the `@id` of the Sheet's
+  `pagefront:configurator`
+- `PDP-E-007` — `baseConfiguration` omits a priced dimension, or names a
+  dimension or option the configurator does not declare
+- `PDP-E-008` — the modifier of a base option is not zero
+- `PDP-E-009` — a modifier names an unknown dimension or option, or a
+  dimension declared `affectsPrice: false`
+- `PDP-E-010` — an Offer's `price` differs from its pricing block's
+  `basePrice`
+- `PDP-E-011` — an AggregateOffer's `lowPrice` or `highPrice` differs
+  from the band computed from a complete pricing block
+- `PDP-E-012` — more than one offer prices the same configurator
+- `PDP-W-032` — a priced option has no modifier and `pricing` is not
+  `partial`
+- `PDP-W-033` — a configurator has priced dimensions and no offer prices it
+- `PDP-W-034` — an offer states a price beside a configurator and no
+  offer carries a pricing block
+- `PDP-W-035` — `basePrice` looks like a component price (heuristic)
+
+Amounts are summed and compared as exact decimals.
+
 ## API
 
 The public surface — everything importable from the package root, and

package/dist/catalogue.js

@@ -2,6 +2,14 @@ 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 { pdpE007 } from "./rules/pdp-e-007.js";
+import { pdpE008 } from "./rules/pdp-e-008.js";
+import { pdpE009 } from "./rules/pdp-e-009.js";
+import { pdpE010 } from "./rules/pdp-e-010.js";
+import { pdpE011 } from "./rules/pdp-e-011.js";
+import { pdpE012 } from "./rules/pdp-e-012.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 +40,11 @@ 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 { pdpW032 } from "./rules/pdp-w-032.js";
+import { pdpW033 } from "./rules/pdp-w-033.js";
+import { pdpW034 } from "./rules/pdp-w-034.js";
+import { pdpW035 } from "./rules/pdp-w-035.js";
 import { pdpI001 } from "./rules/pdp-i-001.js";
 /**
  * The commerce product-sheet rule catalogue — the executable form of
@@ -43,6 +56,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.11.0",
+    rules: [pdpE001, pdpE002, pdpE003, pdpE004, pdpE005, pdpE006, pdpE007, pdpE008, pdpE009, pdpE010, pdpE011, pdpE012, 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, 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.11.0",
     rules: [orgE001, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
 };

package/dist/product-schema.js

@@ -10,7 +10,7 @@ export const PRODUCT_SCHEMA = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://themachineweb.org/pagefront/spec/commerce/product/v0.9.json",
     "title": "Pagefront Product Sheet v0.9",
-    "description": "Formal schema for the Pagefront product sheet. v0.9 is an additive release on top of v0.8: the legalEntity entry's organization now also validates in reference-stub form (@type + @id, no name) so entries can reference a Commerce Organization Sheet; the inline form and all other constraints are unchanged, and v0.8 sheets remain valid once their format_version is updated. v0.8 is an additive release on top of v0.7: it adds a pagefront:featureGroup[] array for grouped, ordered technical specifications (groups of Schema.org PropertyValue entries, with an optional pagefront:presentationValue display variant per entry), a pagefront:productHighlights[] array of ordered publisher-authored selling-point strings, and a pagefront:legalEntity[] array for role-typed legal entities behind a product (closed role enum: brand_owner, licensee, authorized_representative, importer, manufacturer — EU GPSR responsible persons and similar). gtin and gtin13 now accept a string or an array of strings (regional packaging, re-releases); category now accepts the display string, a Schema.org CategoryCode object, or a mixed array of both. The pagefront:Document role enum gains repairability_index, recall_notice, and declaration_of_conformity; the pagefront:RelatedProduct relationship enum gains service. v0.8 also adds two GPSR-driven safety fields: a pagefront:safetyWarning[] array for typed, language-scoped safety warnings (text required; optional pictogram URL and open-vocabulary hazardCategory) and a pagefront:safetyNotice[] array for structured recall/safety notices (closed noticeType enum: recall, warning; closed remedy enum: repair, replacement, refund). v0.7 sheets remain valid under v0.8 once their format_version is updated. Validates the envelope and pagefront-namespaced extensions strictly; Schema.org-typed blocks permit additional unspecified properties.",
+    "description": "Formal schema for the Pagefront product sheet. Revision of 2026-10-01 (breaking, within v0.9): configurator pricing moves from pagefront:configurator to the offer. The configurator loses basePrice, basePriceCurrency and priceFormula, its options lose priceModifier and currency, and it gains an optional @id and an exclusions[] array; configurator dimensions gain affectsPrice; Offer and AggregateOffer accept pagefront:configuratorPricing, which names the configurator it prices and carries baseConfiguration, basePrice, modifiers, optional adjustments[] and a pricing completeness flag. v0.9 sheets that carried prices inside the configurator no longer validate. v0.9 was otherwise an additive release on top of v0.8: the legalEntity entry's organization now also validates in reference-stub form (@type + @id, no name) so entries can reference a Commerce Organization Sheet; the inline form and all other constraints are unchanged, and v0.8 sheets remain valid once their format_version is updated. v0.8 is an additive release on top of v0.7: it adds a pagefront:featureGroup[] array for grouped, ordered technical specifications (groups of Schema.org PropertyValue entries, with an optional pagefront:presentationValue display variant per entry), a pagefront:productHighlights[] array of ordered publisher-authored selling-point strings, and a pagefront:legalEntity[] array for role-typed legal entities behind a product (closed role enum: brand_owner, licensee, authorized_representative, importer, manufacturer — EU GPSR responsible persons and similar). gtin and gtin13 now accept a string or an array of strings (regional packaging, re-releases); category now accepts the display string, a Schema.org CategoryCode object, or a mixed array of both. The pagefront:Document role enum gains repairability_index, recall_notice, and declaration_of_conformity; the pagefront:RelatedProduct relationship enum gains service. v0.8 also adds two GPSR-driven safety fields: a pagefront:safetyWarning[] array for typed, language-scoped safety warnings (text required; optional pictogram URL and open-vocabulary hazardCategory) and a pagefront:safetyNotice[] array for structured recall/safety notices (closed noticeType enum: recall, warning; closed remedy enum: repair, replacement, refund). v0.7 sheets remain valid under v0.8 once their format_version is updated. Validates the envelope and pagefront-namespaced extensions strictly; Schema.org-typed blocks permit additional unspecified properties.",
     "type": "object",
     "required": [
         "format_version",
@@ -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": [
@@ -1238,6 +1254,9 @@ export const PRODUCT_SCHEMA = {
                 },
                 "pagefront:priceOnRequest": {
                     "$ref": "#/$defs/priceOnRequest"
+                },
+                "pagefront:configuratorPricing": {
+                    "$ref": "#/$defs/configuratorPricing"
                 }
             },
             "anyOf": [
@@ -1258,6 +1277,12 @@ export const PRODUCT_SCHEMA = {
                     ]
                 }
             ],
+            "dependentRequired": {
+                "pagefront:configuratorPricing": [
+                    "price",
+                    "priceCurrency"
+                ]
+            },
             "additionalProperties": true
         },
         "aggregateOffer": {
@@ -1308,6 +1333,9 @@ export const PRODUCT_SCHEMA = {
                 },
                 "seller": {
                     "type": "object"
+                },
+                "pagefront:configuratorPricing": {
+                    "$ref": "#/$defs/configuratorPricing"
                 }
             },
             "additionalProperties": true
@@ -1641,15 +1669,9 @@ export const PRODUCT_SCHEMA = {
                 "@type": {
                     "const": "pagefront:Configurator"
                 },
-                "basePrice": {
-                    "type": "string"
-                },
-                "basePriceCurrency": {
+                "@id": {
                     "type": "string",
-                    "pattern": "^[A-Z]{3}$"
-                },
-                "priceFormula": {
-                    "type": "string"
+                    "minLength": 1
                 },
                 "dimensions": {
                     "type": "array",
@@ -1657,6 +1679,14 @@ export const PRODUCT_SCHEMA = {
                         "$ref": "#/$defs/configuratorDimension"
                     },
                     "minItems": 1
+                },
+                "exclusions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/configurationSelection",
+                        "type": "object",
+                        "minProperties": 1
+                    }
                 }
             },
             "additionalProperties": false
@@ -1691,20 +1721,19 @@ export const PRODUCT_SCHEMA = {
                                     }
                                 ]
                             },
-                            "priceModifier": {
-                                "type": "string"
-                            },
-                            "currency": {
-                                "type": "string",
-                                "pattern": "^[A-Z]{3}$"
-                            },
                             "description": {
                                 "type": "string"
-                            }
+                            },
+                            "priceModifier": false,
+                            "currency": false
                         },
                         "additionalProperties": true
                     }
                 },
+                "affectsPrice": {
+                    "type": "boolean",
+                    "default": true
+                },
                 "system": {
                     "type": "string"
                 },
@@ -1714,6 +1743,101 @@ export const PRODUCT_SCHEMA = {
             },
             "additionalProperties": false
         },
+        "configurationSelection": {
+            "type": "object",
+            "additionalProperties": {
+                "anyOf": [
+                    {
+                        "type": "string"
+                    },
+                    {
+                        "type": "number"
+                    },
+                    {
+                        "type": "boolean"
+                    }
+                ]
+            }
+        },
+        "configuratorPricing": {
+            "type": "object",
+            "required": [
+                "@type",
+                "configurator",
+                "baseConfiguration",
+                "basePrice",
+                "modifiers"
+            ],
+            "properties": {
+                "@type": {
+                    "const": "pagefront:ConfiguratorPricing"
+                },
+                "configurator": {
+                    "type": "object",
+                    "required": [
+                        "@id"
+                    ],
+                    "properties": {
+                        "@type": {
+                            "const": "pagefront:Configurator"
+                        },
+                        "@id": {
+                            "type": "string",
+                            "minLength": 1
+                        }
+                    },
+                    "additionalProperties": false
+                },
+                "baseConfiguration": {
+                    "$ref": "#/$defs/configurationSelection"
+                },
+                "basePrice": {
+                    "type": "string",
+                    "pattern": "^[0-9]+(\\.[0-9]+)?$"
+                },
+                "modifiers": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string",
+                            "pattern": "^-?[0-9]+(\\.[0-9]+)?$"
+                        }
+                    }
+                },
+                "adjustments": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": [
+                            "when",
+                            "priceModifier"
+                        ],
+                        "properties": {
+                            "when": {
+                                "$ref": "#/$defs/configurationSelection",
+                                "type": "object",
+                                "minProperties": 1
+                            },
+                            "priceModifier": {
+                                "type": "string",
+                                "pattern": "^-?[0-9]+(\\.[0-9]+)?$"
+                            }
+                        },
+                        "additionalProperties": false
+                    }
+                },
+                "pricing": {
+                    "type": "string",
+                    "enum": [
+                        "complete",
+                        "partial"
+                    ],
+                    "default": "complete"
+                }
+            },
+            "additionalProperties": false
+        },
         "madeToOrderTerms": {
             "type": "object",
             "required": [

package/dist/rules/configurator-pricing.d.ts

@@ -0,0 +1,114 @@
+import type { Sheet } from "@pagefront/lint-core";
+/**
+ * Shared helpers for the configurator-pricing rules (PDP-E-001's
+ * `configurator` arm, PDP-E-007 to PDP-E-012, PDP-W-032 to PDP-W-035).
+ * They implement the catalogue's Definitions: *pricing block*, *priced
+ * dimension*, *option key*, *computed total* and *computed band*.
+ */
+type Obj = Record<string, unknown>;
+export declare function asObject(value: unknown): Obj | null;
+/** Own-property lookup: option keys are publisher strings (`constructor`, …). */
+export declare function own(obj: Obj | null, key: string): unknown;
+/**
+ * A name selector in the engine's path style (RFC 9535 normalized
+ * paths). Option keys are publisher strings, so the quote, the
+ * backslash and control characters are escaped as the RFC prescribes.
+ */
+export declare function seg(key: string): string;
+export interface Decimal {
+    units: bigint;
+    /** Number of decimal places `units` is scaled by. */
+    scale: number;
+}
+/**
+ * A decimal reading of an amount: a plain decimal string, or a JSON
+ * number whose shortest serialization is a plain decimal. Anything else
+ * is not comparable and yields undefined.
+ */
+export declare function parseDecimal(value: unknown): Decimal | undefined;
+export declare function addDecimal(a: Decimal, b: Decimal): Decimal;
+/** Negative, zero or positive as `a` is below, equal to or above `b`. */
+export declare function compareDecimal(a: Decimal, b: Decimal): number;
+export declare function isZero(d: Decimal): boolean;
+/** Renders with the decimal's own number of places (`859.00` at scale 2). */
+export declare function formatDecimal(d: Decimal): string;
+/** The string form an option value is matched by (Definitions: *option key*). */
+export declare function optionKey(value: unknown): string | undefined;
+export interface Dimension {
+    name: string;
+    /** `affectsPrice` is not `false`. */
+    priced: boolean;
+    /** Option keys in document order; null when the dimension enumerates none. */
+    optionKeys: string[] | null;
+}
+export interface Configurator {
+    id: string | undefined;
+    dimensions: Dimension[];
+    byName: Map<string, Dimension>;
+    /** Each exclusion as dimension name → option key. */
+    exclusions: Map<string, string>[];
+}
+/** The Sheet's `pagefront:configurator`, or null when absent or shapeless. */
+export declare function readConfigurator(sheet: Sheet): Configurator | null;
+export declare function hasPricedDimension(configurator: Configurator): boolean;
+/** The pricing block of an `offers` entry, or null. */
+export declare function pricingBlock(offer: unknown): Obj | null;
+/** The `configurator.@id` a pricing block names, when it is a string. */
+export declare function pricedConfiguratorId(block: Obj): string | undefined;
+/**
+ * The configurator a pricing block prices: the Sheet's configurator when
+ * the block's reference equals its `@id` by exact string match. Null is
+ * the unresolved reference PDP-E-001 reports; the pricing rules are
+ * silent on it.
+ */
+export declare function resolveConfigurator(block: Obj, sheet: Sheet): Configurator | null;
+export declare function offerEntries(sheet: Sheet): unknown[];
+/**
+ * True when an `offers` entry states a price, in the sense PDP-W-033 and
+ * PDP-W-034 share: an `AggregateOffer`, or an `Offer` with `price` or a
+ * non-empty `priceSpecification`. Price-on-request offers state none.
+ */
+export declare function entryStatesPrice(entry: unknown): boolean;
+export declare function isComplete(block: Obj): boolean;
+export type BaseConfigurationProblem = {
+    kind: "omitted";
+    dimension: string;
+} | {
+    kind: "unknown-dimension";
+    dimension: string;
+} | {
+    kind: "unknown-option";
+    dimension: string;
+    value: string;
+};
+/** PDP-E-007's findings: omitted dimensions first, then pairs in document order. */
+export declare function baseConfigurationProblems(configurator: Configurator, block: Obj): BaseConfigurationProblem[];
+export type MissingModifierProblem = {
+    kind: "no-options";
+    dimension: string;
+} | {
+    kind: "missing";
+    dimension: string;
+    option: string;
+};
+/** PDP-W-032's findings, whatever the block's `pricing` value. */
+export declare function missingModifierProblems(configurator: Configurator, block: Obj): MissingModifierProblem[];
+export interface Band {
+    min: Decimal;
+    max: Decimal;
+}
+/**
+ * The minimum and maximum computed total over all non-excluded
+ * configurations, or null when it cannot be computed (an amount is not
+ * a decimal, a modifier is missing, or every configuration is
+ * excluded). The caller has established that the block resolves to
+ * `configurator`.
+ *
+ * Only the dimensions named in an exclusion or an adjustment are
+ * enumerated together. Every other priced dimension contributes its
+ * smallest modifier to the minimum and its largest to the maximum,
+ * independently of the rest, which yields the same band as the full
+ * enumeration.
+ */
+export declare function computeBand(configurator: Configurator, block: Obj): Band | null;
+export {};