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

package/src/eslint-rules/require-craft-resource-trigger-yield.cjs

@@ -0,0 +1,209 @@
+const PRIMITIVE_METHODS = {
+  query: new Set(['call']),
+  mutation: new Set(['mutate']),
+  asyncProcess: new Set(['method']),
+};
+
+const CORE_PACKAGE = '@craft-ts/core';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require query, mutation, and asyncProcess triggers to be consumed with yield* inside generator functions.',
+    },
+    schema: [],
+    messages: {
+      requireYield:
+        '{{primitive}}.{{method}}(...) must be consumed with `yield*` inside a generator function.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const imported = new Map();
+    const primitiveNames = new Map();
+    const primitiveRefs = new Map();
+    const calls = [];
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== CORE_PACKAGE) return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== 'ImportSpecifier') continue;
+          imported.set(specifier.local.name, specifier.imported.name);
+          if (PRIMITIVE_METHODS[specifier.imported.name]) {
+            primitiveNames.set(
+              specifier.local.name,
+              specifier.imported.name,
+            );
+          }
+        }
+      },
+
+      VariableDeclarator(node) {
+        if (node.id.type === 'Identifier') {
+          const primitive = findPrimitiveCreation(node.init);
+          if (primitive) {
+            primitiveRefs.set(node.id.name, {
+              primitive,
+              methods: PRIMITIVE_METHODS[primitive],
+            });
+          }
+        }
+
+        if (node.id.type !== 'ObjectPattern') return;
+        const primitive = findPrimitiveCreation(node.init);
+        if (!primitive) return;
+
+        for (const property of node.id.properties) {
+          if (
+            property.type !== 'Property' ||
+            property.computed ||
+            property.value.type !== 'Identifier'
+          ) {
+            continue;
+          }
+
+          primitiveRefs.set(property.value.name, {
+            primitive,
+            methods: PRIMITIVE_METHODS[primitive],
+          });
+        }
+      },
+
+      CallExpression(node) {
+        calls.push(node);
+      },
+
+      'Program:exit'() {
+        // Resolve simple aliases after all primitive destructuring declarations
+        // have been collected (`const q = users`).
+        let changed = true;
+        while (changed) {
+          changed = false;
+          walk(sourceCode.ast, (node) => {
+            if (
+              node.type !== 'VariableDeclarator' ||
+              node.id.type !== 'Identifier' ||
+              node.init?.type !== 'Identifier'
+            ) {
+              return;
+            }
+            const ref = primitiveRefs.get(node.init.name);
+            if (ref && !primitiveRefs.has(node.id.name)) {
+              primitiveRefs.set(node.id.name, ref);
+              changed = true;
+            }
+          });
+        }
+
+        for (const node of calls) {
+          if (!isInsideGeneratorFunction(node)) continue;
+          const trigger = getTrigger(node);
+          if (!trigger || isYieldStarConsumed(node)) continue;
+
+          context.report({
+            node,
+            messageId: 'requireYield',
+            data: trigger,
+          });
+        }
+      },
+    };
+
+    function getTrigger(node) {
+      if (node.callee.type !== 'MemberExpression') return null;
+      if (node.callee.object.type !== 'Identifier') return null;
+
+      const ref = primitiveRefs.get(node.callee.object.name);
+      if (!ref) return null;
+
+      const method = node.callee.computed
+        ? node.callee.property.type === 'Literal'
+          ? String(node.callee.property.value)
+          : undefined
+        : node.callee.property.name;
+      if (!method || !ref.methods.has(method)) return null;
+
+      return { primitive: ref.primitive, method };
+    }
+
+    function findPrimitiveCreation(node) {
+      let current = node;
+      while (current) {
+        if (current.type === 'YieldExpression') {
+          current = current.argument;
+          continue;
+        }
+        if (
+          current.type === 'TSAsExpression' ||
+          current.type === 'TSTypeAssertion' ||
+          current.type === 'ChainExpression'
+        ) {
+          current = current.expression;
+          continue;
+        }
+        if (current.type !== 'CallExpression') return undefined;
+
+        if (
+          current.callee.type === 'Identifier' &&
+          (current.callee.name === 'craftUse' ||
+            imported.get(current.callee.name) === 'craftUse')
+        ) {
+          current = current.arguments[0];
+          continue;
+        }
+
+        if (
+          current.callee.type === 'Identifier' &&
+          primitiveNames.has(current.callee.name)
+        ) {
+          return primitiveNames.get(current.callee.name);
+        }
+        return undefined;
+      }
+      return undefined;
+    }
+  },
+};
+
+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 isYieldStarConsumed(node) {
+  let parent = node.parent;
+  while (parent && parent.type === 'ParenthesizedExpression') {
+    parent = parent.parent;
+  }
+  return parent?.type === 'YieldExpression' && parent.delegate === true;
+}
+
+function walk(node, visitor) {
+  if (!node || typeof node !== 'object') return;
+  if (node.type) visitor(node);
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'parent' || key === 'tokens' || key === 'comments') continue;
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child.type === 'string') walk(child, visitor);
+      }
+    } else if (value && typeof value.type === 'string') {
+      walk(value, visitor);
+    }
+  }
+}

