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

package/src/eslint-rules/no-angular-inject.cjs

@@ -5,10 +5,14 @@ module.exports = {
       description:
         'Disallow Angular inject() usage so dependencies go through craftService or toCraftService.',
     },
+    hasSuggestions: true,
     schema: [],
   },
   create(context) {
     const angularNamespaceImports = new Set();
+    const angularInjectImports = new Map();
+    const reportedInjectImports = new Set();
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
 
     return {
       ImportDeclaration(node) {
@@ -22,11 +26,7 @@ module.exports = {
             specifier.imported.type === 'Identifier' &&
             specifier.imported.name === 'inject'
           ) {
-            context.report({
-              node: specifier,
-              message:
-                'Angular inject() is forbidden. Expose a craftService/toCraftService injector instead.',
-            });
+            angularInjectImports.set(specifier.local.name, specifier);
             continue;
           }
 
@@ -36,24 +36,50 @@ module.exports = {
         }
       },
       CallExpression(node) {
-        const callee = node.callee;
-        if (
-          callee.type !== 'MemberExpression' ||
-          callee.computed ||
-          callee.object.type !== 'Identifier' ||
-          !angularNamespaceImports.has(callee.object.name) ||
-          callee.property.type !== 'Identifier' ||
-          callee.property.name !== 'inject'
-        ) {
+        const angularInjectNode = getAngularInjectCallee(
+          node.callee,
+          angularInjectImports,
+          angularNamespaceImports,
+        );
+        if (!angularInjectNode) {
           return;
         }
 
+        if (node.callee.type === 'Identifier') {
+          reportedInjectImports.add(node.callee.name);
+        }
+
+        const tokenText = getInjectTokenText(node.arguments[0], sourceCode);
+        const helperName = getRecommendedInjectorName(node.arguments[0]);
+
         context.report({
-          node: callee.property,
-          message:
-            'Angular inject() is forbidden. Expose a craftService/toCraftService injector instead.',
+          node: angularInjectNode,
+          message: createInjectMessage(tokenText, helperName),
+          suggest: [
+            createTemporaryDisableSuggestion(
+              sourceCode,
+              angularInjectNode,
+              'no-angular-inject',
+              helperName
+                ? `replace this Angular inject(${tokenText}) call with ${helperName} from a craftService/toCraftService adapter`
+                : 'replace this Angular inject() call with a craftService/toCraftService injector',
+            ),
+          ],
         });
       },
+      'Program:exit'() {
+        for (const [localName, specifier] of angularInjectImports) {
+          if (reportedInjectImports.has(localName)) {
+            continue;
+          }
+
+          context.report({
+            node: specifier,
+            message:
+              'Angular inject() is forbidden. Import and use the injectX helper exposed by a craftService/toCraftService adapter instead.',
+          });
+        }
+      },
     };
   },
 };
