@pagefront/lint-commerce 0.8.0 → 0.10.0

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

@@ -0,0 +1,26 @@
+import { asObject } from "./configurator-pricing.js";
+/**
+ * PDP-E-013 — Text dimension with options.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires on a dimension whose `inputType` is `text` and whose `options`
+ * is an array with at least one entry.
+ */
+export const pdpE013 = {
+    id: "PDP-E-013",
+    title: "Text dimension with options",
+    severity: "error",
+    target: "$.data['pagefront:configurator'].dimensions[*]",
+    check: (match) => {
+        const d = asObject(match.value);
+        if (d === null || d["inputType"] !== "text")
+            return null;
+        if (!Array.isArray(d["options"]) || d["options"].length === 0)
+            return null;
+        return { values: { dimension: typeof d["name"] === "string" ? d["name"] : "(unnamed)" } };
+    },
+    messageTemplate: "Dimension `{dimension}` at `{path}` declares `inputType: \"text\"` and enumerates options.",
+    remediation: "Remove `options` from a free-text dimension, or remove `inputType: \"text\"` from a dimension the buyer picks a value in.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-014 — Size advice in another system than the sizing dimension.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the adjustment carries a `sizeSystem`, the configurator has
+ * a sizing dimension in `UK`, `EU`, `US` or `JP`, and the adjustment's
+ * system corresponds to none of them. The `https://schema.org/` prefix
+ * on `sizeSystem` is accepted.
+ */
+export declare const pdpE014: Rule;

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

@@ -0,0 +1,34 @@
+import { asObject, CORRESPONDING_SIZE_SYSTEM, readConfigurator } from "./configurator-pricing.js";
+/**
+ * PDP-E-014 — Size advice in another system than the sizing dimension.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when the adjustment carries a `sizeSystem`, the configurator has
+ * a sizing dimension in `UK`, `EU`, `US` or `JP`, and the adjustment's
+ * system corresponds to none of them. The `https://schema.org/` prefix
+ * on `sizeSystem` is accepted.
+ */
+export const pdpE014 = {
+    id: "PDP-E-014",
+    title: "Size advice in another system than the sizing dimension",
+    severity: "error",
+    target: "$.data['pagefront:sizeRecommendation'].sizeAdjustment",
+    check: (match, ctx) => {
+        const sizeSystem = asObject(match.value)?.["sizeSystem"];
+        if (typeof sizeSystem !== "string")
+            return null;
+        const systems = (readConfigurator(ctx.sheet)?.dimensions ?? [])
+            .map((d) => d.system)
+            .filter((s) => s !== undefined && Object.hasOwn(CORRESPONDING_SIZE_SYSTEM, s));
+        if (systems.length === 0)
+            return null;
+        const bare = sizeSystem.replace(/^https?:\/\/schema\.org\//, "");
+        if (systems.some((s) => CORRESPONDING_SIZE_SYSTEM[s] === bare))
+            return null;
+        return { values: { sizeSystem, dimensionSystem: systems[0] } };
+    },
+    messageTemplate: "Size adjustment at `{path}` is in `{sizeSystem}` but the Sheet's sizing dimension is in `{dimensionSystem}`.",
+    remediation: "State the adjustment in the sizing dimension's system if the merchant states it there. If the merchant's advice is in another system, remove `sizeAdjustment` and keep the merchant's wording in `description`.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#size-guidance-pagefrontsizechart-and-pagefrontsizerecommendation",
+};

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

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

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

@@ -0,0 +1,91 @@
+import { asObject, seg } from "./configurator-pricing.js";
+/**
+ * PDP-E-015 — Amounts mix numbers and strings.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Walks `data` in document order over the catalogue's closed list of
+ * amount fields and fires once per Sheet when at least one amount is a
+ * JSON number and at least one is a string. `numberPath` and
+ * `stringPath` are the first amount of each carrier.
+ */
+const OFFER_FIELDS = ["price", "lowPrice", "highPrice"];
+const SPECIFICATION_FIELDS = ["price", "minPrice", "maxPrice"];
+const MONETARY_FIELDS = ["value", "minValue", "maxValue"];
+const ROLE_OF_KEY = {
+    offers: "offer",
+    priceSpecification: "specification",
+    hasVariant: "variant",
+    "pagefront:promotions": "promotion",
+    "pagefront:configuratorPricing": "pricing",
+};
+function record(found, value, path) {
+    if (typeof value === "number")
+        found.numberPath ??= path;
+    else if (typeof value === "string")
+        found.stringPath ??= path;
+}
+function amountFields(node, role) {
+    const fields = [];
+    if (role === "offer")
+        fields.push(...OFFER_FIELDS);
+    if (role === "specification")
+        fields.push(...SPECIFICATION_FIELDS);
+    if (role === "variant")
+        fields.push("price");
+    if (role === "promotion")
+        fields.push("discountAmount");
+    if (role === "pricing")
+        fields.push("basePrice");
+    if (role === "adjustment")
+        fields.push("priceModifier");
+    if (node["@type"] === "MonetaryAmount")
+        fields.push(...MONETARY_FIELDS);
+    return fields;
+}
+function walk(node, path, role, found) {
+    if (Array.isArray(node)) {
+        node.forEach((item, index) => walk(item, `${path}[${index}]`, role, found));
+        return;
+    }
+    const obj = asObject(node);
+    if (obj === null)
+        return;
+    const fields = amountFields(obj, role);
+    for (const [key, value] of Object.entries(obj)) {
+        const childPath = `${path}${seg(key)}`;
+        if (fields.includes(key)) {
+            record(found, value, childPath);
+            continue;
+        }
+        if (role === "modifiers") {
+            // one entry per dimension; every value under it is an amount
+            for (const [option, amount] of Object.entries(asObject(value) ?? {})) {
+                record(found, amount, `${childPath}${seg(option)}`);
+            }
+            continue;
+        }
+        let childRole = ROLE_OF_KEY[key];
+        if (role === "pricing" && key === "modifiers")
+            childRole = "modifiers";
+        if (role === "pricing" && key === "adjustments")
+            childRole = "adjustment";
+        walk(value, childPath, childRole, found);
+    }
+}
+export const pdpE015 = {
+    id: "PDP-E-015",
+    title: "Amounts mix numbers and strings",
+    severity: "error",
+    target: "$.data",
+    check: (match) => {
+        const found = {};
+        walk(match.value, match.path, undefined, found);
+        if (found.numberPath === undefined || found.stringPath === undefined)
+            return null;
+        return { values: { numberPath: found.numberPath, stringPath: found.stringPath } };
+    },
+    messageTemplate: "Amounts mix numbers and strings; use one carrier throughout the Sheet.",
+    remediation: "Carry every amount the same way. Decimal strings are recommended when amounts have fractional parts.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#amounts",
+};

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

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-016 — Sheet carries both format_version and release.
+ * Transcribed from commerce/spec/rules.md (normative); the check is
+ * shared with ORG-E-002 (release-schema.ts).
+ */
+export declare const pdpE016: Rule;

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

@@ -0,0 +1,13 @@
+import { BOTH_VERSION_FIELDS, bothVersionFields } from "./release-schema.js";
+/**
+ * PDP-E-016 — Sheet carries both format_version and release.
+ * Transcribed from commerce/spec/rules.md (normative); the check is
+ * shared with ORG-E-002 (release-schema.ts).
+ */
+export const pdpE016 = {
+    id: "PDP-E-016",
+    ...BOTH_VERSION_FIELDS,
+    check: bothVersionFields,
+    introduced: "release 0.3.0",
+    specReference: "product.md#the-envelope",
+};

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

@@ -4,7 +4,8 @@ import type { Rule } from "@pagefront/lint-core";
  * 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.
+ * `complete`. One finding per priced option with no modifier, one per
+ * priced text dimension with no `*` modifier, and one per priced select
+ * dimension that enumerates no options, all at the block.
  */
 export declare const pdpW032: Rule;

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

@@ -4,8 +4,9 @@ import { asObject, isComplete, missingModifierProblems, resolveConfigurator, } f
  * 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.
+ * `complete`. One finding per priced option with no modifier, one per
+ * priced text dimension with no `*` modifier, and one per priced select
+ * dimension that enumerates no options, all at the block.
  */
 export const pdpW032 = {
     id: "PDP-W-032",
@@ -19,24 +20,31 @@ export const pdpW032 = {
         const configurator = resolveConfigurator(block, ctx.sheet);
         if (configurator === null)
             return null;
-        const hits = missingModifierProblems(configurator, block).map((p) => p.kind === "no-options"
+        const hits = missingModifierProblems(configurator, block).map((p) => p.kind === "no-text-modifier"
             ? {
                 values: {
                     dimension: p.dimension,
-                    problem: `cannot state modifiers for \`${p.dimension}\`, a priced dimension that enumerates no options`,
+                    problem: `states no \`*\` modifier for text dimension \`${p.dimension}\``,
                 },
             }
-            : {
-                values: {
-                    dimension: p.dimension,
-                    option: p.option,
-                    problem: `states no modifier for option \`${p.option}\` of \`${p.dimension}\``,
-                },
-            });
+            : 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\"`.",
+    remediation: "State the modifier, zero included; for a text dimension, state it under the key `\"*\"`. 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-036.d.ts

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

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

@@ -0,0 +1,31 @@
+import { valueAtPath } from "@pagefront/lint-core";
+import { asObject } from "./configurator-pricing.js";
+/**
+ * PDP-W-036 — Option value looks like a display label.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Heuristic on string option values: whitespace, an uppercase letter,
+ * or a decimal number followed by letters to the end (a unit suffix).
+ * Options of a sizing dimension (one declaring `system`) are exempt;
+ * PDP-W-037 checks those.
+ */
+const UNIT_SUFFIX = /^-?\d+(\.\d+)?\p{L}+$/u;
+export const pdpW036 = {
+    id: "PDP-W-036",
+    title: "Option value looks like a display label",
+    severity: "warning",
+    target: "$.data['pagefront:configurator'].dimensions[*].options[*]",
+    check: (match, ctx) => {
+        const value = asObject(match.value)?.["value"];
+        if (typeof value !== "string")
+            return null;
+        const dimension = asObject(valueAtPath(ctx.sheet, match.path.replace(/\['options'\]\[\d+\]$/, "")));
+        if (typeof dimension?.["system"] === "string")
+            return null;
+        return /\s/.test(value) || /\p{Lu}/u.test(value) || UNIT_SUFFIX.test(value) ? {} : null;
+    },
+    messageTemplate: "Option value should be a stable identifier; put the label in description.",
+    remediation: "Replace the value with a lowercase identifier without spaces (`yellow_gold`, `0.5`) and move the label to `description`. Put a unit in the dimension's `note`. Update the pricing block's keys, `baseConfiguration`, `when` and `exclusions` to the new value.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

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

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

@@ -0,0 +1,37 @@
+import { valueAtPath } from "@pagefront/lint-core";
+import { asObject } from "./configurator-pricing.js";
+/**
+ * PDP-W-037 — Option in a sizing dimension is not a size.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Heuristic on string option values of a dimension whose `system` is
+ * `UK`, `EU`, `US` or `JP`: the value is written as that system writes
+ * a size. Other systems are out of scope.
+ */
+const NUMERIC_SIZE = /^\d+(\.\d+|½)?$/;
+const SIZE_IN_SYSTEM = {
+    UK: /^[A-Z]\s*½?$/,
+    EU: NUMERIC_SIZE,
+    US: NUMERIC_SIZE,
+    JP: NUMERIC_SIZE,
+};
+export const pdpW037 = {
+    id: "PDP-W-037",
+    title: "Option in a sizing dimension is not a size",
+    severity: "warning",
+    target: "$.data['pagefront:configurator'].dimensions[*].options[*]",
+    check: (match, ctx) => {
+        const value = asObject(match.value)?.["value"];
+        if (typeof value !== "string")
+            return null;
+        const dimension = asObject(valueAtPath(ctx.sheet, match.path.replace(/\['options'\]\[\d+\]$/, "")));
+        const system = dimension?.["system"];
+        if (typeof system !== "string" || !Object.hasOwn(SIZE_IN_SYSTEM, system))
+            return null;
+        return SIZE_IN_SYSTEM[system].test(value) ? null : {};
+    },
+    messageTemplate: "Option does not look like a size in the declared system.",
+    remediation: "Remove the entry if it is a service, and describe the service in the dimension's `note` or in `pagefront:madeToOrderTerms.aftermarketServices`. If it is a size, write it as the system writes it, without the system's name.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

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

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

@@ -0,0 +1,30 @@
+import { asObject } from "./configurator-pricing.js";
+/**
+ * PDP-W-038 — Configurator note reads as page copy.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Heuristic on English Sheets (`inLanguage` `en` or `en-…`): the
+ * dimension's `note` contains `you`, `your`, `select`, `order` or
+ * `contact` as a whole word, delimited by non-letters.
+ */
+const PAGE_COPY_WORD = /(?<!\p{L})(you|your|select|order|contact)(?!\p{L})/iu;
+export const pdpW038 = {
+    id: "PDP-W-038",
+    title: "Configurator note reads as page copy",
+    severity: "warning",
+    target: "$.data['pagefront:configurator'].dimensions[*]",
+    check: (match, ctx) => {
+        const inLanguage = asObject(ctx.sheet.data)?.["inLanguage"];
+        if (typeof inLanguage !== "string" || !/^en(-|$)/i.test(inLanguage))
+            return null;
+        const note = asObject(match.value)?.["note"];
+        if (typeof note !== "string")
+            return null;
+        const found = PAGE_COPY_WORD.exec(note);
+        return found === null ? null : { values: { word: found[1].toLowerCase() } };
+    },
+    messageTemplate: "Note reads as page copy; state the fact.",
+    remediation: "Restate the note as a fact in the third person: what the merchant offers or recommends, with no \"you\" and no instruction.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#configurator-pricing-and-price-bands",
+};

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

@@ -0,0 +1,10 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-039 — Size advice carried as prose only.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when `pagefront:sizeRecommendation` carries a non-empty
+ * `description` and no `sizeAdjustment`, and the configurator has a
+ * sizing dimension. `{system}` is the first sizing dimension's system.
+ */
+export declare const pdpW039: Rule;

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

@@ -0,0 +1,29 @@
+import { asObject, readConfigurator } from "./configurator-pricing.js";
+/**
+ * PDP-W-039 — Size advice carried as prose only.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * Fires when `pagefront:sizeRecommendation` carries a non-empty
+ * `description` and no `sizeAdjustment`, and the configurator has a
+ * sizing dimension. `{system}` is the first sizing dimension's system.
+ */
+export const pdpW039 = {
+    id: "PDP-W-039",
+    title: "Size advice carried as prose only",
+    severity: "warning",
+    target: "$.data['pagefront:sizeRecommendation']",
+    check: (match, ctx) => {
+        const recommendation = asObject(match.value);
+        if (recommendation === null || recommendation["sizeAdjustment"] !== undefined)
+            return null;
+        const description = recommendation["description"];
+        if (typeof description !== "string" || description.trim() === "")
+            return null;
+        const sizing = (readConfigurator(ctx.sheet)?.dimensions ?? []).find((d) => d.system !== undefined);
+        return sizing?.system === undefined ? null : { values: { system: sizing.system } };
+    },
+    messageTemplate: "Size advice at `{path}` could not be stated in the Sheet's sizing system (`{system}`); it is carried as prose only.",
+    remediation: "If the merchant states the advice in the sizing dimension's system, add a `sizeAdjustment` in that system. If it does not, no action: do not convert between systems.",
+    introduced: "v0.9 (2026-10-01 revision)",
+    specReference: "product.md#size-guidance-pagefrontsizechart-and-pagefrontsizerecommendation",
+};

package/dist/rules/release-schema.d.ts

@@ -0,0 +1,16 @@
+import type { CheckFn, Rule } from "@pagefront/lint-core";
+import type { SheetType } from "../sheet-type.js";
+/**
+ * Release / schema mismatch. On the release line the `$schema` version
+ * segment must be the sheet-spec version the release manifest maps the
+ * declared `release` and the sheet type to; a release the manifest does
+ * not list has no mapping and the rule is silent. On the legacy line
+ * the segment must equal `format_version`, as before. Quiet when
+ * `$schema` is absent or names no version, and when the sheet carries
+ * both fields (the both-fields rule reports that).
+ */
+export declare function releaseSchemaMismatch(sheetType: SheetType): CheckFn;
+export declare const RELEASE_SCHEMA_MISMATCH: Pick<Rule, "title" | "severity" | "target" | "messageTemplate" | "remediation">;
+/** A sheet carrying both `format_version` and `release`. */
+export declare const bothVersionFields: CheckFn;
+export declare const BOTH_VERSION_FIELDS: Pick<Rule, "title" | "severity" | "target" | "messageTemplate" | "remediation">;

package/dist/rules/release-schema.js

@@ -0,0 +1,77 @@
+import { sheetSpecVersionFor } from "../releases.js";
+/**
+ * Shared checks for the envelope's version fields, used by the product
+ * and organization catalogues (PDP-E-002 / ORG-E-003, PDP-E-016 /
+ * ORG-E-002). Transcribed from commerce/spec/rules.md (normative).
+ */
+/** The trailing `v<version>.json` of a `$schema` URL. */
+const SCHEMA_VERSION = /v(\d+(?:\.\d+)*)\.json$/;
+const SHEET_LABEL = {
+    product: "Product Sheet",
+    organization: "Organization Sheet",
+};
+/**
+ * Release / schema mismatch. On the release line the `$schema` version
+ * segment must be the sheet-spec version the release manifest maps the
+ * declared `release` and the sheet type to; a release the manifest does
+ * not list has no mapping and the rule is silent. On the legacy line
+ * the segment must equal `format_version`, as before. Quiet when
+ * `$schema` is absent or names no version, and when the sheet carries
+ * both fields (the both-fields rule reports that).
+ */
+export function releaseSchemaMismatch(sheetType) {
+    return (_match, ctx) => {
+        const { release, format_version: formatVersion, $schema: schema } = ctx.sheet;
+        if (typeof schema !== "string")
+            return null;
+        const schemaVersion = SCHEMA_VERSION.exec(schema)?.[1];
+        if (schemaVersion === undefined)
+            return null;
+        if (release !== undefined && formatVersion !== undefined)
+            return null;
+        if (typeof release === "string") {
+            const expected = sheetSpecVersionFor(release, sheetType);
+            if (expected === undefined || expected === schemaVersion)
+                return null;
+            return {
+                path: "$['release']",
+                values: {
+                    declared: `\`release\` \`${release}\` bundles ${SHEET_LABEL[sheetType]} spec \`${expected}\``,
+                    release,
+                    expected,
+                    schema_version: schemaVersion,
+                },
+            };
+        }
+        if (formatVersion !== undefined) {
+            const declared = String(formatVersion);
+            if (declared === schemaVersion)
+                return null;
+            return {
+                path: "$['format_version']",
+                values: {
+                    declared: `\`format_version\` is \`${declared}\``,
+                    format_version: declared,
+                    schema_version: schemaVersion,
+                },
+            };
+        }
+        return null;
+    };
+}
+export const RELEASE_SCHEMA_MISMATCH = {
+    title: "Release / schema mismatch",
+    severity: "error",
+    target: "$",
+    messageTemplate: "{declared} but `$schema` URL declares version `{schema_version}`.",
+    remediation: "Point `$schema` at the sheet-spec version the declared release bundles (see releases.md), or declare the release that bundles the schema the sheet was written against. On a legacy sheet, align `format_version` and the `$schema` version.",
+};
+/** A sheet carrying both `format_version` and `release`. */
+export const bothVersionFields = (_match, ctx) => ctx.sheet.release !== undefined && ctx.sheet.format_version !== undefined ? {} : null;
+export const BOTH_VERSION_FIELDS = {
+    title: "Sheet carries both format_version and release",
+    severity: "error",
+    target: "$",
+    messageTemplate: "Sheet carries both `format_version` and `release`; a sheet declares one.",
+    remediation: "Keep `release` and remove `format_version`. A sheet on the legacy draft line keeps `format_version` alone and its legacy `$schema`.",
+};

package/dist/schema-validators.d.ts

@@ -8,3 +8,5 @@ import type { ValidateFunction } from "ajv";
 
 export const validateProduct: ValidateFunction;
 export const validateOrganization: ValidateFunction;
+export const validateLegacyProduct: ValidateFunction;
+export const validateLegacyOrganization: ValidateFunction;