@wix/zero-config-implementation 1.5.0

package/src/component-loader.ts

@@ -0,0 +1,256 @@
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { pascalCase } from 'case-anything'
+import { ResultAsync, errAsync, okAsync } from 'neverthrow'
+import { getPackageEntryPoints } from 'pkg-entry-points'
+import type { ComponentType } from 'react'
+import { readPackageUpSync } from 'read-package-up'
+import { IoError, NotFoundError } from './errors'
+
+type NotFoundErrorInstance = InstanceType<typeof NotFoundError>
+type IoErrorInstance = InstanceType<typeof IoError>
+export type LoaderError = NotFoundErrorInstance | IoErrorInstance
+
+export interface ComponentLoaderResult {
+  loadComponent: (name: string) => ComponentType<unknown> | null
+  packageName: string
+  entryPath: string | undefined
+  exportNames: string[]
+}
+
+/**
+ * Creates a component loader that dynamically loads components from the
+ * user's package. Finds the nearest package.json, resolves its entry point,
+ * and loads the module.
+ *
+ * The returned `loadComponent` is synchronous (required by processComponent).
+ * ESM modules are loaded via async `import()` during creation, so this
+ * function itself is async.
+ *
+ * @returns A `ResultAsync` containing a `ComponentLoaderResult` on success.
+ * @errors {NotFoundError} When no package.json is found or the package has no resolvable entry points.
+ * @errors {IoError} When module loading fails (CJS require or ESM import).
+ */
+export function createComponentLoader(componentPath: string): ResultAsync<ComponentLoaderResult, LoaderError> {
+  // 1. Find nearest package.json
+  const result = readPackageUpSync({ cwd: dirname(resolve(componentPath)) })
+  if (!result) {
+    return errAsync(new NotFoundError('No package.json found', { props: { phase: 'load' } }))
+  }
+
+  const { packageJson, path: packageJsonPath } = result
+  const packageDir = dirname(packageJsonPath)
+  const packageName = packageJson.name
+
+  // 2. Resolve entry point(s) via pkg-entry-points (handles exports + legacy main/module)
+  return ResultAsync.fromPromise(
+    getPackageEntryPoints(packageDir),
+    (err) =>
+      new IoError(`Failed to resolve entry points for "${packageName}"`, {
+        cause: err instanceof Error ? err : new Error(String(err)),
+        props: { phase: 'load' },
+      }),
+  ).andThen((entryPoints) => {
+    return loadFromEntryPoints(entryPoints, packageDir, packageName, packageJsonPath)
+  })
+}
+
+/**
+ * Given resolved entry points, load the appropriate module(s) and construct the
+ * `ComponentLoaderResult`.
+ *
+ * @returns A `ResultAsync` containing a `ComponentLoaderResult` on success.
+ * @errors {NotFoundError} When the package has no resolvable or loadable entry points.
+ * @errors {IoError} When module loading fails.
+ */
+function loadFromEntryPoints(
+  entryPoints: Record<string, [string[], string][]>,
+  packageDir: string,
+  packageName: string | undefined,
+  packageJsonPath: string,
+): ResultAsync<ComponentLoaderResult, LoaderError> {
+  const subpaths = Object.keys(entryPoints)
+
+  if (subpaths.length === 0) {
+    return errAsync(
+      new NotFoundError(
+        `Package "${packageName}" has no resolvable entry point. Add an "exports", "module", or "main" field to ${packageJsonPath}`,
+        { props: { phase: 'load' } },
+      ),
+    )
+  }
+
+  // 3. Load module(s)
+  const dotEntry = entryPoints['.']
+  if (dotEntry || subpaths.length === 1) {
+    // Single entry point: either explicit "." or the only available subpath
+    const tuples = dotEntry ?? entryPoints[subpaths[0]]
+    const resolved = selectBestPath(tuples)
+    if (!resolved) {
+      return errAsync(
+        new NotFoundError(`Package "${packageName}" has no loadable exports`, {
+          props: { phase: 'load' },
+        }),
+      )
+    }
+    const entryPath = join(packageDir, resolved)
+    return loadModule(entryPath).map((exports) => {
+      return {
+        loadComponent: (name: string) => findComponent(exports, name),
+        packageName: packageName ?? packageDir,
+        entryPath,
+        exportNames: Object.keys(exports),
+      }
+    })
+  }
+
+  // Multiple subpaths (no ".") — load all
+  return loadAllSubpaths(entryPoints, subpaths, packageDir, packageName)
+}
+
+/**
+ * Loads all subpath entry points and merges them into a single loader result.
+ *
+ * @returns A `ResultAsync` containing a `ComponentLoaderResult` on success.
+ * @errors {NotFoundError} When none of the subpath modules could be loaded.
+ * @errors {IoError} When module loading fails.
+ */
+function loadAllSubpaths(
+  entryPoints: Record<string, [string[], string][]>,
+  subpaths: string[],
+  packageDir: string,
+  packageName: string | undefined,
+): ResultAsync<ComponentLoaderResult, LoaderError> {
+  const allModules: Record<string, unknown>[] = []
+  const allExportNames: string[] = []
+  const loadErrors: IoErrorInstance[] = []
+
+  // Build a sequential chain that loads each subpath
+  let chain: ResultAsync<void, never> = okAsync(undefined)
+
+  for (const subpath of subpaths) {
+    const resolved = selectBestPath(entryPoints[subpath])
+    if (!resolved) {
+      continue
+    }
+    const subEntryPath = join(packageDir, resolved)
+
+    chain = chain.andThen(() =>
+      loadModule(subEntryPath)
+        .map((exports) => {
+          allModules.push(exports)
+          allExportNames.push(...Object.keys(exports))
+        })
+        .orElse((err) => {
+          loadErrors.push(err)
+          return okAsync(undefined)
+        }),
+    )
+  }
+
+  return chain.andThen(() => {
+    if (allModules.length === 0) {
+      const message = loadErrors[0]?.message ?? `Package "${packageName}" has no loadable exports`
+      return errAsync(
+        new NotFoundError(message, {
+          cause: loadErrors[0],
+          props: { phase: 'load' },
+        }),
+      )
+    }
+
+    return okAsync({
+      loadComponent: (name: string) => {
+        for (const mod of allModules) {
+          const found = findComponent(mod, name)
+          if (found) return found
+        }
+        return null
+      },
+      packageName: packageName ?? packageDir,
+      entryPath: undefined,
+      exportNames: allExportNames,
+    } satisfies ComponentLoaderResult)
+  })
+}
+
+/**
+ * Attempts to load a module, first via ESM `import()`, then via CJS `require`.
+ *
+ * ESM `import()` is preferred because it participates in the ESM loader hook
+ * pipeline (registered via `module.register()` in the CLI). This is required
+ * for JSX interception to work — the loader hook redirects `react/jsx-runtime`
+ * to the interceptable version. CJS `require()` bypasses ESM hooks even when
+ * loading ESM modules (Node 22+), so it's only used as a fallback.
+ *
+ * @param entryPath - Absolute path to the module entry point.
+ * @returns A `ResultAsync` containing the module exports on success.
+ * @errors {IoError} When both ESM import and CJS require fail.
+ */
+export function loadModule(entryPath: string): ResultAsync<Record<string, unknown>, IoErrorInstance> {
+  return ResultAsync.fromPromise(import(entryPath) as Promise<Record<string, unknown>>, () => null).orElse(() => {
+    try {
+      const require = createRequire(import.meta.url)
+      const exports = require(entryPath)
+      return okAsync(exports as Record<string, unknown>)
+    } catch (requireErr) {
+      const cause = requireErr instanceof Error ? requireErr : new Error(String(requireErr))
+      return errAsync(
+        new IoError(`Failed to load ${entryPath}: ${cause.message}`, {
+          cause,
+          props: { phase: 'load' },
+        }),
+      )
+    }
+  })
+}
+
+function selectBestPath(tuples: [string[], string][]): string | undefined {
+  const preferred = ['import', 'node', 'default']
+  for (const cond of preferred) {
+    const match = tuples.find(([c]) => c.includes(cond) && !c.includes('types'))
+    if (match) {
+      return match[1]
+    }
+  }
+  const fallback = tuples.find(([c]) => !c.includes('types'))?.[1]
+  return fallback
+}
+
+function isPascalCase(name: string): boolean {
+  return name.length > 0 && pascalCase(name) === name
+}
+
+function isComponent(value: unknown): value is ComponentType<unknown> {
+  if (typeof value === 'function') return isPascalCase(value.name)
+  // React.memo() and React.forwardRef() return objects, not functions
+  if (typeof value === 'object' && value !== null && '$$typeof' in value) return true
+  return false
+}
+
+export function findComponent(moduleExports: Record<string, unknown>, name: string): ComponentType<unknown> | null {
+  // Direct named export
+  const direct = moduleExports[name]
+  if ((typeof direct === 'function' && isPascalCase(name)) || isComponent(direct)) {
+    return direct as ComponentType<unknown>
+  }
+
+  // Check default export
+  const defaultExport = moduleExports.default
+  if (defaultExport) {
+    // default is the component itself (matches by function name)
+    if (typeof defaultExport === 'function' && defaultExport.name === name) {
+      return defaultExport as ComponentType<unknown>
+    }
+
+    // CJS interop: default is an object with named exports
+    if (typeof defaultExport === 'object' && defaultExport !== null) {
+      const nested = (defaultExport as Record<string, unknown>)[name]
+      if (isComponent(nested)) {
+        return nested as ComponentType<unknown>
+      }
+    }
+  }
+
+  return null
+}

