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

package/README.md

@@ -10,6 +10,66 @@ Development tools for ng-craft: ESLint configs, ESLint rules, and codemods.
 npm install -D @craft-ng/dev-tools
 ```
 
+## Angular Brand Codemod Config
+
+`craft-brand` can load a typed project config from `craft-brand.config.ts`.
+
+```ts
+import { defineAngularBrandConfig } from '@craft-ng/dev-tools';
+
+export default defineAngularBrandConfig({
+  importAugmentations: [
+    {
+      match: {
+        module: '@ngx-translate/core',
+        symbols: ['TranslatePipe'],
+        metadata: ['imports'],
+      },
+      deps: [{ key: 'TranslateService', symbol: 'TranslateService' }],
+      missingProvider: [
+        { key: 'TranslateService', symbol: 'TranslateService' },
+      ],
+    },
+  ],
+});
+```
+
+Rule semantics:
+
+- `match.module`: module specifier to match
+- `match.symbols`: optional exported symbol names that trigger the rule
+- `match.metadata`: `imports` and/or `hostDirectives`
+- `deps`: synthetic entries added to generated `GenDeps`
+- `missingProvider`: synthetic entries added to generated `missingProvider`
+
+Entry semantics:
+
+- `key`: property name generated in `GenDeps`
+- `symbol`: imported type name used in the generated type
+- `module`: optional import source override, defaults to `match.module`
+
+Discovery behavior:
+
+- `craft-brand` auto-discovers `craft-brand.config.ts` by walking upward from `--root`
+- the ESLint rules `brand-angular-gen-deps-required` and `brand-angular-deps-match` use the same upward discovery from the analyzed file, bounded by `context.cwd`
+- `--config <path>` overrides auto-discovery for the CLI
+- `brand-angular-gen-deps-required` can generate a missing `GenDeps_*` alias in the current file
+- `brand-angular-deps-match` can autofix an existing `GenDeps_*` alias in the current file
+
+Current scope:
+
+- `TypeScript` config file only
+- declarative rules only
+- matching only from Angular `imports` and `hostDirectives`
+- no arbitrary `typeText` generation and no helper-local `typeof injectX` expressions
+
+Example CLI usage:
+
+```bash
+craft-brand --root apps/demo/src
+craft-brand --root apps/demo/src --config ./craft-brand.config.ts
+```
+
 ```bash
 import craftRules from '@craft-ng/dev-tools/eslint-rules';
 
@@ -19,9 +79,13 @@ export default [
       'craft-ng': craftRules
     },
     rules: {
+      // Adds a Quick Fix in VS Code through the ESLint extension
+      'craft-ng/brand-angular-gen-deps-required': 'error',
       'craft-ng/brand-angular-deps-match': 'error',
       'craft-ng/no-angular-inject': 'error',
-      'craft-ng/no-direct-angular-class-export': 'error',
+      'craft-ng/prefer-craft-service': 'error',
+      'craft-ng/prefer-craft-http-client': 'error',
+      'craft-ng/prefer-browser-boundaries': 'error',
     }
   }
 ];
@@ -61,10 +125,14 @@ module.exports = defineConfig([
         },
       ],
       '@typescript-eslint/consistent-type-definitions': 'off',
-      // Ajoutez vos règles craft-ng ici
+      // `brand-angular-gen-deps-required` generates missing GenDeps aliases with ESLint autofix
+      'craft-ng/brand-angular-gen-deps-required': 'error',
+      // `brand-angular-deps-match` refreshes existing GenDeps aliases with ESLint autofix
       'craft-ng/brand-angular-deps-match': 'error',
       'craft-ng/no-angular-inject': 'error',
