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

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

@@ -1,4 +1,4 @@
-/** Generates O(1) DI checks for renderComponent/errorComponent/withErrorComponent. */
+/** Generates O(1) DI checks for route, exception, and route-load error components. */
 module.exports = {
   meta: { type: 'problem', fixable: 'code', schema: [] },
   create(context) {
@@ -6,7 +6,11 @@ module.exports = {
     return {
       'Program:exit'(program) {
         const text = source.getText();
-        if (!/renderComponent|errorComponent|withErrorComponent/.test(text))
+        if (
+          !/renderComponent|errorComponent|withErrorComponent|withRouteLoadError|provideRouteLoadErrorComponent/.test(
+            text,
+          )
+        )
           return;
 
         const cascade = readCascadeContext(text);
@@ -14,25 +18,34 @@ module.exports = {
         walk(program, (node) => {
           if (isCall(node, 'craftRoutes')) {
             collectRouteChecks(node, source, cascade, checks);
-          } else if (isCall(node, 'withErrorComponent')) {
+          } 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, ['CraftGlobalError']),
+                names: joinNames(
+                  cascade.names,
+                  routeLoad
+                    ? ['CraftRouteLoadError', 'CraftRouteLoadRecovery']
+                    : ['CraftGlobalError'],
+                ),
                 values: cascade.values,
-                label: 'global error component',
+                label: routeLoad
+                  ? 'global route load error component'
+                  : 'global error component',
               });
             }
           }
         });
 
+        const existingChecks = readExistingCheckDeps(text);
         const missing = checks.filter(
-          (check) =>
-            !text.includes(
-              `RouteExceptionComponentCheckedDI<\n  ${check.deps},`,
-            ),
+          (check) => !existingChecks.has(normalizeTypeText(check.deps)),
         );
         if (missing.length === 0) return;
 
@@ -84,6 +97,29 @@ function collectRouteChecks(call, source, cascade, checks) {
       });
     }
 
+    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');
@@ -193,10 +229,30 @@ function ensureImports(text) {
   );
 }
 
