@craft-ng/dev-tools 0.5.0-beta.2 → 0.5.0-beta.4

package/src/eslint-rules/require-assert-exhaustive-route-exceptions.cjs

@@ -0,0 +1,259 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { IndentationText, Project, QuoteKind, SyntaxKind } = require('ts-morph');
+
+const projectCache = new Map();
+
+const ROUTES_FACTORY = 'craftRoutes';
+const ASSERT_FN = 'assertExhaustiveRouteExceptions';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Ensure every craftRoutes(...) collection is checked with assertExhaustiveRouteExceptions(...) so a route's handleExceptions stays exhaustive over its reachable codes.",
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      missingAssert:
+        "craftRoutes collection '{{routesName}}' must be checked with assertExhaustiveRouteExceptions({{routesName}}).",
+    },
+  },
+  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(ROUTES_FACTORY)) {
+          return;
+        }
+
+        const sourceFile = getProjectSourceFile(
+          getProject(getCwd(context)),
+          filePath,
+          text,
+        );
+
+        const collections = collectRouteCollections(sourceFile);
+        if (collections.length === 0) {
+          return;
+        }
+
+        const asserted = collectAssertedNames(sourceFile);
+        const issues = collections.filter(
+          (collection) => !asserted.has(collection.routesName),
+        );
+        if (issues.length === 0) {
+          return;
+        }
+
+        const reportLoc = getNodeLoc(sourceCode, issues[0].callExpression);
+
+        // Insert bottom-up so earlier statement indices stay valid.
+        for (const issue of [...issues].sort(
+          (a, b) => b.statementIndex - a.statementIndex,
+        )) {
+          sourceFile.insertStatements(
+            issue.statementIndex + 1,
+            `${ASSERT_FN}(${issue.routesName});`,
+          );
+        }
+        ensureAssertImport(sourceFile);
+
+        const fixedText = sourceFile.getFullText();
+        if (fixedText === text) {
+          return;
+        }
+
+        const routesNames = issues.map((i) => i.routesName).join(', ');
+
+        context.report({
+          loc: reportLoc,
+          message: `craftRoutes collection(s) missing ${ASSERT_FN}(): ${routesNames}`,
+          fix(fixer) {
+            return fixer.replaceTextRange([0, text.length], fixedText);
+          },
+        });
+      },
+    };
+  },
+};
+
+function collectRouteCollections(sourceFile) {
+  const collections = [];
+
+  for (const call of sourceFile.getDescendantsOfKind(
+    SyntaxKind.CallExpression,
+  )) {
+    if (call.getExpression().getText() !== ROUTES_FACTORY) {
+      continue;
+    }
+
+    const routesName = getRoutesBindingName(call);
+    if (!routesName) {
+      continue;
+    }
+
+    const statement = call.getFirstAncestorByKind(
+      SyntaxKind.VariableStatement,
+    );
+    if (!statement || statement.getParent() !== sourceFile) {
+      // Only top-level `const { xRoutes } = craftRoutes(...)` declarations can
+      // be safely followed by a sibling assert statement.
+      continue;
+    }
+
+    collections.push({
+      routesName,
+      callExpression: call,
+      statementIndex: statement.getChildIndex(),
+    });
+  }
+
+  return collections;
+}
+
+// The routes object is destructured as `{ <name>Routes, inject... }`. Resolve
+// the local name bound to the `<name>Routes` property (honouring renames).
+function getRoutesBindingName(call) {
+  const declaration = call.getFirstAncestorByKind(
+    SyntaxKind.VariableDeclaration,
+  );
+  if (!declaration) {
+    return undefined;
+  }
+
+  const nameNode = declaration.getNameNode();
+  if (!nameNode || nameNode.getKind() !== SyntaxKind.ObjectBindingPattern) {
+    return undefined;
+  }
+
+  const elements = nameNode.getElements();
+  const firstArg = call.getArguments()[0];
+  const expectedProperty =
+    firstArg && firstArg.getKind() === SyntaxKind.StringLiteral
+      ? `${firstArg.getLiteralValue()}Routes`
+      : undefined;
+
+  if (expectedProperty) {
+    const match = elements.find(
+      (element) =>
+        (element.getPropertyNameNode()?.getText() ?? element.getName()) ===
+        expectedProperty,
+    );
+    if (match) {
+      return match.getName();
+    }
+  }
+
+  // Fallback: the single binding whose property name ends with `Routes`.
+  const routesElements = elements.filter((element) =>
+    (element.getPropertyNameNode()?.getText() ?? element.getName()).endsWith(
+      'Routes',
+    ),
+  );
+  return routesElements.length === 1 ? routesElements[0].getName() : undefined;
+}
+
+function collectAssertedNames(sourceFile) {
+  const asserted = new Set();
+
+  for (const call of sourceFile.getDescendantsOfKind(
+    SyntaxKind.CallExpression,
+  )) {
+    if (call.getExpression().getText() !== ASSERT_FN) {
+      continue;
+    }
+    const arg = call.getArguments()[0];
+    if (arg) {
+      asserted.add(arg.getText());
+    }
+  }
+
+  return asserted;
+}
+
+function ensureAssertImport(sourceFile) {
+  const craftNgCoreImport = sourceFile
+    .getImportDeclarations()
+    .find((imp) => imp.getModuleSpecifierValue() === '@craft-ng/core');
+
+  if (craftNgCoreImport) {
+    const alreadyImported = craftNgCoreImport
+      .getNamedImports()
+      .some((ni) => ni.getName() === ASSERT_FN);
+    if (!alreadyImported) {
+      craftNgCoreImport.addNamedImport(ASSERT_FN);
+    }
+  } else {
+    sourceFile.addImportDeclaration({
+      moduleSpecifier: '@craft-ng/core',
+      namedImports: [ASSERT_FN],
+    });
+  }
+}
+
+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()),
+  };
+}

