@pagefront/lint-commerce 0.3.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.6.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

@@ -1,3 +1,4 @@
+import { orgE001 } from "./rules/org-e-001.js";
 import { orgW001 } from "./rules/org-w-001.js";
 import { orgW002 } from "./rules/org-w-002.js";
 import { orgW003 } from "./rules/org-w-003.js";
@@ -16,6 +17,6 @@ import { orgW006 } from "./rules/org-w-006.js";
 export const organizationCatalogue = {
     vertical: "commerce",
     formatVersion: "0.9",
-    catalogueVersion: "0.6.0",
-    rules: [orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
+    catalogueVersion: "0.8.0",
+    rules: [orgE001, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
 };

package/dist/rules/context-prefix.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared by PDP-E-003 and ORG-E-001: does the data block declare the
+ * `pagefront` prefix, and which `pagefront:` term does it use first?
+ * A term is a property name or an `@type` value beginning with
+ * `pagefront:`, anywhere in the block; the walk is depth-first in
+ * document order, so the named term is the first one a reader meets.
+ */
+export declare const VOCABULARY_IRI = "https://themachineweb.org/pagefront/vocabulary/";
+export declare const declaresPagefrontPrefix: (context: unknown) => boolean;
+export declare const firstPagefrontTerm: (value: unknown) => string | undefined;
+/** The check both rules share: null when the prefix is declared or no term is used. */
+export declare const missingPrefixTerm: (data: unknown) => {
+    values: {
+        term: string;
+    };
+} | null;

package/dist/rules/context-prefix.js

@@ -0,0 +1,44 @@
+/**
+ * Shared by PDP-E-003 and ORG-E-001: does the data block declare the
+ * `pagefront` prefix, and which `pagefront:` term does it use first?
+ * A term is a property name or an `@type` value beginning with
+ * `pagefront:`, anywhere in the block; the walk is depth-first in
+ * document order, so the named term is the first one a reader meets.
+ */
+export const VOCABULARY_IRI = "https://themachineweb.org/pagefront/vocabulary/";
+export const declaresPagefrontPrefix = (context) => Array.isArray(context) &&
+    context.some((entry) => typeof entry === "object" &&
+        entry !== null &&
+        !Array.isArray(entry) &&
+        entry["pagefront"] === VOCABULARY_IRI);
+export const firstPagefrontTerm = (value) => {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = firstPagefrontTerm(item);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    for (const [key, child] of Object.entries(value)) {
+        if (key.startsWith("pagefront:"))
+            return key;
+        if (key === "@type" && typeof child === "string" && child.startsWith("pagefront:"))
+            return child;
+        const found = firstPagefrontTerm(child);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+};
+/** The check both rules share: null when the prefix is declared or no term is used. */
+export const missingPrefixTerm = (data) => {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    if (declaresPagefrontPrefix(data["@context"]))
+        return null;
+    const term = firstPagefrontTerm(data);
+    return term === undefined ? null : { values: { term } };
+};

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/org-e-001.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-E-001 — `pagefront:` term without the vocabulary prefix in `@context`.
+ * Transcribed from commerce/spec/rules.md (normative). The organization
+ * counterpart of PDP-E-003; the check is shared (context-prefix.ts).
+ */
+export declare const orgE001: Rule;

package/dist/rules/org-e-001.js

@@ -0,0 +1,17 @@
+import { missingPrefixTerm } from "./context-prefix.js";
+/**
+ * ORG-E-001 — `pagefront:` term without the vocabulary prefix in `@context`.
+ * Transcribed from commerce/spec/rules.md (normative). The organization
+ * counterpart of PDP-E-003; the check is shared (context-prefix.ts).
+ */
+export const orgE001 = {
+    id: "ORG-E-001",
+    title: "pagefront: term without the vocabulary prefix",
+    severity: "error",
+    target: "$.data",
+    check: (match) => missingPrefixTerm(match.value),
+    messageTemplate: "The Sheet uses `{term}` but `@context` at `{path}` does not declare the `pagefront` prefix, so the term does not resolve to the Pagefront vocabulary.",
+    remediation: 'Declare the prefix: `"@context": ["https://schema.org", {"pagefront": "https://themachineweb.org/pagefront/vocabulary/"}]`.',
+    introduced: "v0.9",
+    specReference: "vocabulary.md#how-to-use-this-vocabulary",
+};

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

@@ -1,11 +1,7 @@
 import type { Rule } from "@pagefront/lint-core";
 /**
  * PDP-E-003 — `pagefront:` term without the vocabulary prefix in `@context`.
- * Transcribed from commerce/spec/rules.md (normative).
- *
- * A term is a property name or an `@type` value beginning with
- * `pagefront:`, anywhere in the data block. The walk is depth-first in
- * document order, so the named term is the first one a reader meets.
+ * Transcribed from commerce/spec/rules.md (normative). The check is
+ * shared with ORG-E-001 (context-prefix.ts).
  */
-export declare const VOCABULARY_IRI = "https://themachineweb.org/pagefront/vocabulary/";
 export declare const pdpE003: Rule;

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

@@ -1,53 +1,15 @@
+import { missingPrefixTerm } from "./context-prefix.js";
 /**
  * PDP-E-003 — `pagefront:` term without the vocabulary prefix in `@context`.
- * Transcribed from commerce/spec/rules.md (normative).
- *
- * A term is a property name or an `@type` value beginning with
- * `pagefront:`, anywhere in the data block. The walk is depth-first in
- * document order, so the named term is the first one a reader meets.
+ * Transcribed from commerce/spec/rules.md (normative). The check is
+ * shared with ORG-E-001 (context-prefix.ts).
  */
-export const VOCABULARY_IRI = "https://themachineweb.org/pagefront/vocabulary/";
-const declaresPrefix = (context) => Array.isArray(context) &&
-    context.some((entry) => typeof entry === "object" &&
-        entry !== null &&
-        !Array.isArray(entry) &&
-        entry["pagefront"] === VOCABULARY_IRI);
-const firstTerm = (value) => {
-    if (Array.isArray(value)) {
-        for (const item of value) {
-            const found = firstTerm(item);
-            if (found !== undefined)
-                return found;
-        }
-        return undefined;
-    }
-    if (typeof value !== "object" || value === null)
-        return undefined;
-    for (const [key, child] of Object.entries(value)) {
-        if (key.startsWith("pagefront:"))
-            return key;
-        if (key === "@type" && typeof child === "string" && child.startsWith("pagefront:"))
-            return child;
-        const found = firstTerm(child);
-        if (found !== undefined)
-            return found;
-    }
-    return undefined;
-};
 export const pdpE003 = {
     id: "PDP-E-003",
     title: "pagefront: term without the vocabulary prefix",
     severity: "error",
     target: "$.data",
-    check: (match) => {
-        const data = match.value;
-        if (typeof data !== "object" || data === null || Array.isArray(data))
-            return null;
-        if (declaresPrefix(data["@context"]))
-            return null;
-        const term = firstTerm(data);
-        return term === undefined ? null : { values: { term } };
-    },
+    check: (match) => missingPrefixTerm(match.value),
     messageTemplate: "The Sheet uses `{term}` but `@context` at `{path}` does not declare the `pagefront` prefix, so the term does not resolve to the Pagefront vocabulary.",
     remediation: 'Declare the prefix: `"@context": ["https://schema.org", {"pagefront": "https://themachineweb.org/pagefront/vocabulary/"}]`.',
     introduced: "v0.9",

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.3.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.3.0";
+export const PACKAGE_VERSION = "0.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagefront/lint-commerce",
-  "version": "0.3.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": {