@pagefront/lint-commerce 0.1.0

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

@@ -0,0 +1,47 @@
+/**
+ * PDP-W-027 — Empty accepted answer.
+ * Transcribed from commerce/spec/rules.md (normative).
+ *
+ * The target selects `acceptedAnswer` objects, so presence is given by
+ * the match; the check tests `text` (absent, empty, or whitespace-only
+ * — the schema requires non-empty `text`, so only the whitespace arm
+ * is reachable on Layer-1-valid input; the others are defensive).
+ * `{name}` is the parent question's `name` (schema-required), read
+ * from the sheet via the match's path index; `(unnamed)` defensively
+ * on invalid input.
+ */
+export const pdpW027 = {
+    id: "PDP-W-027",
+    title: "Empty accepted answer",
+    severity: "warning",
+    target: "$.data.question[*].acceptedAnswer",
+    check: (match, ctx) => {
+        const answer = match.value;
+        if (typeof answer !== "object" || answer === null)
+            return null;
+        const text = answer["text"];
+        const empty = text === undefined ||
+            text === null ||
+            (typeof text === "string" && text.trim() === "");
+        if (!empty)
+            return null;
+        let name = "(unnamed)";
+        const index = /\['question'\]\[(\d+)\]/.exec(match.path)?.[1];
+        const data = typeof ctx.sheet.data === "object" && ctx.sheet.data !== null
+            ? ctx.sheet.data
+            : {};
+        if (index !== undefined && Array.isArray(data["question"])) {
+            const question = data["question"][Number(index)];
+            if (typeof question === "object" &&
+                question !== null &&
+                typeof question["name"] === "string") {
+                name = question["name"];
+            }
+        }
+        return { values: { name } };
+    },
+    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",
+    specReference: "product.md#product-qa",
+};

package/dist/schema-properties.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The data-block property inventory for PDP-I-001, derived from the
+ * Pagefront JSON Schema (commerce/spec/product.json, format 0.9) —
+ * the normative property inventory per the catalogue's Definitions
+ * section. Generated from `$defs.dataBlock.properties`; the
+ * inventory drift test (test/inventory.test.mjs) fails when the
+ * schema and this list diverge. Regenerate on schema change, in the
+ * same catalogue-versioned change.
+ */
+export declare const DATA_BLOCK_PROPERTIES: readonly string[];

package/dist/schema-properties.js

@@ -0,0 +1,67 @@
+/**
+ * The data-block property inventory for PDP-I-001, derived from the
+ * Pagefront JSON Schema (commerce/spec/product.json, format 0.9) —
+ * the normative property inventory per the catalogue's Definitions
+ * section. Generated from `$defs.dataBlock.properties`; the
+ * inventory drift test (test/inventory.test.mjs) fails when the
+ * schema and this list diverge. Regenerate on schema change, in the
+ * same catalogue-versioned change.
+ */
+export const DATA_BLOCK_PROPERTIES = [
+    "@context",
+    "@id",
+    "@type",
+    "additionalProperty",
+    "aggregateRating",
+    "brand",
+    "category",
+    "color",
+    "countryOfOrigin",
+    "depth",
+    "description",
+    "gtin",
+    "gtin13",
+    "hasCertification",
+    "hasPart",
+    "hasVariant",
+    "height",
+    "image",
+    "inLanguage",
+    "isPartOf",
+    "isRelatedTo",
+    "isSimilarTo",
+    "isVariantOf",
+    "manufacturer",
+    "material",
+    "mpn",
+    "name",
+    "offers",
+    "pagefront:availableLanguages",
+    "pagefront:careInstructions",
+    "pagefront:configurator",
+    "pagefront:construction",
+    "pagefront:document",
+    "pagefront:fabricComposition",
+    "pagefront:featureGroup",
+    "pagefront:gemstone",
+    "pagefront:legalEntity",
+    "pagefront:madeToOrderTerms",
+    "pagefront:manufacturingChain",
+    "pagefront:materialComposition",
+    "pagefront:productHighlights",
+    "pagefront:relatedProduct",
+    "pagefront:safetyNotice",
+    "pagefront:safetyWarning",
+    "pagefront:sizeChart",
+    "pagefront:sizeRecommendation",
+    "productGroupID",
+    "productID",
+    "question",
+    "review",
+    "sku",
+    "url",
+    "variesBy",
+    "video",
+    "weight",
+    "width",
+];

package/dist/sheet-type.d.ts

@@ -0,0 +1,16 @@
+import type { Sheet } from "@pagefront/lint-core";
+/**
+ * Sheet-type detection for page-type dispatch: organization sheets are
+ * a different page type from product sheets, and each page type's
+ * rules must never run on the other's sheets.
+ *
+ * The envelope `$schema` is authoritative when it names a page type
+ * (`/schemas/organization/` or `/schemas/product/` in its path). The
+ * data-block fallback — `@type` of `Organization` / `OnlineStore` /
+ * `OnlineBusiness` with `pagefront:commerceRole` present — applies
+ * only when `$schema` is absent or names neither, so a declared schema
+ * always wins over shape heuristics. The default is `product`, the
+ * page type the catalogue predates dispatch with.
+ */
+export type SheetType = "product" | "organization";
+export declare function detectSheetType(sheet: Sheet): SheetType;

