@fragments-sdk/cli 0.2.2

package/src/service/enhance/scanner.ts

@@ -0,0 +1,445 @@
+/**
+ * AST Scanner for Component Usage Analysis
+ *
+ * Scans TypeScript/TSX files to find:
+ * - Component imports (named, default, aliased)
+ * - Component usages in JSX with props
+ */
+
+import { parse, type ParserOptions } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import * as t from "@babel/types";
+
+// Handle CommonJS/ESM interop
+const traverse = (_traverse as unknown as { default: typeof _traverse }).default || _traverse;
+import { readFile } from "node:fs/promises";
+import type {
+  ComponentImport,
+  ComponentUsage,
+  UsageProps,
+} from "./types.js";
+
+/**
+ * Babel parser options for React/TypeScript files
+ */
+const PARSER_OPTIONS: ParserOptions = {
+  sourceType: "module",
+  plugins: [
+    "jsx",
+    "typescript",
+    ["decorators", { decoratorsBeforeExport: true }],
+    "classProperties",
+    "classPrivateProperties",
+    "classPrivateMethods",
+    "exportDefaultFrom",
+    "exportNamespaceFrom",
+    "dynamicImport",
+    "nullishCoalescingOperator",
+    "optionalChaining",
+    "objectRestSpread",
+  ],
+};
+
+/**
+ * Scan a file for component imports
+ *
+ * Handles:
+ * - Named imports: import { Button } from './Button'
+ * - Default imports: import Button from './Button'
+ * - Aliased imports: import { Button as Btn } from './Button'
+ * - Namespace imports: import * as Components from './index'
+ */
+export async function scanFileForImports(
+  filePath: string
+): Promise<ComponentImport[]> {
+  const imports: ComponentImport[] = [];
+
+  try {
+    const sourceCode = await readFile(filePath, "utf-8");
+    const ast = parse(sourceCode, PARSER_OPTIONS);
+
+    traverse(ast, {
+      ImportDeclaration(path) {
+        const source = path.node.source.value;
+        const line = path.node.loc?.start.line ?? 0;
+
+        for (const specifier of path.node.specifiers) {
+          if (t.isImportSpecifier(specifier)) {
+            // Named import: import { Button } from './Button'
+            // or aliased: import { Button as Btn } from './Button'
+            const importedName = t.isIdentifier(specifier.imported)
+              ? specifier.imported.name
+              : specifier.imported.value;
+            const localName = specifier.local.name;
+
+            // Only track PascalCase names (likely components)
+            if (isPascalCase(importedName)) {
+              imports.push({
+                componentName: importedName,
+                localName,
+                source,
+                isDefault: false,
+                filePath,
+                line,
+              });
+            }
+          } else if (t.isImportDefaultSpecifier(specifier)) {
+            // Default import: import Button from './Button'
+            const localName = specifier.local.name;
+
+            // Only track PascalCase names (likely components)
+            if (isPascalCase(localName)) {
+              imports.push({
+                componentName: localName,
+                localName,
+                source,
+                isDefault: true,
+                filePath,
+                line,
+              });
+            }
+          }
+          // Skip namespace imports for now (import * as X)
+        }
+      },
+    });
+  } catch (error) {
+    // Return empty array for files with parse errors
+    // Caller can check if empty means "no imports" or "parse error"
+    console.warn(`Failed to parse ${filePath}:`, (error as Error).message);
+    return [];
+  }
+
+  return imports;
+}
+
+/**
+ * Scan a file for component usages in JSX
+ *
+ * @param filePath - File to scan
+ * @param componentNames - Map of localName -> componentName for components to track
+ */
+export async function scanFileForUsages(
+  filePath: string,
+  componentNames: Map<string, string>
+): Promise<ComponentUsage[]> {
+  const usages: ComponentUsage[] = [];
+
+  try {
+    const sourceCode = await readFile(filePath, "utf-8");
+    const lines = sourceCode.split("\n");
+    const ast = parse(sourceCode, PARSER_OPTIONS);
+
+    traverse(ast, {
+      JSXOpeningElement(path) {
+        const elementName = getJSXElementName(path.node.name);
+        if (!elementName) return;
+
+        // Check if this is a tracked component (by local name)
+        const componentName = componentNames.get(elementName);
+        if (!componentName) return;
+
+        const loc = path.node.loc;
+        if (!loc) return;
+
+        // Extract props
+        const props = extractProps(path.node.attributes);
+
+        // Get surrounding context (3 lines before and after)
+        const contextLines = getContextLines(lines, loc.start.line - 1, 3);
+
+        // Check if conditionally rendered
+        const isConditional = checkIfConditional(path);
+
+        // Get parent element name
+        const parentElement = getParentElementName(path);
+
+        usages.push({
+          componentName,
+          filePath,
+          line: loc.start.line,
+          column: loc.start.column,
+          props,
+          context: contextLines,
+          parentElement,
+          hasSpreadProps: props.spreads.length > 0,
+          isConditional,
+        });
+      },
+    });
+  } catch (error) {
+    console.warn(`Failed to parse ${filePath}:`, (error as Error).message);
+    return [];
+  }
+
+  return usages;
+}
+
+/**
+ * Scan a file for both imports and usages in a single pass
+ * More efficient for scanning many files
+ */
+export async function scanFile(
+  filePath: string,
+  trackedComponents?: Set<string>
+): Promise<{ imports: ComponentImport[]; usages: ComponentUsage[] }> {
+  const imports: ComponentImport[] = [];
+  const usages: ComponentUsage[] = [];
+
+  try {
+    const sourceCode = await readFile(filePath, "utf-8");
+    const lines = sourceCode.split("\n");
+    const ast = parse(sourceCode, PARSER_OPTIONS);
+
+    // Track local names to component names mapping within this file
+    const localToComponent = new Map<string, string>();
+
+    traverse(ast, {
+      ImportDeclaration(path) {
+        const source = path.node.source.value;
+        const line = path.node.loc?.start.line ?? 0;
+
+        for (const specifier of path.node.specifiers) {
+          if (t.isImportSpecifier(specifier)) {
+            const importedName = t.isIdentifier(specifier.imported)
+              ? specifier.imported.name
+              : specifier.imported.value;
+            const localName = specifier.local.name;
+
+            if (isPascalCase(importedName)) {
+              // If we're tracking specific components, only add those
+              if (!trackedComponents || trackedComponents.has(importedName)) {
+                imports.push({
+                  componentName: importedName,
+                  localName,
+                  source,
+                  isDefault: false,
+                  filePath,
+                  line,
+                });
+                localToComponent.set(localName, importedName);
+              }
+            }
+          } else if (t.isImportDefaultSpecifier(specifier)) {
+            const localName = specifier.local.name;
+
+            if (isPascalCase(localName)) {
+              if (!trackedComponents || trackedComponents.has(localName)) {
+                imports.push({
+                  componentName: localName,
+                  localName,
+                  source,
+                  isDefault: true,
+                  filePath,
+                  line,
+                });
+                localToComponent.set(localName, localName);
+              }
+            }
+          }
+        }
+      },
+
+      JSXOpeningElement(path) {
+        const elementName = getJSXElementName(path.node.name);
+        if (!elementName) return;
+
+        // Check if this is a tracked component (by local name)
+        const componentName = localToComponent.get(elementName);
+        if (!componentName) return;
+
+        const loc = path.node.loc;
+        if (!loc) return;
+
+        const props = extractProps(path.node.attributes);
+        const contextLines = getContextLines(lines, loc.start.line - 1, 3);
+        const isConditional = checkIfConditional(path);
+        const parentElement = getParentElementName(path);
+
+        usages.push({
+          componentName,
+          filePath,
+          line: loc.start.line,
+          column: loc.start.column,
+          props,
+          context: contextLines,
+          parentElement,
+          hasSpreadProps: props.spreads.length > 0,
+          isConditional,
+        });
+      },
+    });
+  } catch (error) {
+    console.warn(`Failed to parse ${filePath}:`, (error as Error).message);
+    return { imports: [], usages: [] };
+  }
+
+  return { imports, usages };
+}
+
+/**
+ * Check if a string is PascalCase (likely a component name)
+ */
+function isPascalCase(str: string): boolean {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(str);
+}
+
+/**
+ * Get the element name from a JSX element name node
+ */
+function getJSXElementName(
+  name: t.JSXIdentifier | t.JSXMemberExpression | t.JSXNamespacedName
+): string | null {
+  if (t.isJSXIdentifier(name)) {
+    return name.name;
+  }
+  if (t.isJSXMemberExpression(name)) {
+    // Handle Component.SubComponent - return the full path
+    const parts: string[] = [];
+    let current: t.JSXMemberExpression | t.JSXIdentifier = name;
+    while (t.isJSXMemberExpression(current)) {
+      parts.unshift(current.property.name);
+      current = current.object as t.JSXMemberExpression | t.JSXIdentifier;
+    }
+    if (t.isJSXIdentifier(current)) {
+      parts.unshift(current.name);
+    }
+    return parts.join(".");
+  }
+  return null;
+}
+
+/**
+ * Extract props from JSX attributes
+ */
+function extractProps(
+  attributes: (t.JSXAttribute | t.JSXSpreadAttribute)[]
+): UsageProps {
+  const result: UsageProps = {
+    static: {},
+    dynamic: [],
+    spreads: [],
+  };
+
+  for (const attr of attributes) {
+    if (t.isJSXSpreadAttribute(attr)) {
+      // {...props} or {...otherProps}
+      if (t.isIdentifier(attr.argument)) {
+        result.spreads.push(attr.argument.name);
+      } else {
+        result.spreads.push("(expression)");
+      }
+    } else if (t.isJSXAttribute(attr)) {
+      const propName = t.isJSXIdentifier(attr.name)
+        ? attr.name.name
+        : `${attr.name.namespace.name}:${attr.name.name.name}`;
+
+      const value = attr.value;
+
+      if (value === null) {
+        // Boolean shorthand: <Button disabled />
+        result.static[propName] = true;
+      } else if (t.isStringLiteral(value)) {
+        // String literal: <Button variant="primary" />
+        result.static[propName] = value.value;
+      } else if (t.isJSXExpressionContainer(value)) {
+        const expr = value.expression;
+
+        if (t.isStringLiteral(expr)) {
+          result.static[propName] = expr.value;
+        } else if (t.isNumericLiteral(expr)) {
+          result.static[propName] = expr.value;
+        } else if (t.isBooleanLiteral(expr)) {
+          result.static[propName] = expr.value;
+        } else if (t.isTemplateLiteral(expr) && expr.expressions.length === 0) {
+          // Static template literal: variant={`primary`}
+          result.static[propName] = expr.quasis.map((q) => q.value.raw).join("");
+        } else {
+          // Dynamic expression
+          result.dynamic.push(propName);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get surrounding context lines
+ */
+function getContextLines(
+  lines: string[],
+  centerLine: number,
+  radius: number
+): string {
+  const start = Math.max(0, centerLine - radius);
+  const end = Math.min(lines.length, centerLine + radius + 1);
+  return lines.slice(start, end).join("\n");
+}
+
+/**
+ * Check if JSX element is conditionally rendered
+ */
+function checkIfConditional(path: babel.NodePath<t.JSXOpeningElement>): boolean {
+  let current: babel.NodePath | null = path.parentPath;
+
+  while (current) {
+    // Check for {condition && <Component />}
+    if (
+      current.isLogicalExpression() &&
+      current.node.operator === "&&"
+    ) {
+      return true;
+    }
+
+    // Check for {condition ? <Component /> : null}
+    if (current.isConditionalExpression()) {
+      return true;
+    }
+
+    // Check for ternary in JSX expression container
+    if (
+      current.isJSXExpressionContainer() &&
+      current.parentPath?.isJSXElement()
+    ) {
+      const expr = current.node.expression;
+      if (
+        t.isLogicalExpression(expr) ||
+        t.isConditionalExpression(expr)
+      ) {
+        return true;
+      }
+    }
+
+    current = current.parentPath;
+  }
+
+  return false;
+}
+
+/**
+ * Get the parent JSX element name
+ */
+function getParentElementName(
+  path: babel.NodePath<t.JSXOpeningElement>
+): string | undefined {
+  let current: babel.NodePath | null = path.parentPath;
+  const currentElementName = getJSXElementName(path.node.name);
+
+  while (current) {
+    if (current.isJSXElement()) {
+      const opening = current.node.openingElement;
+      const name = getJSXElementName(opening.name);
+      if (name && name !== currentElementName) {
+        return name;
+      }
+    }
+    current = current.parentPath;
+  }
+
+  return undefined;
+}
+
+// Type import for babel NodePath
+import type * as babel from "@babel/traverse";