@cimplify/sdk 0.100.2 → 0.100.4

package/dist/lint.js

@@ -0,0 +1,540 @@
+'use strict';
+
+require('./chunk-OWW5GUSB.js');
+var re2js = require('re2js');
+
+// src/lint/types.ts
+var LINT_RULE_SET_SCHEMA_VERSION = 1;
+var MAX_LINT_RULE_MANIFEST_BYTES = 256 * 1024;
+var MAX_RULES = 64;
+var MAX_ARRAY_ITEMS = 64;
+var MAX_TOTAL_REGEX_PATTERNS = 64;
+var MAX_TOTAL_RULE_TERMS = 512;
+var MAX_PATH_SEGMENTS = 8;
+var MAX_NAME_LENGTH = 160;
+var MAX_MESSAGE_LENGTH = 512;
+var MAX_HELP_LENGTH = 1024;
+var MAX_PATTERN_LENGTH = 512;
+var MAX_MODULE_LENGTH = 256;
+var MAX_IDENTIFIER_LENGTH = 128;
+var RULE_ID_PATTERN = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+var JAVASCRIPT_IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var JSX_COMPONENT_IDENTIFIER_PATTERN = /^[A-Z][A-Za-z0-9_$]*$/;
+var NUMERIC_OPERATORS = /* @__PURE__ */ new Set(["+", "-", "*", "/", "%", "**", "<", "<=", ">", ">="]);
+var PRIMITIVE_KINDS = /* @__PURE__ */ new Set([
+  "required-result-check",
+  "required-wrapper-call",
+  "banned-import",
+  "banned-call-argument",
+  "banned-jsx-element",
+  "banned-classname-pattern"
+]);
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function expectRecord(value, label) {
+  if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
+  return value;
+}
+function expectOnlyKeys(value, label, allowed, required) {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key)) throw new TypeError(`${label} has unknown property ${key}`);
+  }
+  for (const key of required) {
+    if (!(key in value)) throw new TypeError(`${label} is missing ${key}`);
+  }
+}
+function expectString(value, label, maxLength) {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+    throw new TypeError(`${label} must be a non-empty string of at most ${maxLength} characters`);
+  }
+  if (value.includes("\0")) throw new TypeError(`${label} cannot contain NUL`);
+  return value;
+}
+function expectBoolean(value, label) {
+  if (typeof value !== "boolean") throw new TypeError(`${label} must be boolean`);
+  return value;
+}
+function expectArray(value, label, options = {}) {
+  if (!Array.isArray(value) || value.length > MAX_ARRAY_ITEMS) {
+    throw new TypeError(`${label} must be an array of at most ${MAX_ARRAY_ITEMS} items`);
+  }
+  if (options.nonEmpty && value.length === 0) throw new TypeError(`${label} cannot be empty`);
+  return value;
+}
+function expectStringArray(value, label, maxLength = MAX_IDENTIFIER_LENGTH, options = {}) {
+  return expectArray(value, label, options).map(
+    (item, index) => expectString(item, `${label}[${index}]`, maxLength)
+  );
+}
+function expectIntegerArray(value, label) {
+  return expectArray(value, label, { nonEmpty: true }).map((item, index) => {
+    if (typeof item !== "number" || !Number.isSafeInteger(item) || item < 0 || item > 32) {
+      throw new TypeError(`${label}[${index}] must be an integer between 0 and 32`);
+    }
+    return item;
+  });
+}
+function validateSafePattern(value, label) {
+  const pattern = expectString(value, label, MAX_PATTERN_LENGTH);
+  try {
+    re2js.RE2JS.compile(pattern);
+  } catch {
+    throw new TypeError(`${label} is not a valid linear-time regular expression`);
+  }
+  return pattern;
+}
+function expectIdentifier(value, label, pattern = JAVASCRIPT_IDENTIFIER_PATTERN) {
+  const identifier = expectString(value, label, MAX_IDENTIFIER_LENGTH);
+  if (!pattern.test(identifier)) throw new TypeError(`${label} must be a safe identifier`);
+  return identifier;
+}
+function validateImportBindings(value, label) {
+  for (const [index, item] of expectArray(value, label, { nonEmpty: true }).entries()) {
+    const binding = expectRecord(item, `${label}[${index}]`);
+    expectOnlyKeys(binding, `${label}[${index}]`, ["source", "imported"], ["source", "imported"]);
+    expectString(binding.source, `${label}[${index}].source`, MAX_MODULE_LENGTH);
+    expectStringArray(binding.imported, `${label}[${index}].imported`, MAX_IDENTIFIER_LENGTH, {
+      nonEmpty: true
+    });
+  }
+}
+function validateImportSources(value, label) {
+  for (const [index, item] of expectArray(value, label, { nonEmpty: true }).entries()) {
+    const source = expectRecord(item, `${label}[${index}]`);
+    expectOnlyKeys(source, `${label}[${index}]`, ["value", "match"], ["value", "match"]);
+    expectString(source.value, `${label}[${index}].value`, MAX_MODULE_LENGTH);
+    if (source.match !== "exact" && source.match !== "prefix") {
+      throw new TypeError(`${label}[${index}].match must be exact or prefix`);
+    }
+  }
+}
+function validatePrimitive(value, label) {
+  const primitive = expectRecord(value, label);
+  if (!PRIMITIVE_KINDS.has(primitive.kind)) {
+    throw new TypeError(`${label}.kind is unsupported`);
+  }
+  switch (primitive.kind) {
+    case "required-result-check":
+      expectOnlyKeys(
+        primitive,
+        label,
+        ["kind", "factories", "guardProperty", "valueProperty"],
+        ["kind", "factories", "guardProperty", "valueProperty"]
+      );
+      validateImportBindings(primitive.factories, `${label}.factories`);
+      expectString(primitive.guardProperty, `${label}.guardProperty`, MAX_IDENTIFIER_LENGTH);
+      expectString(primitive.valueProperty, `${label}.valueProperty`, MAX_IDENTIFIER_LENGTH);
+      break;
+    case "required-wrapper-call": {
+      expectOnlyKeys(
+        primitive,
+        label,
+        ["kind", "context", "activationImports", "subjectNamePattern", "wrapper", "operators"],
+        ["kind", "context", "activationImports", "subjectNamePattern", "wrapper"]
+      );
+      if (primitive.context !== "jsx-child" && primitive.context !== "numeric-operation") {
+        throw new TypeError(`${label}.context is unsupported`);
+      }
+      validateImportSources(primitive.activationImports, `${label}.activationImports`);
+      validateSafePattern(primitive.subjectNamePattern, `${label}.subjectNamePattern`);
+      const wrapper = expectRecord(primitive.wrapper, `${label}.wrapper`);
+      if (wrapper.syntax === "jsx") {
+        expectOnlyKeys(
+          wrapper,
+          `${label}.wrapper`,
+          ["syntax", "source", "imported", "prop"],
+          ["syntax", "source", "imported", "prop"]
+        );
+        if (primitive.context !== "jsx-child") {
+          throw new TypeError(`${label} uses a JSX wrapper outside JSX context`);
+        }
+        expectString(wrapper.source, `${label}.wrapper.source`, MAX_MODULE_LENGTH);
+        expectIdentifier(
+          wrapper.imported,
+          `${label}.wrapper.imported`,
+          JSX_COMPONENT_IDENTIFIER_PATTERN
+        );
+        expectIdentifier(wrapper.prop, `${label}.wrapper.prop`);
+      } else if (wrapper.syntax === "call") {
+        expectOnlyKeys(wrapper, `${label}.wrapper`, ["syntax", "imports"], ["syntax", "imports"]);
+        if (primitive.context !== "numeric-operation") {
+          throw new TypeError(`${label} uses a call wrapper outside numeric context`);
+        }
+        validateImportBindings(wrapper.imports, `${label}.wrapper.imports`);
+      } else {
+        throw new TypeError(`${label}.wrapper.syntax is unsupported`);
+      }
+      if (primitive.operators !== void 0) {
+        const operators = expectStringArray(primitive.operators, `${label}.operators`, 4, {
+          nonEmpty: true
+        });
+        if (operators.some((operator) => !NUMERIC_OPERATORS.has(operator))) {
+          throw new TypeError(`${label}.operators contains an unsupported operator`);
+        }
+      }
+      break;
+    }
+    case "banned-import":
+      expectOnlyKeys(primitive, label, ["kind", "sources"], ["kind", "sources"]);
+      validateImportSources(primitive.sources, `${label}.sources`);
+      break;
+    case "banned-call-argument":
+      expectOnlyKeys(
+        primitive,
+        label,
+        [
+          "kind",
+          "callees",
+          "globalCalleesOnly",
+          "argumentIndexes",
+          "objectPaths",
+          "caseInsensitive"
+        ],
+        ["kind", "callees", "argumentIndexes", "objectPaths"]
+      );
+      expectStringArray(primitive.callees, `${label}.callees`, MAX_IDENTIFIER_LENGTH, {
+        nonEmpty: true
+      });
+      if (primitive.globalCalleesOnly !== void 0) {
+        expectBoolean(primitive.globalCalleesOnly, `${label}.globalCalleesOnly`);
+      }
+      expectIntegerArray(primitive.argumentIndexes, `${label}.argumentIndexes`);
+      for (const [index, item] of expectArray(primitive.objectPaths, `${label}.objectPaths`, {
+        nonEmpty: true
+      }).entries()) {
+        const segments = expectStringArray(
+          item,
+          `${label}.objectPaths[${index}]`,
+          MAX_IDENTIFIER_LENGTH,
+          { nonEmpty: true }
+        );
+        if (segments.length > MAX_PATH_SEGMENTS) {
+          throw new TypeError(
+            `${label}.objectPaths[${index}] exceeds ${MAX_PATH_SEGMENTS} segments`
+          );
+        }
+      }
+      if (primitive.caseInsensitive !== void 0) {
+        expectBoolean(primitive.caseInsensitive, `${label}.caseInsensitive`);
+      }
+      break;
+    case "banned-jsx-element":
+      expectOnlyKeys(primitive, label, ["kind", "elements"], ["kind", "elements"]);
+      expectStringArray(primitive.elements, `${label}.elements`, MAX_IDENTIFIER_LENGTH, {
+        nonEmpty: true
+      });
+      break;
+    case "banned-classname-pattern":
+      expectOnlyKeys(primitive, label, ["kind", "patterns", "replacements"], ["kind", "patterns"]);
+      for (const [index, pattern] of expectArray(primitive.patterns, `${label}.patterns`, {
+        nonEmpty: true
+      }).entries()) {
+        validateSafePattern(pattern, `${label}.patterns[${index}]`);
+      }
+      if (primitive.replacements !== void 0) {
+        for (const [index, item] of expectArray(
+          primitive.replacements,
+          `${label}.replacements`
+        ).entries()) {
+          const replacement = expectRecord(item, `${label}.replacements[${index}]`);
+          expectOnlyKeys(
+            replacement,
+            `${label}.replacements[${index}]`,
+            ["from", "to"],
+            ["from", "to"]
+          );
+          expectString(replacement.from, `${label}.replacements[${index}].from`, 256);
+          expectString(replacement.to, `${label}.replacements[${index}].to`, 256);
+        }
+      }
+      break;
+    default:
+      throw new TypeError(`${label}.kind is unsupported`);
+  }
+  return primitive;
+}
+function validateFix(value, label, primitive) {
+  const fix = expectRecord(value, label);
+  expectOnlyKeys(fix, label, ["kind"], ["kind"]);
+  if (fix.kind === "wrap-jsx-expression") {
+    if (primitive.kind !== "required-wrapper-call" || primitive.context !== "jsx-child" || primitive.wrapper.syntax !== "jsx") {
+      throw new TypeError(`${label} is incompatible with its primitive`);
+    }
+  } else if (fix.kind === "replace-classname") {
+    if (primitive.kind !== "banned-classname-pattern") {
+      throw new TypeError(`${label} is incompatible with its primitive`);
+    }
+  } else if (fix.kind === "remove-object-property") {
+    if (primitive.kind !== "banned-call-argument") {
+      throw new TypeError(`${label} is incompatible with its primitive`);
+    }
+  } else {
+    throw new TypeError(`${label}.kind is unsupported`);
+  }
+  return fix;
+}
+function validatedRule(value, label) {
+  const rule = expectRecord(value, label);
+  expectOnlyKeys(
+    rule,
+    label,
+    ["id", "severity", "message", "help", "primitive", "fix"],
+    ["id", "severity", "message", "help", "primitive"]
+  );
+  const id = expectString(rule.id, `${label}.id`, MAX_IDENTIFIER_LENGTH);
+  if (!RULE_ID_PATTERN.test(id)) throw new TypeError(`${label}.id is invalid`);
+  if (rule.severity !== "error" && rule.severity !== "warning") {
+    throw new TypeError(`${label}.severity must be error or warning`);
+  }
+  expectString(rule.message, `${label}.message`, MAX_MESSAGE_LENGTH);
+  expectString(rule.help, `${label}.help`, MAX_HELP_LENGTH);
+  const primitive = validatePrimitive(rule.primitive, `${label}.primitive`);
+  if (rule.fix !== void 0) validateFix(rule.fix, `${label}.fix`, primitive);
+  return rule;
+}
+function deepFreeze(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const nested of Object.values(value)) deepFreeze(nested, seen);
+  return Object.freeze(value);
+}
+function validateLintRule(value) {
+  return deepFreeze(validatedRule(value, "lint rule"));
+}
+function validateLintRuleSet(value) {
+  const candidate = expectRecord(value, "lint rule set");
+  expectOnlyKeys(
+    candidate,
+    "lint rule set",
+    ["schemaVersion", "name", "rules"],
+    ["schemaVersion", "name", "rules"]
+  );
+  if (candidate.schemaVersion !== LINT_RULE_SET_SCHEMA_VERSION) {
+    throw new TypeError(
+      `unsupported lint rule schema ${String(candidate.schemaVersion)}; expected ${LINT_RULE_SET_SCHEMA_VERSION}`
+    );
+  }
+  const name = expectString(candidate.name, "lint rule set.name", MAX_NAME_LENGTH);
+  if (!name.trim()) throw new TypeError("lint rule set.name cannot be blank");
+  if (!Array.isArray(candidate.rules) || candidate.rules.length > MAX_RULES) {
+    throw new TypeError(`lint rule set.rules must contain at most ${MAX_RULES} rules`);
+  }
+  const ids = /* @__PURE__ */ new Set();
+  let regexPatterns = 0;
+  let ruleTerms = 0;
+  for (const [index, value2] of candidate.rules.entries()) {
+    const rule = validatedRule(value2, `rules[${index}]`);
+    if (ids.has(rule.id)) throw new TypeError(`lint rule set contains duplicate id ${rule.id}`);
+    ids.add(rule.id);
+    const primitive = rule.primitive;
+    switch (primitive.kind) {
+      case "required-result-check":
+        ruleTerms += primitive.factories.length;
+        ruleTerms += primitive.factories.reduce((sum, factory) => sum + factory.imported.length, 0);
+        break;
+      case "required-wrapper-call":
+        regexPatterns += 1;
+        ruleTerms += primitive.activationImports.length;
+        if (primitive.wrapper.syntax === "call") {
+          ruleTerms += primitive.wrapper.imports.length;
+          ruleTerms += primitive.wrapper.imports.reduce(
+            (sum, pattern) => sum + pattern.imported.length,
+            0
+          );
+        }
+        ruleTerms += primitive.operators?.length ?? 0;
+        break;
+      case "banned-import":
+        ruleTerms += primitive.sources.length;
+        break;
+      case "banned-call-argument":
+        ruleTerms += primitive.callees.length + primitive.argumentIndexes.length;
+        ruleTerms += primitive.objectPaths.reduce((sum, objectPath) => sum + objectPath.length, 0);
+        break;
+      case "banned-jsx-element":
+        ruleTerms += primitive.elements.length;
+        break;
+      case "banned-classname-pattern":
+        regexPatterns += primitive.patterns.length;
+        ruleTerms += (primitive.replacements?.length ?? 0) * 2;
+        break;
+    }
+  }
+  if (regexPatterns > MAX_TOTAL_REGEX_PATTERNS) {
+    throw new TypeError(
+      `lint rule set exceeds ${MAX_TOTAL_REGEX_PATTERNS} total regular expressions`
+    );
+  }
+  if (ruleTerms > MAX_TOTAL_RULE_TERMS) {
+    throw new TypeError(`lint rule set exceeds ${MAX_TOTAL_RULE_TERMS} total match terms`);
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(candidate);
+  } catch {
+    throw new TypeError("lint rule set must be JSON-serializable data");
+  }
+  if (new TextEncoder().encode(serialized).byteLength > MAX_LINT_RULE_MANIFEST_BYTES) {
+    throw new TypeError(`lint rule set exceeds ${MAX_LINT_RULE_MANIFEST_BYTES} UTF-8 bytes`);
+  }
+  return deepFreeze(candidate);
+}
+
+// src/lint/define.ts
+function defineLintRule(rule) {
+  return validateLintRule(rule);
+}
+function defineLintRuleSet(options) {
+  return validateLintRuleSet({
+    schemaVersion: LINT_RULE_SET_SCHEMA_VERSION,
+    name: options.name,
+    rules: [...options.rules]
+  });
+}
+
+// src/lint/rules.ts
+var MONEY_NAME_PATTERN = "(?:^|_)(?:price|amount|subtotal|total|tax|fee|discount|cost)(?:$|_)";
+var SDK_CLIENT_FACTORIES = [
+  { source: "@cimplify/sdk", imported: ["createCimplifyClient"] },
+  { source: "@cimplify/sdk/server", imported: ["getServerClient"] }
+];
+var SDK_MODULES = [{ value: "@cimplify/sdk", match: "prefix" }];
+var PARSE_PRICE_IMPORTS = [
+  { source: "@cimplify/sdk", imported: ["parsePrice"] },
+  { source: "@cimplify/sdk/utils", imported: ["parsePrice"] }
+];
+var TAILWIND_COLOR_SCALE = "(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|100|200|300|400|500|600|700|800|900|950)";
+var COLOR_UTILITY = "(?:accent|bg|border|caret|decoration|divide|fill|from|outline|placeholder|ring|shadow|stroke|text|to|via)";
+var checkResultOkRule = defineLintRule({
+  id: "sdk/check-result-ok",
+  severity: "error",
+  message: "Check `result.ok` before reading `result.value`.",
+  help: "Cimplify SDK calls return Result values. Handle the error branch before using the value.",
+  primitive: {
+    kind: "required-result-check",
+    factories: SDK_CLIENT_FACTORIES,
+    guardProperty: "ok",
+    valueProperty: "value"
+  }
+});
+var renderPriceComponentRule = defineLintRule({
+  id: "sdk/render-price-component",
+  severity: "error",
+  message: "Render money with the SDK `Price` component.",
+  help: "`Price` applies the active business currency and locale consistently.",
+  primitive: {
+    kind: "required-wrapper-call",
+    context: "jsx-child",
+    activationImports: SDK_MODULES,
+    subjectNamePattern: MONEY_NAME_PATTERN,
+    wrapper: {
+      syntax: "jsx",
+      source: "@cimplify/sdk/react",
+      imported: "Price",
+      prop: "amount"
+    }
+  },
+  fix: { kind: "wrap-jsx-expression" }
+});
+var parsePriceBeforeMathRule = defineLintRule({
+  id: "sdk/parse-price-before-math",
+  severity: "error",
+  message: "Call `parsePrice` before using a money value in numeric operations.",
+  help: "Money arrives over the wire as a decimal string; implicit coercion can produce incorrect comparisons and totals.",
+  primitive: {
+    kind: "required-wrapper-call",
+    context: "numeric-operation",
+    activationImports: SDK_MODULES,
+    subjectNamePattern: MONEY_NAME_PATTERN,
+    wrapper: { syntax: "call", imports: PARSE_PRICE_IMPORTS },
+    operators: ["+", "-", "*", "/", "%", "**", "<", "<=", ">", ">="]
+  }
+});
+var noReactQueryRule = defineLintRule({
+  id: "sdk/no-react-query",
+  severity: "error",
+  message: "Use Cimplify SDK hooks instead of React Query.",
+  help: "Use the SDK hooks and their provider-owned cache so cart, catalogue, and account state stay coherent.",
+  primitive: {
+    kind: "banned-import",
+    sources: [
+      { value: "react-query", match: "exact" },
+      { value: "@tanstack/react-query", match: "prefix" }
+    ]
+  }
+});
+var noCookieInCacheKeyRule = defineLintRule({
+  id: "sdk/no-cookie-in-cache-key",
+  severity: "error",
+  message: "Remove the Cookie header from this cacheable request.",
+  help: "Cookie-bearing requests bypass the shared cache by design. Keep personalized cart/account reads in a client island.",
+  primitive: {
+    kind: "banned-call-argument",
+    callees: ["fetch", "Request"],
+    globalCalleesOnly: true,
+    argumentIndexes: [1],
+    objectPaths: [["headers", "cookie"]],
+    caseInsensitive: true
+  },
+  fix: { kind: "remove-object-property" }
+});
+var noRawImgRule = defineLintRule({
+  id: "ui/no-raw-img",
+  severity: "warning",
+  message: "Use `next/image` instead of a raw `<img>` element.",
+  help: "The storefront image loader supplies responsive sizes, modern formats, and intrinsic dimensions.",
+  primitive: { kind: "banned-jsx-element", elements: ["img"] }
+});
+var themeTokensOnlyRule = defineLintRule({
+  id: "ui/theme-tokens-only",
+  severity: "warning",
+  message: "Use storefront theme tokens instead of hard-coded color utilities.",
+  help: "Define palette changes in `app/globals.css` and consume semantic utilities such as `bg-background` and `text-foreground`.",
+  primitive: {
+    kind: "banned-classname-pattern",
+    patterns: [
+      `^${COLOR_UTILITY}-${TAILWIND_COLOR_SCALE}$`,
+      `^${COLOR_UTILITY}-(?:black|white)$`,
+      `^${COLOR_UTILITY}-\\[(?:#|rgba?\\(|hsla?\\(|oklch\\(|oklab\\(|lab\\(|lch\\(|color:)`
+    ],
+    replacements: [
+      { from: "bg-white", to: "bg-background" },
+      { from: "bg-black", to: "bg-foreground" },
+      { from: "text-black", to: "text-foreground" },
+      { from: "border-black", to: "border-foreground" },
+      { from: "border-white", to: "border-background" }
+    ]
+  },
+  fix: { kind: "replace-classname" }
+});
+var starterLintRuleSet = defineLintRuleSet({
+  name: "@cimplify/sdk/starter",
+  rules: [
+    checkResultOkRule,
+    renderPriceComponentRule,
+    parsePriceBeforeMathRule,
+    noReactQueryRule,
+    noCookieInCacheKeyRule,
+    noRawImgRule,
+    themeTokensOnlyRule
+  ]
+});
+var starterLintRules = starterLintRuleSet.rules;
+
+exports.LINT_RULE_SET_SCHEMA_VERSION = LINT_RULE_SET_SCHEMA_VERSION;
+exports.MAX_LINT_RULE_MANIFEST_BYTES = MAX_LINT_RULE_MANIFEST_BYTES;
+exports.checkResultOkRule = checkResultOkRule;
+exports.defineLintRule = defineLintRule;
+exports.defineLintRuleSet = defineLintRuleSet;
+exports.noCookieInCacheKeyRule = noCookieInCacheKeyRule;
+exports.noRawImgRule = noRawImgRule;
+exports.noReactQueryRule = noReactQueryRule;
+exports.parsePriceBeforeMathRule = parsePriceBeforeMathRule;
+exports.renderPriceComponentRule = renderPriceComponentRule;
+exports.starterLintRuleSet = starterLintRuleSet;
+exports.starterLintRules = starterLintRules;
+exports.themeTokensOnlyRule = themeTokensOnlyRule;
+exports.validateLintRule = validateLintRule;
+exports.validateLintRuleSet = validateLintRuleSet;