@craft-ts/dev-tools 0.7.0-beta.13 → 0.7.0-beta.16

package/src/eslint-rules/no-raw-class.cjs

@@ -0,0 +1,76 @@
+const STYLE_MODULE = '@craft-ts/style';
+
+/**
+ * A `class:` binding is a sheet class, never a string.
+ *
+ * Without this, the visual matrix is a fiction: a class assembled at render
+ * time is a visual state nothing recorded, so the matrix enumerates what the
+ * sheets declare while the DOM shows something else. Partial tightness here
+ * buys 0 % of the guarantee, not 90 %.
+ *
+ * It fires **only in files that import `@craft-ts/style`**. A component that
+ * has not been migrated is not claiming the guarantee, and reporting it would
+ * teach people to disable the rule long before the app is ready for it. The day
+ * a file starts using the design system, it starts being held to it.
+ */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow string and computed class bindings in files that use @craft-ts/style.',
+    },
+    schema: [],
+    messages: {
+      rawClass:
+        'A class binding must be a class from a craftStyles sheet, not a string. This one is invisible to the visual matrix, so the state it produces is one nothing will ever capture. Move the rule into the sheet and bind the class it returns.',
+      computedClass:
+        'A class binding must not be computed at render time. Every string this can produce is a visual state nobody can enumerate; make the variation an axis — when(tone.danger, [...]) — and set a data attribute instead.',
+    },
+  },
+  create(context) {
+    let usesStyle = false;
+    const reports = [];
+
+    const report = (node, messageId) => reports.push({ node, messageId });
+
+    const inspect = (value) => {
+      if (!value) return;
+      if (value.type === 'Literal' && typeof value.value === 'string') {
+        report(value, 'rawClass');
+        return;
+      }
+      if (value.type === 'TemplateLiteral') {
+        report(value, value.expressions.length ? 'computedClass' : 'rawClass');
+        return;
+      }
+      if (
+        value.type === 'FunctionExpression' ||
+        value.type === 'ArrowFunctionExpression'
+      ) {
+        report(value, 'computedClass');
+      }
+    };
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value === STYLE_MODULE) usesStyle = true;
+      },
+      Property(node) {
+        const key = node.key;
+        const name =
+          key.type === 'Identifier'
+            ? key.name
+            : key.type === 'Literal'
+              ? key.value
+              : undefined;
+        if (name !== 'class') return;
+        inspect(node.value);
+      },
+      'Program:exit'() {
+        if (!usesStyle) return;
+        for (const entry of reports) context.report(entry);
+      },
+    };
+  },
+};

package/src/eslint-rules/no-raw-css-value.cjs