+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 ? source.getText(value) : undefined;
+  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(

package/src/eslint-rules/require-lazy-load-with-retry.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+const LAZY_PROPERTIES = new Set([
+  'loadComponent',
+  'loadChildren',
+]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require lazy route imports to use the withRetry helper so browser-cached module failures can be retried.',
+    },
+    fixable: 'code',
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const importsByLoader = new Map();
+
+    return {
+      ImportExpression(node) {
+        const loader = enclosingLazyLoader(node);
+        if (!loader || isWrappedWithRetry(node)) return;
+
+        const imports = importsByLoader.get(loader) ?? [];
+        imports.push(node);
+        importsByLoader.set(loader, imports);
+      },
+      'Program:exit'() {
+        for (const [loader, imports] of importsByLoader) {
+          context.report({
+            node: imports[0],
+            message:
+              'Lazy route imports must be wrapped with withRetry(import(...)).',
+            fix(fixer) {
+              const parameterFixes = addWithRetryParameter(
+                fixer,
+                sourceCode,
+                loader,
+              );
+              if (!parameterFixes) return null;
+
+              return [
+                ...parameterFixes,
+                ...imports.flatMap((moduleImport) => [
+                  fixer.insertTextBefore(moduleImport, 'withRetry('),
+                  fixer.insertTextAfter(moduleImport, ')'),
+                ]),
+              ];
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+function enclosingLazyLoader(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      (current.type === 'ArrowFunctionExpression' ||
+        current.type === 'FunctionExpression') &&
+      current.parent?.type === 'Property' &&
+      LAZY_PROPERTIES.has(propertyName(current.parent)) &&
+      isInsideCraftRoute(current.parent)
+    ) {
+      return current;
+    }
+    if (current.type === 'Property' || current.type === 'Program') return null;
+    current = current.parent;
+  }
+  return null;
+}
+
+function isInsideCraftRoute(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'CallExpression' &&
+      current.callee.type === 'Identifier' &&
+      (current.callee.name === 'craftRoute' ||
+        current.callee.name === 'craftRoutes')
+    ) {
+      return true;
+    }
+    if (current.type === 'Program') return false;
+    current = current.parent;
+  }
+  return false;
+}
+
+function propertyName(property) {
+  if (property.computed) return undefined;
+  if (property.key.type === 'Identifier') return property.key.name;
+  if (property.key.type === 'Literal') return property.key.value;
+  return undefined;
+}
+
+function isWrappedWithRetry(node) {
+  return (
+    node.parent?.type === 'CallExpression' &&
+    node.parent.callee.type === 'Identifier' &&
+    node.parent.callee.name === 'withRetry' &&
+    node.parent.arguments[0] === node
+  );
+}
+
+function addWithRetryParameter(fixer, sourceCode, loader) {
+  if (loader.params.length === 0) {
+    const arrow = sourceCode.getTokenBefore(loader.body, {
+      filter: (token) => token.value === '=>',
+    });
+    if (!arrow) return null;
+
+    const closeParen = sourceCode.getTokenBefore(arrow);
+    const openParen = closeParen && sourceCode.getTokenBefore(closeParen);
+    if (openParen?.value !== '(' || closeParen?.value !== ')') return null;
+    return [
+      fixer.replaceTextRange(
+        [openParen.range[1], closeParen.range[0]],
+        '{ withRetry }',
+      ),
+    ];
+  }
+
+  if (loader.params.length !== 1 || loader.params[0].type !== 'ObjectPattern') {
+    return null;
+  }
+
+  const pattern = loader.params[0];
+  if (
+    pattern.properties.some(
+      (property) =>
+        property.type === 'Property' &&
+        property.key.type === 'Identifier' &&
+        property.key.name === 'withRetry',
+    )
+  ) {
+    return [];
+  }
+
+  const closingBrace = sourceCode.getLastToken(pattern);
+  const prefix = pattern.properties.length > 0 ? ', ' : '';
+  return [fixer.insertTextBefore(closingBrace, `${prefix}withRetry`)];
+}

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

@@ -0,0 +1,267 @@
+const DEFAULT_PRIMITIVES = [
+  'state',
+  'query',
+  'mutation',
+  'asyncProcess',
+  'queryParam',
+];
+
+const FACTORY_HOST_CALLEES = new Set(['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)
+  ) {
+    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-ng/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-ng/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/generators/route/compat.d.ts

@@ -0,0 +1,3 @@
+export declare const routeSchematic: (generatorOptions: import("./schema.js").RouteGeneratorSchema) => (tree: any, context: any) => Promise<any>;
+export declare const routeSplitSchematic: (generatorOptions: import("./schema.js").RouteSplitGeneratorSchema) => (tree: any, context: any) => Promise<any>;
+export default routeSchematic;

package/src/generators/route/compat.js

@@ -0,0 +1,6 @@
+import { convertNxGenerator } from '@nx/devkit';
+import { routeGenerator, routeSplitGenerator } from './generator.js';
+export const routeSchematic = convertNxGenerator(routeGenerator);
+export const routeSplitSchematic = convertNxGenerator(routeSplitGenerator);
+export default routeSchematic;
+//# sourceMappingURL=compat.js.map

package/src/generators/route/compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.js","sourceRoot":"","sources":["../../../../../../libs/dev-tools/src/generators/route/compat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErE,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAC;AAE3E,eAAe,cAAc,CAAC"}

package/src/generators/route/generator.d.ts

@@ -0,0 +1,31 @@
+import { type GeneratorCallback, type Tree } from '@nx/devkit';
+import type { RouteGeneratorSchema, RouteSplitGeneratorSchema } from './schema.js';
+export declare function routeGenerator(tree: Tree, options: RouteGeneratorSchema): Promise<GeneratorCallback | void>;
+type ConfiguredRouteTargetOptions = Pick<RouteGeneratorSchema, 'component' | 'createComponent' | 'redirectTo'>;
+type ComponentCreationTarget = {
+    name: string;
+    path: string;
+};
+type ResolvedRouteTargetOptions = {
+    component?: string;
+    createComponent?: ComponentCreationTarget;
+    redirectTo?: string;
+};
+type RouteQuestion = (prompt: string) => Promise<string>;
+type RouteParentOption = {
+    collectionName: string;
+    filePath: string;
+    routesName: string;
+};
+export declare function resolveRouteParentOption(parents: RouteParentOption[], interactive: {
+    configuredParent?: string;
+    rootDir: string;
+    routePath: string;
+    ask?: RouteQuestion;
+}): Promise<string | undefined>;
+export declare function resolveRouteTargetOptions(options: ConfiguredRouteTargetOptions, interactive: {
+    componentBase: string;
+    ask?: RouteQuestion;
+}): Promise<ResolvedRouteTargetOptions>;
+export declare function routeSplitGenerator(tree: Tree, options: RouteSplitGeneratorSchema): Promise<GeneratorCallback | void>;
+export default routeGenerator;