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

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,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-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 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-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-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) {

package/src/index.d.ts

@@ -1 +1,9 @@
 export * from './scripts/angular-brand-codemod';
+export * from './scripts/primitives/migrate-primitives';
+export * from './scripts/migrate';
+export * from './scripts/primitives/migration-diagnostic';
+export * from './scripts/routes/migrate-routes';
+export * from './scripts/routes/migration-diagnostic';
+export * from './scripts/services/config';
+export * from './scripts/services/migrate-services';
+export * from './scripts/services/migration-diagnostic';

package/src/index.js

@@ -1,3 +1,11 @@
 // Export programmatic API for codemod
 export * from './scripts/angular-brand-codemod';
+export * from './scripts/primitives/migrate-primitives';
+export * from './scripts/migrate';
+export * from './scripts/primitives/migration-diagnostic';
+export * from './scripts/routes/migrate-routes';
+export * from './scripts/routes/migration-diagnostic';
+export * from './scripts/services/config';
+export * from './scripts/services/migrate-services';
+export * from './scripts/services/migration-diagnostic';
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/dev-tools/src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,cAAc,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/dev-tools/src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,mBAAmB,CAAC;AAClC,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC"}

package/src/scripts/angular-brand-codemod.d.ts

@@ -19,6 +19,22 @@ export type AngularBrandImportAugmentationRule = {
 export type AngularBrandConfig = {
     importAugmentations?: readonly AngularBrandImportAugmentationRule[];
 };
+export type ServiceMigrationScope = 'global' | 'toProvide' | 'manuallyProvidedAtRoot' | 'function' | 'abstract';
+export type ServiceMigrationStrategy = 'craftService' | 'toCraftService' | 'companion' | 'ignore';
+export type ServiceMigrationOverride = {
+    file?: string;
+    module?: string;
+    symbol?: string;
+    name?: string;
+    scope?: ServiceMigrationScope;
+    strategy?: ServiceMigrationStrategy;
+};
+export type CraftDevToolsConfig = {
+    brand?: AngularBrandConfig;
+    serviceMigration?: {
+        overrides?: readonly ServiceMigrationOverride[];
+    };
+};
 export type TransformResult = {
     changed: boolean;
     skipped: boolean;
@@ -97,6 +113,7 @@ export type RunSummary = {
     files: RunFileReport[];
 };
 export declare function defineAngularBrandConfig<Config extends AngularBrandConfig>(config: Config): Config;
+export declare function defineCraftDevToolsConfig<Config extends CraftDevToolsConfig>(config: Config): Config;
 export declare function discoverAngularBrandConfigFilePath(searchFromDir: string, stopDir?: string): string | undefined;
 export declare function loadAngularBrandConfigFromFile(configFilePath: string): AngularBrandConfig;
 export declare function transformSourceFile(sourceFile: SourceFile, options?: AngularBrandCodemodOptions): TransformResult;