package/src/eslint-rules/require-effect-adapters.cjs

@@ -0,0 +1,86 @@
+const ADAPTERS = {
+  query: 'queryEffect',
+  mutation: 'mutationEffect',
+  asyncProcess: 'asyncProcessEffect',
+};
+
+function isExemptFile(filename) {
+  return (
+    /(?:^|[/\\])libs[/\\]effect[/\\]/.test(filename) ||
+    /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(filename)
+  );
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require Effect-aware Craft adapters in the demo-effect application.',
+    },
+    schema: [],
+    messages: {
+      direct: 'Use {{adapter}}(...) in demo-effect instead of {{primitive}}(...).\nEffect demos must use the Effect-aware CraftTS adapters.',
+    },
+  },
+  create(context) {
+    if (isExemptFile(context.filename ?? '')) {
+      return {};
+    }
+
+    const directImports = new Map();
+    const directCalls = [];
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== '@craft-ts/core') return;
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type !== 'ImportSpecifier' ||
+            specifier.importKind === 'type'
+          ) {
+            continue;
+          }
+
+          const imported =
+            specifier.imported.type === 'Identifier'
+              ? specifier.imported.name
+              : specifier.imported.value;
+          if (!Object.hasOwn(ADAPTERS, imported)) continue;
+
+          directImports.set(specifier.local.name, imported);
+          context.report({
+            node: specifier,
+            messageId: 'direct',
+            data: { adapter: ADAPTERS[imported], primitive: imported },
+          });
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !directImports.has(node.callee.name)
+        ) {
+          return;
+        }
+
+        directCalls.push(node);
+      },
+
+      'Program:exit'() {
+        for (const node of directCalls) {
+          const primitive = directImports.get(node.callee.name);
+          if (!primitive) continue;
+
+          context.report({
+            node: node.callee,
+            messageId: 'direct',
+            data: { adapter: ADAPTERS[primitive], primitive },
+          });
+        }
+      },
+    };
+  },
+};

package/src/eslint-rules/require-exception-component-di-check.cjs

