@pagefront/lint-commerce 0.12.0 → 0.13.0

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

@@ -0,0 +1,31 @@
+import { asObject } from "./configurator-pricing.js";
+import { declaresRegion } from "./checkout-template.js";
+/**
+ * PDP-E-020 — Checkout template without a region.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer that carries `checkoutPageURLTemplate` declares the market the
+ * checkout serves with `areaServed` or `eligibleRegion` ("Where to buy").
+ * A region property that is empty or whitespace-only counts as absent.
+ * The template's own validity is PDP-E-019's concern. Applies from
+ * release 0.5.0, whose Product Sheet spec 0.11.0 introduces the
+ * requirement.
+ */
+export const pdpE020 = {
+    id: "PDP-E-020",
+    title: "Checkout template without a region",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = asObject(match.value);
+        if (offer === null || !Object.prototype.hasOwnProperty.call(offer, "checkoutPageURLTemplate"))
+            return null;
+        return declaresRegion(offer) ? null : { path: match.path, values: {} };
+    },
+    messageTemplate: "Offer at `{path}` carries `checkoutPageURLTemplate` and neither `areaServed` nor `eligibleRegion`.",
+    remediation: "Declare the region the checkout serves, or remove the template.",
+    introduced: "release 0.5.0",
+    // The requirement is introduced by release 0.5.0 (Product Sheet spec 0.11.0).
+    appliesFrom: "0.5.0",
+    specReference: "product.md#where-to-buy",
+};

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

@@ -0,0 +1,11 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-021 — Offer `url` is not an absolute URL.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer's `url` is the page on which the shopper buys it ("Where to
+ * buy"); when present it must be a full absolute URL with the scheme
+ * http or https. Silent when the Offer carries no `url` (PDP-W-040's
+ * concern on a sheet with several offers). Applies from release 0.5.0.
+ */
+export declare const pdpE021: Rule;

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

@@ -0,0 +1,32 @@
+import { asObject, own } from "./configurator-pricing.js";
+import { isAbsoluteHttpUrl } from "./checkout-template.js";
+/**
+ * PDP-E-021 — Offer `url` is not an absolute URL.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer's `url` is the page on which the shopper buys it ("Where to
+ * buy"); when present it must be a full absolute URL with the scheme
+ * http or https. Silent when the Offer carries no `url` (PDP-W-040's
+ * concern on a sheet with several offers). Applies from release 0.5.0.
+ */
+export const pdpE021 = {
+    id: "PDP-E-021",
+    title: "Offer url is not an absolute URL",
+    severity: "error",
+    target: "$.data.offers[*]",
+    check: (match) => {
+        const offer = asObject(match.value);
+        if (offer === null || !Object.prototype.hasOwnProperty.call(offer, "url"))
+            return null;
+        const url = own(offer, "url");
+        if (isAbsoluteHttpUrl(url))
+            return null;
+        return { path: `${match.path}['url']`, values: { url: JSON.stringify(url) } };
+    },
+    messageTemplate: "Offer `url` at `{path}` is `{url}`, which is not an absolute `http` or `https` URL.",
+    remediation: "Give the offer the absolute URL of the page where it is bought.",
+    introduced: "release 0.5.0",
+    // The requirement is introduced by release 0.5.0 (Product Sheet spec 0.11.0).
+    appliesFrom: "0.5.0",
+    specReference: "product.md#where-to-buy",
+};

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

@@ -46,7 +46,7 @@ export const pdpW021 = {
         }
         return hits;
     },
-    messageTemplate: "Variant link `{name}` at `{path}` appears to reference a separate Sheet by `@id` but omits the recommended `sheet_url`; consumers must reach the target Sheet via `url` + `describedby`.",
+    messageTemplate: "Variant link `{name}` at `{path}` appears to reference a separate Sheet by `@id` but omits the recommended `sheet_url`; consumers must reach the target Sheet via `url` + `alternate`.",
     remediation: "Add `sheet_url` with the target's Sheet URL — the variant's Sheet URL on a parent `hasVariant` entry, or the parent's Sheet URL on a variant's `isVariantOf`. If you do not emit a separate Sheet for the target (the family is modeled inline in one ProductGroup Sheet), no cross-Sheet link exists and `sheet_url` does not apply.",
     introduced: "v0.7",
     appliesFrom: "0.3.0",

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

@@ -3,10 +3,10 @@ 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
+ * Fires when an offer's `seller` carries `@id` but neither
+ * `pagefront:sheetUrl` nor `url`, 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.
+ * inherit sit on a seller sheet no consumer can reach, by the hint or
+ * through the seller's page. The finding sits at the `seller` path.
  */
 export declare const pdpW031: Rule;

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

@@ -2,11 +2,11 @@
  * 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
