@craft-ts/dev-tools 0.7.0-beta.13

package/src/eslint-rules/require-component-monitoring.cjs

@@ -0,0 +1,212 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  IndentationText,
+  Project,
+  QuoteKind,
+  Scope,
+  SyntaxKind,
+} = require('ts-morph');
+
+const projectCache = new Map();
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Ensure Angular @Component and @Directive classes declare 'private readonly _monitoring = componentMonitoring()'.",
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      missingMonitoring:
+        "Component/Directive '{{className}}' must declare 'private readonly _monitoring = componentMonitoring()'.",
+    },
+  },
+  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('@Component') && !text.includes('@Directive')) {
+          return;
+        }
+
+        const sourceFile = getProjectSourceFile(
+          getProject(getCwd(context)),
+          filePath,
+          text,
+        );
+
+        const issues = collectMonitoringIssues(sourceFile);
+        if (issues.length === 0) {
+          return;
+        }
+
+        const reportLoc = getNodeLoc(sourceCode, issues[0].classDeclaration);
+
+        for (const issue of issues) {
+          applyMonitoringFix(issue);
+        }
+        ensureComponentMonitoringImport(sourceFile);
+
+        const fixedText = sourceFile.getFullText();
+        if (fixedText === text) {
+          return;
+        }
+
+        const classNames = issues.map((i) => i.className).join(', ');
+
+        context.report({
+          loc: reportLoc,
+          message: `Component(s) missing componentMonitoring(): ${classNames}`,
+          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 getNodeLoc(sourceCode, node) {
+  return {
+    start: sourceCode.getLocFromIndex(node.getStart()),
+    end: sourceCode.getLocFromIndex(node.getEnd()),
+  };
+}
+
+function isAngularComponentOrDirective(classDeclaration) {
+  for (const decorator of classDeclaration.getDecorators()) {
+    const name = decorator.getName();
+    if (name === 'Component' || name === 'Directive') {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasMonitoringProperty(classDeclaration) {
+  for (const prop of classDeclaration.getProperties()) {
+    if (
+      prop.getName() === '_monitoring' &&
+      prop.hasModifier(SyntaxKind.PrivateKeyword) &&
+      prop.isReadonly()
+    ) {
+      const initializer = prop.getInitializer();
+      if (
+        initializer &&
+        initializer.getKindName() === 'CallExpression' &&
+        initializer.getText().startsWith('componentMonitoring(')
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function collectMonitoringIssues(sourceFile) {
+  const issues = [];
+
+  for (const classDeclaration of sourceFile.getClasses()) {
+    const className = classDeclaration.getName();
+    if (!className) continue;
+    if (!isAngularComponentOrDirective(classDeclaration)) continue;
+    if (hasMonitoringProperty(classDeclaration)) continue;
+
+    issues.push({ className, classDeclaration });
+  }
+
+  return issues;
+}
+
+function applyMonitoringFix(issue) {
+  const { classDeclaration } = issue;
+
+  // Insert as first property of the class
+  classDeclaration.insertProperty(0, {
+    name: '_monitoring',
+    scope: Scope.Private,
+    isReadonly: true,
+    initializer: 'componentMonitoring()',
+  });
+}
+
+function ensureComponentMonitoringImport(sourceFile) {
+  const craftTsCoreImport = sourceFile
+    .getImportDeclarations()
+    .find((imp) => imp.getModuleSpecifierValue() === '@craft-ts/core');
+
+  if (craftTsCoreImport) {
+    const namedImports = craftTsCoreImport.getNamedImports();
+    const alreadyImported = namedImports.some(
+      (ni) => ni.getName() === 'componentMonitoring',
+    );
+    if (!alreadyImported) {
+      craftTsCoreImport.addNamedImport('componentMonitoring');
+    }
+  } else {
+    sourceFile.addImportDeclaration({
+      moduleSpecifier: '@craft-ts/core',
+      namedImports: ['componentMonitoring'],
+    });
+  }
+}

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-ts\/core['"]/g)?.join('\n') ??
+        '',
+    )
+  ) {
+    return text;
+  }
+  const pattern = /import\s*\{([\s\S]*?)\}\s*from\s*(['"]@craft-ts\/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-ts/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-craft-method-for-yieldable-callback.cjs

@@ -0,0 +1,236 @@
+const YIELDABLE_METHOD_NAME = 'YIELDABLE_METHOD';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require callbacks returned from a craftComponent factory to use craftMethod when they call yieldable Craft methods.',
+    },
+    schema: [],
+    messages: {
+      requireCraftMethod:
+        "Callback '{{name}}' calls a yieldable Craft method and must be created with `craftMethod(...)`.",
+      missingTypeInfo:
+        'This rule requires TypeScript type information to identify yieldable Craft methods.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const parserServices = sourceCode.parserServices ?? context.parserServices;
+    const checker = parserServices?.program?.getTypeChecker?.();
+    const esTreeNodeToTSNodeMap = parserServices?.esTreeNodeToTSNodeMap;
+    let reportedMissingTypeInfo = false;
+
+    return {
+      Program() {
+        if (!checker || !esTreeNodeToTSNodeMap) {
+          context.report({
+            node: sourceCode.ast,
+            messageId: 'missingTypeInfo',
+          });
+          reportedMissingTypeInfo = true;
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          reportedMissingTypeInfo ||
+          !checker ||
+          !esTreeNodeToTSNodeMap ||
+          node.callee.type !== 'Identifier' ||
+          node.callee.name !== 'craftComponent' ||
+          node.arguments.length < 4
+        ) {
+          return;
+        }
+
+        inspectFactory(node.arguments[2]);
+      },
+    };
+
+    function inspectFactory(factory) {
+      const localFunctions = collectLocalFunctions(factory);
+      const returnedObject = findReturnedObject(factory);
+
+      if (!returnedObject) return;
+
+      for (const property of returnedObject.properties) {
+        if (property.type !== 'Property') continue;
+
+        const callback = resolveCallback(property.value, localFunctions);
+        if (!callback) continue;
+
+        const yieldableCalls = [];
+        walkFunctionBody(callback, (node) => {
+          if (node.type === 'CallExpression' && isDirectYieldableCall(node)) {
+            yieldableCalls.push(node);
+          }
+        });
+
+        if (yieldableCalls.length === 0) continue;
+
+        context.report({
+          node: callback,
+          messageId: 'requireCraftMethod',
+          data: { name: getPropertyName(property) },
+        });
+      }
+    }
+
+    function collectLocalFunctions(factory) {
+      const localFunctions = new Map();
+      if (!factory) return localFunctions;
+
+      if (
+        factory.type === 'ArrowFunctionExpression' &&
+        factory.body.type === 'ObjectExpression'
+      ) {
+        return localFunctions;
+      }
+
+      walkFunctionBody(factory.body, (node) => {
+        if (node.type === 'FunctionDeclaration' && node.id) {
+          localFunctions.set(node.id.name, node);
+          return 'skip';
+        }
+
+        if (
+          node.type === 'VariableDeclarator' &&
+          node.id.type === 'Identifier' &&
+          node.init &&
+          isFunctionNode(node.init)
+        ) {
+          localFunctions.set(node.id.name, node.init);
+        }
+      });
+
+      return localFunctions;
+    }
+
+    function findReturnedObject(factory) {
+      if (!factory) return undefined;
+
+      if (
+        factory.type === 'ArrowFunctionExpression' &&
+        factory.body.type === 'ObjectExpression'
+      ) {
+        return factory.body;
+      }
+
+      let returnedObject;
+      walkFunctionBody(factory.body, (node) => {
+        if (
+          !returnedObject &&
+          node.type === 'ReturnStatement' &&
+          node.argument?.type === 'ObjectExpression'
+        ) {
+          returnedObject = node.argument;
+          return 'skip';
+        }
+      });
+
+      return returnedObject;
+    }
+
+    function resolveCallback(value, localFunctions) {
+      if (isFunctionNode(value)) {
+        return value;
+      }
+
+      if (value?.type === 'Identifier') {
+        return localFunctions.get(value.name);
+      }
+
+      return undefined;
+    }
+
+    function isDirectYieldableCall(node) {
+      const tsNode = esTreeNodeToTSNodeMap.get(node.callee);
+      if (!tsNode) return false;
+
+      const calleeType = checker.getTypeAtLocation(tsNode);
+      if (hasYieldableBrand(calleeType, new Set())) {
+        return true;
+      }
+
+      const signature = calleeType.getCallSignatures?.()[0];
+      return signature ? returnsGenerator(signature.getReturnType()) : false;
+    }
+
+    function hasYieldableBrand(type, seen) {
+      if (!type || seen.has(type)) return false;
+      seen.add(type);
+
+      if (type.isUnion?.() || type.isIntersection?.()) {
+        return type.types.some((part) => hasYieldableBrand(part, seen));
+      }
+
+      return checker
+        .getPropertiesOfType(type)
+        .some((property) =>
+          String(property.escapedName).includes(YIELDABLE_METHOD_NAME),
+        );
+    }
+
+    function returnsGenerator(type) {
+      const symbol = type.aliasSymbol ?? type.getSymbol?.();
+      const name = symbol && String(symbol.escapedName ?? symbol.name);
+      if (name === 'Generator' || name === 'YieldableInvocation') {
+        return true;
+      }
+
+      if (type.isUnion?.()) {
+        return type.types.every((part) => returnsGenerator(part));
+      }
+
+      return (
+        checker
+          .getPropertiesOfType(type)
+          .some((property) => property.name === 'next') &&
+        checker
+          .getPropertiesOfType(type)
+          .some((property) => property.name === 'return')
+      );
+    }
+
+    function getPropertyName(property) {
+      if (property.key.type === 'Identifier') return property.key.name;
+      if (property.key.type === 'Literal') return String(property.key.value);
+      return '<anonymous>';
+    }
+
+    function walkFunctionBody(node, visit) {
+      walk(node, (child) => {
+        if (child !== node && isFunctionNode(child)) {
+          return 'skip';
+        }
+        return visit(child);
+      });
+    }
+
+    function walk(node, visit) {
+      if (!node || typeof node.type !== 'string') return;
+      if (visit(node) === 'skip') return;
+
+      const keys = sourceCode.visitorKeys[node.type] ?? [];
+      for (const key of keys) {
+        const child = node[key];
+        if (Array.isArray(child)) {
+          child.forEach((item) => walk(item, visit));
+        } else {
+          walk(child, visit);
+        }
+      }
+    }
+
+    function isFunctionNode(node) {
+      return (
+        node?.type === 'ArrowFunctionExpression' ||
+        node?.type === 'FunctionExpression' ||
+        node?.type === 'FunctionDeclaration'
+      );
+    }
+  },
+};