@@ -0,0 +1,163 @@
+const STYLE_MODULE = '@craft-ts/style';
+
+/**
+ * A style helper never takes a literal.
+ *
+ * The types already say so — no generated signature accepts a `string` — so
+ * this rule is not a second guard against the same mistake. It exists for the
+ * two places typing cannot reach: a value flowing in through `any`, and code
+ * that has not been typechecked yet while it is being written. The message
+ * points at the exact replacement, because a rule that only says "no" sends an
+ * agent looking for a way round.
+ *
+ * It extends `no-hardcoded-design-values` to style-helper arguments rather than
+ * duplicating it: same intent, one more position.
+ */
+const REPLACEMENTS = {
+  length: 'a scale step or a unit — space(4), unit.rem(1.5), radii.md',
+  color: 'a palette token — palette.surface.raised',
+  keyword: 'the keyword member — display.flex, position.sticky',
+};
+
+const GLOBAL_KEYWORDS = new Set([
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+]);
+
+const LENGTH_LIKE = /^-?\d*\.?\d+(px|rem|em|%|vh|vw|ch|ex|pt|cm|mm|in)$/;
+const COLOR_LIKE = /^(#[0-9a-fA-F]{3,8}|rgb|rgba|hsl|hsla|var\()/;
+
+/**
+ * Helpers whose argument is legitimately a primitive.
+ *
+ * `space(4)` is how a scale step is written, `cssVars('badge', …)` takes a
+ * name, `unsafeLength('13px', reason)` is the marked way out. Flagging these
+ * would teach people to disable the rule, which costs more than the rule buys.
+ */
+const TAKES_PRIMITIVES = new Set([
+  'space',
+  'num',
+  'int',
+  'ident',
+  'cssString',
+  'url',
+  'unsafeLength',
+  'unsafeAssume',
+  'oneOf',
+  'craftStyles',
+  'cssVars',
+  'definePalette',
+  'defineStateAxis',
+  'defineBreakpoints',
+  'defineAxis',
+]);
+
+/** Namespaces whose members are value constructors: `unit.px(4)`, `at.…`. */
+const PRIMITIVE_NAMESPACES = new Set(['unit', 'kind', 'at']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow string and number literals as arguments to @craft-ts/style helpers.',
+    },
+    schema: [],
+    messages: {
+      rawValue:
+        "'{{value}}' is a raw CSS value, not a design-system value. Pass {{replacement}} instead. If the scale is missing the value, add it to the scale; if it genuinely cannot be proven, use unsafeLength('{{value}}', reason) so the debt is countable.",
+      rawGlobal:
+        "'{{value}}' is a CSS-wide keyword; pass it as a token — global.{{token}}(prop.<name>) — so no helper has to accept a string.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const styleImports = new Set();
+    const namespaces = new Set();
+
+    const replacementFor = (value) => {
+      if (typeof value === 'number') return REPLACEMENTS.length;
+      if (COLOR_LIKE.test(value)) return REPLACEMENTS.color;
+      if (LENGTH_LIKE.test(value)) return REPLACEMENTS.length;
+      return REPLACEMENTS.keyword;
+    };
+
+    const isStyleHelper = (callee) => {
+      if (callee.type === 'Identifier') {
+        return (
+          styleImports.has(callee.name) && !TAKES_PRIMITIVES.has(callee.name)
+        );
+      }
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.object.type === 'Identifier'
+      ) {
+        const object = callee.object.name;
+        if (PRIMITIVE_NAMESPACES.has(object)) return false;
+        if (namespaces.has(object)) {
+          // `style.space(4)` through a namespace import is still a value
+          // constructor; the member name is what decides.
+          return (
+            callee.property.type === 'Identifier' &&
+            !TAKES_PRIMITIVES.has(callee.property.name) &&
+            !PRIMITIVE_NAMESPACES.has(callee.property.name)
+          );
+        }
+        return styleImports.has(object);
+      }
+      return false;
+    };
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== STYLE_MODULE) return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === 'ImportNamespaceSpecifier') {
+            namespaces.add(specifier.local.name);
+          } else if (specifier.type === 'ImportSpecifier') {
+            styleImports.add(specifier.local.name);
+          }
+        }
+      },
+      CallExpression(node) {
+        if (!isStyleHelper(node.callee)) return;
+        for (const argument of node.arguments) {
+          const isLiteral =
+            argument.type === 'Literal' &&
+            (typeof argument.value === 'string' ||
+              typeof argument.value === 'number');
+          const isTemplate =
+            argument.type === 'TemplateLiteral' && argument.quasis.length > 0;
+          if (!isLiteral && !isTemplate) continue;
+
+          const value = isLiteral
+            ? argument.value
+            : sourceCode.getText(argument).slice(1, -1);
+
+          if (typeof value === 'string' && GLOBAL_KEYWORDS.has(value)) {
+            context.report({
+              node: argument,
+              messageId: 'rawGlobal',
+              data: {
+                value,
+                token: value.replace(/-([a-z])/g, (_, char) =>
+                  char.toUpperCase(),
+                ),
+              },
+            });
+            continue;
+          }
+
+          context.report({
+            node: argument,
+            messageId: 'rawValue',
+            data: { value: String(value), replacement: replacementFor(value) },
+          });
+        }
+      },
+    };
+  },
+};

package/src/eslint-rules/no-raw-user-url.cjs