package/dist/sheet-type.js

@@ -0,0 +1,20 @@
+const ORG_DATA_TYPES = new Set(["Organization", "OnlineStore", "OnlineBusiness"]);
+export function detectSheetType(sheet) {
+    const schema = sheet.$schema;
+    if (typeof schema === "string") {
+        if (schema.includes("/schemas/organization/"))
+            return "organization";
+        if (schema.includes("/schemas/product/"))
+            return "product";
+    }
+    const data = sheet.data;
+    if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+        const d = data;
+        if (typeof d["@type"] === "string" &&
+            ORG_DATA_TYPES.has(d["@type"]) &&
+            d["pagefront:commerceRole"] !== undefined) {
+            return "organization";
+        }
+    }
+    return "product";
+}

package/dist/validate-and-lint.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The Layer 1 → Layer 2 sequencing as a library function — the same
+ * pipeline the CLI runs, importable by CI scripts and production
+ * validation layers. Ajv is an implementation detail behind this
+ * boundary: callers see `SchemaError`, never Ajv's own error type.
+ */
+import type { LintOptions, Report } from "@pagefront/lint-core";
+/**
+ * One Layer 1 (JSON Schema) validation failure, in a shape this
+ * package owns. `instancePath` is a JSON Pointer to the offending
+ * location (`""` for the document root); `keyword` is the schema
+ * keyword that failed (e.g. `"required"`, `"format"`).
+ */
+export interface SchemaError {
+    instancePath: string;
+    message: string;
+    keyword: string;
+}
+export type ValidateAndLintResult = {
+    layer: 1;
+    schemaErrors: SchemaError[];
+} | {
+    layer: 2;
+    report: Report;
+};
+/**
+ * Validate a parsed-but-unvalidated document against the bundled
+ * product JSON Schema (Layer 1), and — only if it passes — lint it
+ * against the commerce rule catalogue (Layer 2). The engine assumes a
+ * schema-valid Sheet, so a failing document never reaches the
+ * catalogue; Layer 1 success is also what makes the internal cast to
+ * `Sheet` sound (the schema requires the envelope fields).
+ *
+ * The bundled schemas are the current catalogue's format version. A
+ * document declaring some other `format_version` failing Layer 1 is
+ * the intended behavior, not a gap: this package lints exactly one
+ * format version, and there is no separate "unsupported version"
+ * outcome.
+ *
+ * Dispatches by page type (see sheet-type.ts): product sheets validate
+ * against the product schema and lint with the product catalogue;
+ * Commerce Organization Sheets validate against the organization
+ * schema and lint with the organization catalogue. Detection reads the
+ * envelope `$schema` first, falling back to data-block shape, so a
+ * document of either type routes to its own schema's errors.
+ */
+export declare function validateAndLint(input: unknown, options?: LintOptions): ValidateAndLintResult;

package/dist/validate-and-lint.js

@@ -0,0 +1,53 @@
+import { lintSheet } from "./lint-sheet.js";
+import { PRODUCT_SCHEMA } from "./product-schema.js";
+import { ORGANIZATION_SCHEMA } from "./organization-schema.js";
+import { detectSheetType } from "./sheet-type.js";
+// ajv ships CJS with `module.exports === exports.default`; under
+// NodeNext the default import binding is the CJS namespace, so the
+// class/function is reached via `.default` (identical at runtime).
+import Ajv2020Module from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+const Ajv2020 = Ajv2020Module.default;
+const addFormats = addFormatsModule.default;
+// Compiled once at module scope: pipeline consumers call
+// validateAndLint in a loop, and schema compilation is the expensive
+// step. `allowUnionTypes` because the product schema legitimately
+// uses union `type` keywords.
+const ajv = new Ajv2020({ allErrors: true, allowUnionTypes: true });
+addFormats(ajv);
+const validateProduct = ajv.compile(PRODUCT_SCHEMA);
+const validateOrganization = ajv.compile(ORGANIZATION_SCHEMA);
+/**
+ * Validate a parsed-but-unvalidated document against the bundled
+ * product JSON Schema (Layer 1), and — only if it passes — lint it
+ * against the commerce rule catalogue (Layer 2). The engine assumes a
+ * schema-valid Sheet, so a failing document never reaches the
+ * catalogue; Layer 1 success is also what makes the internal cast to
+ * `Sheet` sound (the schema requires the envelope fields).
+ *
+ * The bundled schemas are the current catalogue's format version. A
+ * document declaring some other `format_version` failing Layer 1 is
+ * the intended behavior, not a gap: this package lints exactly one
+ * format version, and there is no separate "unsupported version"
+ * outcome.
+ *
+ * Dispatches by page type (see sheet-type.ts): product sheets validate
+ * against the product schema and lint with the product catalogue;
+ * Commerce Organization Sheets validate against the organization
+ * schema and lint with the organization catalogue. Detection reads the
+ * envelope `$schema` first, falling back to data-block shape, so a
+ * document of either type routes to its own schema's errors.
+ */
+export function validateAndLint(input, options) {
+    const sheetType = detectSheetType((typeof input === "object" && input !== null ? input : {}));
+    const validate = sheetType === "organization" ? validateOrganization : validateProduct;
+    if (!validate(input)) {
+        const schemaErrors = (validate.errors ?? []).map((error) => ({
+            instancePath: error.instancePath,
+            message: error.message ?? "invalid",
+            keyword: error.keyword,
+        }));
+        return { layer: 1, schemaErrors };
+    }
+    return { layer: 2, report: lintSheet(input, options) };
+}

