@pagefront/lint-commerce 0.6.0 → 0.8.0

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

@@ -0,0 +1,62 @@
+import { asObject, resolveConfigurator, seg } from "./configurator-pricing.js";
+/**
+ * PDP-E-009 — Modifier for an unknown dimension or option.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Applies to a pricing block whose `configurator` reference resolves.
+ * A `modifiers` key naming no dimension, or a dimension declared
+ * `affectsPrice: false`, fires once at that key; under a priced
+ * dimension, each option key that is not one of its options fires at
+ * its own path.
+ */
+export const pdpE009 = {
+    id: "PDP-E-009",
+    title: "Modifier for an unknown dimension or option",
+    severity: "error",
+    target: "$.data.offers[*]['pagefront:configuratorPricing']",
+    check: (match, ctx) => {
+        const block = asObject(match.value);
+        const modifiers = asObject(block?.["modifiers"]);
+        if (block === null || modifiers === null)
+            return null;
+        const configurator = resolveConfigurator(block, ctx.sheet);
+        if (configurator === null)
+            return null;
+        const hits = [];
+        for (const [dimension, entry] of Object.entries(modifiers)) {
+            const path = `${match.path}['modifiers']${seg(dimension)}`;
+            const d = configurator.byName.get(dimension);
+            if (d === undefined) {
+                hits.push({
+                    path,
+                    values: { dimension, problem: `names \`${dimension}\`, which is not a dimension of the configurator` },
+                });
+                continue;
+            }
+            if (!d.priced) {
+                hits.push({
+                    path,
+                    values: { dimension, problem: `names \`${dimension}\`, which is declared \`affectsPrice: false\`` },
+                });
+                continue;
+            }
+            for (const option of Object.keys(asObject(entry) ?? {})) {
+                if (d.optionKeys !== null && d.optionKeys.includes(option))
+                    continue;
+                hits.push({
+                    path: `${path}${seg(option)}`,
+                    values: {
+                        dimension,
+                        option,
+                        problem: `names \`${option}\`, which is not an option of \`${dimension}\``,
+                    },
+                });
+            }
+        }
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "Modifier at `{path}` {problem}.",
+    remediation: "Spell dimension names and option values as the configurator spells them. Remove modifiers for dimensions that do not change the price, or remove `affectsPrice: false` from a dimension that does.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-010 — Offer price disagrees with base price.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An `Offer` carrying a pricing block has `price` equal to the block's
+ * `basePrice` as a number, whatever the block's `pricing` value. The
+ * finding sits at the Offer's `price`.
+ */
+export declare const pdpE010: Rule;

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

@@ -0,0 +1,37 @@
+import { asObject, compareDecimal, parseDecimal, pricingBlock } from "./configurator-pricing.js";
+/**
+ * PDP-E-010 — Offer price disagrees with base price.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An `Offer` carrying a pricing block has `price` equal to the block's
+ * `basePrice` as a number, whatever the block's `pricing` value. The
+ * finding sits at the Offer's `price`.
+ */
+export const pdpE010 = {
+    id: "PDP-E-010",
+    title: "Offer price disagrees with base price",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = asObject(match.value);
+        if (offer === null || offer["@type"] !== "Offer")
+            return null;
+        const block = pricingBlock(offer);
+        if (block === null)
+            return null;
+        const price = parseDecimal(offer["price"]);
+        const basePrice = parseDecimal(block["basePrice"]);
+        if (price === undefined || basePrice === undefined)
+            return null;
+        if (compareDecimal(price, basePrice) === 0)
+            return null;
+        return {
+            path: `${match.path}['price']`,
+            values: { price: String(offer["price"]), basePrice: String(block["basePrice"]) },
+        };
+    },
+    messageTemplate: "Offer `price` at `{path}` is `{price}` but its pricing block's `basePrice` is `{basePrice}`.",
+    remediation: "Make the two amounts equal. If `price` is the amount the page shows on load, set `baseConfiguration` to the configuration the page preselects and `basePrice` to its total.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-011 — AggregateOffer band disagrees with computed band.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Applies to an `AggregateOffer` whose pricing block is complete. Silent
+ * when the band cannot be computed: the reference does not resolve, the
+ * block fires PDP-E-007 or PDP-W-032, or every configuration is
+ * excluded. One finding per disagreeing bound, at the bound.
+ */
+export declare const pdpE011: Rule;

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

@@ -0,0 +1,53 @@
+import { asObject, baseConfigurationProblems, compareDecimal, computeBand, formatDecimal, isComplete, missingModifierProblems, parseDecimal, pricingBlock, resolveConfigurator, } from "./configurator-pricing.js";
+/**
+ * PDP-E-011 — AggregateOffer band disagrees with computed band.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Applies to an `AggregateOffer` whose pricing block is complete. Silent
+ * when the band cannot be computed: the reference does not resolve, the
+ * block fires PDP-E-007 or PDP-W-032, or every configuration is
+ * excluded. One finding per disagreeing bound, at the bound.
+ */
+export const pdpE011 = {
+    id: "PDP-E-011",
+    title: "AggregateOffer band disagrees with computed band",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match, ctx) => {
+        const offer = asObject(match.value);
+        if (offer === null || offer["@type"] !== "AggregateOffer")
+            return null;
+        const block = pricingBlock(offer);
+        if (block === null || !isComplete(block))
+            return null;
+        const configurator = resolveConfigurator(block, ctx.sheet);
+        if (configurator === null)
+            return null;
+        if (baseConfigurationProblems(configurator, block).length > 0)
+            return null;
+        if (missingModifierProblems(configurator, block).length > 0)
+            return null;
+        const band = computeBand(configurator, block);
+        if (band === null)
+            return null;
+        const hits = [];
+        const bounds = [
+            { bound: "lowPrice", extreme: "cheapest", computed: band.min },
+            { bound: "highPrice", extreme: "dearest", computed: band.max },
+        ];
+        for (const { bound, extreme, computed } of bounds) {
+            const stated = parseDecimal(offer[bound]);
+            if (stated === undefined || compareDecimal(stated, computed) === 0)
+                continue;
+            hits.push({
+                path: `${match.path}['${bound}']`,
+                values: { bound, extreme, stated: String(offer[bound]), computed: formatDecimal(computed) },
+            });
+        }
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "`{bound}` at `{path}` is `{stated}` but the {extreme} non-excluded configuration computed from the pricing block totals `{computed}`.",
+    remediation: "Correct the bound, or correct the price list: a missing adjustment, a missing exclusion and a wrong modifier each move the computed band. If the price list is known to have gaps, declare `pricing: \"partial\"`.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

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

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

@@ -0,0 +1,32 @@
+import { pricedConfiguratorId, pricingBlock } from "./configurator-pricing.js";
+/**
+ * PDP-E-012 — Configurator priced by more than one offer.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires on each `offers` entry whose pricing block names a configurator
+ * that an earlier entry already prices (exact string match on
+ * `configurator.@id`); `{firstPath}` is the first such entry.
+ */
+function pricedId(offer) {
+    const block = pricingBlock(offer);
+    return block === null ? undefined : pricedConfiguratorId(block);
+}
+export const pdpE012 = {
+    id: "PDP-E-012",
+    title: "Configurator priced by more than one offer",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match, ctx) => {
+        const value = pricedId(match.value);
+        if (value === undefined)
+            return null;
+        const first = ctx.allMatches.find((m) => pricedId(m.value) === value);
+        if (first === undefined || first.path === match.path)
+            return null;
+        return { values: { value, firstPath: first.path } };
+    },
+    messageTemplate: "Offer at `{path}` prices configurator `{value}`, which the offer at `{firstPath}` already prices.",
+    remediation: "Keep one pricing block per configurator. Publish each further market's price list in that market's own Sheet.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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/pdp-w-032.d.ts

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-032 — Priced option without a modifier.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Applies to a resolving pricing block whose `pricing` is absent or
+ * `complete`. One finding per priced option with no modifier, and one
+ * per priced dimension that enumerates no options, all at the block.
+ */
+export declare const pdpW032: Rule;

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

@@ -0,0 +1,42 @@
+import { asObject, isComplete, missingModifierProblems, resolveConfigurator, } from "./configurator-pricing.js";
+/**
+ * PDP-W-032 — Priced option without a modifier.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Applies to a resolving pricing block whose `pricing` is absent or
+ * `complete`. One finding per priced option with no modifier, and one
+ * per priced dimension that enumerates no options, all at the block.
+ */
+export const pdpW032 = {
+    id: "PDP-W-032",
+    title: "Priced option without a modifier",
+    severity: "warning",
+    target: "$.data.offers[*]['pagefront:configuratorPricing']",
+    check: (match, ctx) => {
+        const block = asObject(match.value);
+        if (block === null || !isComplete(block))
+            return null;
+        const configurator = resolveConfigurator(block, ctx.sheet);
+        if (configurator === null)
+            return null;
+        const hits = missingModifierProblems(configurator, block).map((p) => p.kind === "no-options"
+            ? {
+                values: {
+                    dimension: p.dimension,
+                    problem: `cannot state modifiers for \`${p.dimension}\`, a priced dimension that enumerates no options`,
+                },
+            }
+            : {
+                values: {
+                    dimension: p.dimension,
+                    option: p.option,
+                    problem: `states no modifier for option \`${p.option}\` of \`${p.dimension}\``,
+                },
+            });
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "Pricing block at `{path}` {problem}, and `pricing` is not `partial`.",
+    remediation: "State the modifier, `\"0\"` included. If the dimension never changes the price, declare `affectsPrice: false` on it. If the price is not known, declare `pricing: \"partial\"`.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-033 — Priced configurator with no offer pricing it.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the configurator has a priced dimension, no `offers` entry
+ * carries a pricing block, and no `offers` entry states a price. The
+ * last case is PDP-W-034's; the two never fire on the same Sheet.
+ */
+export declare const pdpW033: Rule;

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

@@ -0,0 +1,30 @@
+import { entryStatesPrice, hasPricedDimension, offerEntries, pricingBlock, readConfigurator, } from "./configurator-pricing.js";
+/**
+ * PDP-W-033 — Priced configurator with no offer pricing it.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the configurator has a priced dimension, no `offers` entry
+ * carries a pricing block, and no `offers` entry states a price. The
+ * last case is PDP-W-034's; the two never fire on the same Sheet.
+ */
+export const pdpW033 = {
+    id: "PDP-W-033",
+    title: "Priced configurator with no offer pricing it",
+    severity: "warning",
+    target: "$.data['pagefront:configurator']",
+    check: (_match, ctx) => {
+        const configurator = readConfigurator(ctx.sheet);
+        if (configurator === null || !hasPricedDimension(configurator))
+            return null;
+        const offers = offerEntries(ctx.sheet);
+        if (offers.some((o) => pricingBlock(o) !== null))
+            return null;
+        if (offers.some(entryStatesPrice))
+            return null;
+        return {};
+    },
+    messageTemplate: "Configurator at `{path}` has priced dimensions but no offer prices it.",
+    remediation: "Add an offer carrying `pagefront:configuratorPricing` for this configurator. If no option changes the price, declare `affectsPrice: false` on each dimension.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-034 — Offer beside a configurator with no pricing block.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires once per Sheet, at the first `offers` entry that states a
+ * price, when the Sheet carries a configurator with a priced dimension
+ * and no `offers` entry carries a pricing block.
+ */
+export declare const pdpW034: Rule;

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

@@ -0,0 +1,28 @@
+import { entryStatesPrice, hasPricedDimension, pricingBlock, readConfigurator, } from "./configurator-pricing.js";
+/**
+ * PDP-W-034 — Offer beside a configurator with no pricing block.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires once per Sheet, at the first `offers` entry that states a
+ * price, when the Sheet carries a configurator with a priced dimension
+ * and no `offers` entry carries a pricing block.
+ */
+export const pdpW034 = {
+    id: "PDP-W-034",
+    title: "Offer beside a configurator with no pricing block",
+    severity: "warning",
+    target: "$.data.offers[*]",
+    check: (match, ctx) => {
+        const configurator = readConfigurator(ctx.sheet);
+        if (configurator === null || !hasPricedDimension(configurator))
+            return null;
+        if (ctx.allMatches.some((m) => pricingBlock(m.value) !== null))
+            return null;
+        const first = ctx.allMatches.find((m) => entryStatesPrice(m.value));
+        return first !== undefined && first.path === match.path ? {} : null;
+    },
+    messageTemplate: "Offer price is not linked to the configurator; state which configuration it prices.",
+    remediation: "Add `pagefront:configuratorPricing` to the offer: give the configurator an `@id`, reference it, and name the configuration the price is the total of. When only that one total is known, declare `pricing: \"partial\"`.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-035 — `basePrice` may be a component price.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Heuristic, one finding per pricing block: (a) `basePrice` equals the
+ * largest modifier of one dimension's `modifiers` entry, or (b)
+ * `basePrice` is below every non-zero modifier of one entry that has at
+ * least one.
+ */
+export declare const pdpW035: Rule;

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

@@ -0,0 +1,41 @@
+import { asObject, compareDecimal, isZero, parseDecimal, } from "./configurator-pricing.js";
+/**
+ * PDP-W-035 — `basePrice` may be a component price.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Heuristic, one finding per pricing block: (a) `basePrice` equals the
+ * largest modifier of one dimension's `modifiers` entry, or (b)
+ * `basePrice` is below every non-zero modifier of one entry that has at
+ * least one.
+ */
+export const pdpW035 = {
+    id: "PDP-W-035",
+    title: "`basePrice` may be a component price",
+    severity: "warning",
+    target: "$.data.offers[*]['pagefront:configuratorPricing']",
+    check: (match) => {
+        const block = asObject(match.value);
+        const modifiers = asObject(block?.["modifiers"]);
+        const basePrice = parseDecimal(block?.["basePrice"]);
+        if (modifiers === null || basePrice === undefined)
+            return null;
+        for (const entry of Object.values(modifiers)) {
+            const amounts = Object.values(asObject(entry) ?? {})
+                .map(parseDecimal)
+                .filter((d) => d !== undefined);
+            if (amounts.length === 0)
+                continue;
+            const largest = amounts.reduce((a, b) => (compareDecimal(b, a) > 0 ? b : a));
+            if (compareDecimal(basePrice, largest) === 0)
+                return {};
+            const nonZero = amounts.filter((d) => !isZero(d));
+            if (nonZero.length > 0 && nonZero.every((d) => compareDecimal(basePrice, d) < 0))
+                return {};
+        }
+        return null;
+    },
+    messageTemplate: "basePrice may be a component price, not a configured total.",
+    remediation: "Confirm that `basePrice` is what a buyer pays for the whole of `baseConfiguration`. If it is the price of one part, replace it with the configured total and recompute the modifiers as differences from that total.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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)";