@@ -0,0 +1,114 @@
+const { report } = require('./security-rule-utils.cjs');
+
+/**
+ * Attributs d'URL dont le nom n'a pas d'autre sens courant en JavaScript.
+ * `data`, `ping`, `cite` ou `manifest` sont exclus à dessein : ce sont des
+ * noms de champs métier fréquents, et la règle ne verrait que le nom.
+ */
+const URL_KEYS = /^(?:href|src|srcset|action|formaction|poster|xlink:href)$/i;
+/** Helpers de la lib : leur retour est déjà validé. */
+const SAFE_CALLS = new Set(['safeUrl', 'safeResourceUrl', 'safeUrlList']);
+
+function isSafeExpression(node) {
+  if (!node) return true;
+  switch (node.type) {
+    case 'Literal':
+    case 'TemplateLiteral':
+      // Une URL écrite dans le source n'est pas une donnée utilisateur.
+      return true;
+    case 'CallExpression':
+      return (
+        (node.callee.type === 'Identifier' && SAFE_CALLS.has(node.callee.name)) ||
+        (node.callee.type === 'MemberExpression' &&
+          node.callee.property.type === 'Identifier' &&
+          SAFE_CALLS.has(node.callee.property.name))
+      );
+    case 'ConditionalExpression':
+      return (
+        isSafeExpression(node.consequent) && isSafeExpression(node.alternate)
+      );
+    case 'LogicalExpression':
+      return isSafeExpression(node.left) && isSafeExpression(node.right);
+    case 'TSAsExpression':
+    case 'TSNonNullExpression':
+      return isSafeExpression(node.expression);
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression':
+      // Une valeur de template Craft est un générateur ; une fonction
+      // ordinaire est un accesseur (`href: () => location.href`), pas une
+      // valeur posée dans le DOM.
+      return node.generator ? returnsSafely(node) : true;
+    default:
+      return false;
+  }
+}
+
+function isTemplateAttributeObject(property, sourceCode) {
+  const ancestors = sourceCode.getAncestors
+    ? sourceCode.getAncestors(property)
+    : [];
+  const object = ancestors[ancestors.length - 1];
+  const parent = ancestors[ancestors.length - 2];
+  return Boolean(
+    object &&
+      object.type === 'ObjectExpression' &&
+      parent &&
+      parent.type === 'CallExpression' &&
+      parent.arguments.includes(object),
+  );
+}
+
+/** Vrai quand chaque valeur retournée par le générateur est déjà validée. */
+function returnsSafely(node) {
+  if (node.body.type !== 'BlockStatement') return isSafeExpression(node.body);
+  const returns = [];
+  const visit = (statement) => {
+    if (!statement || typeof statement.type !== 'string') return;
+    if (statement.type === 'ReturnStatement') {
+      returns.push(statement.argument);
+      return;
+    }
+    // Les fonctions imbriquées ont leur propre valeur de retour.
+    if (
+      statement.type === 'FunctionDeclaration' ||
+      statement.type === 'FunctionExpression' ||
+      statement.type === 'ArrowFunctionExpression'
+    ) {
+      return;
+    }
+    for (const key of Object.keys(statement)) {
+      const value = statement[key];
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value.type === 'string') visit(value);
+    }
+  };
+  node.body.body.forEach(visit);
+  return returns.length > 0 && returns.every(isSafeExpression);
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    schema: [],
+    docs: { description: 'Sanitize user-controlled DOM URLs.' },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return {
+      Property(node) {
+        const name = node.key && (node.key.name ?? node.key.value);
+        if (!URL_KEYS.test(String(name))) return;
+        // Les attributs d'un template Craft sont un objet passé en argument
+        // d'un helper d'élément — `a('book', { href }, …)`. Un objet affecté
+        // à une variable est une structure de données, pas du DOM.
+        if (!isTemplateAttributeObject(node, sourceCode)) return;
+        if (isSafeExpression(node.value)) return;
+        report(
+          context,
+          node,
+          `Wrap the dynamic "${name}" value in safeUrl(), safeResourceUrl() or safeUrlList().`,
+        );
+      },
+    };
+  },
+};

package/src/eslint-rules/no-trust-forwarded-headers.cjs