package/dist/validate-organization.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Layer 1 validation for the Commerce Organization Sheet — the
+ * organization analogue of validateAndLint's first stage. There is
+ * deliberately no Layer 2 here: the commerce rule catalogue is
+ * product-scoped, and an organization catalogue does not exist yet
+ * (dispatching per-page-type schemas and catalogues is tracked as
+ * "Rule namespaces" in core/spec/linter.md), so a schema-valid
+ * document simply passes.
+ *
+ * As with the product pipeline, Ajv is an implementation detail:
+ * callers see `SchemaError`, never Ajv's own error type.
+ */
+import type { SchemaError } from "./validate-and-lint.js";
+export type ValidateOrganizationResult = {
+    valid: true;
+} | {
+    valid: false;
+    schemaErrors: SchemaError[];
+};
+/**
+ * Validate a parsed-but-unvalidated document against the bundled
+ * Commerce Organization Sheet JSON Schema. The bundled schema is the
+ * current format version; a document declaring some other
+ * `format_version` failing Layer 1 is the intended behavior, exactly
+ * as in the product pipeline.
+ */
+export declare function validateOrganizationSheet(input: unknown): ValidateOrganizationResult;

package/dist/validate-organization.js

@@ -0,0 +1,30 @@
+import { ORGANIZATION_SCHEMA } from "./organization-schema.js";
+// ajv ships CJS with `module.exports === exports.default`; under
+// NodeNext the default import binding is the CJS namespace, so the
+// class/function is reached via `.default` (identical at runtime).
+import Ajv2020Module from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+const Ajv2020 = Ajv2020Module.default;
+const addFormats = addFormatsModule.default;
+// Compiled once at module scope, mirroring validate-and-lint.
+const ajv = new Ajv2020({ allErrors: true, allowUnionTypes: true });
+addFormats(ajv);
+const validate = ajv.compile(ORGANIZATION_SCHEMA);
+/**
+ * Validate a parsed-but-unvalidated document against the bundled
+ * Commerce Organization Sheet JSON Schema. The bundled schema is the
+ * current format version; a document declaring some other
+ * `format_version` failing Layer 1 is the intended behavior, exactly
+ * as in the product pipeline.
+ */
+export function validateOrganizationSheet(input) {
+    if (!validate(input)) {
+        const schemaErrors = (validate.errors ?? []).map((error) => ({
+            instancePath: error.instancePath,
+            message: error.message ?? "invalid",
+            keyword: error.keyword,
+        }));
+        return { valid: false, schemaErrors };
+    }
+    return { valid: true };
+}

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This package's version, as a generated constant so the library
+ * entry stays free of Node built-ins (browser consumers bundle it).
+ * Must match package.json's `version` — the drift test
+ * (test/linter-version.test.mjs) fails when they diverge. Regenerate
+ * on version bump.
+ */
+export declare const PACKAGE_VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,8 @@
+/**
+ * This package's version, as a generated constant so the library
+ * entry stays free of Node built-ins (browser consumers bundle it).
+ * Must match package.json's `version` — the drift test
+ * (test/linter-version.test.mjs) fails when they diverge. Regenerate
+ * on version bump.
+ */
+export const PACKAGE_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pagefront/lint-commerce",
+  "version": "0.1.0",
+  "description": "Pagefront commerce linter: the commerce rule catalogue and CLI, on the @pagefront/lint-core engine.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/themachineweb/pagefront.git",
+    "directory": "commerce/lint"
+  },
+  "homepage": "https://github.com/themachineweb/pagefront/tree/main/commerce/lint#readme",
+  "bugs": "https://github.com/themachineweb/pagefront/issues",
+  "keywords": [
+    "pagefront",
+    "linter",
+    "commerce",
+    "product",
+    "schema.org",
+    "json-ld",
+    "structured-data"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "pagefront-lint-commerce": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@pagefront/lint-core": "^0.1.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^5.0.0"
+  }
+}