+ * Fires when an offer's `seller` carries `@id` but neither
+ * `pagefront:sheetUrl` nor `url`, 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.
+ * inherit sit on a seller sheet no consumer can reach, by the hint or
+ * through the seller's page. The finding sits at the `seller` path.
  */
 export const pdpW031 = {
     id: "PDP-W-031",
@@ -22,14 +22,16 @@ export const pdpW031 = {
         if (typeof seller !== "object" || seller === null || Array.isArray(seller))
             return null;
         const s = seller;
-        if (s["@id"] === undefined || s["pagefront:sheetUrl"] !== undefined)
+        if (s["@id"] === undefined)
+            return null;
+        if (s["pagefront:sheetUrl"] !== undefined || s["url"] !== 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.",
+    messageTemplate: "Seller at `{path}` has an `@id` but neither `pagefront:sheetUrl` nor `url`, and the Offer states no return or shipping terms of its own.",
+    remediation: "Add `url` or `pagefront:sheetUrl` to the seller reference, or state the terms on the Offer.",
     introduced: "v0.9",
     appliesFrom: "0.3.0",
     appliesToLegacy: true,

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

@@ -0,0 +1,12 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-W-040 — Offer without `url` among several offers.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer without `url` is bought on the product's page; that default
+ * serves a single offer. When `offers` is an array with more than one
+ * entry, each entry should state its own `url` ("Where to buy"). One
+ * finding per entry without it; silent on a single offer. Applies from
+ * release 0.5.0.
+ */
+export declare const pdpW040: Rule;

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

@@ -0,0 +1,37 @@
+import { asObject, own } from "./configurator-pricing.js";
+/**
+ * PDP-W-040 — Offer without `url` among several offers.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * An Offer without `url` is bought on the product's page; that default
+ * serves a single offer. When `offers` is an array with more than one
+ * entry, each entry should state its own `url` ("Where to buy"). One
+ * finding per entry without it; silent on a single offer. Applies from
+ * release 0.5.0.
+ */
+export const pdpW040 = {
+    id: "PDP-W-040",
+    title: "Offer without url among several offers",
+    severity: "warning",
+    target: "$.data",
+    check: (match) => {
+        const data = asObject(match.value);
+        const offers = own(data, "offers");
+        if (!Array.isArray(offers) || offers.length < 2)
+            return null;
+        const hits = [];
+        offers.forEach((entry, index) => {
+            const offer = asObject(entry);
+            if (offer !== null && !Object.prototype.hasOwnProperty.call(offer, "url")) {
+                hits.push({ path: `${match.path}['offers'][${index}]`, values: {} });
+            }
+        });
+        return hits.length > 0 ? hits : null;
+    },
+    messageTemplate: "Offer at `{path}` has no `url`, and the sheet carries several offers.",
+    remediation: "Give each offer the URL of the page where it is bought.",
+    introduced: "release 0.5.0",
+    // "Where to buy" is introduced by release 0.5.0 (Product Sheet spec 0.11.0).
+    appliesFrom: "0.5.0",
+    specReference: "product.md#where-to-buy",
+};

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

@@ -1,5 +1,5 @@
 import type { CheckFn, Rule } from "@pagefront/lint-core";
-import type { SheetType } from "../sheet-type.js";
+import { type SheetType } from "../sheet-type.js";
 /**
  * Release / schema mismatch. The rule reads `$schema` and is quiet
  * whenever it is absent, on both lines: whether `$schema` is required is
@@ -8,7 +8,8 @@ import type { SheetType } from "../sheet-type.js";
  * present `$schema` must be the URL of the sheet-spec schema the release
  * manifest maps the declared `release` and the sheet type to; a release
  * the manifest does not list has no mapping (the unknown-release rule
- * reports it). On the legacy line the `$schema` version segment must
+ * reports it), and neither has a listed release that bundles no schema
+ * for the sheet type (Layer 1 reports that). On the legacy line the `$schema` version segment must
  * equal `format_version`, as before. Quiet when the sheet carries both
  * fields (the both-fields rule reports that).
  */

package/dist/rules/release-schema.js

@@ -1,15 +1,13 @@
-import { KNOWN_RELEASES, schemaUrlFor, sheetSpecVersionFor } from "../releases.js";
+import { knownReleases, schemaUrlFor, sheetSpecVersionFor } from "../releases.js";
+import { SHEET_LABEL } from "../sheet-type.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).
+ * Shared checks for the envelope's version fields, used by the product,
+ * organization and collection catalogues (PDP-E-002 / ORG-E-003 /
+ * COL-E-003, PDP-E-016 / ORG-E-002, PDP-E-018 / ORG-E-004 / COL-E-004).
+ * 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. The rule reads `$schema` and is quiet
  * whenever it is absent, on both lines: whether `$schema` is required is
@@ -18,7 +16,8 @@ const SHEET_LABEL = {
  * present `$schema` must be the URL of the sheet-spec schema the release
  * manifest maps the declared `release` and the sheet type to; a release
  * the manifest does not list has no mapping (the unknown-release rule
- * reports it). On the legacy line the `$schema` version segment must
+ * reports it), and neither has a listed release that bundles no schema
+ * for the sheet type (Layer 1 reports that). On the legacy line the `$schema` version segment must
  * equal `format_version`, as before. Quiet when the sheet carries both
  * fields (the both-fields rule reports that).
  */
@@ -104,9 +103,10 @@ export const BOTH_VERSION_FIELDS = {
  */
 export const unknownRelease = (_match, ctx) => {
     const { release } = ctx.sheet;
-    if (typeof release !== "string" || KNOWN_RELEASES.includes(release))
+    const known = knownReleases();
+    if (typeof release !== "string" || known.includes(release))
         return null;
-    return { path: "$['release']", values: { release, known: KNOWN_RELEASES.join(", ") } };
+    return { path: "$['release']", values: { release, known: known.join(", ") } };
 };
 export const UNKNOWN_RELEASE = {
     title: "Unknown release",

package/dist/schema-registry.d.ts

@@ -18,6 +18,17 @@ export type SchemaResolution = {
     kind: "unknown-release";
     declared: string;
 }
+/**
+ * The release bundles no schema for the sheet's type: the type joined
+ * the line after that release (`release` is the release tried, the
+ * declared one or the current one), or the sheet is on the legacy
+ * draft line and the type was never on it (`release` is null).
+ */
+ | {
+    kind: "unbundled-type";
+    sheetType: SheetType;
+    release: string | null;
+}
 /** A legacy sheet's `$schema` names no schema this package bundles. */
  | {
     kind: "unknown-schema";

package/dist/schema-registry.js

@@ -1,5 +1,6 @@
 import { SCHEMA_IDS } from "./generated/schema-ids.js";
-import { CURRENT_RELEASE, legacySchemaUrl, schemaUrlFor, sheetSpecVersionFor, } from "./releases.js";
+import { overrides } from "./overrides.js";
+import { currentRelease, knownReleases, legacySchemaUrl, schemaUrlFor, sheetSpecVersionFor, } from "./releases.js";
 import { detectSheetLine, detectSheetType } from "./sheet-type.js";
 /**
  * The identifiers the legacy schemas carried before 2026-09-08
@@ -29,24 +30,38 @@ export function resolveSchema(sheet, sheetType) {
     if (sheet.release !== undefined) {
         // A non-string release is validated against the current schema,
         // whose `release` pattern rejects it.
-        if (typeof sheet.release !== "string") {
-            return { kind: "schema", id: schemaUrlFor(type, sheetSpecVersionFor(CURRENT_RELEASE, type)) };
-        }
+        if (typeof sheet.release !== "string")
+            return currentSchema(type);
+        if (!knownReleases().includes(sheet.release))
+            return { kind: "unknown-release", declared: sheet.release };
         const version = sheetSpecVersionFor(sheet.release, type);
         if (version === undefined)
-            return { kind: "unknown-release", declared: sheet.release };
+            return { kind: "unbundled-type", sheetType: type, release: sheet.release };
         return { kind: "schema", id: schemaUrlFor(type, version) };
     }
     if (typeof declared === "string") {
-        if (SCHEMA_IDS.includes(declared))
+        if (SCHEMA_IDS.includes(declared) || overrides().validators?.[declared] !== undefined) {
             return { kind: "schema", id: declared };
+        }
         const former = FORMER_LEGACY_ID.exec(declared);
         if (former !== null)
             return { kind: "schema", id: legacySchemaUrl(former[1]) };
         if (detectSheetLine(sheet) === "legacy")
             return { kind: "unknown-schema", declared };
     }
-    if (detectSheetLine(sheet) === "legacy")
-        return { kind: "schema", id: legacySchemaUrl(type) };
-    return { kind: "schema", id: schemaUrlFor(type, sheetSpecVersionFor(CURRENT_RELEASE, type)) };
+    if (detectSheetLine(sheet) === "legacy") {
+        const legacy = legacySchemaUrl(type);
+        return legacy === undefined
+            ? { kind: "unbundled-type", sheetType: type, release: null }
+            : { kind: "schema", id: legacy };
+    }
+    return currentSchema(type);
+}
+/** The current release's schema for a type, or unbundled-type when the current release has none. */
+function currentSchema(type) {
+    const release = currentRelease();
+    const version = sheetSpecVersionFor(release, type);
+    if (version === undefined)
+        return { kind: "unbundled-type", sheetType: type, release };
+    return { kind: "schema", id: schemaUrlFor(type, version) };
 }