@pagefront/lint-commerce 0.11.0 → 0.12.0

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

@@ -35,5 +35,7 @@ export const pdpW023 = {
     messageTemplate: "Recall safety notice at `{path}` coexists with offer at `{offerPath}` declaring `InStock`; the recall overrides commercial signals and the offer data likely needs updating.",
     remediation: "Update the offer's `availability` to reflect the corrective measure (typically `Discontinued` or `OutOfStock`). If the recall has been resolved and the product legitimately relisted, remove the stale `pagefront:safetyNotice` entry instead.",
     introduced: "v0.8",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#safety-notices",
 };

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

@@ -54,5 +54,7 @@ export const pdpW024 = {
     messageTemplate: "`pagefront:legalEntity` entry with role `{role}` at `{path}` declares an organization without an `address`.",
     remediation: "Add the entity's postal address to the `organization`. If no address is available, the entry still identifies the organization but should not be relied on as a regulatory responsible-person declaration.",
     introduced: "v0.8",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#legal-entities",
 };

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

@@ -31,5 +31,7 @@ export const pdpW025 = {
     messageTemplate: "Feature `{name}` at `{path}` carries value `{value}`, which parses as a number plus a unit.",
     remediation: "Move the numeric part into `value`, express the unit as a `unitCode`, and if the merchant's display formatting matters, carry the original string in `pagefront:presentationValue`.",
     introduced: "v0.8",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#feature-groups",
 };

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

@@ -27,5 +27,7 @@ export const pdpW026 = {
     messageTemplate: "Safety data sheet at `{path}` declares no `inLanguage`.",
     remediation: "Add the document's BCP 47 language tag as `inLanguage`. If the document is multilingual, declare the primary language.",
     introduced: "v0.8",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#documents",
 };

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

@@ -43,5 +43,7 @@ export const pdpW027 = {
     messageTemplate: "Question `{name}` at `{path}` has an `acceptedAnswer` with no text.",
     remediation: "Populate `acceptedAnswer.text` with the answer prose, or remove the `acceptedAnswer` (and consider whether an unanswered question belongs in the sheet at all).",
     introduced: "v0.8",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#product-qa",
 };

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

@@ -25,5 +25,7 @@ export const pdpW028 = {
     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",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#tax-inclusion",
 };

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

@@ -24,5 +24,7 @@ export const pdpW029 = {
     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",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#tax-inclusion",
 };

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

@@ -48,5 +48,7 @@ export const pdpW030 = {
     messageTemplate: "Warranty at `{path}` states neither a duration nor a description.",
     remediation: "State the warranty as written in `description`, and add `durationOfWarranty` where a finite length is stated. A lifetime warranty carries `description` (and optionally `name`) with no `durationOfWarranty`.",
     introduced: "v0.9",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#warranty",
 };

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

@@ -31,5 +31,7 @@ export const pdpW031 = {
     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",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "organization.md#linking-contract-identity-only",
 };

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

@@ -46,5 +46,7 @@ export const pdpW032 = {
     messageTemplate: "Pricing block at `{path}` {problem}, and `pricing` is not `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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -26,5 +26,7 @@ export const pdpW033 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -24,5 +24,7 @@ export const pdpW034 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -37,5 +37,7 @@ export const pdpW035 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -27,5 +27,7 @@ export const pdpW036 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -33,5 +33,7 @@ export const pdpW037 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -26,5 +26,7 @@ export const pdpW038 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#configurator-pricing-and-price-bands",
 };

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

@@ -25,5 +25,7 @@ export const pdpW039 = {
     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)",
+    appliesFrom: "0.3.0",
+    appliesToLegacy: true,
     specReference: "product.md#size-guidance-pagefrontsizechart-and-pagefrontsizerecommendation",
 };

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

@@ -1,16 +1,27 @@
 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).
+ * Release / schema mismatch. The rule reads `$schema` and is quiet
+ * whenever it is absent, on both lines: whether `$schema` is required is
+ * the schema's own statement (Product Sheet spec 0.10.0 and Organization
+ * Sheet spec 0.4.0 onward), not this rule's. On the release line a
+ * 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
+ * equal `format_version`, as before. Quiet 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">;
+/**
+ * Unknown release: the sheet declares a `release` the release manifest
+ * does not list, so no sheet-spec version and no schema can be resolved
+ * for it. Only a string `release` is judged; another JSON type is
+ * Layer 1's concern.
+ */
+export declare const unknownRelease: CheckFn;
+export declare const UNKNOWN_RELEASE: Pick<Rule, "title" | "severity" | "target" | "messageTemplate" | "remediation">;

package/dist/rules/release-schema.js

