@craft-ng/dev-tools 0.1.9 → 0.4.0-beta.1

package/src/eslint-rules/no-angular-provide-app-initializer.cjs

@@ -0,0 +1,79 @@
+const path = require('node:path');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow Angular provideAppInitializer() usage outside the internal @craft-ng bridge in favor of onAppStart().',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filePath = getFilePath(context);
+    if (filePath && path.basename(filePath) === 'craft-app-config.ts') {
+      return {};
+    }
+
+    const angularNamespaceImports = new Set();
+
+    return {
+      ImportDeclaration(node) {
+        if (!isAngularModule(node.source.value)) {
+          return;
+        }
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type === 'ImportSpecifier' &&
+            specifier.imported.type === 'Identifier' &&
+            specifier.imported.name === 'provideAppInitializer'
+          ) {
+            context.report({
+              node: specifier,
+              message:
+                'Angular provideAppInitializer() is forbidden. Model startup work with onAppStart(...) through craftService({ appStart: true }, ...).',
+            });
+            continue;
+          }
+
+          if (specifier.type === 'ImportNamespaceSpecifier') {
+            angularNamespaceImports.add(specifier.local.name);
+          }
+        }
+      },
+      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 !== 'provideAppInitializer'
+        ) {
+          return;
+        }
+
+        context.report({
+          node: callee.property,
+          message:
+            'Angular provideAppInitializer() is forbidden. Model startup work with onAppStart(...) through craftService({ appStart: true }, ...).',
+        });
+      },
+    };
+  },
+};
+
+function getFilePath(context) {
+  const filePath = context.filename ?? context.getFilename();
+  if (!filePath || filePath === '<input>') {
+    return undefined;
+  }
+
+  return filePath;
+}
+
+function isAngularModule(sourceValue) {
+  return typeof sourceValue === 'string' && sourceValue.startsWith('@angular/');
+}

package/src/eslint-rules/prefer-browser-boundaries.cjs

@@ -0,0 +1,92 @@
+const BLOCKED_GLOBALS = new Map([
+  ['window', 'BrowserWindow'],
+  ['document', 'BrowserDocument'],
+  ['localStorage', 'LocalStorage'],
+  ['sessionStorage', 'SessionStorage'],
+  ['location', 'BrowserLocation'],
+  ['history', 'BrowserHistory'],
+  ['navigator', 'BrowserNavigator'],
+  ['performance', 'BrowserPerformance'],
+  ['crypto', 'BrowserCrypto'],
+  ['console', 'Console'],
+  ['alert', 'BrowserWindow.alert'],
+  ['confirm', 'BrowserWindow.confirm'],
+  ['scrollTo', 'BrowserWindow.scrollTo'],
+]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow direct browser globals when an @craft-ng browser boundary exists.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    function report(node, actualName) {
+      const preferredBoundary = BLOCKED_GLOBALS.get(actualName);
+
+      if (!preferredBoundary) {
+        return;
+      }
+
+      context.report({
+        node,
+        message: `Use the @craft-ng browser boundary ${preferredBoundary} instead of direct ${actualName} access.`,
+      });
+    }
+
+    function findReference(node) {
+      let scope = sourceCode.getScope(node);
+
+      while (scope) {
+        const reference = scope.references.find(
+          (candidate) => candidate.identifier === node,
+        );
+
+        if (reference) {
+          return reference;
+        }
+
+        scope = scope.upper;
+      }
+
+      return undefined;
+    }
+
+    function isGlobalReference(node) {
+      const reference = findReference(node);
+      return Boolean(
+        reference &&
+          (reference.resolved == null || reference.resolved.defs.length === 0),
+      );
+    }
+
+    return {
+      Identifier(node) {
+        if (!BLOCKED_GLOBALS.has(node.name) || !isGlobalReference(node)) {
+          return;
+        }
+
+        report(node, node.name);
+      },
+      MemberExpression(node) {
+        if (
+          node.object.type !== 'Identifier' ||
+          node.object.name !== 'globalThis' ||
+          !isGlobalReference(node.object) ||
+          node.property.type !== 'Identifier' ||
+          node.computed ||
+          !BLOCKED_GLOBALS.has(node.property.name)
+        ) {
+          return;
+        }
+
+        report(node, node.property.name);
+      },
+    };
+  },
+};