@@ -0,0 +1,43 @@
+const { report } = require('./security-rule-utils.cjs');
+
+const FORWARDED = /^x-forwarded-(?:for|host|proto)$/i;
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          // Frontière proxy de confiance : le fichier qui valide ces en-têtes
+          // doit pouvoir les lire, sinon la règle n'est pas tenable.
+          allowIn: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    docs: {
+      description:
+        'Do not trust forwarded headers outside the configured proxy boundary.',
+    },
+  },
+  create(context) {
+    const allowIn = (context.options[0] && context.options[0].allowIn) || [
+      'proxy-boundary',
+      'trusted-proxy',
+    ];
+    const filename = context.filename ?? context.getFilename();
+    if (allowIn.some((fragment) => filename.includes(fragment))) return {};
+    return {
+      Literal(node) {
+        if (typeof node.value === 'string' && FORWARDED.test(node.value)) {
+          report(
+            context,
+            node,
+            'Forwarded headers are untrusted input; read them only in the proxy boundary module that validates them.',
+          );
+        }
+      },
+    };
+  },
+};

package/src/eslint-rules/no-unsafe-html.cjs

@@ -0,0 +1,93 @@
+const { report } = require('./security-rule-utils.cjs');
+
+const RAW_SINKS = /^(?:innerHTML|outerHTML|srcdoc)$/;
+const DANGEROUS_CALLS = new Set([
+  'insertAdjacentHTML',
+  'createContextualFragment',
+  'write',
+  'writeln',
+]);
+
+/** `unsafeHtml(...)` n'est acceptable qu'accompagné d'une exception datée. */
+function hasRecordedException(sourceCode) {
+  return /allowUnsafe\s*\(/.test(sourceCode);
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    schema: [],
+    docs: { description: 'Require an explicit Craft HTML sanitizer.' },
+  },
+  create(context) {
+    const sourceCode = (context.sourceCode ?? context.getSourceCode()).getText();
+    return {
+      AssignmentExpression(node) {
+        if (
+          node.left.type === 'MemberExpression' &&
+          !node.left.computed &&
+          node.left.property.type === 'Identifier' &&
+          RAW_SINKS.test(node.left.property.name)
+        ) {
+          report(
+            context,
+            node,
+            'Raw HTML and srcdoc assignments are forbidden; use sanitizedHtml or an audited unsafeHtml exception.',
+          );
+        }
+      },
+      CallExpression(node) {
+        if (
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'unsafeHtml' &&
+          !hasRecordedException(sourceCode)
+        ) {
+          report(
+            context,
+            node,
+            'unsafeHtml requires an allowUnsafe(...) exception with an owner, a reason, a risk and an expiry date.',
+          );
+          return;
+        }
+        if (
+          node.callee.type === 'Identifier' &&
+          (node.callee.name === 'eval' || node.callee.name === 'Function')
+        ) {
+          report(context, node, 'Dynamic code evaluation is forbidden.');
+          return;
+        }
+        if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.property.type === 'Identifier' &&
+          DANGEROUS_CALLS.has(node.callee.property.name)
+        ) {
+          const owner =
+            node.callee.object.type === 'Identifier'
+              ? node.callee.object.name
+              : '';
+          if (
+            node.callee.property.name !== 'write' &&
+            node.callee.property.name !== 'writeln'
+          ) {
+            report(
+              context,
+              node,
+              `${node.callee.property.name} is forbidden; use the Craft sanitized HTML API.`,
+            );
+          } else if (owner === 'document') {
+            report(
+              context,
+              node,
+              'document.write injects unparsed markup; use the Craft sanitized HTML API.',
+            );
+          }
+        }
+      },
+      NewExpression(node) {
+        if (node.callee.type === 'Identifier' && node.callee.name === 'Function') {
+          report(context, node, 'Dynamic code evaluation is forbidden.');
+        }
+      },
+    };
+  },
+};

package/src/eslint-rules/no-unsafe-transfer-state.cjs

