@pagefront/lint-commerce 0.4.0 → 0.5.0

package/dist/catalogue.js

@@ -1,6 +1,7 @@
 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 { pdpW001 } from "./rules/pdp-w-001.js";
 import { pdpW002 } from "./rules/pdp-w-002.js";
 import { pdpW003 } from "./rules/pdp-w-003.js";
@@ -28,6 +29,8 @@ import { pdpW024 } from "./rules/pdp-w-024.js";
 import { pdpW025 } from "./rules/pdp-w-025.js";
 import { pdpW026 } from "./rules/pdp-w-026.js";
 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 { pdpI001 } from "./rules/pdp-i-001.js";
 /**
  * The commerce product-sheet rule catalogue — the executable form of
@@ -39,6 +42,6 @@ import { pdpI001 } from "./rules/pdp-i-001.js";
 export const commerceCatalogue = {
     vertical: "commerce",
     formatVersion: "0.9",
-    catalogueVersion: "0.7.0",
-    rules: [pdpE001, pdpE002, pdpE003, 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, pdpI001],
+    catalogueVersion: "0.8.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, 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.7.0",
+    catalogueVersion: "0.8.0",
     rules: [orgE001, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
 };

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

@@ -0,0 +1,28 @@
+/**
+ * Shared helpers for the offer-price rules (PDP-E-004, PDP-W-028,
+ * PDP-W-029). The schema admits `priceSpecification` as one object or
+ * an array of objects; the rules treat an object as a single entry.
+ */
+export interface PriceSpecificationEntry {
+    entry: Record<string, unknown>;
+    /** Concrete JSONPath of the entry, in the engine's normalized style. */
+    path: string;
+}
+/**
+ * Every object entry of an offer's `priceSpecification`, with the path
+ * each would carry in a finding. A bare object yields one entry at the
+ * field's own path; an array yields one per object element.
+ */
+export declare function priceSpecificationEntries(offer: Record<string, unknown>, offerPath: string): PriceSpecificationEntry[];
+/**
+ * True when the offer states a price at all: a `price` field, or a
+ * `priceSpecification` with at least one member. Offers declaring
+ * `pagefront:priceOnRequest` are outside the pricing rules entirely.
+ */
+export declare function statesPrice(offer: Record<string, unknown>): boolean;
+/**
+ * A numeric reading of a Schema.org price value: a number, or a string
+ * holding a plain decimal. Anything else (empty, localized, with a
+ * currency symbol) is not comparable and yields undefined.
+ */
+export declare function numericPrice(value: unknown): number | undefined;

package/dist/rules/offer-price.js

@@ -0,0 +1,57 @@
+/**
+ * Shared helpers for the offer-price rules (PDP-E-004, PDP-W-028,
+ * PDP-W-029). The schema admits `priceSpecification` as one object or
+ * an array of objects; the rules treat an object as a single entry.
+ */
+/**
+ * Every object entry of an offer's `priceSpecification`, with the path
+ * each would carry in a finding. A bare object yields one entry at the
+ * field's own path; an array yields one per object element.
+ */
+export function priceSpecificationEntries(offer, offerPath) {
+    const spec = offer["priceSpecification"];
+    const fieldPath = `${offerPath}['priceSpecification']`;
+    if (Array.isArray(spec)) {
+        const out = [];
+        spec.forEach((item, index) => {
+            if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+                out.push({ entry: item, path: `${fieldPath}[${index}]` });
+            }
+        });
+        return out;
+    }
+    if (typeof spec === "object" && spec !== null) {
+        return [{ entry: spec, path: fieldPath }];
+    }
+    return [];
+}
+/**
+ * True when the offer states a price at all: a `price` field, or a
+ * `priceSpecification` with at least one member. Offers declaring
+ * `pagefront:priceOnRequest` are outside the pricing rules entirely.
+ */
+export function statesPrice(offer) {
+    if (offer["pagefront:priceOnRequest"] !== undefined)
+        return false;
+    if (offer["price"] !== undefined)
+        return true;
+    const spec = offer["priceSpecification"];
+    if (Array.isArray(spec))
+        return spec.length > 0;
+    if (typeof spec === "object" && spec !== null)
+        return Object.keys(spec).length > 0;
+    return false;
+}
+/**
+ * A numeric reading of a Schema.org price value: a number, or a string
+ * holding a plain decimal. Anything else (empty, localized, with a
+ * currency symbol) is not comparable and yields undefined.
+ */
+export function numericPrice(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "string" && /^\s*-?\d+(\.\d+)?\s*$/.test(value)) {
+        return Number(value);
+    }
+    return undefined;
+}

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

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

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