@@ -61,3 +87,101 @@ module.exports = {
 function isAngularModule(sourceValue) {
   return typeof sourceValue === 'string' && sourceValue.startsWith('@angular/');
 }
+
+function getAngularInjectCallee(
+  callee,
+  angularInjectImports,
+  angularNamespaceImports,
+) {
+  if (callee.type === 'Identifier' && angularInjectImports.has(callee.name)) {
+    return callee;
+  }
+
+  if (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'Identifier' &&
+    angularNamespaceImports.has(callee.object.name) &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'inject'
+  ) {
+    return callee.property;
+  }
+
+  return undefined;
+}
+
+function createInjectMessage(tokenText, helperName) {
+  if (!helperName) {
+    return 'Angular inject() is forbidden. Use the injectX helper exposed by a craftService/toCraftService adapter instead.';
+  }
+
+  return `Angular inject(${tokenText}) is forbidden. Use ${helperName} from a craftService/toCraftService adapter instead.`;
+}
+
+function getInjectTokenText(argument, sourceCode) {
+  if (!argument) {
+    return '';
+  }
+
+  return sourceCode.getText(argument);
+}
+
+function getRecommendedInjectorName(argument) {
+  const tokenName = getTokenName(argument);
+  if (!tokenName) {
+    return undefined;
+  }
+
+  return `inject${toPascalCase(tokenName)}`;
+}
+
+function getTokenName(argument) {
+  if (!argument) {
+    return undefined;
+  }
+
+  if (argument.type === 'Identifier') {
+    return argument.name;
+  }
+
+  if (
+    argument.type === 'MemberExpression' &&
+    !argument.computed &&
+    argument.property.type === 'Identifier'
+  ) {
+    return argument.property.name;
+  }
+
+  return undefined;
+}
+
+function toPascalCase(value) {
+  return value
+    .replace(/^[^A-Za-z$]+/, '')
+    .split(/[^A-Za-z0-9$]+|(?<=[a-z0-9])(?=[A-Z])/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+}
+
+function createTemporaryDisableSuggestion(
+  sourceCode,
+  node,
+  ruleName,
+  migrationNote,
+) {
+  return {
+    desc: 'Insert a temporary eslint-disable-next-line comment with a migration note.',
+    fix(fixer) {
+      const lineStart = sourceCode.getIndexFromLoc({
+        line: node.loc.start.line,
+        column: 0,
+      });
+      return fixer.insertTextBeforeRange(
+        [lineStart, lineStart],
+        `// eslint-disable-next-line craft-ng/${ruleName} -- ${migrationNote}\n`,
+      );
+    },
+  };
+}

package/src/eslint-rules/prefer-craft-effect.cjs

@@ -0,0 +1,12 @@
+const { createPreferCraftSignalRule } = require('./prefer-craft-signal-utils.cjs');
+
+module.exports = createPreferCraftSignalRule({
+  angularName: 'effect',
+  craftName: 'craftEffect',
+  needsName: true,
+  messageId: 'preferCraftEffect',
+  message:
+    "Angular effect() is forbidden. Use craftEffect('name', ...) from @craft-ng/core instead for observability and host name tracking.",
+  description:
+    'Disallow Angular effect() in favor of craftEffect() from @craft-ng/core.',
+});

package/src/eslint-rules/prefer-craft-router-outlet.cjs

@@ -0,0 +1,190 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { IndentationText, Project, QuoteKind, SyntaxKind } = require('ts-morph');
+
+const projectCache = new Map();
+
+const ANGULAR_ROUTER_MODULE = '@angular/router';
+const CRAFT_CORE_MODULE = '@craft-ng/core';
+const ANGULAR_SYMBOL = 'RouterOutlet';
+const CRAFT_SYMBOL = 'CraftRouterOutlet';
+const ANGULAR_TAG = 'router-outlet';
+const CRAFT_TAG = 'craft-router-outlet';
+
+// Match `<router-outlet`, `</router-outlet`, but NOT `<craft-router-outlet`
+// (the `(?<![\w-])` guard stops the `-router-outlet` suffix from matching).
+const TAG_PATTERN = /<(\/?)(?<![\w-])router-outlet\b/g;
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow Angular RouterOutlet / <router-outlet>. Use CraftRouterOutlet / <craft-router-outlet> (the non-blocking outlet) instead.',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      forbidden:
+        'Use CraftRouterOutlet / <craft-router-outlet> instead of Angular RouterOutlet / <router-outlet>.',
+    },
+  },
+  create(context) {
+    return {
+      'Program:exit'() {
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+        const filePath = getFilePath(context);
+        if (!filePath || !filePath.endsWith('.ts')) {
+          return;
+        }
+
+        const text = sourceCode.getText();
+        const hasImport = text.includes(ANGULAR_SYMBOL);
+        const hasTag = TAG_PATTERN.test(text);
+        TAG_PATTERN.lastIndex = 0;
+        if (!hasImport && !hasTag) {
+          return;
+        }
+
+        const sourceFile = getProjectSourceFile(
+          getProject(getCwd(context)),
+          filePath,
+          text,
+        );
+
+        const importChanged = rewriteAngularRouterOutletImport(sourceFile);
+
+        // Rewrite the inline template tag(s) on the post-import-edit text so the
+        // single whole-file fix carries both changes.
+        let fixedText = sourceFile.getFullText();
+        const tagChanged = TAG_PATTERN.test(fixedText);
+        TAG_PATTERN.lastIndex = 0;
+        if (tagChanged) {
+          fixedText = fixedText.replace(TAG_PATTERN, `<$1${CRAFT_TAG}`);
+        }
+
+        if ((!importChanged && !tagChanged) || fixedText === text) {
+          return;
+        }
+
+        context.report({
+          loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
+          messageId: 'forbidden',
+          fix(fixer) {
+            return fixer.replaceTextRange([0, text.length], fixedText);
+          },
+        });
+      },
+    };
+  },
+};
+
+// Removes `RouterOutlet` from the `@angular/router` import, renames every
+// `RouterOutlet` reference to `CraftRouterOutlet`, and ensures the craft import.
+// Returns whether anything changed.
+function rewriteAngularRouterOutletImport(sourceFile) {
+  const routerImport = sourceFile
+    .getImportDeclarations()
+    .find((imp) => imp.getModuleSpecifierValue() === ANGULAR_ROUTER_MODULE);
+
+  const routerOutletSpecifier = routerImport
+    ?.getNamedImports()
+    .find((named) => named.getName() === ANGULAR_SYMBOL);
+
+  if (!routerOutletSpecifier) {
+    return false;
+  }
+
+  // Drop the named import (and the whole declaration if it becomes empty).
+  routerOutletSpecifier.remove();
+  if (
+    routerImport.getNamedImports().length === 0 &&
+    !routerImport.getDefaultImport() &&
+    !routerImport.getNamespaceImport()
+  ) {
+    routerImport.remove();
+  }
+
+  // Rename remaining `RouterOutlet` references (imports array, GenDeps, …).
+  for (const identifier of sourceFile.getDescendantsOfKind(
+    SyntaxKind.Identifier,
+  )) {
+    if (!identifier.wasForgotten() && identifier.getText() === ANGULAR_SYMBOL) {
+      identifier.replaceWithText(CRAFT_SYMBOL);
+    }
+  }
+
+  ensureCraftImport(sourceFile);
+  return true;
+}
+
+function ensureCraftImport(sourceFile) {
+  const craftImport = sourceFile
+    .getImportDeclarations()
+    .find((imp) => imp.getModuleSpecifierValue() === CRAFT_CORE_MODULE);
+
+  if (craftImport) {
+    const alreadyImported = craftImport
+      .getNamedImports()
+      .some((named) => named.getName() === CRAFT_SYMBOL);
+    if (!alreadyImported) {
+      craftImport.addNamedImport(CRAFT_SYMBOL);
+    }
+  } else {
+    sourceFile.addImportDeclaration({
+      moduleSpecifier: CRAFT_CORE_MODULE,
+      namedImports: [CRAFT_SYMBOL],
+    });
+  }
+}
+
+function getProject(cwd) {
+  let project = projectCache.get(cwd);
+  if (project) {
+    return project;
+  }
+
+  const manipulationSettings = {
+    indentationText: IndentationText.TwoSpaces,
+    quoteKind: QuoteKind.Single,
+  };
+  const tsConfigFilePath = path.join(cwd, 'tsconfig.json');
+  project = fs.existsSync(tsConfigFilePath)
+    ? new Project({ tsConfigFilePath, manipulationSettings })
+    : new Project({
+        compilerOptions: { experimentalDecorators: true, target: 9 },
+        manipulationSettings,
+      });
+
+  projectCache.set(cwd, project);
+  return project;
+}
+
+function getProjectSourceFile(project, filePath, text) {
+  const normalizedPath = path.resolve(filePath);
+  const existingSourceFile = project.getSourceFile(normalizedPath);
+  if (existingSourceFile) {
+    existingSourceFile.replaceWithText(text);
+    return existingSourceFile;
+  }
+
+  const sourceFile = project.addSourceFileAtPathIfExists(normalizedPath);
+  if (sourceFile) {
+    sourceFile.replaceWithText(text);
+    return sourceFile;
+  }
+
+  return project.createSourceFile(normalizedPath, text, { overwrite: true });
+}
+
+function getFilePath(context) {
+  const filePath = context.filename ?? context.getFilename();
+  if (!filePath || filePath === '<input>') {
+    return undefined;
+  }
+  return filePath;
+}
+
+function getCwd(context) {
+  return context.cwd ?? process.cwd();
+}

