@craft-ng/dev-tools 0.1.0

package/README.md

@@ -0,0 +1,324 @@
+# @craft-ng/dev-tools
+
+Development tools for ng-craft: ESLint configs, ESLint rules, and codemods.
+
+## Installation
+
+### Depuis npm (après publication)
+
+```bash
+npm install -D @craft-ng/dev-tools
+```
+
+### Publication sur npm
+
+Pour publier le package sur npm (mainteneurs uniquement) :
+
+#### 1. Se connecter à npm
+
+```bash
+npm login
+```
+
+Vous aurez besoin d'un compte npm avec les droits de publication sur le scope `@craft-ng`.
+
+#### 2. Builder le package
+
+```bash
+npx nx build dev-tools
+```
+
+#### 3. Mettre à jour la version
+
+Modifiez la version dans `libs/dev-tools/package.json` selon [semver](https://semver.org/) :
+
+- **Patch** (0.1.0 → 0.1.1) : Corrections de bugs
+- **Minor** (0.1.0 → 0.2.0) : Nouvelles fonctionnalités rétrocompatibles
+- **Major** (0.1.0 → 1.0.0) : Changements non rétrocompatibles
+
+#### 4. Publier
+
+Depuis le répertoire de build :
+
+```bash
+cd dist/libs/dev-tools
+npm publish --access public
+```
+
+> **Note** : L'option `--access public` est nécessaire pour les packages scoped (`@craft-ng/...`) si vous souhaitez les rendre publics.
+
+#### 5. Créer un tag Git (recommandé)
+
+Retournez à la racine et créez un tag :
+
+```bash
+cd ../../..
+git tag dev-tools-v0.1.0
+git push origin dev-tools-v0.1.0
+```
+
+### En développement local (avant publication)
+
+Pour tester ce package dans un autre projet avant de le publier sur npm :
+
+#### 1. Builder le package
+
+Depuis la racine du monorepo ng-craft :
+
+```bash
+npx nx build dev-tools
+```
+
+Cela génère les fichiers compilés dans `dist/libs/dev-tools/`.
+
+#### 2. Créer un lien npm local
+
+Depuis la racine du monorepo :
+
+```bash
+cd dist/libs/dev-tools
+npm link
+```
+
+#### 3. Utiliser le lien dans votre autre projet
+
+Dans votre projet Angular externe :
+
+```bash
+cd /chemin/vers/votre-projet
+npm link @craft-ng/dev-tools
+```
+
+> **Note** : Après chaque modification du code de `@craft-ng/dev-tools`, vous devez rebuilder avec `npx nx build dev-tools` pour que les changements soient pris en compte dans les projets liés.
+
+#### 4. Supprimer le lien (quand terminé)
+
+Dans votre projet externe :
+
+```bash
+npm unlink @craft-ng/dev-tools
+npm install
+```
+
+## Configuration complète dans un nouveau projet
+
+Voici un exemple de configuration complète pour utiliser tous les outils dans un projet Angular :
+
+### 1. Installer les dépendances
+
+```bash
+npm install -D @craft-ng/dev-tools @craft-ng/core
+npm install -D @angular-eslint/eslint-plugin @typescript-eslint/eslint-plugin eslint
+```
+
+### 2. Configurer ESLint
+
+Créez ou modifiez `eslint.config.mjs` :
+
+```javascript
+import craftAngular from '@craft-ng/dev-tools/eslint/angular';
+import craftRules from '@craft-ng/dev-tools/eslint-rules';
+
+export default [
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+  ...craftAngular,
+  {
+    files: ['**/*.ts'],
+    plugins: {
+      '@craft-ng': craftRules,
+    },
+    rules: {
+      // Règles craft-ng recommandées
+      '@craft-ng/brand-angular-deps-match': 'error',
+      '@craft-ng/no-angular-inject': 'error',
+      '@craft-ng/no-direct-angular-class-export': 'error',
+    },
+  },
+];
+```
+
+### 3. Transformer votre code existant
+
+```bash
+# Prévisualiser les changements (dry-run)
+npx craft-brand --root ./src --dry-run
+
+# Appliquer les transformations
+npx craft-brand --root ./src
+```
+
+### 4. Ajouter des scripts npm
+
+Dans votre `package.json` :
+
+```json
+{
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "codemod:preview": "craft-brand --dry-run",
+    "codemod:apply": "craft-brand"
+  }
+}
+```
+
+## Features
+
+### 1. ESLint Configurations
+
+Pre-configured ESLint settings for ng-craft projects.
+
+#### Basic TypeScript Config
+
+```javascript
+// eslint.config.mjs
+import craftEslint from '@craft-ng/dev-tools/eslint';
+
+export default [...craftEslint];
+```
+
+#### Angular Config
+
+```javascript
+// eslint.config.mjs
+import craftAngular from '@craft-ng/dev-tools/eslint/angular';
+
+export default [...craftAngular];
+```
+
+### 2. ESLint Rules
+
+Custom ESLint rules for enforcing ng-craft patterns.
+
+#### Available Rules
+
+- **`brand-angular-deps-match`** - Ensures `deps({ injected, importDeps, providers })` matches the Angular symbol dependencies
+- **`no-angular-inject`** - Disallows Angular `inject()`, `@Injectable`, and `@Service` usage
+- **`no-direct-angular-class-export`** - Disallows direct exports of Angular symbols managed through `brandAngularSymbol`
+
+#### Usage
+
+```javascript
+// eslint.config.mjs
+import craftAngular from '@craft-ng/dev-tools/eslint/angular';
+import craftRules from '@craft-ng/dev-tools/eslint-rules';
+
+export default [
+  ...craftAngular,
+  {
+    plugins: {
+      '@craft-ng': craftRules,
+    },
+    rules: {
+      '@craft-ng/brand-angular-deps-match': 'error',
+      '@craft-ng/no-angular-inject': 'error',
+      '@craft-ng/no-direct-angular-class-export': 'error',
+    },
+  },
+];
+```
+
+### 3. Codemod: `craft-brand`
+
+Automatically transforms Angular components, directives, pipes, and injectables to use `brandAngularSymbol` and `deps()`.
+
+#### CLI Usage
+
+```bash
+# Transform all TypeScript files in the current directory
+npx craft-brand
+
+# Transform with specific root directory
+npx craft-brand --root ./src
+
+# Dry run (preview changes without writing)
+npx craft-brand --dry-run
+
+# Only transform standalone components/directives
+npx craft-brand --transform-only-standalone-declarables
+
+# Custom helper import path
+npx craft-brand --helper-import @my-lib/core
+
+# Use specific tsconfig
+npx craft-brand --tsconfig ./tsconfig.app.json
+```
+
+#### Programmatic Usage
+
+```typescript
+import { runAngularBrandCodemod } from '@craft-ng/dev-tools';
+
+await runAngularBrandCodemod({
+  rootDir: './src',
+  dryRun: true,
+  transformOnlyStandaloneDeclarables: false,
+  includeProviders: true,
+  includeViewProviders: true,
+  helperImportPath: '@craft-ng/core',
+  log: console.log,
+});
+```
+
+#### What it does
+
+Transforms this:
+
+```typescript
+import { Component, inject } from '@angular/core';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule],
+  providers: [MyService],
+})
+export class DemoComponent {
+  private api = inject(ApiService);
+  constructor(private http: HttpClient) {}
+}
+```
+
+Into this:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { brandAngularSymbol, deps } from '@craft-ng/core';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule],
+  providers: [MyService],
+})
+class DemoComponent {
+  private api = inject(ApiService);
+  constructor(private http: HttpClient) {}
+}
+
+export default brandAngularSymbol(
+  DemoComponent,
+  deps({
+    injected: [HttpClient, ApiService],
+    importDeps: [CommonModule],
+    providers: [MyService],
+  }),
+);
+```
+
+#### CLI Options
+
+| Option                                    | Description                                        | Default                |
+| ----------------------------------------- | -------------------------------------------------- | ---------------------- |
+| `--root <dir>`                            | Project root directory                             | `cwd`                  |
+| `--tsconfig <path>`                       | Path to tsconfig.json                              | `<root>/tsconfig.json` |
+| `--helper-import <path>`                  | Import path for `brandAngularSymbol` and `deps`    | `@craft-ng/core`       |
+| `--transform-only-standalone-declarables` | Only transform standalone components/directives    | `false`                |
+| `--no-providers`                          | Do not include metadata providers in `deps()`      | `false`                |
+| `--no-view-providers`                     | Do not include component viewProviders in `deps()` | `false`                |
+| `--dry-run`                               | Print results without writing files                | `false`                |
+| `--help`                                  | Show help                                          | -                      |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@craft-ng/dev-tools",
+  "version": "0.1.0",
+  "description": "Development tools for ng-craft: ESLint configs, ESLint rules, and codemods",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./eslint": "./src/eslint/index.mjs",
+    "./eslint/angular": "./src/eslint/angular.mjs",
+    "./eslint-rules": "./src/eslint-rules/index.cjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "craft-brand": "./src/bin/craft-brand.js"
+  },
+  "files": [
+    "src/**/*",
+    "README.md"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "ts-morph": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@angular-eslint/eslint-plugin": ">=21.0.0",
+    "@typescript-eslint/eslint-plugin": ">=8.0.0",
+    "eslint": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular-eslint/eslint-plugin": {
+      "optional": true
+    },
+    "@typescript-eslint/eslint-plugin": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "ng-craft",
+    "angular",
+    "codemod",
+    "eslint",
+    "eslint-config",
+    "eslint-plugin",
+    "typescript"
+  ],
+  "module": "./src/index.js"
+}

package/src/bin/craft-brand.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/bin/craft-brand.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runAngularBrandCodemod } from '../scripts/angular-brand-codemod.js';
+runAngularBrandCodemod({
+    log: console.log,
+}).catch((error) => {
+    console.error('Error running codemod:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=craft-brand.js.map

package/src/bin/craft-brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-brand.js","sourceRoot":"","sources":["../../../../../libs/dev-tools/src/bin/craft-brand.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,sBAAsB,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC,GAAG;CACjB,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/src/eslint/angular.mjs

@@ -0,0 +1,26 @@
+import baseConfig from './index.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'app',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'app',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+];

package/src/eslint/index.mjs

@@ -0,0 +1,18 @@
+export default [
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+      'no-empty-object-type': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unsafe-function-type': 'off',
+    },
+  },
+];

package/src/eslint-rules/brand-angular-deps-match.cjs

@@ -0,0 +1,193 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { Project } = require('ts-morph');
+const {
+  analyzeSourceFileDependencies,
+  readExistingDependencyGroups,
+} = require('../scripts/angular-brand-codemod.js');
+
+const projectCache = new Map();
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure deps({ injected, importDeps, providers }) matches the Angular symbol dependencies.',
+    },
+    schema: [],
+  },
+  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();
+        if (!text.includes('brandAngularSymbol') || !text.includes('deps(')) {
+          return;
+        }
+
+        const sourceFile = getProjectSourceFile(
+          getProject(getCwd(context)),
+          filePath,
+          text,
+        );
+        const analysis = analyzeSourceFileDependencies(sourceFile);
+        if (
+          !analysis.classDeclaration ||
+          analysis.skipped ||
+          !analysis.className
+        ) {
+          return;
+        }
+
+        const existing = readExistingDependencyGroups(
+          sourceFile,
+          analysis.className,
+        );
+        if (!existing.found) {
+          return;
+        }
+
+        if (existing.warnings.length > 0) {
+          for (const warning of existing.warnings) {
+            reportNode(
+              context,
+              sourceCode,
+              existing.depsObjectNode ?? existing.exportAssignmentNode,
+              warning,
+            );
+          }
+          return;
+        }
+
+        reportIfMismatch(
+          context,
+          sourceCode,
+          existing,
+          'injected',
+          analysis.dependencyGroups.injected,
+          existing.dependencyGroups.injected,
+        );
+        reportIfMismatch(
+          context,
+          sourceCode,
+          existing,
+          'importDeps',
+          analysis.dependencyGroups.importDeps,
+          existing.dependencyGroups.importDeps,
+        );
+        reportIfMismatch(
+          context,
+          sourceCode,
+          existing,
+          'providers',
+          analysis.dependencyGroups.providers,
+          existing.dependencyGroups.providers,
+        );
+      },
+    };
+  },
+};
+
+function getProject(cwd) {
+  let project = projectCache.get(cwd);
+  if (project) {
+    return project;
+  }
+
+  const tsConfigFilePath = path.join(cwd, 'tsconfig.json');
+  project = fs.existsSync(tsConfigFilePath)
+    ? new Project({ tsConfigFilePath })
+    : new Project({
+        compilerOptions: {
+          experimentalDecorators: true,
+          target: 9,
+        },
+      });
+
+  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();
+}
+
+function reportIfMismatch(
+  context,
+  sourceCode,
+  existing,
+  propertyName,
+  expected,
+  actual,
+) {
+  if (isSameDependencyList(expected, actual)) {
+    return;
+  }
+
+  reportNode(
+    context,
+    sourceCode,
+    existing.propertyNodes[propertyName] ??
+      existing.depsObjectNode ??
+      existing.exportAssignmentNode,
+    `deps.${propertyName} does not match the Angular symbol. Expected ${formatDependencyList(expected)} but found ${formatDependencyList(actual)}.`,
+  );
+}
+
+function reportNode(context, sourceCode, node, message) {
+  context.report({
+    loc: node ? getNodeLoc(sourceCode, node) : undefined,
+    message,
+  });
+}
+
+function getNodeLoc(sourceCode, node) {
+  return {
+    start: sourceCode.getLocFromIndex(node.getStart()),
+    end: sourceCode.getLocFromIndex(node.getEnd()),
+  };
+}
+
+function isSameDependencyList(left, right) {
+  return (
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  );
+}
+
+function formatDependencyList(dependencies) {
+  return `[${dependencies.join(', ')}]`;
+}

package/src/eslint-rules/index.cjs

@@ -0,0 +1,12 @@
+// ESLint rules for ng-craft
+const brandAngularDepsMatch = require('./brand-angular-deps-match.cjs');
+const noAngularInject = require('./no-angular-inject.cjs');
+const noDirectAngularClassExport = require('./no-direct-angular-class-export.cjs');
+
+module.exports = {
+  rules: {
+    'brand-angular-deps-match': brandAngularDepsMatch,
+    'no-angular-inject': noAngularInject,
+    'no-direct-angular-class-export': noDirectAngularClassExport,
+  },
+};