@@ -0,0 +1,314 @@
+/** Generates O(1) DI checks for route, exception, and route-load error components. */
+module.exports = {
+  meta: { type: 'problem', fixable: 'code', schema: [] },
+  create(context) {
+    const source = context.sourceCode ?? context.getSourceCode();
+    return {
+      'Program:exit'(program) {
+        const text = source.getText();
+        if (
+          !/renderComponent|errorComponent|withErrorComponent|withRouteLoadError|provideRouteLoadErrorComponent/.test(
+            text,
+          )
+        )
+          return;
+
+        const cascade = readCascadeContext(text);
+        const checks = [];
+        walk(program, (node) => {
+          if (isCall(node, 'craftRoutes')) {
+            collectRouteChecks(node, source, cascade, checks);
+          } else if (
+            isCall(node, 'withErrorComponent') ||
+            isCall(node, 'withRouteLoadError')
+          ) {
+            const descriptor = node.arguments[0];
+            const deps = readProperty(descriptor, 'componentDeps', source);
+            if (deps) {
+              const routeLoad = isCall(node, 'withRouteLoadError');
+              checks.push({
+                deps,
+                names: joinNames(
+                  cascade.names,
+                  routeLoad
+                    ? ['CraftRouteLoadError', 'CraftRouteLoadRecovery']
+                    : ['CraftGlobalError'],
+                ),
+                values: cascade.values,
+                label: routeLoad
+                  ? 'global route load error component'
+                  : 'global error component',
+              });
+            }
+          }
+        });
+
+        const existingChecks = readExistingCheckDeps(text);
+        const missing = checks.filter(
+          (check) => !existingChecks.has(normalizeTypeText(check.deps)),
+        );
+        if (missing.length === 0) return;
+
+        let fixed = ensureImports(text);
+        fixed += missing.map(renderCheck).join('');
+        context.report({
+          node: program,
+          message: `${missing.length} exception component(s) must be checked with RouteExceptionComponentCheckedDI.`,
+          fix: (fixer) => fixer.replaceTextRange([0, text.length], fixed),
+        });
+      },
+    };
+  },
+};
+
+function collectRouteChecks(call, source, cascade, checks) {
+  const collection = literal(call.arguments[0]);
+  const array = call.arguments[1];
+  if (!collection || array?.type !== 'ArrayExpression') return;
+
+  for (const entry of array.elements) {
+    const routeCall = unwrapRouteCall(entry);
+    const def = routeCall ? routeCall.arguments[1] : entry;
+    const path = routeCall
+      ? literal(routeCall.arguments[0])
+      : literal(propertyValue(def, 'path'));
+    if (path === undefined || def?.type !== 'ObjectExpression') continue;
+    const baseNames = routeNames(collection, path, def);
+    if (routeCall && routeCall !== entry) {
+      walk(entry.arguments[0], (node) => {
+        if (
+          node?.type === 'CallExpression' &&
+          node.callee?.type === 'Identifier' &&
+          node.callee.name.startsWith('provide')
+        ) {
+          baseNames.push(node.callee.name.slice('provide'.length));
+        }
+      });
+    }
+
+    const routeError = propertyValue(def, 'errorComponent');
+    const routeDeps = readProperty(routeError, 'componentDeps', source);
+    if (routeDeps) {
+      checks.push({
+        deps: routeDeps,
+        names: joinNames(cascade.names, [...baseNames, 'CraftGlobalError']),
+        values: cascade.values,
+        label: `error component: ${path}`,
+      });
+    }
+
+    const providers = propertyValue(def, 'providers');
+    if (providers?.type === 'ArrayExpression') {
+      for (const provider of providers.elements) {
+        if (!isCall(provider, 'provideRouteLoadErrorComponent')) continue;
+        const deps = readProperty(
+          provider.arguments[0],
+          'componentDeps',
+          source,
+        );
+        if (!deps) continue;
+        checks.push({
+          deps,
+          names: joinNames(cascade.names, [
+            ...baseNames,
+            'CraftRouteLoadError',
+            'CraftRouteLoadRecovery',
+          ]),
+          values: cascade.values,
+          label: `route load error component: ${path}`,
+        });
+      }
+    }
+
+    const handlers = routeCall
+      ? routeCall.arguments[2]
+      : propertyValue(def, 'handleExceptions');
+    if (handlers?.type !== 'ObjectExpression') continue;
+    for (const handler of handlers.properties) {
+      if (handler.type !== 'Property') continue;
+      const code = propertyName(handler);
+      walk(handler.value, (node) => {
+        if (!isCall(node, 'renderComponent')) return;
+        const deps = readProperty(node.arguments[0], 'componentDeps', source);
+        if (!deps) return;
+        const helper = `${pascal(collection)}${routeBase(path)}${pascal(code)}Exception`;
+        checks.push({
+          deps,
+          names: joinNames(cascade.names, [...baseNames, helper]),
+          values: cascade.values,
+          label: `render component: ${path}#${code}`,
+        });
+      });
+    }
+  }
+}
+
+function unwrapRouteCall(entry) {
+  if (isCall(entry, 'craftRoute')) return entry;
+  if (
+    entry?.type === 'CallExpression' &&
+    entry.callee?.type === 'MemberExpression' &&
+    entry.callee.property?.type === 'Identifier' &&
+    entry.callee.property.name === 'withProviders' &&
+    isCall(entry.callee.object, 'craftRoute')
+  ) {
+    return entry.callee.object;
+  }
+  return undefined;
+}
+
+function routeNames(collection, path, def) {
+  const prefix = pascal(collection);
+  const base = routeBase(path);
+  const names = path
+    .split('/')
+    .filter((x) => x.startsWith(':'))
+    .map((x) => `${prefix}${pascal(x.slice(1).replace(/\?$/, ''))}Params`);
+  if (propertyValue(def, 'data')) names.push(`${prefix}${base}Data`);
+  if (propertyValue(def, 'queryParams'))
+    names.push(`${prefix}${base}QueryParams`);
+  if (propertyValue(def, 'withLoaderViewTransitionImage'))
+    names.push(`${prefix}${base}ViewTransition`);
+  const providers = propertyValue(def, 'providers');
+  if (providers?.type === 'ArrayExpression') {
+    for (const provider of providers.elements) {
+      if (
+        provider?.type === 'CallExpression' &&
+        provider.callee?.type === 'Identifier' &&
+        provider.callee.name.startsWith('provide')
+      ) {
+        names.push(provider.callee.name.slice('provide'.length));
+      }
+    }
+  }
+  return names;
+}
+
+function renderCheck(check, index) {
+  const id = check.label
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .map(pascal)
+    .join('');
+  return `\n\ntype _Check${id}${index ?? ''}DI = RouteExceptionComponentCheckedDI<\n  ${check.deps},\n  ${check.names || 'never'},\n  ${check.values},\n  '${check.label}',\n>;\ntype _CanRun${id}${index ?? ''} = CanRun<_Check${id}${index ?? ''}DI>;`;
+}
+
+function readCascadeContext(text) {
+  const match = text.match(
+    /ValidateCascadeRoutesFile<\s*([^,]+),\s*([^,]+),\s*typeof\s+\w+\s*>/m,
+  );
+  return {
+    names: match?.[1]?.trim() ?? 'never',
+    values: match?.[2]?.trim() ?? 'never',
+  };
+}
+
+function joinNames(parent, names) {
+  return (
+    [parent === 'never' ? '' : parent, ...names.map((name) => `'${name}'`)]
+      .filter(Boolean)
+      .join(' | ') || 'never'
+  );
+}
+
+function ensureImports(text) {
+  const names = ['CanRun', 'RouteExceptionComponentCheckedDI'];
+  const match = text.match(
+    /import\s*\{([\s\S]*?)\}\s*from\s*(['"]@craft-ts\/core['"])/,
+  );
+  if (!match)
+    return `import type { ${names.join(', ')} } from '@craft-ts/core';\n${text}`;
+  const missing = names.filter(
+    (name) => !new RegExp(`\\b${name}\\b`).test(match[1]),
+  );
+  if (!missing.length) return text;
+  return text.replace(
+    match[0],
+    `import {${match[1].trimEnd()},\n  type ${missing.join(',\n  type ')},\n} from ${match[2]}`,
+  );
+}
+
+function readExistingCheckDeps(text) {
+  const deps = new Set();
+  const regex = /RouteExceptionComponentCheckedDI<\s*([\s\S]*?),\s*(?:'[^']*'|never)/g;
+  let match;
+  while ((match = regex.exec(text))) {
+    deps.add(normalizeTypeText(match[1]));
+  }
+  return deps;
+}
+
+function normalizeTypeText(text) {
+  return String(text).replace(/\s+/g, '');
+}
+
+function readProperty(node, name, source) {
+  const value = propertyValue(node, name);
+  return value ? readTypeText(value, source) : undefined;
+}
+
+function readTypeText(node, source) {
+  if (node?.type === 'TSAsExpression') return source.getText(node.typeAnnotation);
+  return source.getText(node);
+}
+
+function propertyValue(node, name) {
+  if (node?.type !== 'ObjectExpression') return undefined;
+  return node.properties.find(
+    (p) => p.type === 'Property' && propertyName(p) === name,
+  )?.value;
+}
+function propertyName(property) {
+  return property.key?.type === 'Identifier'
+    ? property.key.name
+    : (literal(property.key) ?? '');
+}
+function literal(node) {
+  return node?.type === 'Literal'
+    ? node.value
+    : node?.type === 'StringLiteral'
+      ? node.value
+      : undefined;
+}
+function isCall(node, name) {
+  return (
+    node?.type === 'CallExpression' &&
+    node.callee?.type === 'Identifier' &&
+    node.callee.name === name
+  );
+}
+function pascal(value) {
+  return String(value)
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map(
+      (x) =>
+        x[0].toUpperCase() +
+        (x === x.toUpperCase() ? x.slice(1).toLowerCase() : x.slice(1)),
+    )
+    .join('');
+}
+function routeBase(path) {
+  return (
+    String(path)
+      .split('/')
+      .filter(Boolean)
+      .map((x) => pascal(x.replace(/^:/, '').replace(/\?$/, '')))
+      .join('') || 'Root'
+  );
+}
+function walk(node, visit) {
+  if (!node || typeof node !== 'object') return;
+  visit(node);
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'parent' || key === 'range' || key === 'loc') continue;
+    if (Array.isArray(value)) value.forEach((child) => walk(child, visit));
+    else if (
+      value &&
+      typeof value === 'object' &&
+      typeof value.type === 'string'
+    )
+      walk(value, visit);
+  }
+}

package/src/eslint-rules/require-focus-visible.cjs

@@ -0,0 +1,36 @@
+'use strict';
+
+const { componentInfo } = require('./css-rule-utils.cjs');
+
+const INTERACTIVE_SELECTOR = /(^|[\s,>+~])(button|a|input|select|textarea|\[tabindex\b)/i;
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require :focus-visible (or :focus) when a component styles interactive elements.',
+    },
+    schema: [],
+    messages: {
+      missing:
+        'Component styles target {{selector}} but never define :focus-visible or :focus.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return {
+      CallExpression(node) {
+        const info = componentInfo(context, sourceCode, node);
+        if (!info?.css) return;
+        if (!INTERACTIVE_SELECTOR.test(info.css)) return;
+        if (/:focus-visible|:focus\b/.test(info.css)) return;
+        context.report({
+          node: info.styles?.value ?? info.stylesUrl.value,
+          messageId: 'missing',
+          data: { selector: 'button/a/input/[tabindex]' },
+        });
+      },
+    };
+  },
+};