package/src/component-renderer.ts

@@ -0,0 +1,192 @@
+/**
+ * Component Renderer - Renders React components with createElement interception
+ *
+ * This module intercepts React's element creation functions to track
+ * DOM element creation during server-side rendering. This allows tracking which props
+ * flow into which DOM elements.
+ *
+ * ## Interception Strategy
+ *
+ * Three complementary layers ensure interception regardless of how JSX is compiled:
+ *
+ * 1. **Vite alias** — `react/jsx-runtime` is aliased to `jsx-runtime-interceptor.ts`
+ *    in vite.config.ts. This handles ESM imports resolved at build time.
+ *
+ * 2. **`React.createElement` monkey-patch** — Classic JSX transform and explicit
+ *    `React.createElement()` calls are intercepted by temporarily replacing the
+ *    function on the React module object.
+ *
+ * 3. **CJS module export patch** — Pre-built CJS bundles call
+ *    `require('react/jsx-runtime')` at runtime, bypassing the Vite alias. We use
+ *    `createRequire` to obtain the real CJS module objects and temporarily replace
+ *    their `jsx`/`jsxs`/`jsxDEV` exports during rendering. This is safe because
+ *    CJS module exports are mutable (`writable: true`).
+ *
+ * ## Intercepted Functions
+ *
+ * - `React.createElement` - Classic JSX transform (monkey-patched)
+ * - `jsx` / `jsxs` from `react/jsx-runtime` - New JSX transform via interceptor module
+ * - `jsx` / `jsxs` / `jsxDEV` on the real CJS `react/jsx-runtime` and
+ *   `react/jsx-dev-runtime` module objects (monkey-patched for CJS consumers)
+ *
+ * ## Known Limitations
+ *
+ * 1. **Global state** - During render, we temporarily replace element creation
+ *    functions globally. This is not thread-safe and could cause issues if multiple
+ *    renders happen concurrently. Interceptors are restored in a finally block.
+ *
+ * 2. **React version compatibility** - This approach may break with future React versions
+ *    if the internal rendering pipeline changes. Tested with React 18.x.
+ *
+ * @module component-renderer
+ */
+
+import { createRequire } from 'node:module'
+import React from 'react'
+import type { ComponentType, ReactElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import type { ExtractorStore } from './information-extractors/react/extractors/core/store'
+import type { CreateElementEvent } from './information-extractors/react/extractors/core/types'
+
+// Import the interceptor API - use direct path since vite alias doesn't apply to all packages
+import { getOriginals, setJsxInterceptors } from './jsx-runtime-interceptor'
+
+export const TRACE_ATTR = 'data-trace-id'
+
+export type { CreateElementEvent }
+
+export interface CreateElementListener {
+  onCreateElement: (event: CreateElementEvent) => void
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Interception
+// ─────────────────────────────────────────────────────────────────────────────
+
+const isDOMTag = (type: unknown): type is string => typeof type === 'string' && /^[a-z]/.test(type)
+
+type ElementCreator = (type: unknown, props: unknown, ...rest: unknown[]) => ReactElement
+
+/**
+ * Creates an intercepted version of an element creation function.
+ * Works with both createElement (children as rest params) and jsx/jsxs (children in props).
+ */
+function createInterceptor(
+  original: ElementCreator,
+  listeners: CreateElementListener[],
+  getNextId: () => string,
+  store: ExtractorStore,
+): ElementCreator {
+  return (type, elementProps, ...rest) => {
+    if (!isDOMTag(type)) {
+      return original(type, elementProps, ...rest)
+    }
+
+    const props = (elementProps ?? {}) as Record<string, unknown>
+    const traceId = getNextId()
+
+    // Children location differs: createElement uses rest params, jsx/jsxs uses props.children
+    const children = rest.length > 0 ? rest : props.children ? [props.children] : []
+
+    const event: CreateElementEvent = {
+      tag: type,
+      props: { ...props, children },
+      traceId,
+      children: children as unknown[],
+      store,
+    }
+
+    listeners.forEach((listener) => listener.onCreateElement(event))
+
+    const stampedProps = { ...props, [TRACE_ATTR]: traceId }
+    return original(type, stampedProps, ...rest)
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Renderer
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Renders a React component to static HTML while intercepting element creation.
+ *
+ * Uses monkey-patching of React.createElement and jsx/jsxs to notify listeners
+ * when DOM elements are created. Each DOM element gets a unique `data-trace-id`
+ * attribute for tracking.
+ *
+ * @param Component - The React component to render
+ * @param componentProps - Props to pass to the component
+ * @param listeners - Listeners to notify on each DOM element creation
+ * @param store - Shared ExtractorStore, included in each CreateElementEvent
+ * @returns Static HTML string with trace IDs on DOM elements
+ *
+ * @example
+ * ```ts
+ * const store = new ExtractorStore()
+ * const tracker = createPropTracker(getSpyMetadata)
+ * const html = renderWithExtractors(MyComponent, { title: 'Hello' }, [tracker], store)
+ * // html contains: <div data-trace-id="t1">...</div>
+ * // tracker.stores now has prop→DOM bindings
+ * ```
+ */
+export function renderWithExtractors(
+  Component: ComponentType<unknown>,
+  componentProps: unknown,
+  listeners: CreateElementListener[],
+  store: ExtractorStore,
+): string {
+  let nextId = 0
+  const getNextId = () => `t${++nextId}`
+
+  // Store originals
+  const originalCreateElement = React.createElement
+  const { jsx: originalJsx, jsxs: originalJsxs, jsxDEV: originalJsxDEV } = getOriginals()
+
+  // Obtain real CJS module objects so we can patch them for pre-built CJS consumers
+  const cjsRequire = createRequire(import.meta.url)
+  const cjsRuntime = cjsRequire('react/jsx-runtime') as Record<string, unknown>
+  const cjsDevRuntime = cjsRequire('react/jsx-dev-runtime') as Record<string, unknown>
+
+  // Save the original CJS exports
+  const origCjsJsx = cjsRuntime.jsx
+  const origCjsJsxs = cjsRuntime.jsxs
+  const origCjsJsxDEV = cjsDevRuntime.jsxDEV
+
+  // Create interceptors
+  const interceptedCreateElement = createInterceptor(
+    originalCreateElement as ElementCreator,
+    listeners,
+    getNextId,
+    store,
+  )
+  const interceptedJsx = createInterceptor(originalJsx as ElementCreator, listeners, getNextId, store)
+  const interceptedJsxs = createInterceptor(originalJsxs as ElementCreator, listeners, getNextId, store)
+  const interceptedJsxDEV = createInterceptor(originalJsxDEV as ElementCreator, listeners, getNextId, store)
+
+  try {
+    // @ts-expect-error Monkey-patch createElement
+    React.createElement = interceptedCreateElement
+    // Use the interceptor API for jsx-runtime (includes jsxDEV for dev mode)
+    setJsxInterceptors(
+      interceptedJsx as typeof originalJsx,
+      interceptedJsxs as typeof originalJsxs,
+      interceptedJsxDEV as typeof originalJsxDEV,
+    )
+    // Patch real CJS module exports for pre-built CJS bundles
+    cjsRuntime.jsx = interceptedJsx
+    cjsRuntime.jsxs = interceptedJsxs
+    cjsDevRuntime.jsxDEV = interceptedJsxDEV
+
+    const element = React.createElement(Component, componentProps as Record<string, unknown>)
+    return renderToStaticMarkup(element)
+  } finally {
+    // Restore originals
+    React.createElement = originalCreateElement
+    setJsxInterceptors() // Restores to originals
+    // Restore CJS module exports
+    cjsRuntime.jsx = origCjsJsx
+    cjsRuntime.jsxs = origCjsJsxs
+    cjsDevRuntime.jsxDEV = origCjsJsxDEV
+  }
+}