package/src/eslint-rules/prefer-craft-http-client.cjs

@@ -0,0 +1,120 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow Angular HttpClient usage in favor of CraftHttpClient.',
+    },
+    hasSuggestions: true,
+    schema: [],
+  },
+  create(context) {
+    const angularHttpNamespaceImports = new Set();
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== '@angular/common/http') {
+          return;
+        }
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type === 'ImportSpecifier' &&
+            specifier.imported.type === 'Identifier' &&
+            specifier.imported.name === 'HttpClient'
+          ) {
+            context.report({
+              node: specifier,
+              message:
+                'Angular HttpClient is forbidden. Use CraftHttpClient from @craft-ng/core instead.',
+              suggest: [
+                createTemporaryDisableSuggestion(
+                  sourceCode,
+                  specifier,
+                  'prefer-craft-http-client',
+                  'migrate this usage to CraftHttpClient',
+                ),
+              ],
+            });
+            continue;
+          }
+
+          if (specifier.type === 'ImportNamespaceSpecifier') {
+            angularHttpNamespaceImports.add(specifier.local.name);
+          }
+        }
+      },
+      MemberExpression(node) {
+        if (
+          node.computed ||
+          node.object.type !== 'Identifier' ||
+          !angularHttpNamespaceImports.has(node.object.name) ||
+          node.property.type !== 'Identifier' ||
+          node.property.name !== 'HttpClient'
+        ) {
+          return;
+        }
+
+        context.report({
+          node: node.property,
+          message:
+            'Angular HttpClient is forbidden. Use CraftHttpClient from @craft-ng/core instead.',
+          suggest: [
+            createTemporaryDisableSuggestion(
+              sourceCode,
+              node,
+              'prefer-craft-http-client',
+              'migrate this usage to CraftHttpClient',
+            ),
+          ],
+        });
+      },
+      TSQualifiedName(node) {
+        if (
+          node.left.type !== 'Identifier' ||
+          !angularHttpNamespaceImports.has(node.left.name) ||
+          node.right.type !== 'Identifier' ||
+          node.right.name !== 'HttpClient'
+        ) {
+          return;
+        }
+
+        context.report({
+          node: node.right,
+          message:
+            'Angular HttpClient is forbidden. Use CraftHttpClient from @craft-ng/core instead.',
+          suggest: [
+            createTemporaryDisableSuggestion(
+              sourceCode,
+              node,
+              'prefer-craft-http-client',
+              'migrate this usage to CraftHttpClient',
+            ),
+          ],
+        });
+      },
+    };
+  },
+};
+
+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-service.cjs

