@pagefront/lint-commerce 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -7,8 +7,12 @@
  * `validateOrganizationSheet` (Layer 1 for the Commerce Organization
  * Sheet; no organization catalogue exists yet), the commerce
  * catalogue object, and the types those signatures mention.
- * `product-schema.ts`, `organization-schema.ts`, and the individual
- * rule modules are internal.
+ * The bundled schemas (`generated/`), the compiled validators and the
+ * individual rule modules are internal. The release manifest
+ * (`RELEASE_MANIFEST`, `sheetSpecVersionFor`, `schemaUrlFor`) and the
+ * list of bundled schema ids (`BUNDLED_SCHEMA_IDS`) are exported so
+ * callers can resolve a release to its sheet-spec versions and tell
+ * which `$schema` values this package validates.
  */
 export { lintSheet } from "./lint-sheet.js";
 export { validateAndLint } from "./validate-and-lint.js";
@@ -17,6 +21,8 @@ export { validateOrganizationSheet } from "./validate-organization.js";
 export type { ValidateOrganizationResult } from "./validate-organization.js";
 export { commerceCatalogue } from "./catalogue.js";
 export { organizationCatalogue } from "./organization-catalogue.js";
-export { detectSheetType } from "./sheet-type.js";
-export type { SheetType } from "./sheet-type.js";
+export { detectSheetType, detectSheetLine } from "./sheet-type.js";
+export type { SheetType, SheetLine } from "./sheet-type.js";
+export { RELEASE_MANIFEST, KNOWN_RELEASES, CURRENT_RELEASE, sheetSpecVersionFor, schemaUrlFor, } from "./releases.js";
+export { SCHEMA_IDS as BUNDLED_SCHEMA_IDS } from "./generated/schema-ids.js";
 export type { Report, Finding, Summary, Severity, LintOptions, Sheet, } from "@pagefront/lint-core";

package/dist/index.js

@@ -7,12 +7,18 @@
  * `validateOrganizationSheet` (Layer 1 for the Commerce Organization
  * Sheet; no organization catalogue exists yet), the commerce
  * catalogue object, and the types those signatures mention.
- * `product-schema.ts`, `organization-schema.ts`, and the individual
- * rule modules are internal.
+ * The bundled schemas (`generated/`), the compiled validators and the
+ * individual rule modules are internal. The release manifest
+ * (`RELEASE_MANIFEST`, `sheetSpecVersionFor`, `schemaUrlFor`) and the
+ * list of bundled schema ids (`BUNDLED_SCHEMA_IDS`) are exported so
+ * callers can resolve a release to its sheet-spec versions and tell
+ * which `$schema` values this package validates.
  */
 export { lintSheet } from "./lint-sheet.js";
 export { validateAndLint } from "./validate-and-lint.js";
 export { validateOrganizationSheet } from "./validate-organization.js";
 export { commerceCatalogue } from "./catalogue.js";
 export { organizationCatalogue } from "./organization-catalogue.js";
-export { detectSheetType } from "./sheet-type.js";
+export { detectSheetType, detectSheetLine } from "./sheet-type.js";
+export { RELEASE_MANIFEST, KNOWN_RELEASES, CURRENT_RELEASE, sheetSpecVersionFor, schemaUrlFor, } from "./releases.js";
+export { SCHEMA_IDS as BUNDLED_SCHEMA_IDS } from "./generated/schema-ids.js";

package/dist/organization-catalogue.js

@@ -1,4 +1,7 @@
+import { KNOWN_RELEASES } from "./releases.js";
 import { orgE001 } from "./rules/org-e-001.js";
