@sfdc-webapps/cli 1.0.2

package/src/utils/route-merger.ts

@@ -0,0 +1,357 @@
+import * as logger from './logger.js';
+import { Project, ArrayLiteralExpression, SourceFile, Node } from 'ts-morph';
+import path from 'path';
+import { mergeImports } from './import-merger.js';
+
+// Simplified RouteObject type covering common react-router fields
+interface RouteObject {
+  path?: string;
+  index?: boolean;
+  children?: RouteObject[];
+  element?: any;
+  handle?: any;
+  loader?: any;
+  action?: any;
+  errorElement?: any;
+  [key: string]: any; // Allow additional properties
+}
+
+/**
+ * Route Merging Strategy: Replace-Matching with Deep Children Merge
+ *
+ * This function merges React Router routes from a feature into a base app using
+ * a "replace-matching" strategy with intelligent children array merging.
+ *
+ * ## How It Works:
+ *
+ * 1. **Top-Level Routes:**
+ *    - Routes with the SAME path → Merge their children arrays
+ *    - Routes with DIFFERENT paths → Add feature route to result
+ *
+ * 2. **Children Array Merging (when parent paths match):**
+ *    - Index routes (`index: true`) → Feature replaces base if both exist
+ *    - Named routes (`path: 'about'`) → Feature replaces base if paths match
+ *    - New routes → Added to children array
+ *    - Preserves base routes not in feature
+ *
+ * 3. **Route Deletion:**
+ *    - Routes with path starting with `__delete__` are deletion markers
+ *    - The route with matching path (without prefix) is removed from result
+ *    - Example: `{ path: '__delete__new' }` removes the route with `path: 'new'`
+ *
+ * 4. **Recursion:**
+ *    - Applies same logic to nested children arrays
+ *
+ * ## Example:
+ *
+ * **Base App Routes:**
+ * ```typescript
+ * [{
+ *   path: '/',
+ *   element: <AppLayout />,
+ *   children: [
+ *     { index: true, element: <Home /> }
+ *   ]
+ * }]
+ * ```
+ *
+ * **Feature Routes:**
+ * ```typescript
+ * [{
+ *   path: '/',
+ *   element: <AppLayout />,
+ *   children: [
+ *     { path: 'about', element: <About /> },
+ *     { path: 'contact', element: <Contact /> }
+ *   ]
+ * }]
+ * ```
+ *
+ * **Merged Result:**
+ * ```typescript
+ * [{
+ *   path: '/',
+ *   element: <AppLayout />,  // Uses feature's element
+ *   children: [
+ *     { index: true, element: <Home /> },       // Preserved from base
+ *     { path: 'about', element: <About /> },    // Added from feature
+ *     { path: 'contact', element: <Contact /> } // Added from feature
+ *   ]
+ * }]
+ * ```
+ *
+ * ## Deletion Example:
+ *
+ * **Base/Previous Routes:**
+ * ```typescript
+ * [{
+ *   path: '/',
+ *   children: [
+ *     { path: 'home', element: <Home /> },
+ *     { path: 'about', element: <About /> },
+ *     { path: 'new', element: <New /> }
+ *   ]
+ * }]
+ * ```
+ *
+ * **Feature Routes (deleting 'new'):**
+ * ```typescript
+ * [{
+ *   path: '/',
+ *   children: [
+ *     { path: '__delete__new', element: <></> }
+ *   ]
+ * }]
+ * ```
+ *
+ * **Merged Result:**
+ * ```typescript
+ * [{
+ *   path: '/',
+ *   children: [
+ *     { path: 'home', element: <Home /> },   // Preserved
+ *     { path: 'about', element: <About /> }  // Preserved
+ *     // 'new' route removed
+ *   ]
+ * }]
+ * ```
+ *
+ * @param featurePath - Path to the feature's routes.tsx file
+ * @param targetPath - Path to the base app's routes.tsx file
+ * @returns The merged routes source code
+ */
+export function mergeRoutes(
+  featurePath: string,
+  targetPath: string,
+  project?: Project
+): string {
+  try {
+    const proj = project || new Project();
+
+    const targetFile = project
+      ? proj.getSourceFile(targetPath) || proj.addSourceFileAtPath(path.resolve(targetPath))
+      : proj.addSourceFileAtPath(path.resolve(targetPath));
+
+    const featureFile = project
+      ? proj.getSourceFile(featurePath) || proj.addSourceFileAtPath(path.resolve(featurePath))
+      : proj.addSourceFileAtPath(path.resolve(featurePath));
+
+    // Get initial routes arrays to validate they exist
+    const initialTargetArray = getRoutesArrayLiteral(targetFile, 'routes');
+    const initialFeatureArray = getRoutesArrayLiteral(featureFile, 'routes');
+
+    if (!initialTargetArray) {
+      logger.warning('Could not extract routes array from target file');
+      return featureFile.getText();
+    }
+
+    if (!initialFeatureArray) {
+      logger.warning('Could not extract routes array from feature file');
+      return targetFile.getText();
+    }
+
+    // Merge imports from feature file into target file
+    // Note: This calls organizeImports() which invalidates AST node references
+    mergeImports(featureFile, targetFile);
+
+    // Re-get routes arrays after import merging (organizeImports invalidates previous references)
+    const targetArray = getRoutesArrayLiteral(targetFile, 'routes');
+    const featureArray = getRoutesArrayLiteral(featureFile, 'routes');
+
+    if (!targetArray || !featureArray) {
+      logger.error('Routes array was lost after import merging');
+      throw new Error('Failed to re-acquire routes arrays after import merging');
+    }
+
+    // Parse arrays to RouteObject[]
+    const targetRoutes = parseRoutesFromAST(targetArray);
+    const featureRoutes = parseRoutesFromAST(featureArray);
+
+    // Deep merge the routes
+    const mergedRoutes = deepMergeRoutes(targetRoutes, featureRoutes);
+
+    // Convert back to code and update the target
+    const mergedCode = generateRoutesCode(mergedRoutes);
+    targetArray.replaceWithText(mergedCode);
+
+    return targetFile.getText();
+  } catch (err) {
+    logger.error(`Route merge failed: ${err instanceof Error ? err.message : String(err)}`);
+    throw new Error('Failed to merge routes');
+  }
+}
+
+/**
+ * Get the array literal expression for the routes variable
+ */
+function getRoutesArrayLiteral(
+  file: SourceFile,
+  varName: string
+): ArrayLiteralExpression | undefined {
+  const variable = file.getVariableDeclaration(varName);
+
+  if (!variable) {
+    logger.warning(`Variable "${varName}" not found in ${file.getFilePath()}`);
+    return undefined;
+  }
+
+  const initializer = variable.getInitializer();
+
+  if (!initializer || !ArrayLiteralExpression.isArrayLiteralExpression(initializer)) {
+    logger.warning(`Variable "${varName}" is not initialized with an array literal`);
+    return undefined;
+  }
+
+  return initializer;
+}
+
+/**
+ * Parse routes from AST ArrayLiteralExpression to RouteObject[]
+ */
+function parseRoutesFromAST(arrayLiteral: ArrayLiteralExpression): RouteObject[] {
+  const routes: RouteObject[] = [];
+
+  for (const element of arrayLiteral.getElements()) {
+    if (Node.isObjectLiteralExpression(element)) {
+      const route: RouteObject = {};
+
+      for (const prop of element.getProperties()) {
+        if (Node.isPropertyAssignment(prop)) {
+          const name = prop.getName();
+          const initializer = prop.getInitializer();
+
+          if (!initializer) continue;
+
+          if (name === 'children' && Node.isArrayLiteralExpression(initializer)) {
+            // Recursively parse children
+            route.children = parseRoutesFromAST(initializer);
+          } else {
+            // Store the raw text for other properties
+            route[name] = initializer.getText();
+          }
+        }
+      }
+
+      routes.push(route);
+    }
+  }
+
+  return routes;
+}
+
+/**
+ * Deep merge two route arrays
+ * - Routes are matched by path equality
+ * - Feature routes replace target routes with the same path
+ * - Children arrays are recursively merged
+ * - All properties from feature route are preserved
+ * - Routes with path starting with '__delete__' are deletion markers
+ */
+function deepMergeRoutes(targetRoutes: RouteObject[], featureRoutes: RouteObject[]): RouteObject[] {
+  const result = [...targetRoutes];
+
+  for (const featureRoute of featureRoutes) {
+    // Check if this is a deletion marker
+    const DELETE_PREFIX = '__delete__';
+    if (featureRoute.path && typeof featureRoute.path === 'string') {
+      // Remove quotes from path string if present
+      const pathValue = featureRoute.path.replace(/^['"`]|['"`]$/g, '');
+
+      if (pathValue.startsWith(DELETE_PREFIX)) {
+        // This is a deletion marker - remove the route with matching path
+        const targetPath = pathValue.substring(DELETE_PREFIX.length);
+
+        const deleteIndex = result.findIndex((targetRoute) => {
+          if (targetRoute.path && typeof targetRoute.path === 'string') {
+            const targetPathValue = targetRoute.path.replace(/^['"`]|['"`]$/g, '');
+            return targetPathValue === targetPath;
+          }
+          return false;
+        });
+
+        if (deleteIndex >= 0) {
+          result.splice(deleteIndex, 1);
+          logger.info(`Deleted route with path: ${targetPath}`);
+        } else {
+          logger.error(`\nValidation error: Cannot delete route that doesn't exist!\n`);
+          logger.info(`Route marked for deletion: ${targetPath}`);
+          logger.warning(`The route doesn't exist in the current routes.\n`);
+          throw new Error('Route deletion failed - cannot proceed');
+        }
+
+        // Don't add the deletion marker to result
+        continue;
+      }
+    }
+
+    const matchIndex = result.findIndex((targetRoute) => {
+      // Match by path if both have paths
+      if (featureRoute.path && targetRoute.path) {
+        return featureRoute.path === targetRoute.path;
+      }
+      // Match index routes
+      if (featureRoute.index && targetRoute.index) {
+        return true;
+      }
+      return false;
+    });
+
+    if (matchIndex >= 0) {
+      const targetRoute = result[matchIndex];
+
+      // Merge the route, starting with feature route properties
+      const mergedRoute: RouteObject = { ...featureRoute };
+
+      // If both have children, recursively merge them
+      if (targetRoute.children && featureRoute.children) {
+        mergedRoute.children = deepMergeRoutes(targetRoute.children, featureRoute.children);
+      } else if (targetRoute.children) {
+        // Only target has children, preserve them
+        mergedRoute.children = targetRoute.children;
+      }
+      // If only feature has children, they're already in mergedRoute
+
+      result[matchIndex] = mergedRoute;
+    } else {
+      // No match found, add the new route
+      result.push(featureRoute);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate TypeScript code from RouteObject[]
+ */
+function generateRoutesCode(routes: RouteObject[]): string {
+  if (routes.length === 0) {
+    return '[]';
+  }
+
+  const routeStrings = routes.map((route) => generateRouteCode(route, 1));
+  return `[\n${routeStrings.join(',\n')}\n]`;
+}
+
+/**
+ * Generate code for a single route object
+ */
+function generateRouteCode(route: RouteObject, indentLevel: number): string {
+  const indent = '  '.repeat(indentLevel);
+  const props: string[] = [];
+
+  for (const [key, value] of Object.entries(route)) {
+    if (key === 'children' && Array.isArray(value)) {
+      // Recursively generate children
+      const childrenCode = value.length > 0
+        ? `[\n${value.map((child) => generateRouteCode(child, indentLevel + 2)).join(',\n')}\n${indent}  ]`
+        : '[]';
+      props.push(`children: ${childrenCode}`);
+    } else if (value !== undefined) {
+      // For other properties, use the raw text we stored
+      props.push(`${key}: ${value}`);
+    }
+  }
+
+  return `${indent}{\n${props.map((p) => `${indent}  ${p}`).join(',\n')}\n${indent}}`;
+}

package/src/utils/validation.ts

@@ -0,0 +1,150 @@
+import { existsSync, statSync } from 'fs';
+import { getMonorepoRoot } from './paths.js';
+import { join, isAbsolute, basename } from 'path';
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Get the web application directory path from a base app path
+ * Structure: <basePath>/digitalExperiences/webApplications/<appName>
+ */
+export function getWebApplicationPath(basePath: string): string {
+  const appName = basename(basePath);
+  return join(basePath, 'digitalExperiences', 'webApplications', appName);
+}
+
+/**
+ * Validate that a feature path exists and resolve it to an absolute path
+ */
+export function validateAndResolveFeaturePath(featurePath: string): string {
+  let resolvedPath: string;
+
+  // If it's an absolute path, use it as-is
+  if (isAbsolute(featurePath)) {
+    resolvedPath = featurePath;
+  } else {
+    // If it's relative, resolve from monorepo root
+    resolvedPath = join(getMonorepoRoot(), featurePath);
+  }
+
+  if (!existsSync(resolvedPath)) {
+    throw new ValidationError(
+      `Feature path '${featurePath}' does not exist`
+    );
+  }
+
+  if (!statSync(resolvedPath).isDirectory()) {
+    throw new ValidationError(
+      `Feature path '${featurePath}' is not a directory`
+    );
+  }
+
+  // Check if it has a feature.ts file
+  const featureFilePath = join(resolvedPath, 'feature.ts');
+  if (!existsSync(featureFilePath)) {
+    throw new ValidationError(
+      `Feature path '${featurePath}' does not contain a feature.ts file`
+    );
+  }
+
+  return resolvedPath;
+}
+
+/**
+ * Validate and resolve an app path (can be relative or absolute)
+ * Validates that the web application directory exists with proper structure
+ * Returns the absolute path to the base app directory
+ */
+export function validateAndResolveAppPath(appPath: string): string {
+  let resolvedBasePath: string;
+
+  // If it's an absolute path, use it as-is
+  if (isAbsolute(appPath)) {
+    resolvedBasePath = appPath;
+  } else {
+    // If it's relative, resolve from monorepo root
+    resolvedBasePath = join(getMonorepoRoot(), appPath);
+  }
+
+  if (!existsSync(resolvedBasePath)) {
+    throw new ValidationError(
+      `App path '${appPath}' does not exist`
+    );
+  }
+
+  if (!statSync(resolvedBasePath).isDirectory()) {
+    throw new ValidationError(
+      `App path '${appPath}' is not a directory`
+    );
+  }
+
+  // Get the web application directory path
+  const webAppPath = getWebApplicationPath(resolvedBasePath);
+
+  if (!existsSync(webAppPath)) {
+    throw new ValidationError(
+      `Web application directory does not exist at '${webAppPath}'. Expected structure: digitalExperiences/webApplications/<app-name>`
+    );
+  }
+
+  if (!statSync(webAppPath).isDirectory()) {
+    throw new ValidationError(
+      `Web application path '${webAppPath}' is not a directory`
+    );
+  }
+
+  // Check if it has a package.json
+  const packageJsonPath = join(webAppPath, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    throw new ValidationError(
+      `Web application '${webAppPath}' does not contain a package.json file`
+    );
+  }
+
+  return resolvedBasePath;
+}
+
+const APP_FEATURE_NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * Validate that a app or feature name is valid
+ * - Must be in kebab-case (lowercase with hyphens)
+ * - Only alphanumeric characters and hyphens allowed
+ * - Cannot start or end with hyphens
+ * - No consecutive hyphens
+ * - Cannot be reserved names: "base", "cli"
+ * - Max 50 characters
+ */
+export function validateAppOrFeatureName(name: string): void {
+  // Check empty
+  if (!name || name.trim().length === 0) {
+    throw new ValidationError('App or feature name cannot be empty');
+  }
+
+  // Check format
+  if (!APP_FEATURE_NAME_REGEX.test(name)) {
+    throw new ValidationError(
+      `App or feature name '${name}' is invalid. Must be kebab-case (lowercase letters, numbers, and hyphens only).\nExamples: "nav-menu", "user-auth", "dashboard-v2"`
+    );
+  }
+
+  // Check reserved names
+  const reserved = ['app', 'feature'];
+  if (reserved.includes(name)) {
+    throw new ValidationError(
+      `App or feature name '${name}' is reserved. Please choose a different name.`
+    );
+  }
+
+  // Check length
+  if (name.length > 50) {
+    throw new ValidationError(
+      `App or feature name '${name}' is too long. Maximum 50 characters.`
+    );
+  }
+}