@@ -0,0 +1,140 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow Angular @Injectable and @Service decorators in favor of craftService or toCraftService.',
+    },
+    hasSuggestions: true,
+    schema: [],
+  },
+  create(context) {
+    const angularNamespaceImports = new Set();
+    const angularInjectableImports = new Set();
+    const angularServiceImports = new Set();
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      ImportDeclaration(node) {
+        if (!isAngularModule(node.source.value)) {
+          return;
+        }
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type === 'ImportSpecifier' &&
+            specifier.imported.type === 'Identifier' &&
+            specifier.imported.name === 'Injectable'
+          ) {
+            angularInjectableImports.add(specifier.local.name);
+            continue;
+          }
+
+          if (
+            specifier.type === 'ImportSpecifier' &&
+            specifier.imported.type === 'Identifier' &&
+            specifier.imported.name === 'Service'
+          ) {
+            angularServiceImports.add(specifier.local.name);
+            continue;
+          }
+
+          if (specifier.type === 'ImportNamespaceSpecifier') {
+            angularNamespaceImports.add(specifier.local.name);
+          }
+        }
+      },
+      Decorator(node) {
+        const decoratorName = getAngularBlockedDecoratorName(
+          node.expression,
+          angularInjectableImports,
+          angularServiceImports,
+          angularNamespaceImports,
+        );
+        if (!decoratorName) {
+          return;
+        }
+
+        context.report({
+          node,
+          message: `Angular @${decoratorName} is forbidden. Author services with craftService(...) and adapt Angular dependencies with toCraftService(...) instead.`,
+          suggest: [
+            createTemporaryDisableSuggestion(
+              sourceCode,
+              node,
+              'prefer-craft-service',
+              'migrate this Angular service to craftService(...) or toCraftService(...)',
+            ),
+          ],
+        });
+      },
+    };
+  },
+};
+
+function isAngularModule(sourceValue) {
+  return typeof sourceValue === 'string' && sourceValue.startsWith('@angular/');
+}
+
+function getAngularBlockedDecoratorName(
+  expression,
+  angularInjectableImports,
+  angularServiceImports,
+  angularNamespaceImports,
+) {
+  if (expression.type === 'Identifier') {
+    if (angularInjectableImports.has(expression.name)) {
+      return 'Injectable';
+    }
+
+    if (angularServiceImports.has(expression.name)) {
+      return 'Service';
+    }
+
+    return undefined;
+  }
+
+  if (expression.type === 'CallExpression') {
+    return getAngularBlockedDecoratorName(
+      expression.callee,
+      angularInjectableImports,
+      angularServiceImports,
+      angularNamespaceImports,
+    );
+  }
+
+  if (
+    expression.type === 'MemberExpression' &&
+    !expression.computed &&
+    expression.object.type === 'Identifier' &&
+    angularNamespaceImports.has(expression.object.name) &&
+    expression.property.type === 'Identifier' &&
+    (expression.property.name === 'Injectable' ||
+      expression.property.name === 'Service')
+  ) {
+    return expression.property.name;
+  }
+
+  return undefined;
+}
+
+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/scripts/angular-brand-codemod.d.ts

@@ -1,5 +1,24 @@
 import { ClassDeclaration, Node, SourceFile } from 'ts-morph';
 export type AngularKind = 'component' | 'directive' | 'pipe' | 'injectable';
+export type AngularBrandMetadataContext = 'imports' | 'hostDirectives';
+export type AngularBrandConfigEntry = {
+    key: string;
+    symbol: string;
+    typeText?: string;
+    module?: string;
+};
+export type AngularBrandImportAugmentationRule = {
+    match: {
+        module: string;
+        symbols?: readonly string[];
+        metadata?: readonly AngularBrandMetadataContext[];
+    };
+    deps?: readonly AngularBrandConfigEntry[];
+    missingProvider?: readonly AngularBrandConfigEntry[];
+};
+export type AngularBrandConfig = {
+    importAugmentations?: readonly AngularBrandImportAugmentationRule[];
+};
 export type TransformResult = {
     changed: boolean;
     skipped: boolean;
@@ -16,6 +35,8 @@ export type AngularBrandCodemodOptions = {
     transformOnlyStandaloneDeclarables?: boolean;
     includeProviders?: boolean;
     includeViewProviders?: boolean;
+    config?: AngularBrandConfig;
+    configFilePath?: string;
 };
 export type AngularClassSearchResult = {
     classDeclaration?: ClassDeclaration;
@@ -43,6 +64,7 @@ export type GeneratedDependencyEntry = {
 };
 export type GeneratedDependencyGroups = {
     deps: GeneratedDependencyEntry[];
+    propertiesDeps: GeneratedDependencyEntry[];
     provided: GeneratedDependencyEntry[];
     missingProvider: GeneratedDependencyEntry[];
 };
@@ -74,6 +96,9 @@ export type RunSummary = {
     countByAngularKind: Record<AngularKind, number>;
     files: RunFileReport[];
 };
+export declare function defineAngularBrandConfig<Config extends AngularBrandConfig>(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;
 export declare function analyzeSourceFileDependencies(sourceFile: SourceFile, options?: AngularBrandCodemodOptions): DependencyAnalysisResult;
 export declare function findAngularDecoratedClass(sourceFile: SourceFile): AngularClassSearchResult;