@craft-ng/dev-tools 0.5.1-beta.0 → 0.6.0-beta.2

package/src/eslint-rules/craft-name-match-utils.cjs

@@ -0,0 +1,179 @@
+function createNameMatchRule({
+  calleeName,
+  description,
+  supportsObjectConfigForm = false,
+}) {
+  return {
+    meta: {
+      type: 'problem',
+      docs: { description },
+      fixable: 'code',
+      schema: [],
+      messages: {
+        missingName: `${calleeName} must be called with a string literal name matching '{{declaredName}}' as the first argument.`,
+        mismatchedName: `${calleeName} first argument '{{actual}}' must match the declared name '{{declaredName}}'.`,
+      },
+    },
+    create(context) {
+      const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+      return {
+        CallExpression(node) {
+          if (
+            node.callee.type !== 'Identifier' ||
+            node.callee.name !== calleeName
+          ) {
+            return;
+          }
+
+          const declaredName = getDeclaredName(node);
+          if (!declaredName) {
+            return;
+          }
+
+          const firstArg = node.arguments[0];
+
+          if (!firstArg) {
+            context.report({
+              node,
+              messageId: 'missingName',
+              data: { declaredName },
+              fix(fixer) {
+                const openParen = sourceCode.getTokenAfter(
+                  node.callee,
+                  (token) => token.type === 'Punctuator' && token.value === '(',
+                );
+                if (!openParen) return null;
+                return fixer.insertTextAfter(openParen, `'${declaredName}'`);
+              },
+            });
+            return;
+          }
+
+          if (supportsObjectConfigForm && firstArg.type === 'ObjectExpression') {
+            const nameProp = firstArg.properties.find(
+              (p) =>
+                p.type === 'Property' &&
+                !p.computed &&
+                p.key.type === 'Identifier' &&
+                p.key.name === 'name',
+            );
+            if (!nameProp) {
+              context.report({
+                node: firstArg,
+                messageId: 'missingName',
+                data: { declaredName },
+              });
+              return;
+            }
+            const nameValue = nameProp.value;
+            if (isStringLiteral(nameValue)) {
+              const actual = getStringLiteralValue(nameValue);
+              if (actual === declaredName) {
+                return;
+              }
+              context.report({
+                node: nameValue,
+                messageId: 'mismatchedName',
+                data: { declaredName, actual },
+                fix(fixer) {
+                  return fixer.replaceText(nameValue, `'${declaredName}'`);
+                },
+              });
+            } else {
+              context.report({
+                node: nameValue,
+                messageId: 'mismatchedName',
+                data: { declaredName, actual: sourceCode.getText(nameValue) },
+              });
+            }
+            return;
+          }
+
+          if (isStringLiteral(firstArg)) {
+            const actual = getStringLiteralValue(firstArg);
+            if (actual === declaredName) {
+              return;
+            }
+            context.report({
+              node: firstArg,
+              messageId: 'mismatchedName',
+              data: { declaredName, actual },
+              fix(fixer) {
+                return fixer.replaceText(firstArg, `'${declaredName}'`);
+              },
+            });
+            return;
+          }
+
+          context.report({
+            node: firstArg,
+            messageId: 'missingName',
+            data: { declaredName },
+            fix(fixer) {
+              return fixer.insertTextBefore(firstArg, `'${declaredName}', `);
+            },
+          });
+        },
+      };
+    },
+  };
+}
+
+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;
+  }
+
+  if (
+    parent.type === 'Property' &&
+    parent.value === callNode &&
+    !parent.computed &&
+    parent.key.type === 'Identifier' &&
+    parent.parent &&
+    parent.parent.type === 'ObjectExpression'
+  ) {
+    return parent.key.name;
+  }
+
+  return undefined;
+}
+
+function isStringLiteral(node) {
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    return true;
+  }
+  if (
+    node.type === 'TemplateLiteral' &&
+    node.expressions.length === 0 &&
+    node.quasis.length === 1
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function getStringLiteralValue(node) {
+  if (node.type === 'Literal') {
+    return node.value;
+  }
+  return node.quasis[0].value.cooked;
+}
+
+module.exports = { createNameMatchRule };

package/src/eslint-rules/craft-signal-source-name-match.cjs

@@ -0,0 +1,8 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+module.exports = createNameMatchRule({
+  calleeName: 'signalSource',
+  description:
+    "Ensure signalSource(name, ...) is called with a string literal first argument that matches the declared variable, class property, or object property name.",
+  supportsObjectConfigForm: false,
+});

package/src/eslint-rules/craft-source-name-match.cjs

@@ -0,0 +1,8 @@
+const { createNameMatchRule } = require('./craft-name-match-utils.cjs');
+
+module.exports = createNameMatchRule({
+  calleeName: 'source$',
+  description:
+    "Ensure source$(name) is called with a string literal first argument that matches the declared variable, class property, or object property name.",
+  supportsObjectConfigForm: false,
+});

package/src/eslint-rules/global-exception-registry-match.cjs

@@ -30,8 +30,12 @@ module.exports = {
         }
 
         const text = sourceCode.getText();
-        // Cheap pre-filter: the delegated outcome must appear.
-        if (!text.includes('globalError')) {
+        // Cheap pre-filter: either a delegated outcome (`globalError()`) that must
+        // be registered, or an existing registry that may now hold orphaned entries.
+        if (
+          !text.includes('globalError') &&
+          !text.includes('CraftGlobalExceptionRegistry')
+        ) {
           return;
         }
 
@@ -41,7 +45,11 @@ module.exports = {
           text,
         );
         const requiredRegistrations = collectRequiredRegistrations(sourceFile);
-        if (requiredRegistrations.length === 0) {
+        // Nothing to register AND no registry to prune → nothing to do.
+        if (
+          requiredRegistrations.length === 0 &&
+          !getGlobalRegistryInterface(sourceFile)
+        ) {
           return;
         }
 
@@ -51,19 +59,25 @@ module.exports = {
         );
         if (
           registryState.missing.length === 0 &&
-          registryState.outOfDate.length === 0
+          registryState.outOfDate.length === 0 &&
+          registryState.orphaned.length === 0
         ) {
           return;
         }
 
+        // Capture the report location BEFORE mutating: purging an orphaned entry
+        // removes its node, so `reportNode.getStart()` would throw afterwards.
+        const reportLoc = getNodeLoc(sourceCode, registryState.reportNode);
+
         ensureRegistryEntries(sourceFile, requiredRegistrations);
+        removeOrphanedRegistryEntries(sourceFile, requiredRegistrations);
         const fixedText = sourceFile.getFullText();
         if (fixedText === text) {
           return;
         }
 
         context.report({
-          loc: getNodeLoc(sourceCode, registryState.reportNode),
+          loc: reportLoc,
           message: formatRegistryMessage(registryState),
           fix(fixer) {
             return fixer.replaceTextRange([0, text.length], fixedText);
@@ -369,8 +383,9 @@ function analyzeRegistryState(sourceFile, requiredRegistrations) {
 
   const missing = [];
   const outOfDate = [];
+  const requiredByPath = groupByPath(requiredRegistrations);
 
-  for (const [routePath, entries] of groupByPath(requiredRegistrations)) {
+  for (const [routePath, entries] of requiredByPath) {
     const property = propertiesByName.get(routePath);
     if (!property) {
       missing.push(routePath);
@@ -383,11 +398,47 @@ function analyzeRegistryState(sourceFile, requiredRegistrations) {
     }
   }
 
-  return {
-    missing,
-    outOfDate,
-    reportNode: requiredRegistrations[0].reportNode,
-  };
+  // Orphaned: a registry entry whose route path no longer delegates any code to
+  // `globalError()` (the guard/handler was refactored, or the route removed).
+  // Such an entry resolves `CraftRouteExceptionType<…>` to `never`, silently
+  // collapsing `CraftGlobalHandledException` for every consumer.
+  const orphaned = [];
+  for (const routePath of propertiesByName.keys()) {
+    if (!requiredByPath.has(routePath)) {
+      orphaned.push(routePath);
+    }
+  }
+
+  // With no globalError() route left, the report anchors on the first orphaned
+  // registry property (falling back to the interface itself).
+  const reportNode =
+    requiredRegistrations[0]?.reportNode ??
+    (orphaned.length > 0
+      ? propertiesByName.get(orphaned[0])
+      : registryInterface);
+
+  return { missing, outOfDate, orphaned, reportNode };
+}
+
+function removeOrphanedRegistryEntries(sourceFile, requiredRegistrations) {
+  const registryInterface = getGlobalRegistryInterface(sourceFile);
+  if (!registryInterface) {
+    return;
+  }
+
+  const requiredPaths = new Set(
+    requiredRegistrations.map((registration) => registration.path),
+  );
+  for (const property of registryInterface.getProperties()) {
+    if (!requiredPaths.has(readInterfacePropertyName(property))) {
+      property.remove();
+    }
+  }
+
+  // Deliberately keep an emptied `interface CraftGlobalExceptionRegistry {}`
+  // rather than deleting the interface / `declare module` block: the block may
+  // carry sibling augmentations (e.g. CraftRouterRoutesRegistry) or leading
+  // documentation, and an empty registry is valid + stable (no re-report).
 }
 
 // A file may have several `declare module '@craft-ng/core'` blocks (e.g. one for
@@ -468,7 +519,7 @@ function getNodeLoc(sourceCode, node) {
   };
 }
 
-function formatRegistryMessage({ missing, outOfDate }) {
+function formatRegistryMessage({ missing, outOfDate, orphaned }) {
   const segments = [];
   if (missing.length > 0) {
     segments.push(`missing ${formatNameList(missing)}`);
@@ -476,6 +527,9 @@ function formatRegistryMessage({ missing, outOfDate }) {
   if (outOfDate.length > 0) {
     segments.push(`out of date for ${formatNameList(outOfDate)}`);
   }
+  if (orphaned.length > 0) {
+    segments.push(`orphaned for ${formatNameList(orphaned)}`);
+  }
   return `CraftGlobalExceptionRegistry is ${segments.join(' and ')}. Run ESLint --fix on this file to register globalError() route exceptions.`;
 }
 
@@ -492,6 +546,17 @@ function formatNameList(names) {
     .join(', ')}, and '${names[names.length - 1]}'`;
 }
 
+// Compares two type strings for equality up to Prettier's formatting freedom.
+// The rule emits the type on one line, but Prettier re-wraps long entries across
+// lines — which introduces spaces around `<`/`>`/`,` and a trailing `;` before the
+// closing brace. Collapsing whitespace alone would leave those, so the comparison
+// would flip to "out of date" and fight Prettier forever. We additionally strip
+// spaces adjacent to punctuation (keeping token boundaries like `typeof demoRoutes`
+// intact) and drop a member-terminating `;` right before a `}`.
 function normalizeText(text) {
-  return text.replace(/\s+/g, ' ').trim();
+  return text
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([<>(),;])\s*/g, '$1')
+    .replace(/;(?=}|$)/g, '')
+    .trim();
 }

package/src/eslint-rules/index.cjs

@@ -5,6 +5,8 @@ const globalExceptionRegistryMatch = require('./global-exception-registry-match.
 const componentTestGenDepsMatch = require('./component-test-gen-deps-match.cjs');
 const craftMethodNameMatch = require('./craft-method-name-match.cjs');
 const craftComputedNameMatch = require('./craft-computed-name-match.cjs');
+const craftSourceNameMatch = require('./craft-source-name-match.cjs');
+const craftSignalSourceNameMatch = require('./craft-signal-source-name-match.cjs');
 const preferCraftComputed = require('./prefer-craft-computed.cjs');
 const preferCraftState = require('./prefer-craft-state.cjs');
 const preferCraftEffect = require('./prefer-craft-effect.cjs');
@@ -15,7 +17,7 @@ const preferCraftHttpClient = require('./prefer-craft-http-client.cjs');
 const preferCraftService = require('./prefer-craft-service.cjs');
 const preferBrowserBoundaries = require('./prefer-browser-boundaries.cjs');
 const requireComponentMonitoring = require('./require-component-monitoring.cjs');
-const requireTrackOnDependentPrimitives = require('./require-track-on-dependent-primitives.cjs');
+const requirePrimitiveGeneratorUnwrap = require('./require-primitive-generator-unwrap.cjs');
 const requireAssertExhaustiveRouteExceptions = require('./require-assert-exhaustive-route-exceptions.cjs');
 const preferCraftRouterOutlet = require('./prefer-craft-router-outlet.cjs');
 const requirePendingComponentDiCheck = require('./require-pending-component-di-check.cjs');
@@ -23,6 +25,7 @@ const requireCraftExceptionHandler = require('./require-craft-exception-handler.
 const requireExceptionComponentDiCheck = require('./require-exception-component-di-check.cjs');
 const requireChildRouteMountCheck = require('./require-child-route-mount-check.cjs');
 const requireLazyLoadWithRetry = require('./require-lazy-load-with-retry.cjs');
+const requireCascadeRouteDiCheck = require('./require-cascade-route-di-check.cjs');
 
 module.exports = {
   rules: {
@@ -33,6 +36,8 @@ module.exports = {
     'component-test-gen-deps-match': componentTestGenDepsMatch,
     'craft-method-name-match': craftMethodNameMatch,
     'craft-computed-name-match': craftComputedNameMatch,
+    'craft-source-name-match': craftSourceNameMatch,
+    'craft-signal-source-name-match': craftSignalSourceNameMatch,
     'prefer-craft-computed': preferCraftComputed,
     'prefer-craft-state': preferCraftState,
     'prefer-craft-effect': preferCraftEffect,
@@ -43,7 +48,7 @@ module.exports = {
     'prefer-craft-service': preferCraftService,
     'prefer-browser-boundaries': preferBrowserBoundaries,
     'require-component-monitoring': requireComponentMonitoring,
-    'require-track-on-dependent-primitives': requireTrackOnDependentPrimitives,
+    'require-primitive-generator-unwrap': requirePrimitiveGeneratorUnwrap,
     'require-assert-exhaustive-route-exceptions':
       requireAssertExhaustiveRouteExceptions,
     'prefer-craft-router-outlet': preferCraftRouterOutlet,
@@ -52,5 +57,6 @@ module.exports = {
     'require-exception-component-di-check': requireExceptionComponentDiCheck,
     'require-child-route-mount-check': requireChildRouteMountCheck,
     'require-lazy-load-with-retry': requireLazyLoadWithRetry,
+    'require-cascade-route-di-check': requireCascadeRouteDiCheck,
   },
 };

package/src/eslint-rules/require-cascade-route-di-check.cjs

@@ -0,0 +1,223 @@
+'use strict';
+
+const {
+  IndentationText,
+  Node,
+  Project,
+  QuoteKind,
+  SyntaxKind,
+} = require('ts-morph');
+
+const CRAFT_MODULE = '@craft-ng/core';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require every craftRoutes collection to have a ValidateCascadeRoutesFile + CanRun DI check in the same file.',
+    },
+    fixable: 'code',
+    schema: [],
+  },
+  create(context) {
+    return {
+      'Program:exit'() {
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+        const text = sourceCode.getText();
+        if (!text.includes('craftRoutes(')) return;
+
+        const project = new Project({
+          useInMemoryFileSystem: true,
+          manipulationSettings: {
+            indentationText: IndentationText.TwoSpaces,
+            quoteKind: QuoteKind.Single,
+          },
+        });
+        const sourceFile = project.createSourceFile('/route-file.ts', text);
+        const collections = collectCollections(sourceFile);
+        if (collections.length === 0) return;
+
+        const cascadeChecks = collectCascadeChecks(sourceFile);
+        const canRunChecks = collectCanRunChecks(sourceFile);
+        const missing = collections.filter(({ routesName }) => {
+          const aliases = cascadeChecks.get(routesName) ?? [];
+          return (
+            aliases.length === 0 ||
+            !aliases.some((name) => canRunChecks.has(name))
+          );
+        });
+        if (missing.length === 0) return;
+        const reportLoc = nodeLocation(
+          sourceCode,
+          missing[0].call.getStart(),
+          missing[0].call.getWidth(),
+        );
+
+        for (const collection of missing) {
+          const suffix = toPascalCase(
+            collection.collectionName ||
+              collection.routesName.replace(/Routes$/, ''),
+          );
+          const existingChecks = cascadeChecks.get(collection.routesName) ?? [];
+          const checkName =
+            existingChecks[0] ??
+            uniqueTypeName(sourceFile, `_Check${suffix}DI`);
+          const canRunName = uniqueTypeName(sourceFile, `_CanRun${suffix}`);
+          if (existingChecks.length === 0) {
+            sourceFile.addTypeAlias({
+              name: checkName,
+              type: `ValidateCascadeRoutesFile<never, Router, typeof ${collection.routesName}>`,
+            });
+          }
+          sourceFile.addTypeAlias({
+            name: canRunName,
+            type: `CanRun<${checkName}>`,
+          });
+        }
+        if (
+          missing.some(
+            (collection) => !cascadeChecks.get(collection.routesName)?.length,
+          )
+        ) {
+          ensureNamedImport(
+            sourceFile,
+            'ValidateCascadeRoutesFile',
+            CRAFT_MODULE,
+            true,
+          );
+          ensureNamedImport(sourceFile, 'Router', '@angular/router', true);
+        }
+        ensureNamedImport(sourceFile, 'CanRun', CRAFT_MODULE, true);
+        sourceFile.formatText();
+
+        const fixedText = sourceFile.getFullText();
+        context.report({
+          loc: reportLoc,
+          message: `craftRoutes collection(s) missing a same-file ValidateCascadeRoutesFile + CanRun check: ${missing
+            .map((item) => item.routesName)
+            .join(', ')}`,
+          fix(fixer) {
+            return fixer.replaceTextRange([0, text.length], fixedText);
+          },
+        });
+      },
+    };
+  },
+};
+
+function collectCollections(sourceFile) {
+  const collections = [];
+  for (const call of sourceFile.getDescendantsOfKind(
+    SyntaxKind.CallExpression,
+  )) {
+    if (call.getExpression().getText() !== 'craftRoutes') continue;
+    const declaration = call.getFirstAncestorByKind(
+      SyntaxKind.VariableDeclaration,
+    );
+    const binding = declaration?.getNameNode();
+    if (!binding || !Node.isObjectBindingPattern(binding)) continue;
+    const firstArg = call.getArguments()[0];
+    const collectionName = Node.isStringLiteral(firstArg)
+      ? firstArg.getLiteralValue()
+      : '';
+    const expected = collectionName
+      ? `${uncapitalize(toPascalCase(collectionName))}Routes`
+      : '';
+    const routeElements = binding
+      .getElements()
+      .filter((element) =>
+        (
+          element.getPropertyNameNode()?.getText() ?? element.getName()
+        ).endsWith('Routes'),
+      );
+    const element =
+      routeElements.find(
+        (candidate) =>
+          (candidate.getPropertyNameNode()?.getText() ??
+            candidate.getName()) === expected,
+      ) ?? (routeElements.length === 1 ? routeElements[0] : undefined);
+    if (!element) continue;
+    collections.push({ collectionName, routesName: element.getName(), call });
+  }
+  return collections;
+}
+
+function collectCascadeChecks(sourceFile) {
+  const result = new Map();
+  for (const alias of sourceFile.getTypeAliases()) {
+    const typeNode = alias.getTypeNode();
+    if (!typeNode || !Node.isTypeReference(typeNode)) continue;
+    if (typeNode.getTypeName().getText() !== 'ValidateCascadeRoutesFile')
+      continue;
+    const routeType = typeNode.getTypeArguments()[2]?.getText() ?? '';
+    const match = /^typeof\s+([A-Za-z_$][\w$]*)$/.exec(routeType.trim());
+    if (!match) continue;
+    const aliases = result.get(match[1]) ?? [];
+    aliases.push(alias.getName());
+    result.set(match[1], aliases);
+  }
+  return result;
+}
+
+function collectCanRunChecks(sourceFile) {
+  const result = new Set();
+  for (const alias of sourceFile.getTypeAliases()) {
+    const typeNode = alias.getTypeNode();
+    if (!typeNode || !Node.isTypeReference(typeNode)) continue;
+    if (typeNode.getTypeName().getText() !== 'CanRun') continue;
+    const checked = typeNode.getTypeArguments()[0]?.getText();
+    if (checked) result.add(checked);
+  }
+  return result;
+}
+
+function ensureNamedImport(sourceFile, name, moduleSpecifier, typeOnly) {
+  const existing = sourceFile
+    .getImportDeclarations()
+    .find(
+      (declaration) =>
+        declaration.getModuleSpecifierValue() === moduleSpecifier,
+    );
+  if (existing) {
+    if (!existing.getNamedImports().some((item) => item.getName() === name)) {
+      existing.addNamedImport({
+        name,
+        isTypeOnly: typeOnly && !existing.isTypeOnly(),
+      });
+    }
+    return;
+  }
+  sourceFile.addImportDeclaration({
+    moduleSpecifier,
+    isTypeOnly: typeOnly,
+    namedImports: [name],
+  });
+}
+
+function uniqueTypeName(sourceFile, base) {
+  let name = base;
+  let index = 2;
+  while (sourceFile.getTypeAlias(name)) name = `${base}${index++}`;
+  return name;
+}
+
+function nodeLocation(sourceCode, start, width) {
+  const from = sourceCode.getLocFromIndex(start);
+  const to = sourceCode.getLocFromIndex(start + width);
+  return { start: from, end: to };
+}
+
+function toPascalCase(value) {
+  return (
+    value
+      .split(/[^A-Za-z0-9]+/)
+      .filter(Boolean)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join('') || 'Routes'
+  );
+}
+
+function uncapitalize(value) {
+  return value.charAt(0).toLowerCase() + value.slice(1);
+}