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

package/src/eslint-rules/require-primitive-generator-unwrap.cjs

@@ -0,0 +1,274 @@
+const DEFAULT_PRIMITIVES = [
+  'state',
+  'query',
+  'mutation',
+  'asyncProcess',
+  'queryParam',
+];
+
+const FACTORY_HOST_CALLEES = new Set([
+  'craftComponent',
+  'craftService',
+  'toCraftService',
+]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require craft primitive invocations (which return a generator) to be consumed with `yield*` inside a generator factory or `craftUse(...)` elsewhere.',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          primitives: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      requireUnwrap:
+        "'{{name}}(...)' returns a primitive generator that must be consumed: use `yield* {{name}}(...)` inside a generator factory, or `craftUse({{name}}(...))` elsewhere.",
+    },
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const primitives = new Set(options.primitives ?? DEFAULT_PRIMITIVES);
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !primitives.has(node.callee.name) ||
+          // Creation calls always take a config; destructured readers such as
+          // `({ state }) => state().page` are argument-less.
+          node.arguments.length === 0
+        ) {
+          return;
+        }
+
+        if (!resolvesToImport(node.callee, sourceCode, context)) {
+          return;
+        }
+
+        if (
+          isConsumed(node) ||
+          isDirectFactoryReturn(node) ||
+          isTrackedTypeOnlyPosition(node)
+        ) {
+          return;
+        }
+
+        const primitiveName = node.callee.name;
+
+        context.report({
+          node,
+          messageId: 'requireUnwrap',
+          data: { name: primitiveName },
+          fix(fixer) {
+            const text = sourceCode.getText(node);
+
+            if (isInsideGeneratorFunction(node)) {
+              const wrapped = needsYieldParens(node)
+                ? `(yield* ${text})`
+                : `yield* ${text}`;
+              return [fixer.replaceText(node, wrapped)];
+            }
+
+            const fixes = [fixer.replaceText(node, `craftUse(${text})`)];
+            const importFix = createCraftUseImportFix(fixer, sourceCode);
+            if (importFix) {
+              fixes.push(importFix);
+            }
+            return fixes;
+          },
+        });
+      },
+    };
+  },
+};
+
+function resolvesToImport(identifier, sourceCode, context) {
+  const scope = sourceCode.getScope
+    ? sourceCode.getScope(identifier)
+    : context.getScope();
+  let current = scope;
+  while (current) {
+    const variable = current.variables.find(
+      (candidate) => candidate.name === identifier.name,
+    );
+    if (variable) {
+      if (variable.defs.length === 0) {
+        return false;
+      }
+      return variable.defs.every((def) => def.type === 'ImportBinding');
+    }
+    current = current.upper;
+  }
+  // Unresolved (globals) — not an import of the primitive.
+  return false;
+}
+
+function isConsumed(node) {
+  const parent = skipParens(node.parent);
+  if (!parent) {
+    return false;
+  }
+  if (parent.type === 'YieldExpression') {
+    return true;
+  }
+  return (
+    parent.type === 'CallExpression' &&
+    parent.callee.type === 'Identifier' &&
+    parent.callee.name === 'craftUse' &&
+    skipParensDown(parent.arguments[0]) === node
+  );
+}
+
+function isDirectFactoryReturn(node) {
+  const arrow = skipParens(node.parent);
+  if (!arrow || arrow.type !== 'ArrowFunctionExpression') {
+    return false;
+  }
+  if (skipParensDown(arrow.body) !== node) {
+    return false;
+  }
+  return isFactoryHostArrow(arrow);
+}
+
+function isFactoryHostArrow(arrow) {
+  const parent = arrow.parent;
+  if (
+    parent &&
+    parent.type === 'CallExpression' &&
+    parent.callee.type === 'Identifier' &&
+    FACTORY_HOST_CALLEES.has(parent.callee.name)
+  ) {
+    if (parent.callee.name === 'craftComponent') {
+      return parent.arguments[2] === arrow;
+    }
+    return parent.arguments.includes(arrow);
+  }
+  return (
+    parent &&
+    parent.type === 'Property' &&
+    parent.key &&
+    ((parent.key.type === 'Identifier' && parent.key.name === 'queryParams') ||
+      (parent.key.type === 'Literal' && parent.key.value === 'queryParams')) &&
+    parent.value === arrow
+  );
+}
+
+// `mockHttpRequestForRoute` / type-only fixtures sometimes reference a
+// primitive purely for inference through `typeof`; those never run.
+function isTrackedTypeOnlyPosition(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'TSTypeQuery' ||
+      current.type === 'TSTypeReference' ||
+      current.type === 'TSTypeAnnotation'
+    ) {
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+function isInsideGeneratorFunction(node) {
+  let current = node.parent;
+  while (current) {
+    if (current.type === 'ArrowFunctionExpression') {
+      return false;
+    }
+    if (
+      current.type === 'FunctionDeclaration' ||
+      current.type === 'FunctionExpression'
+    ) {
+      return current.generator === true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+function needsYieldParens(node) {
+  const parent = node.parent;
+  if (!parent) {
+    return false;
+  }
+  return (
+    parent.type === 'SpreadElement' ||
+    parent.type === 'MemberExpression' ||
+    parent.type === 'BinaryExpression' ||
+    parent.type === 'ConditionalExpression' ||
+    parent.type === 'TemplateLiteral' ||
+    (parent.type === 'CallExpression' && parent.callee === node)
+  );
+}
+
+function skipParens(node) {
+  let current = node;
+  while (current && current.type === 'ParenthesizedExpression') {
+    current = current.parent;
+  }
+  return current;
+}
+
+function skipParensDown(node) {
+  let current = node;
+  while (current && current.type === 'ParenthesizedExpression') {
+    current = current.expression;
+  }
+  return current;
+}
+
+function createCraftUseImportFix(fixer, sourceCode) {
+  const program = sourceCode.ast;
+  let craftImport;
+
+  for (const statement of program.body) {
+    if (
+      statement.type === 'ImportDeclaration' &&
+      statement.source.value === '@craft-ts/core'
+    ) {
+      const alreadyImported = statement.specifiers.some(
+        (specifier) =>
+          specifier.type === 'ImportSpecifier' &&
+          specifier.imported.type === 'Identifier' &&
+          specifier.imported.name === 'craftUse',
+      );
+      if (alreadyImported) {
+        return undefined;
+      }
+      craftImport = statement;
+      break;
+    }
+  }
+
+  if (!craftImport) {
+    return fixer.insertTextBefore(
+      program.body[0] ?? program,
+      "import { craftUse } from '@craft-ts/core';\n",
+    );
+  }
+
+  const namedSpecifiers = craftImport.specifiers.filter(
+    (specifier) => specifier.type === 'ImportSpecifier',
+  );
+
+  if (namedSpecifiers.length === 0) {
+    return undefined;
+  }
+
+  const lastSpecifier = namedSpecifiers[namedSpecifiers.length - 1];
+  return fixer.insertTextAfter(lastSpecifier, ', craftUse');
+}

package/src/eslint-rules/require-reactive-template-bindings.cjs

@@ -0,0 +1,305 @@
+const REACTIVE_BRANDS = ['SIGNAL', 'YIELDABLE_VALUE', 'INPUT_BRAND'];
+const { NAMED_HTML_HELPERS } = require('./html-helpers.cjs');
+const STRUCTURAL_HELPERS = new Set([
+  'catchBlock',
+  'content',
+  'defer',
+  'each',
+  'heading',
+  'headingSection',
+  'ifBlock',
+  'liveRegion',
+  'matchBlock',
+  'renderContent',
+  'renderTemplate',
+]);
+const RENDER_HELPERS = new Set(['customElement', 'h', ...NAMED_HTML_HELPERS]);
+const EVENT_NAMES = new Set([
+  'blur',
+  'change',
+  'click',
+  'dblclick',
+  'focus',
+  'input',
+  'keydown',
+  'keypress',
+  'keyup',
+  'mousedown',
+  'mouseup',
+  'pointerdown',
+  'pointerup',
+  'reset',
+  'scroll',
+  'submit',
+]);
+const EAGER_CALLBACK_METHODS = new Set([
+  'every',
+  'filter',
+  'find',
+  'findIndex',
+  'findLast',
+  'findLastIndex',
+  'flatMap',
+  'forEach',
+  'map',
+  'reduce',
+  'reduceRight',
+  'some',
+  'sort',
+]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require reactive values rendered by Craft components to be read inside granular binding callbacks.',
+    },
+    schema: [],
+    messages: {
+      directRead:
+        'Do not read a reactive value directly while building a Craft template. Wrap the rendered expression in a binding callback, for example `() => value()`.',
+      missingTypeInfo:
+        'This rule requires TypeScript type information to identify reactive template values.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const parserServices = sourceCode.parserServices ?? context.parserServices;
+    const checker = parserServices?.program?.getTypeChecker?.();
+    const esTreeNodeToTSNodeMap = parserServices?.esTreeNodeToTSNodeMap;
+    let reportedMissingTypeInfo = false;
+
+    return {
+      Program() {
+        if (!checker || !esTreeNodeToTSNodeMap) {
+          context.report({
+            node: sourceCode.ast,
+            messageId: 'missingTypeInfo',
+          });
+          reportedMissingTypeInfo = true;
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          reportedMissingTypeInfo ||
+          !checker ||
+          !esTreeNodeToTSNodeMap ||
+          node.callee.type !== 'Identifier' ||
+          node.callee.name !== 'craftComponent' ||
+          node.arguments.length < 4
+        ) {
+          return;
+        }
+        inspectTemplate(node.arguments[3]);
+      },
+    };
+
+    function inspectTemplate(template) {
+      walk(template, (node) => {
+        if (node !== template && isNestedCraftComponent(node)) {
+          return 'skip';
+        }
+        if (
+          node.type !== 'CallExpression' ||
+          node.arguments.length !== 0 ||
+          !isReactiveRead(node) ||
+          isInsideBindingOrAction(node, template)
+        ) {
+          return;
+        }
+        context.report({ node, messageId: 'directRead' });
+      });
+    }
+
+    function isReactiveRead(node) {
+      const tsNode = esTreeNodeToTSNodeMap.get(node.callee);
+      if (!tsNode) return false;
+      return hasReactiveBrand(checker.getTypeAtLocation(tsNode), new Set());
+    }
+
+    function hasReactiveBrand(type, seen) {
+      if (!type || seen.has(type)) return false;
+      seen.add(type);
+      if (type.isUnion?.() || type.isIntersection?.()) {
+        return type.types.some((part) => hasReactiveBrand(part, seen));
+      }
+      return checker
+        .getPropertiesOfType(type)
+        .some((property) =>
+          REACTIVE_BRANDS.some((brand) =>
+            String(property.escapedName ?? property.name).includes(brand),
+          ),
+        );
+    }
+
+    function isInsideBindingOrAction(node, template) {
+      let current = node.parent;
+      while (current && current !== template) {
+        if (isFunctionNode(current)) {
+          if (isEventOrOutputCallback(current)) return true;
+          if (isReactiveBindingFunction(current)) return true;
+        }
+        current = current.parent;
+      }
+      return false;
+    }
+
+    function isReactiveBindingFunction(fn) {
+      const renderCall = enclosingRenderCall(fn);
+      if (!renderCall) return !isEagerCollectionCallback(fn);
+      const name = callName(renderCall);
+      return !isStructuralTemplateFunction(fn, renderCall, name);
+    }
+
+    function isEagerCollectionCallback(fn) {
+      const call = fn.parent;
+      return Boolean(
+        call?.type === 'CallExpression' &&
+          call.callee.type === 'MemberExpression' &&
+          !call.callee.computed &&
+          call.callee.property.type === 'Identifier' &&
+          EAGER_CALLBACK_METHODS.has(call.callee.property.name),
+      );
+    }
+
+    function isStructuralTemplateFunction(fn, call, name) {
+      const argument = directArgumentContaining(fn, call);
+      const argumentIndex = argument ? call.arguments.indexOf(argument) : -1;
+      const key = enclosingPropertyName(fn, call);
+
+      if (name === 'each') {
+        return argumentIndex === 2 || key === 'empty';
+      }
+      if (name === 'ifBlock') {
+        return argumentIndex === 1 || argumentIndex === 2;
+      }
+      if (name === 'defer') {
+        return ['resolve', 'placeholder', 'loading', 'error'].includes(key);
+      }
+      if (name === 'exhaustive') {
+        return argumentIndex !== 0;
+      }
+      return Boolean(name && STRUCTURAL_HELPERS.has(name));
+    }
+
+    function directArgumentContaining(node, call) {
+      let current = node;
+      while (current?.parent && current.parent !== call) {
+        current = current.parent;
+      }
+      return current?.parent === call ? current : undefined;
+    }
+
+    function enclosingPropertyName(node, call) {
+      let current = node.parent;
+      while (current && current !== call) {
+        if (current.type === 'Property') return propertyName(current);
+        current = current.parent;
+      }
+      return undefined;
+    }
+
+    function enclosingRenderCall(node) {
+      let current = node.parent;
+      while (current) {
+        if (current.type === 'CallExpression') {
+          return isRenderCall(current) ? current : undefined;
+        }
+        if (
+          current.type !== 'Property' &&
+          current.type !== 'ObjectExpression' &&
+          current.type !== 'ArrayExpression' &&
+          current.type !== 'SpreadElement' &&
+          current.type !== 'TSAsExpression' &&
+          current.type !== 'TSSatisfiesExpression' &&
+          current.type !== 'ChainExpression'
+        ) {
+          return undefined;
+        }
+        current = current.parent;
+      }
+      return undefined;
+    }
+
+    function isRenderCall(node) {
+      const name = callName(node);
+      if (name && (RENDER_HELPERS.has(name) || STRUCTURAL_HELPERS.has(name))) {
+        return true;
+      }
+      if (name === 'exhaustive') return true;
+      return (
+        node.callee.type === 'Identifier' &&
+        /^[A-Z]/.test(node.callee.name) &&
+        ![
+          'Array',
+          'BigInt',
+          'Boolean',
+          'Date',
+          'Number',
+          'Object',
+          'String',
+        ].includes(node.callee.name)
+      );
+    }
+
+    function callName(node) {
+      if (node.callee.type === 'Identifier') return node.callee.name;
+      if (
+        node.callee.type === 'MemberExpression' &&
+        !node.callee.computed &&
+        node.callee.property.type === 'Identifier'
+      ) {
+        return node.callee.property.name;
+      }
+      return undefined;
+    }
+
+    function isEventOrOutputCallback(fn) {
+      const property = fn.parent;
+      if (property?.type !== 'Property' || property.value !== fn) return false;
+      const name = propertyName(property);
+      return Boolean(name && (EVENT_NAMES.has(name) || /^on[A-Z]/.test(name)));
+    }
+
+    function propertyName(property) {
+      if (property.computed) return undefined;
+      if (property.key.type === 'Identifier') return property.key.name;
+      return property.key.type === 'Literal' &&
+        typeof property.key.value === 'string'
+        ? property.key.value
+        : undefined;
+    }
+
+    function isNestedCraftComponent(node) {
+      return (
+        node.type === 'CallExpression' &&
+        node.callee.type === 'Identifier' &&
+        node.callee.name === 'craftComponent'
+      );
+    }
+
+    function isFunctionNode(node) {
+      return (
+        node?.type === 'ArrowFunctionExpression' ||
+        node?.type === 'FunctionExpression'
+      );
+    }
+
+    function walk(node, visitor) {
+      if (!node || typeof node.type !== 'string') return;
+      if (visitor(node) === 'skip') return;
+      const keys = sourceCode.visitorKeys[node.type] ?? [];
+      for (const key of keys) {
+        const child = node[key];
+        if (Array.isArray(child)) {
+          child.forEach((entry) => walk(entry, visitor));
+        } else {
+          walk(child, visitor);
+        }
+      }
+    }
+  },
+};

package/src/eslint-rules/require-reduced-motion.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+const { componentInfo } = require('./css-rule-utils.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require @media (prefers-reduced-motion) when component styles use @keyframes or transition.',
+    },
+    schema: [],
+    messages: {
+      missing:
+        'Component styles use {{feature}} but never gate motion with prefers-reduced-motion.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return {
+      CallExpression(node) {
+        const info = componentInfo(context, sourceCode, node);
+        if (!info?.css) return;
+        const hasKeyframes = /@keyframes\b/.test(info.css);
+        const hasTransition = /\btransition(?:-duration|-property|-timing-function)?\s*:/.test(
+          info.css,
+        );
+        if (!hasKeyframes && !hasTransition) return;
+        if (/prefers-reduced-motion/.test(info.css)) return;
+        context.report({
+          node: info.styles?.value ?? info.stylesUrl.value,
+          messageId: 'missing',
+          data: { feature: hasKeyframes ? '@keyframes' : 'transition' },
+        });
+      },
+    };
+  },
+};