package/src/eslint-rules/prefer-craft-signal-utils.cjs

@@ -0,0 +1,288 @@
+const ANGULAR_CORE = '@angular/core';
+const CRAFT_CORE = '@craft-ng/core';
+
+/**
+ * Factory building a rule that forbids a primitive imported from `@angular/core`
+ * (`signal`, `computed`, `effect`) in favor of its craft counterpart
+ * (`state`, `craftComputed`, `craftEffect`).
+ *
+ * The autofix:
+ *  - renames the call expression callee,
+ *  - inserts the derived name as the first argument when the craft replacement
+ *    requires one (`needsName`) and a name can be derived from the declaration,
+ *  - rewrites the import: drops the forbidden specifier from `@angular/core` and
+ *    adds the replacement import from `@craft-ng/core` (merging into an existing
+ *    `@craft-ng/core` import when present).
+ *
+ * Namespace usages (`import * as core from '@angular/core'; core.signal()`) are
+ * reported without an autofix since they cannot be migrated by a local rename.
+ */
+function createPreferCraftSignalRule({
+  angularName,
+  craftName,
+  needsName,
+  messageId,
+  message,
+  description,
+}) {
+  return {
+    meta: {
+      type: 'problem',
+      docs: { description },
+      fixable: 'code',
+      schema: [],
+      messages: { [messageId]: message },
+    },
+    create(context) {
+      const sourceCode = context.sourceCode ?? context.getSourceCode();
+      const namespaceImports = new Set();
+      const usages = [];
+      let importNode = null;
+      let importSpecifier = null;
+
+      return {
+        ImportDeclaration(node) {
+          if (node.source.value !== ANGULAR_CORE) {
+            return;
+          }
+
+          for (const specifier of node.specifiers) {
+            if (
+              specifier.type === 'ImportSpecifier' &&
+              specifier.imported.type === 'Identifier' &&
+              specifier.imported.name === angularName
+            ) {
+              importNode = node;
+              importSpecifier = specifier;
+            } else if (specifier.type === 'ImportNamespaceSpecifier') {
+              namespaceImports.add(specifier.local.name);
+            }
+          }
+        },
+        CallExpression(node) {
+          const callee = node.callee;
+
+          // Namespace usage (`core.signal()`) cannot be migrated by a local
+          // rename, so report it as-is without a fix.
+          if (
+            callee.type === 'MemberExpression' &&
+            !callee.computed &&
+            callee.object.type === 'Identifier' &&
+            namespaceImports.has(callee.object.name) &&
+            callee.property.type === 'Identifier' &&
+            callee.property.name === angularName
+          ) {
+            context.report({ node: callee.property, messageId });
+            return;
+          }
+
+          if (
+            callee.type !== 'Identifier' ||
+            callee.name !== angularName ||
+            !isAngularImport(angularName, sourceCode, node)
+          ) {
+            return;
+          }
+
+          const declaredName = needsName ? getDeclaredName(node) : undefined;
+          usages.push({
+            callNode: node,
+            callee,
+            declaredName,
+            fixable: !needsName || Boolean(declaredName),
+          });
+        },
+        'Program:exit'() {
+          if (!importSpecifier) {
+            return;
+          }
+
+          // Autofix is all-or-nothing per file: only rewrite the import and
+          // rename usages when every usage can be safely renamed. Otherwise a
+          // partial fix would leave the renamed import referencing a callee
+          // that was never updated (or vice versa).
+          const canAutofix = usages.every((usage) => usage.fixable);
+
+          context.report({
+            node: importSpecifier,
+            messageId,
+            fix: canAutofix
+              ? (fixer) =>
+                  fixImport(
+                    fixer,
+                    sourceCode,
+                    importNode,
+                    importSpecifier,
+                    craftName,
+                  )
+              : undefined,
+          });
+
+          for (const usage of usages) {
+            context.report({
+              node: usage.callee,
+              messageId,
+              fix: canAutofix
+                ? (fixer) => fixUsage(fixer, sourceCode, usage, craftName, needsName)
+                : undefined,
+            });
+          }
+        },
+      };
+    },
+  };
+}
+
+function fixUsage(fixer, sourceCode, usage, craftName, needsName) {
+  const fixes = [fixer.replaceText(usage.callee, craftName)];
+
+  if (needsName) {
+    const openParen = sourceCode.getTokenAfter(
+      usage.callee,
+      (token) => token.type === 'Punctuator' && token.value === '(',
+    );
+    if (!openParen) {
+      return null;
+    }
+    const separator = usage.callNode.arguments.length > 0 ? ', ' : '';
+    fixes.push(
+      fixer.insertTextAfter(openParen, `'${usage.declaredName}'${separator}`),
+    );
+  }
+
+  return fixes;
+}
+
+function fixImport(fixer, sourceCode, importNode, specifier, craftName) {
+  const namedSpecifiers = importNode.specifiers.filter(
+    (s) => s.type === 'ImportSpecifier',
+  );
+  const hasOtherKind = importNode.specifiers.some(
+    (s) => s.type !== 'ImportSpecifier',
+  );
+  const removesWholeImport = namedSpecifiers.length === 1 && !hasOtherKind;
+
+  const craftImport = findCraftImport(sourceCode);
+  const alreadyImported =
+    craftImport &&
+    craftImport.specifiers.some(
+      (s) =>
+        s.type === 'ImportSpecifier' &&
+        s.imported.type === 'Identifier' &&
+        s.imported.name === craftName,
+    );
+
+  // When the forbidden specifier is the only thing imported from @angular/core
+  // and there is no existing @craft-ng/core import to merge into, swap the
+  // whole declaration in place to avoid an insert that overlaps the removal.
+  if (removesWholeImport && !craftImport) {
+    return fixer.replaceText(
+      importNode,
+      `import { ${craftName} } from '${CRAFT_CORE}';`,
+    );
+  }
+
+  const fixes = [removeSpecifier(fixer, sourceCode, importNode, specifier, removesWholeImport)];
+
+  if (craftImport && !alreadyImported) {
+    const lastSpecifier =
+      craftImport.specifiers[craftImport.specifiers.length - 1];
+    fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${craftName}`));
+  } else if (!craftImport) {
+    fixes.push(
+      fixer.insertTextAfter(
+        importNode,
+        `\nimport { ${craftName} } from '${CRAFT_CORE}';`,
+      ),
+    );
+  }
+
+  return fixes;
+}
+
+function removeSpecifier(fixer, sourceCode, importNode, specifier, removesWholeImport) {
+  if (removesWholeImport) {
+    const text = sourceCode.getText();
+    let end = importNode.range[1];
+    if (text[end] === '\n') {
+      end += 1;
+    }
+    return fixer.removeRange([importNode.range[0], end]);
+  }
+
+  const tokenAfter = sourceCode.getTokenAfter(specifier);
+  if (tokenAfter && tokenAfter.value === ',') {
+    return fixer.removeRange([specifier.range[0], tokenAfter.range[1]]);
+  }
+
+  const tokenBefore = sourceCode.getTokenBefore(specifier);
+  if (tokenBefore && tokenBefore.value === ',') {
+    return fixer.removeRange([tokenBefore.range[0], specifier.range[1]]);
+  }
+
+  return fixer.remove(specifier);
+}
+
+function findCraftImport(sourceCode) {
+  return sourceCode.ast.body.find(
+    (statement) =>
+      statement.type === 'ImportDeclaration' &&
+      statement.source.value === CRAFT_CORE &&
+      statement.importKind !== 'type' &&
+      statement.specifiers.some((s) => s.type === 'ImportSpecifier'),
+  );
+}
+
+function getDeclaredName(callNode) {
+  const parent = callNode.parent;
+  if (!parent) return undefined;
+
+  if (
+    parent.type === 'VariableDeclarator' &&
+    parent.init === callNode &&
+    parent.id.type === 'Identifier'
+  ) {
+    return parent.id.name;
+  }
+
+  if (
+    parent.type === 'PropertyDefinition' &&
+    parent.value === callNode &&
+    !parent.computed &&
+    parent.key.type === 'Identifier'
+  ) {
+    return parent.key.name;
+  }
+
+  return undefined;
+}
+
+function isAngularImport(angularName, sourceCode, node) {
+  const getScope = sourceCode.getScope
+    ? (n) => sourceCode.getScope(n)
+    : (n) => sourceCode.scopeManager.acquire(n) ?? sourceCode.scopeManager.globalScope;
+
+  let currentScope = getScope(node);
+  while (currentScope) {
+    for (const variable of currentScope.variables) {
+      if (variable.name !== angularName) {
+        continue;
+      }
+      for (const def of variable.defs) {
+        if (
+          def.type === 'ImportBinding' &&
+          def.parent &&
+          def.parent.source &&
+          def.parent.source.value === ANGULAR_CORE
+        ) {
+          return true;
+        }
+      }
+    }
+    currentScope = currentScope.upper;
+  }
+
+  return false;
+}
+
+module.exports = { createPreferCraftSignalRule };

package/src/eslint-rules/prefer-craft-state.cjs

@@ -0,0 +1,12 @@
+const { createPreferCraftSignalRule } = require('./prefer-craft-signal-utils.cjs');
+
+module.exports = createPreferCraftSignalRule({
+  angularName: 'signal',
+  craftName: 'state',
+  needsName: false,
+  messageId: 'preferCraftState',
+  message:
+    'Angular signal() is forbidden. Use state() from @craft-ng/core instead for observability and host name tracking.',
+  description:
+    'Disallow Angular signal() in favor of state() from @craft-ng/core.',
+});