@@ -0,0 +1,47 @@
+import { numericPrice, priceSpecificationEntries } from "./offer-price.js";
+/**
+ * PDP-E-004 — Offer price disagrees with its mirroring price specification.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * A mirroring entry carries a numeric `price` in the Offer's own
+ * currency and none of the fields that legitimately make an entry's
+ * amount differ from `price` (`priceType` for sale pricing,
+ * `eligibleQuantity` for tiers, `validFrom`/`validThrough` for
+ * scheduled prices). One finding per disagreeing entry, at the entry.
+ */
+const DIFFERENTIATING_FIELDS = ["priceType", "eligibleQuantity", "validFrom", "validThrough"];
+export const pdpE004 = {
+    id: "PDP-E-004",
+    title: "Offer price disagrees with its mirroring price specification",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = match.value;
+        if (typeof offer !== "object" || offer === null)
+            return null;
+        const o = offer;
+        const price = numericPrice(o["price"]);
+        const currency = o["priceCurrency"];
+        if (price === undefined || typeof currency !== "string")
+            return null;
+        const hits = [];
+        for (const { entry, path } of priceSpecificationEntries(o, match.path)) {
+            if (entry["priceCurrency"] !== currency)
+                continue;
+            if (DIFFERENTIATING_FIELDS.some((field) => entry[field] !== undefined))
+                continue;
+            const specPrice = numericPrice(entry["price"]);
+            if (specPrice === undefined || specPrice === price)
+                continue;
+            hits.push({
+                path,
+                values: { price: String(o["price"]), specPrice: String(entry["price"]) },
+            });
+        }
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "Price specification at `{path}` states `{specPrice}` but its Offer's `price` is `{price}`.",
+    remediation: "Make the two amounts equal, or remove the duplicated amount from the specification entry and keep `valueAddedTaxIncluded` (and `priceCurrency`) on it.",
+    introduced: "v0.9",
+    specReference: "product.md#tax-inclusion",
+};

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

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-028 — Offer price without a tax-inclusion statement.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the offer states a price (`price`, or a non-empty
+ * `priceSpecification`) and no `priceSpecification` entry carries a
+ * boolean `valueAddedTaxIncluded`. Price-on-request offers are exempt.
+ */
+export declare const pdpW028: Rule;

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

@@ -0,0 +1,29 @@
+import { priceSpecificationEntries, statesPrice } from "./offer-price.js";
+/**
+ * PDP-W-028 — Offer price without a tax-inclusion statement.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the offer states a price (`price`, or a non-empty
+ * `priceSpecification`) and no `priceSpecification` entry carries a
+ * boolean `valueAddedTaxIncluded`. Price-on-request offers are exempt.
+ */
+export const pdpW028 = {
+    id: "PDP-W-028",
+    title: "Offer price without a tax-inclusion statement",
+    severity: "warning",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = match.value;
+        if (typeof offer !== "object" || offer === null)
+            return null;
+        const o = offer;
+        if (!statesPrice(o))
+            return null;
+        const stated = priceSpecificationEntries(o, match.path).some(({ entry }) => typeof entry["valueAddedTaxIncluded"] === "boolean");
+        return stated ? null : {};
+    },
+    messageTemplate: "Offer at `{path}` states a price but not whether value-added tax is included.",
+    remediation: "Add a `UnitPriceSpecification` entry mirroring `price` with `valueAddedTaxIncluded` set to `true` or `false`; on an Offer that already uses `priceSpecification`, set the flag on each entry.",
+    introduced: "v0.9",
+    specReference: "product.md#tax-inclusion",
+};

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

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-029 — Offer price without a declared region.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the offer states a price and carries neither `areaServed`
+ * nor `eligibleRegion`. `ineligibleRegion` alone does not satisfy the
+ * check. Price-on-request offers are exempt.
+ */
+export declare const pdpW029: Rule;

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

@@ -0,0 +1,28 @@
+import { statesPrice } from "./offer-price.js";
+/**
+ * PDP-W-029 — Offer price without a declared region.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the offer states a price and carries neither `areaServed`
+ * nor `eligibleRegion`. `ineligibleRegion` alone does not satisfy the
+ * check. Price-on-request offers are exempt.
+ */
+export const pdpW029 = {
+    id: "PDP-W-029",
+    title: "Offer price without a declared region",
+    severity: "warning",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = match.value;
+        if (typeof offer !== "object" || offer === null)
+            return null;
+        const o = offer;
+        if (!statesPrice(o))
+            return null;
+        return o["areaServed"] === undefined && o["eligibleRegion"] === undefined ? {} : null;
+    },
+    messageTemplate: "Offer at `{path}` states a price but no region it applies to.",
+    remediation: "Declare `areaServed` (or `eligibleRegion`) for the market whose displayed price this is. Where the market cannot be determined from the storefront, stating the tax basis via `valueAddedTaxIncluded` is the higher priority; see \"Tax inclusion.\"",
+    introduced: "v0.9",
+    specReference: "product.md#tax-inclusion",
+};

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.4.0";
+export declare const PACKAGE_VERSION = "0.5.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.4.0";
+export const PACKAGE_VERSION = "0.5.0";

package/package.json

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