-      'craft-ng/no-direct-angular-class-export': 'error',
+      'craft-ng/prefer-craft-service': 'error',
+      'craft-ng/prefer-craft-http-client': 'error',
+      'craft-ng/prefer-browser-boundaries': 'error',
     },
   },
   {
@@ -74,3 +142,28 @@ module.exports = defineConfig([
   },
 ]);
 ```
+
+## Editor / AI Refresh
+
+`GenDeps_* = GetDeps<...>` remains a source artifact generated in your `.ts` files.
+
+Use two refresh flows:
+
+- Current file without `GenDeps_*`: trigger the VS Code ESLint Quick Fix on `craft-ng/brand-angular-gen-deps-required`, or run `eslint --fix path/to/file.ts`
+- Current file with `GenDeps_*`: trigger the VS Code ESLint Quick Fix on `craft-ng/brand-angular-deps-match`, or run `eslint --fix path/to/file.ts`
+- Bulk refresh: run `craft-brand --root <source-root>`
+
+Recommended workflow:
+
+- after changing `inject(...)`, constructor injection, component `imports`, `providers`, or `viewProviders`, run the Quick Fix for the current file
+- when doing a larger refactor or upgrading a whole app/lib, run `craft-brand --root <source-root>`
+- when a browser API already exists in `@craft-ng/core/browser-boundaries`, enable `craft-ng/prefer-browser-boundaries` to prevent direct access to `window`, `document`, `localStorage`, `console`, and similar globals
+
+Notes:
+
+- the ESLint Quick Fix can generate a missing alias or refresh an existing one, but only for the current file
+- the same flow works well for AI agents: file-local updates via `eslint --fix`, bulk updates via `craft-brand --root`
+- `craft-ng/no-angular-inject` now targets raw Angular `inject()` only
+- `craft-ng/prefer-craft-service` forbids authored Angular `@Injectable()` / `@Service()` classes in favor of `craftService(...)`
+- `craft-ng/prefer-craft-http-client` forbids Angular `HttpClient` in favor of `CraftHttpClient`
+- `craft-ng/prefer-craft-service` and `craft-ng/prefer-craft-http-client` also expose a VS Code Quick Fix suggestion that inserts a temporary local disable comment annotated with the intended migration target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-ng/dev-tools",
-  "version": "0.1.9",
+  "version": "0.4.0-beta.1",
   "description": "Development tools for ng-craft: ESLint configs, ESLint rules, and codemods",
   "type": "module",
   "main": "./src/index.js",

package/src/eslint-rules/app-start-registry-match.cjs

@@ -0,0 +1,357 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  IndentationText,
+  Node,
+  Project,
+  QuoteKind,
+  SyntaxKind,
+} = require('ts-morph');
+
+const projectCache = new Map();
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure craftService definitions using onAppStart are registered in CraftAppStartRegistry.',
+    },
+    fixable: 'code',
+    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('onAppStart')) {
+          return;
+        }
+
+        const sourceFile = getProjectSourceFile(
+          getProject(getCwd(context)),
+          filePath,
+          text,
+        );
+        const requiredRegistrations = collectRequiredRegistrations(sourceFile);
+        if (requiredRegistrations.length === 0) {
+          return;
+        }
+
+        const registryState = analyzeRegistryState(
+          sourceFile,
+          requiredRegistrations,
+        );
+        if (
+          registryState.missing.length === 0 &&
+          registryState.outOfDate.length === 0
+        ) {
+          return;
+        }
+
+        ensureRegistryEntries(sourceFile, requiredRegistrations);
+        const fixedText = sourceFile.getFullText();
+        if (fixedText === text) {
+          return;
+        }
+
+        context.report({
+          loc: getNodeLoc(sourceCode, registryState.reportNode),
+          message: formatRegistryMessage(registryState),
+          fix(fixer) {
+            return fixer.replaceTextRange([0, text.length], fixedText);
+          },
+        });
+      },
+    };
+  },
+};
+
+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();
+}
+
+function collectRequiredRegistrations(sourceFile) {
+  const registrations = new Map();
+
+  for (const declaration of sourceFile.getVariableDeclarations()) {
+    const initializer = declaration.getInitializerIfKind(
+      SyntaxKind.CallExpression,
+    );
+    if (!initializer || getCallExpressionName(initializer) !== 'craftService') {
+      continue;
+    }
+
+    if (!containsOnAppStartCall(initializer)) {
+      continue;
+    }
+
+    const tag = readCraftServiceName(initializer);
+    const injectReference = readInjectReferenceName(declaration);
+    if (!tag || !injectReference || registrations.has(tag)) {
+      continue;
+    }
+
+    registrations.set(tag, {
+      tag,
+      injectReference,
+      reportNode: initializer,
+    });
+  }
+
+  return [...registrations.values()];
+}
+
+function getCallExpressionName(callExpression) {
+  const expression = callExpression.getExpression();
+  return Node.isIdentifier(expression) ? expression.getText() : undefined;
+}
+
+function containsOnAppStartCall(callExpression) {
+  return callExpression
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .some((innerCall) => getCallExpressionName(innerCall) === 'onAppStart');
+}
+
+function readCraftServiceName(callExpression) {
+  const [definitionArgument] = callExpression.getArguments();
+  if (
+    !definitionArgument ||
+    !Node.isObjectLiteralExpression(definitionArgument)
+  ) {
+    return undefined;
+  }
+
+  const nameProperty = definitionArgument
+    .getProperties()
+    .find(
+      (property) =>
+        Node.isPropertyAssignment(property) && property.getName() === 'name',
+    );
+  if (!nameProperty || !Node.isPropertyAssignment(nameProperty)) {
+    return undefined;
+  }
+
+  const initializer = nameProperty.getInitializer();
+  if (
+    !initializer ||
+    (!Node.isStringLiteral(initializer) &&
+      !Node.isNoSubstitutionTemplateLiteral(initializer))
+  ) {
+    return undefined;
+  }
+
+  return initializer.getLiteralText();
+}
+
+function readInjectReferenceName(declaration) {
+  const nameNode = declaration.getNameNode();
+  if (!Node.isObjectBindingPattern(nameNode)) {
+    return undefined;
+  }
+
+  const bindingElement =
+    nameNode
+      .getElements()
+      .find((element) =>
+        element.getNameNode().getText().startsWith('inject'),
+      ) ??
+    (nameNode.getElements().length === 1
+      ? nameNode.getElements()[0]
+      : undefined);
+
+  return bindingElement?.getNameNode().getText();
+}
+
+function analyzeRegistryState(sourceFile, requiredRegistrations) {
+  const moduleDeclaration = getCraftCoreModuleDeclaration(sourceFile);
+  const registryInterface = moduleDeclaration?.getInterface(
+    'CraftAppStartRegistry',
+  );
+  const propertiesByName = new Map(
+    (registryInterface?.getProperties() ?? []).map((property) => [
+      readPropertyName(property),
+      property,
+    ]),
+  );
+  const missing = [];
+  const outOfDate = [];
+
+  for (const registration of requiredRegistrations) {
+    const property = propertiesByName.get(registration.tag);
+    if (!property) {
+      missing.push(registration.tag);
+      continue;
+    }
+
+    const currentType = normalizeText(property.getTypeNode()?.getText() ?? '');
+    const expectedType = normalizeText(
+      `typeof ${registration.injectReference}`,
+    );
+    if (currentType !== expectedType) {
+      outOfDate.push(registration.tag);
+    }
+  }
+
+  return {
+    missing,
+    outOfDate,
+    reportNode: requiredRegistrations[0].reportNode,
+  };
+}
+
+function getCraftCoreModuleDeclaration(sourceFile) {
+  return sourceFile.getModules().find((moduleDeclaration) => {
+    const nameNode = moduleDeclaration.getNameNode();
+    return (
+      Node.isStringLiteral(nameNode) &&
+      nameNode.getLiteralText() === '@craft-ng/core'
+    );
+  });
+}
+
+function readPropertyName(property) {
+  const nameNode = property.getNameNode();
+  if (Node.isIdentifier(nameNode) || Node.isPrivateIdentifier(nameNode)) {
+    return nameNode.getText();
+  }
+
+  if (Node.isStringLiteral(nameNode) || Node.isNumericLiteral(nameNode)) {
+    return nameNode.getLiteralText();
+  }
+
+  return property.getName();
+}
+
+function ensureRegistryEntries(sourceFile, requiredRegistrations) {
+  const moduleDeclaration =
+    getCraftCoreModuleDeclaration(sourceFile) ??
+    sourceFile.addModule({
+      name: "'@craft-ng/core'",
+      hasDeclareKeyword: true,
+    });
+  const registryInterface =
+    moduleDeclaration.getInterface('CraftAppStartRegistry') ??
+    moduleDeclaration.addInterface({
+      name: 'CraftAppStartRegistry',
+    });
+  const propertiesByName = new Map(
+    registryInterface
+      .getProperties()
+      .map((property) => [readPropertyName(property), property]),
+  );
+
+  for (const registration of requiredRegistrations) {
+    const expectedType = `typeof ${registration.injectReference}`;
+    const property = propertiesByName.get(registration.tag);
+    if (!property) {
+      registryInterface.addProperty({
+        name: formatPropertyName(registration.tag),
+        type: expectedType,
+      });
+      continue;
+    }
+
+    property.setType(expectedType);
+  }
+}
+
+function formatPropertyName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : `'${name}'`;
+}
+
+function getNodeLoc(sourceCode, node) {
+  return {
+    start: sourceCode.getLocFromIndex(node.getStart()),
+    end: sourceCode.getLocFromIndex(node.getEnd()),
+  };
+}
+
+function formatRegistryMessage({ missing, outOfDate }) {
+  const segments = [];
+  if (missing.length > 0) {
+    segments.push(`missing ${formatNameList(missing)}`);
+  }
+
+  if (outOfDate.length > 0) {
+    segments.push(`out of date for ${formatNameList(outOfDate)}`);
+  }
+
+  return `CraftAppStartRegistry is ${segments.join(' and ')}. Run ESLint --fix on this file to register app-start services.`;
+}
+
+function formatNameList(names) {
+  if (names.length === 1) {
+    return names[0];
+  }
+
+  if (names.length === 2) {
+    return `${names[0]} and ${names[1]}`;
+  }
+
+  return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`;
+}
+
+function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim();
+}