+import { orgE002 } from "./rules/org-e-002.js";
+import { orgE003 } from "./rules/org-e-003.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,7 +19,7 @@ import { orgW006 } from "./rules/org-w-006.js";
  */
 export const organizationCatalogue = {
     vertical: "commerce",
-    formatVersion: "0.9",
-    catalogueVersion: "0.14.0",
-    rules: [orgE001, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
+    releases: KNOWN_RELEASES,
+    catalogueVersion: "0.15.0",
+    rules: [orgE001, orgE002, orgE003, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
 };

package/dist/releases.d.ts

@@ -0,0 +1,22 @@
+import { RELEASE_MANIFEST } from "./generated/release-manifest.js";
+import type { SheetType } from "./sheet-type.js";
+/**
+ * The commerce release manifest (commerce/spec/releases.json): each
+ * release and the member versions it bundles. Bundled at build time by
+ * scripts/bundle-schemas.mjs, so the package always carries the
+ * manifest it was built from.
+ */
+export { RELEASE_MANIFEST };
+/** Every release the manifest lists, in manifest order. */
+export declare const KNOWN_RELEASES: readonly string[];
+/** The latest release the manifest lists. */
+export declare const CURRENT_RELEASE: string;
+/**
+ * The sheet-spec version a release bundles for a sheet type, or
+ * undefined when the manifest does not list the release.
+ */
+export declare function sheetSpecVersionFor(release: string, sheetType: SheetType): string | undefined;
+/** The published URL of a sheet spec's JSON Schema, which is also its `$id`. */
+export declare function schemaUrlFor(sheetType: SheetType, version: string): string;
+/** The legacy draft line's schema URL for a sheet type. */
+export declare function legacySchemaUrl(sheetType: SheetType): string;

package/dist/releases.js

@@ -0,0 +1,27 @@
+import { RELEASE_MANIFEST } from "./generated/release-manifest.js";
+/**
+ * The commerce release manifest (commerce/spec/releases.json): each
+ * release and the member versions it bundles. Bundled at build time by
+ * scripts/bundle-schemas.mjs, so the package always carries the
+ * manifest it was built from.
+ */
+export { RELEASE_MANIFEST };
+/** Every release the manifest lists, in manifest order. */
+export const KNOWN_RELEASES = RELEASE_MANIFEST.releases.map((r) => r.release);
+/** The latest release the manifest lists. */
+export const CURRENT_RELEASE = KNOWN_RELEASES[KNOWN_RELEASES.length - 1];
+/**
+ * The sheet-spec version a release bundles for a sheet type, or
+ * undefined when the manifest does not list the release.
+ */
+export function sheetSpecVersionFor(release, sheetType) {
+    return RELEASE_MANIFEST.releases.find((r) => r.release === release)?.sheets[sheetType];
+}
+/** The published URL of a sheet spec's JSON Schema, which is also its `$id`. */
+export function schemaUrlFor(sheetType, version) {
+    return RELEASE_MANIFEST.schema_url_template.replace("{sheet}", sheetType).replace("{version}", version);
+}
+/** The legacy draft line's schema URL for a sheet type. */
+export function legacySchemaUrl(sheetType) {
+    return RELEASE_MANIFEST.legacy.schemas[sheetType];
+}

package/dist/rules/org-e-002.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-E-002 — Sheet carries both format_version and release.
+ * The organization-sheet counterpart of PDP-E-016. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export declare const orgE002: Rule;

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

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

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

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-E-003 — Release / schema mismatch.
+ * The organization-sheet counterpart of PDP-E-002. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export declare const orgE003: Rule;

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

@@ -0,0 +1,13 @@
+import { RELEASE_SCHEMA_MISMATCH, releaseSchemaMismatch } from "./release-schema.js";
+/**
+ * ORG-E-003 — Release / schema mismatch.
+ * The organization-sheet counterpart of PDP-E-002. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export const orgE003 = {
+    id: "ORG-E-003",
+    ...RELEASE_SCHEMA_MISMATCH,
+    check: releaseSchemaMismatch("organization"),
+    introduced: "release 0.3.0",
+    specReference: "organization.md#the-envelope",
+};

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

@@ -1,13 +1,7 @@
 import type { Rule } from "@pagefront/lint-core";
 /**
- * PDP-E-002 — Format version / schema mismatch.
- * Transcribed from commerce/spec/rules.md (normative).
- *
- * `$schema` is read via the rule context, per the target line. The
- * version segment is the trailing `v<version>.json` of the `$schema`
- * URL. Two quiet cases, both documented readings: `$schema` absent
- * (optional at Layer 1 — nothing to compare), and a `$schema` with no
- * parseable version segment (it declares no version, so no mismatch
- * can be asserted; the message requires `{schema_version}`).
+ * PDP-E-002 — Release / schema mismatch (until release 0.3.0: "Format
+ * version / schema mismatch"). Transcribed from commerce/spec/rules.md
+ * (normative); the check is shared with ORG-E-003 (release-schema.ts).
  */
 export declare const pdpE002: Rule;

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

@@ -1,33 +1,13 @@
+import { RELEASE_SCHEMA_MISMATCH, releaseSchemaMismatch } from "./release-schema.js";
 /**
- * PDP-E-002 — Format version / schema mismatch.
- * Transcribed from commerce/spec/rules.md (normative).
- *
- * `$schema` is read via the rule context, per the target line. The
- * version segment is the trailing `v<version>.json` of the `$schema`
- * URL. Two quiet cases, both documented readings: `$schema` absent
- * (optional at Layer 1 — nothing to compare), and a `$schema` with no
- * parseable version segment (it declares no version, so no mismatch
- * can be asserted; the message requires `{schema_version}`).
+ * PDP-E-002 — Release / schema mismatch (until release 0.3.0: "Format
+ * version / schema mismatch"). Transcribed from commerce/spec/rules.md
+ * (normative); the check is shared with ORG-E-003 (release-schema.ts).
  */
 export const pdpE002 = {
     id: "PDP-E-002",
-    title: "Format version / schema mismatch",
-    severity: "error",
-    target: "$.format_version",
-    check: (match, ctx) => {
-        const formatVersion = String(match.value);
-        const schema = ctx.sheet.$schema;
-        if (typeof schema !== "string")
-            return null;
-        const segment = /v(\d+(?:\.\d+)*)\.json$/.exec(schema);
-        if (segment === null)
-            return null;
-        return segment[1] === formatVersion
-            ? null
-            : { values: { format_version: formatVersion, schema_version: segment[1] } };
-    },
-    messageTemplate: "`format_version` is `{format_version}` but `$schema` URL declares version `{schema_version}`.",
-    remediation: "Align both fields to the same version. Whichever version was intended, update the other field to match.",
+    ...RELEASE_SCHEMA_MISMATCH,
+    check: releaseSchemaMismatch("product"),
     introduced: "v0.6",
     specReference: "product.md#the-envelope",
 };

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-i-001.js

@@ -1,10 +1,11 @@
-import { DATA_BLOCK_PROPERTIES } from "../schema-properties.js";
+import { DATA_BLOCK_PROPERTIES } from "../generated/schema-properties.js";
 /**
  * PDP-I-001 — Property outside Pagefront's modeled set.
  * Transcribed from commerce/spec/rules.md (normative).
  *
  * The modeled set is the JSON Schema's dataBlock property inventory
- * (schema-properties.ts, drift-tested against product.json). The
+ * of the latest released Product Sheet schema (generated at build
+ * time, see scripts/bundle-schemas.mjs). The
  * target `$.data.*` selects top-level data properties by design; any
  * property outside the inventory fires, including unmodeled
  * `pagefront:`-prefixed ones.

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-registry.d.ts

@@ -0,0 +1,29 @@
+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.
+ */
+export type SchemaResolution = {
+    kind: "schema";
+    id: string;
+}
+/** `$schema` is a string that names no schema this package bundles. */
+ | {
+    kind: "unknown";
+    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.
+ */
+export declare function resolveSchema(sheet: Sheet, sheetType?: SheetType): SchemaResolution;

package/dist/schema-registry.js

@@ -0,0 +1,35 @@
+import { SCHEMA_IDS } from "./generated/schema-ids.js";
+import { CURRENT_RELEASE, legacySchemaUrl, schemaUrlFor, sheetSpecVersionFor, } from "./releases.js";
+import { detectSheetLine, detectSheetType } from "./sheet-type.js";
+/**
+ * The identifiers the legacy schemas carried before 2026-09-08
+ * (`…/pagefront/commerce/schemas/<type>/v0.9.json`); sheets declaring
+ * them validate against the legacy schema they became.
+ */
+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.
+ */
+export function resolveSchema(sheet, sheetType) {
+    const declared = sheet.$schema;
+    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 };
+    }
+    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) };
+}

package/dist/schema-validators.d.ts

@@ -1,10 +1,11 @@
 /**
- * The Layer 1 validators, compiled ahead of time from the bundled
- * schemas by scripts/compile-validators.mjs into dist/schema-validators.js
- * (the second half of `npm run build`). This declaration is the module's
- * type; the script copies it beside the generated file.
+ * The Layer 1 validators, compiled ahead of time from every bundled
+ * schema (commerce/schemas/) by scripts/compile-validators.mjs into
+ * dist/schema-validators.js (the last step of `npm run build`). This
+ * declaration is the module's type; the script copies it beside the
+ * generated file.
  */
 import type { ValidateFunction } from "ajv";
 
-export const validateProduct: ValidateFunction;
-export const validateOrganization: ValidateFunction;
+/** One validator per bundled schema, keyed by the schema's `$id`. */
+export const VALIDATORS: Readonly<Record<string, ValidateFunction>>;