@craft-ng/dev-tools 0.5.0-beta.4 → 0.5.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-ng/dev-tools",
-  "version": "0.5.0-beta.4",
+  "version": "0.5.0-beta.5",
   "description": "Development tools for ng-craft: ESLint configs, ESLint rules, and codemods",
   "type": "module",
   "main": "./src/index.js",

package/src/eslint-rules/global-exception-registry-match.cjs

@@ -176,7 +176,7 @@ function getCallExpressionName(callExpression) {
   if (Node.isIdentifier(expression)) {
     return expression.getText();
   }
-  // `route(...).withProviders` etc. — the leftmost call's callee.
+  // `craftRoute(...).withProviders` etc. — the leftmost call's callee.
   if (Node.isPropertyAccessExpression(expression)) {
     return expression.getName();
   }
@@ -208,7 +208,7 @@ function resolveCollectionVar(craftRoutesCall) {
   return undefined;
 }
 
-// A route array element is either `route('path', { … }, { … })` (optionally
+// A route array element is either `craftRoute('path', { … }, { … })` (optionally
 // followed by `.withProviders(…)`) or a plain `{ path: '…', handleExceptions: { … } }`.
 function extractRouteDefinition(element) {
   if (Node.isObjectLiteralExpression(element)) {
@@ -245,11 +245,11 @@ function extractRouteDefinition(element) {
   return undefined;
 }
 
-// Walks `route(...).withProviders(...)` (any depth) down to the `route(` call.
+// Walks `craftRoute(...).withProviders(...)` (any depth) down to the `craftRoute(` call.
 function findRouteCall(node) {
   let current = node;
   while (Node.isCallExpression(current)) {
-    if (getCallExpressionName(current) === 'route') {
+    if (getCallExpressionName(current) === 'craftRoute') {
       return current;
     }
     const expression = current.getExpression();

package/src/eslint-rules/index.cjs

@@ -19,6 +19,8 @@ const requireTrackOnDependentPrimitives = require('./require-track-on-dependent-
 const requireAssertExhaustiveRouteExceptions = require('./require-assert-exhaustive-route-exceptions.cjs');
 const preferCraftRouterOutlet = require('./prefer-craft-router-outlet.cjs');
 const requirePendingComponentDiCheck = require('./require-pending-component-di-check.cjs');
+const requireCraftExceptionHandler = require('./require-craft-exception-handler.cjs');
+const requireExceptionComponentDiCheck = require('./require-exception-component-di-check.cjs');
 const requireChildRouteMountCheck = require('./require-child-route-mount-check.cjs');
 
 module.exports = {
@@ -45,6 +47,8 @@ module.exports = {
       requireAssertExhaustiveRouteExceptions,
     'prefer-craft-router-outlet': preferCraftRouterOutlet,
     'require-pending-component-di-check': requirePendingComponentDiCheck,
+    'require-craft-exception-handler': requireCraftExceptionHandler,
+    'require-exception-component-di-check': requireExceptionComponentDiCheck,
     'require-child-route-mount-check': requireChildRouteMountCheck,
   },
 };

package/src/eslint-rules/require-craft-exception-handler.cjs

@@ -0,0 +1,142 @@
+/** Enforces craftExceptionHandler(function* (...) {}) in craftRoute() handler maps. */
+module.exports = {
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    schema: [],
+    messages: {
+      wrap: 'Route exception handlers must use craftExceptionHandler(function* (...) {}).',
+      redirect:
+        'Raw redirect(...) is ambiguous: migrate internal routes to redirectTo(...) and opaque URLs to redirectUrl(...).',
+    },
+  },
+  create(context) {
+    const source = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      'Program:exit'(program) {
+        const issues = [];
+
+        for (const statement of program.body) {
+          walk(statement, (node) => {
+            if (
+              node.type !== 'CallExpression' ||
+              node.callee?.type !== 'Identifier' ||
+              node.callee.name !== 'craftRoute' ||
+              node.arguments.length < 3
+            ) {
+              return;
+            }
+
+            const handlers = node.arguments[2];
+            if (handlers?.type !== 'ObjectExpression') return;
+
+            for (const property of handlers.properties) {
+              if (property.type !== 'Property') continue;
+              const value = property.value;
+              if (
+                value.type === 'CallExpression' &&
+                value.callee?.type === 'Identifier' &&
+                value.callee.name === 'craftExceptionHandler'
+              ) {
+                continue;
+              }
+
+              if (
+                value.type !== 'ArrowFunctionExpression' &&
+                value.type !== 'FunctionExpression'
+              ) {
+                issues.push({ node: value, manual: true });
+                continue;
+              }
+
+              const text = source.getText(value);
+              issues.push({
+                node: value,
+                manual: /\bredirect\s*\(/.test(text),
+                replacement: wrapHandler(value, source),
+              });
+            }
+          });
+        }
+
+        if (issues.length === 0) return;
+        const manual = issues.filter((issue) => issue.manual);
+        if (manual.length > 0) {
+          for (const issue of manual) {
+            context.report({ node: issue.node, messageId: 'redirect' });
+          }
+        }
+
+        const fixable = issues.filter((item) => !item.manual);
+        if (fixable.length === 0) return;
+        const original = source.getText();
+        const replacements = fixable
+          .map((issue) => ({
+            range: issue.node.range,
+            text: issue.replacement,
+          }))
+          .sort((a, b) => b.range[0] - a.range[0]);
+        let fixed = original;
+        for (const replacement of replacements) {
+          fixed =
+            fixed.slice(0, replacement.range[0]) +
+            replacement.text +
+            fixed.slice(replacement.range[1]);
+        }
+        fixed = ensureImport(fixed);
+
+        context.report({
+          node: fixable[0].node,
+          messageId: 'wrap',
+          fix: (fixer) => fixer.replaceTextRange([0, original.length], fixed),
+        });
+      },
+    };
+  },
+};
+
+function wrapHandler(node, source) {
+  const params = node.params.map((param) => source.getText(param)).join(', ');
+  const body =
+    node.body.type === 'BlockStatement'
+      ? source.getText(node.body)
+      : `{ return ${source.getText(node.body)}; }`;
+  return `craftExceptionHandler(function* (${params}) ${body})`;
+}
+
+function ensureImport(text) {
+  if (
+    /\bcraftExceptionHandler\b/.test(
+      text.match(/import[\s\S]*?from\s+['"]@craft-ng\/core['"]/g)?.join('\n') ??
+        '',
+    )
+  ) {
+    return text;
+  }
+  const pattern = /import\s*\{([\s\S]*?)\}\s*from\s*(['"]@craft-ng\/core['"])/;
+  if (pattern.test(text)) {
+    return text.replace(pattern, (_all, names, source) => {
+      const separator = names.includes('\n') ? '\n  ' : ' ';
+      return `import {${names.trimEnd()},${separator}craftExceptionHandler\n} from ${source}`;
+    });
+  }
+  return `import { craftExceptionHandler } from '@craft-ng/core';\n${text}`;
+}
+
+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)) {
+      for (const child of value) walk(child, visit);
+    } else if (
+      value &&
+      typeof value === 'object' &&
+      typeof value.type === 'string'
+    ) {
+      walk(value, visit);
+    }
+  }
+}

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

@@ -0,0 +1,258 @@
+/** Generates O(1) DI checks for renderComponent/errorComponent/withErrorComponent. */
+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/.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')) {
+            const descriptor = node.arguments[0];
+            const deps = readProperty(descriptor, 'componentDeps', source);
+            if (deps) {
+              checks.push({
+                deps,
+                names: joinNames(cascade.names, ['CraftGlobalError']),
+                values: cascade.values,
+                label: 'global error component',
+              });
+            }
+          }
+        });
+
+        const missing = checks.filter(
+          (check) =>
+            !text.includes(
+              `RouteExceptionComponentCheckedDI<\n  ${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 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-ng\/core['"])/,
+  );
+  if (!match)
+    return `import type { ${names.join(', ')} } from '@craft-ng/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 readProperty(node, name, source) {
+  const value = propertyValue(node, name);
+  return value ? source.getText(value) : undefined;
+}
+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-pending-component-di-check.cjs

@@ -5,7 +5,7 @@ const { IndentationText, Node, Project, QuoteKind, SyntaxKind } = require('ts-mo
 const projectCache = new Map();
 
 const ROUTES_FACTORY = 'craftRoutes';
-const ROUTE_FN = 'route';
+const ROUTE_FN = 'craftRoute';
 const PENDING_PROP = 'pendingComponent';
 const VT_PROP = 'withLoaderViewTransitionImage';
 const CHECK_TYPE = 'RouteCheckedDI';
@@ -99,7 +99,7 @@ module.exports = {
         }
 
         const fixedText = sourceFile.getFullText();
-        const message = `route(s) with a pendingComponent must be verified with ${CHECK_TYPE}(): ${issues
+        const message = `craftRoute(s) with a pendingComponent must be verified with ${CHECK_TYPE}(): ${issues
           .map((i) => i.path)
           .join(', ')}`;
 
@@ -178,7 +178,7 @@ function collectCollections(sourceFile, filePath) {
   return collections;
 }
 
-// A route element is either `route('<path>', { … })` or a `{ path: '<path>', … }`
+// A route element is either `craftRoute('<path>', { … })` or a `{ path: '<path>', … }`
 // object literal. Returns the path string and the route's object literal.
 function readRoute(element) {
   if (Node.isCallExpression(element) && element.getExpression().getText() === ROUTE_FN) {