@@ -0,0 +1,54 @@
+const { report, isCallNamed } = require('./security-rule-utils.cjs');
+
+function hasProperty(node, name) {
+  if (!node || node.type !== 'ObjectExpression') return false;
+  return node.properties.some((property) => {
+    // Un spread peut porter la propriété : on ne peut pas prouver son
+    // absence, et une règle qui accuse à tort finit désactivée.
+    if (property.type === 'SpreadElement') return true;
+    return (
+      property.type === 'Property' &&
+      (property.key.name ?? property.key.value) === name
+    );
+  });
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    schema: [],
+    docs: { description: 'Require an explicit SSR transfer policy.' },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isCallNamed(node, 'captureCraftTransferSnapshot')) {
+          if (node.arguments.length < 2 || !hasProperty(node.arguments[1], 'policy')) {
+            report(
+              context,
+              node,
+              'SSR transfer requires an explicit policy: captureCraftTransferSnapshot(registry, { policy }).',
+            );
+          }
+          return;
+        }
+        // Un rendu sans politique retombe sur le défaut fermé : le signaler
+        // évite de découvrir en production que rien ne s'hydrate.
+        if (isCallNamed(node, 'renderCraft')) {
+          const options = node.arguments[0];
+          if (
+            options &&
+            options.type === 'ObjectExpression' &&
+            !hasProperty(options, 'securityPolicy')
+          ) {
+            report(
+              context,
+              node,
+              'renderCraft requires an explicit securityPolicy: the transfer snapshot is empty without one.',
+            );
+          }
+        }
+      },
+    };
+  },
+};

package/src/eslint-rules/prefer-craft-template-blocks.cjs

@@ -121,13 +121,13 @@ module.exports = {
     schema: [],
     messages: {
       ternary:
-        'Do not use a ternary in a Craft template. Use ifBlock(...) for boolean visibility or matchBlock.exhaustive(...) for a discriminated union.',
+        'Do not use a ternary in a Craft template. Use ifNode(...) for boolean visibility or matchNode.exhaustive(...) for a discriminated union.',
       logical:
         'Do not use a logical expression in a Craft template. Move the derivation to state, query, or craftComputed, then render it with a Craft block.',
       negation:
         'Do not use negation in a Craft template. Move the boolean derivation to state, query, or craftComputed, then bind the resulting value.',
       controlFlow:
-        'Do not use imperative control flow in a Craft template. Use ifBlock(...), matchBlock.exhaustive(...), each(...), or defer(...) so the render contract stays type-checkable.',
+        'Do not use imperative control flow in a Craft template. Use ifNode(...), matchNode.exhaustive(...), forNode(...), or deferNode(...) so the render contract stays type-checkable.',
     },
   },
 
@@ -169,7 +169,7 @@ module.exports = {
                   fix: (fixer) =>
                     [
                       fixer.replaceText(replacement.node, replacement.text),
-                      namedImportFix(fixer, 'ifBlock'),
+                      namedImportFix(fixer, 'ifNode'),
                     ].filter(Boolean),
                 }),
           });
@@ -200,7 +200,7 @@ module.exports = {
                   fix: (fixer) =>
                     [
                       fixer.replaceText(node, replacement),
-                      namedImportFix(fixer, 'matchBlock'),
+                      namedImportFix(fixer, 'matchNode'),
                     ].filter(Boolean),
                 }),
           });
@@ -244,7 +244,7 @@ module.exports = {
         return undefined;
       }
 
-      const text = `ifBlock(${condition}, () => ${sourceCode.getText(
+      const text = `ifNode(${condition}, () => ${sourceCode.getText(
         node.consequent,
       )}, () => ${sourceCode.getText(node.alternate)})`;
       const parent = node.parent;
@@ -271,7 +271,7 @@ module.exports = {
             `${formatObjectKey(key)}: () => ${expression}`,
         )
         .join(', ');
-      return `return matchBlock.exhaustive(${match.source}, ${JSON.stringify(
+      return `return matchNode.exhaustive(${match.source}, ${JSON.stringify(
         match.key,
       )}, { ${handlers} });`;
     }
@@ -429,8 +429,8 @@ function isRenderableArrow(node) {
   }
 
   return !new Set([
-    'each',
-    'defer',
+    'forNode',
+    'deferNode',
     'content',
     'craftTemplate',
     'renderTemplate',