@@ -1,4 +1,4 @@
-import { sheetSpecVersionFor } from "../releases.js";
+import { KNOWN_RELEASES, schemaUrlFor, 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 /
@@ -11,39 +11,59 @@ const SHEET_LABEL = {
     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).
+ * Release / schema mismatch. The rule reads `$schema` and is quiet
+ * whenever it is absent, on both lines: whether `$schema` is required is
+ * the schema's own statement (Product Sheet spec 0.10.0 and Organization
+ * Sheet spec 0.4.0 onward), not this rule's. On the release line a
+ * 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
+ * equal `format_version`, as before. Quiet 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;
+        const schemaVersion = SCHEMA_VERSION.exec(schema)?.[1];
         if (typeof release === "string") {
             const expected = sheetSpecVersionFor(release, sheetType);
-            if (expected === undefined || expected === schemaVersion)
+            if (expected === undefined)
+                return null;
+            const expectedUrl = schemaUrlFor(sheetType, expected);
+            if (schema === expectedUrl)
                 return null;
+            const declared = `\`release\` \`${release}\` bundles ${SHEET_LABEL[sheetType]} spec \`${expected}\``;
+            if (schemaVersion !== undefined && schemaVersion !== expected) {
+                return {
+                    path: "$['release']",
+                    values: {
+                        declared,
+                        found: `\`$schema\` URL declares version \`${schemaVersion}\``,
+                        release,
+                        expected,
+                        schema_version: schemaVersion,
+                    },
+                };
+            }
             return {
                 path: "$['release']",
                 values: {
-                    declared: `\`release\` \`${release}\` bundles ${SHEET_LABEL[sheetType]} spec \`${expected}\``,
+                    declared,
+                    found: `\`$schema\` is not that schema's URL, \`${expectedUrl}\``,
                     release,
                     expected,
-                    schema_version: schemaVersion,
+                    expected_url: expectedUrl,
                 },
             };
         }
         if (formatVersion !== undefined) {
+            if (schemaVersion === undefined)
+                return null;
             const declared = String(formatVersion);
             if (declared === schemaVersion)
                 return null;
@@ -51,6 +71,7 @@ export function releaseSchemaMismatch(sheetType) {
                 path: "$['format_version']",
                 values: {
                     declared: `\`format_version\` is \`${declared}\``,
+                    found: `\`$schema\` URL declares version \`${schemaVersion}\``,
                     format_version: declared,
                     schema_version: schemaVersion,
                 },
@@ -63,7 +84,7 @@ export const RELEASE_SCHEMA_MISMATCH = {
     title: "Release / schema mismatch",
     severity: "error",
     target: "$",
-    messageTemplate: "{declared} but `$schema` URL declares version `{schema_version}`.",
+    messageTemplate: "{declared} but {found}.",
     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`. */
@@ -75,3 +96,22 @@ export const BOTH_VERSION_FIELDS = {
     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`.",
 };
+/**
+ * Unknown release: the sheet declares a `release` the release manifest
+ * does not list, so no sheet-spec version and no schema can be resolved
+ * for it. Only a string `release` is judged; another JSON type is
+ * Layer 1's concern.
+ */
+export const unknownRelease = (_match, ctx) => {
+    const { release } = ctx.sheet;
+    if (typeof release !== "string" || KNOWN_RELEASES.includes(release))
+        return null;
+    return { path: "$['release']", values: { release, known: KNOWN_RELEASES.join(", ") } };
+};
+export const UNKNOWN_RELEASE = {
+    title: "Unknown release",
+    severity: "error",
+    target: "$",
+    messageTemplate: "`release` at `{path}` is `{release}`, which is not a release this catalogue knows ({known}).",
+    remediation: "Declare a published commerce release (see releases.md). If the release is newer than this linter, update the linter.",
+};

package/dist/schema-registry.d.ts

@@ -2,28 +2,41 @@ import type { Sheet } from "@pagefront/lint-core";
 import type { SheetType } from "./sheet-type.js";
 /**
  * Which frozen schema a sheet is validated against. The package bundles
- * every schema ever published (commerce/schemas/), keyed by `$id`, and a
- * sheet is validated against the one its `$schema` names, on either
- * line. Nothing is substituted: a `$schema` that names no bundled schema
- * is reported as such, and the sheet is not validated against a
- * neighbouring version.
+ * every schema ever published (commerce/schemas/), keyed by `$id`. A
+ * sheet is judged by the release it declares: on the release line the
+ * schema is the one the release manifest gives for the declared
+ * `release` and the sheet's type, whatever `$schema` says (a `$schema`
+ * that disagrees is PDP-E-002's finding, at Layer 2). Legacy sheets,
+ * which declare no release, keep resolving through their `$schema`.
  */
 export type SchemaResolution = {
     kind: "schema";
     id: string;
 }
-/** `$schema` is a string that names no schema this package bundles. */
+/** `release` names no release in the manifest. */
  | {
-    kind: "unknown";
+    kind: "unknown-release";
+    declared: string;
+}
+/** A legacy sheet's `$schema` names no schema this package bundles. */
+ | {
+    kind: "unknown-schema";
     declared: string;
 };
 /**
- * Resolve the schema for a document. A declared `$schema` is taken at
- * its word. Without one, the schema is the one the sheet's own
- * statements lead to: the legacy schema for a sheet on the legacy line,
- * and for a sheet on the release line the sheet-spec version its
- * `release` bundles (the current release's when the release is not in
- * the manifest). `sheetType` forces the type for callers that validate
- * one type only.
+ * Resolve the schema for a document.
+ *
+ * - Release line (`release` present): the sheet-spec version the
+ *   manifest bundles in that release for the sheet's type. The type
+ *   comes from the usual dispatch (`$schema` path, else data-block
+ *   shape), so it does not depend on `$schema` being present.
+ * - Legacy line (`format_version`, no `release`): the schema `$schema`
+ *   names when it is bundled, the legacy schema for the pre-2026-09-08
+ *   identifier or when `$schema` is absent.
+ * - Neither field: the schema `$schema` names when it is bundled, else
+ *   the current release's, whose `required` then reports the missing
+ *   `release`.
+ *
+ * `sheetType` forces the type for callers that validate one type only.
  */
 export declare function resolveSchema(sheet: Sheet, sheetType?: SheetType): SchemaResolution;

package/dist/schema-registry.js

@@ -8,28 +8,45 @@ import { detectSheetLine, detectSheetType } from "./sheet-type.js";
  */
 const FORMER_LEGACY_ID = /^https:\/\/themachineweb\.org\/pagefront\/commerce\/schemas\/(product|organization)\/v0\.9\.json$/;
 /**
- * Resolve the schema for a document. A declared `$schema` is taken at
- * its word. Without one, the schema is the one the sheet's own
- * statements lead to: the legacy schema for a sheet on the legacy line,
- * and for a sheet on the release line the sheet-spec version its
- * `release` bundles (the current release's when the release is not in
- * the manifest). `sheetType` forces the type for callers that validate
- * one type only.
+ * Resolve the schema for a document.
+ *
+ * - Release line (`release` present): the sheet-spec version the
+ *   manifest bundles in that release for the sheet's type. The type
+ *   comes from the usual dispatch (`$schema` path, else data-block
+ *   shape), so it does not depend on `$schema` being present.
+ * - Legacy line (`format_version`, no `release`): the schema `$schema`
+ *   names when it is bundled, the legacy schema for the pre-2026-09-08
+ *   identifier or when `$schema` is absent.
+ * - Neither field: the schema `$schema` names when it is bundled, else
+ *   the current release's, whose `required` then reports the missing
+ *   `release`.
+ *
+ * `sheetType` forces the type for callers that validate one type only.
  */
 export function resolveSchema(sheet, sheetType) {
+    const type = sheetType ?? detectSheetType(sheet);
     const declared = sheet.$schema;
+    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)) };
+        }
+        const version = sheetSpecVersionFor(sheet.release, type);
+        if (version === undefined)
+            return { kind: "unknown-release", declared: sheet.release };
+        return { kind: "schema", id: schemaUrlFor(type, version) };
+    }
     if (typeof declared === "string") {
         if (SCHEMA_IDS.includes(declared))
             return { kind: "schema", id: declared };
         const former = FORMER_LEGACY_ID.exec(declared);
         if (former !== null)
             return { kind: "schema", id: legacySchemaUrl(former[1]) };
-        return { kind: "unknown", declared };
+        if (detectSheetLine(sheet) === "legacy")
+            return { kind: "unknown-schema", declared };
     }
-    const type = sheetType ?? detectSheetType(sheet);
     if (detectSheetLine(sheet) === "legacy")
         return { kind: "schema", id: legacySchemaUrl(type) };
-    const release = typeof sheet.release === "string" ? sheet.release : CURRENT_RELEASE;
-    const version = sheetSpecVersionFor(release, type) ?? sheetSpecVersionFor(CURRENT_RELEASE, type);
-    return { kind: "schema", id: schemaUrlFor(type, version) };
+    return { kind: "schema", id: schemaUrlFor(type, sheetSpecVersionFor(CURRENT_RELEASE, type)) };
 }