package/src/eslint-rules/require-child-route-mount-check.cjs

@@ -0,0 +1,224 @@
+'use strict';
+
+// Parent-side companion to `.withParent<ParentRoutes<'path'>>()`.
+//
+// A `craftRoutes(...)` collection that mounts lazy children via
+// `loadChildren: () => import('./x').then((m) => m.xRoutes)` must be checked once
+// with `assertChildRouteMounts(xRoutes)`, so a `.withParent`-pinned child mounted
+// under the wrong route path becomes a compile error. This rule reports the
+// missing assert and, on `--fix`, inserts the call plus its import.
+//
+// Everything it needs lives in the same file (the collection binding), so the fix
+// is fully derivable and applied with surgical native-AST text insertions.
+
+const ROUTES_FACTORY = 'craftRoutes';
+const ASSERT_FN = 'assertChildRouteMounts';
+const CRAFT_MODULE = '@craft-ng/core';
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure every craftRoutes collection mounting lazy loadChildren is checked with assertChildRouteMounts(...).',
+    },
+    fixable: 'code',
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    const routesCalls = [];
+    const assertedArgs = new Set();
+    let craftImport = null;
+
+    return {
+      ImportDeclaration(node) {
+        if (
+          node.source.value === CRAFT_MODULE &&
+          node.importKind !== 'type' &&
+          !craftImport
+        ) {
+          craftImport = node;
+        }
+      },
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier') {
+          return;
+        }
+        if (node.callee.name === ROUTES_FACTORY) {
+          routesCalls.push(node);
+        } else if (node.callee.name === ASSERT_FN) {
+          const arg = node.arguments[0];
+          if (arg && arg.type === 'Identifier') {
+            assertedArgs.add(arg.name);
+          }
+        }
+      },
+      'Program:exit'() {
+        const fixes = [];
+        const missing = [];
+
+        for (const call of routesCalls) {
+          const collectionName = stringArg(call, 0);
+          const routesArray = call.arguments[1];
+          if (
+            collectionName === undefined ||
+            !routesArray ||
+            routesArray.type !== 'ArrayExpression'
+          ) {
+            continue;
+          }
+
+          if (!routesArray.elements.some(hasLazyLoadChildren)) {
+            continue;
+          }
+
+          const binding = resolveBindingName(call, collectionName);
+          if (!binding || assertedArgs.has(binding)) {
+            continue;
+          }
+
+          const statement = enclosingStatement(call);
+          if (!statement) {
+            continue;
+          }
+
+          fixes.push((fixer) =>
+            fixer.insertTextAfter(statement, `\n\n${ASSERT_FN}(${binding});`),
+          );
+          missing.push({ node: call, binding });
+        }
+
+        if (missing.length === 0) {
+          return;
+        }
+
+        if (!isAssertImported(craftImport)) {
+          fixes.push((fixer) => addAssertImport(fixer, sourceCode, craftImport));
+        }
+
+        context.report({
+          loc: missing[0].node.loc,
+          message: `craftRoutes collection(s) mounting lazy loadChildren must be checked with ${ASSERT_FN}(): ${missing
+            .map((m) => m.binding)
+            .join(', ')}`,
+          fix(fixer) {
+            return fixes.map((makeFix) => makeFix(fixer)).filter(Boolean);
+          },
+        });
+      },
+    };
+  },
+};
+
+// `{ …, loadChildren: () => import('./x').then((m) => m.xRoutes) }`
+function hasLazyLoadChildren(element) {
+  if (!element || element.type !== 'ObjectExpression') {
+    return false;
+  }
+  const loadChildren = findProperty(element, 'loadChildren');
+  return Boolean(loadChildren) && loadChildren.value.type === 'ArrowFunctionExpression';
+}
+
+function findProperty(objectExpression, name) {
+  return objectExpression.properties.find(
+    (property) =>
+      property.type === 'Property' &&
+      !property.computed &&
+      ((property.key.type === 'Identifier' && property.key.name === name) ||
+        (property.key.type === 'Literal' && property.key.value === name)),
+  );
+}
+
+function stringArg(call, index) {
+  const arg = call.arguments[index];
+  return arg && arg.type === 'Literal' && typeof arg.value === 'string'
+    ? arg.value
+    : undefined;
+}
+
+// The collection is destructured as `const { <name>Routes, inject... } = craftRoutes(...)`.
+function resolveBindingName(call, collectionName) {
+  const declarator = enclosingDeclarator(call);
+  if (!declarator || declarator.id.type !== 'ObjectPattern') {
+    return undefined;
+  }
+  const properties = declarator.id.properties.filter(
+    (property) => property.type === 'Property' && property.key.type === 'Identifier',
+  );
+
+  const expected = `${collectionName}Routes`;
+  const exact = properties.find((property) => property.key.name === expected);
+  if (exact && exact.value.type === 'Identifier') {
+    return exact.value.name;
+  }
+
+  const endingInRoutes = properties.filter((property) =>
+    property.key.name.endsWith('Routes'),
+  );
+  return endingInRoutes.length === 1 && endingInRoutes[0].value.type === 'Identifier'
+    ? endingInRoutes[0].value.name
+    : undefined;
+}
+
+function enclosingDeclarator(node) {
+  let current = node.parent;
+  while (current) {
+    if (current.type === 'VariableDeclarator') {
+      return current;
+    }
+    if (current.type === 'Program' || current.type === 'BlockStatement') {
+      return undefined;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
+// The top-level statement to append the assert after.
+function enclosingStatement(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'VariableDeclaration' &&
+      current.parent &&
+      (current.parent.type === 'Program' ||
+        current.parent.type === 'ExportNamedDeclaration')
+    ) {
+      return current.parent.type === 'ExportNamedDeclaration'
+        ? current.parent
+        : current;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
+function isAssertImported(craftImport) {
+  if (!craftImport) {
+    return false;
+  }
+  return craftImport.specifiers.some(
+    (specifier) =>
+      specifier.type === 'ImportSpecifier' &&
+      specifier.imported.name === ASSERT_FN,
+  );
+}
+
+function addAssertImport(fixer, sourceCode, craftImport) {
+  if (craftImport) {
+    const brace = sourceCode.getFirstToken(
+      craftImport,
+      (token) => token.value === '{',
+    );
+    if (brace) {
+      return fixer.insertTextAfter(brace, `\n  ${ASSERT_FN},`);
+    }
+  }
+  // No mergeable value import — add a fresh one at the top of the file.
+  return fixer.insertTextBeforeRange(
+    [0, 0],
+    `import { ${ASSERT_FN} } from '${CRAFT_MODULE}';\n`,
+  );
+}