@wix/zero-config-implementation 1.26.0 → 1.28.0

package/dist/manifest-pipeline.d.ts

@@ -2,13 +2,7 @@ import { ComponentInfo } from './information-extractors/ts';
 import { RunExtractorsOptions, CoupledComponentInfo } from './information-extractors/react';
 import { CSSParserAPI } from './information-extractors/css';
 import { ComponentType } from 'react';
-/** A non-fatal issue encountered during component processing. */
-export interface ExtractionWarning {
-    componentName: string;
-    phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion';
-    error: string;
-    stack?: string;
-}
+import { ExtractionError } from './extraction-types';
 export interface ExtractedCssInfo {
     filePath: string;
     api: CSSParserAPI;
@@ -23,7 +17,6 @@ export interface ComponentInfoWithCss extends CoupledComponentInfo {
 /** The result of processing a single component through the manifest pipeline. */
 export interface ProcessComponentResult {
     component: ComponentInfoWithCss;
-    warnings: ExtractionWarning[];
 }
 /**
  * Processes a single component through the full manifest pipeline:
@@ -33,4 +26,4 @@ export interface ProcessComponentResult {
  * encountered during processing. Always returns a component, falling back
  * to minimal info (without DOM coupling) when rendering fails.
  */
-export declare function processComponent(componentInfo: ComponentInfo, loadComponent: (componentName: string) => ComponentType<unknown> | null, cssImportPaths: string[], loaderHasError?: boolean, options?: RunExtractorsOptions): ProcessComponentResult;
+export declare function processComponent(componentInfo: ComponentInfo, loadComponent: (componentName: string) => ComponentType<unknown> | null, cssImportPaths: string[], loaderHasError: boolean, report: (error: ExtractionError) => void, options?: RunExtractorsOptions): ProcessComponentResult;

package/dist/module-loader.d.ts

@@ -1,7 +1,15 @@
 import { ResultAsync } from 'neverthrow';
 import { ComponentType } from 'react';
-import { IoError } from './errors';
-type IoErrorInstance = InstanceType<typeof IoError>;
+/**
+ * Structured failure from `loadModule` when both ESM import and CJS require fail.
+ * Carries each error separately so callers can report them independently.
+ */
+export interface LoadModuleFailure {
+    /** The ESM import error, or null when no ESM was attempted (e.g. empty path). */
+    esmError: Error | null;
+    /** The CJS require error, or a generic error for the empty-path case. */
+    cjsError: Error;
+}
 /**
  * Attempts to load a module, first via ESM `import()`, then via CJS `require`.
  *
@@ -13,8 +21,7 @@ type IoErrorInstance = InstanceType<typeof IoError>;
  *
  * @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.
+ * @errors {LoadModuleFailure} When both ESM import and CJS require fail.
  */
-export declare function loadModule(entryPath: string): ResultAsync<Record<string, unknown>, IoErrorInstance>;
+export declare function loadModule(entryPath: string): ResultAsync<Record<string, unknown>, LoadModuleFailure>;
 export declare function findComponent(moduleExports: Record<string, unknown>, name: string): ComponentType<unknown> | null;
-export {};

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -83,5 +83,5 @@
       ]
     }
   },
-  "falconPackageHash": "3dd0aab1018f95841806376f73376b94c1dcf15d586caa70806a01f8"
+  "falconPackageHash": "b9b7aa47b7618d7b031628208f9fb26661e34ddb5fe300679306084e"
 }

package/src/extraction-types.ts

@@ -0,0 +1,8 @@
+import type { BaseError } from './errors'
+
+/** A non-fatal issue encountered during component extraction. */
+export interface ExtractionError {
+  componentName: string
+  phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion'
+  error: InstanceType<typeof BaseError>
+}

package/src/index.ts

@@ -1,32 +1,16 @@
 import type { EditorReactComponent } from '@wix/zero-config-schema'
-import { Result, ResultAsync } from 'neverthrow'
+import { Result, type ResultAsync, okAsync } from 'neverthrow'
 import type { ComponentType } from 'react'
 
-import { extractAllComponentInfo, extractCssImports, extractDefaultComponentInfo } from './information-extractors/ts'
-import type { ComponentInfo } from './information-extractors/ts'
-// TypeScript extraction
-import { compileTsFile } from './ts-compiler'
-
-// Error classes
-import { type NotFoundError, ParseError } from './errors'
-
-// Component loader helpers
-import { findComponent, loadModule } from './module-loader'
-
+import { toEditorReactComponent } from './converters'
+import { IoError, type NotFoundError, ParseError } from './errors'
+import type { ExtractionError } from './extraction-types'
 import type { RunExtractorsOptions } from './information-extractors/react'
-// Pipeline orchestration
+import { extractCssImports, extractDefaultComponentInfo } from './information-extractors/ts'
 import { processComponent } from './manifest-pipeline'
-export type {
-  ComponentInfoWithCss,
-  ExtractedCssInfo,
-  ExtractionWarning,
-  ProcessComponentResult,
-} from './manifest-pipeline'
-
-export type { EditorReactComponent } from '@wix/zero-config-schema'
-
-// Converter
-import { toEditorReactComponent } from './converters'
+import { findComponent, loadModule } from './module-loader'
+import type { LoadModuleFailure } from './module-loader'
+import { compileTsFile } from './ts-compiler'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -37,15 +21,6 @@ export interface ManifestResult {
   errors: ExtractionError[]
 }
 
-export type { RunExtractorsOptions } from './information-extractors/react'
-
-export interface ExtractionError {
-  componentName: string
-  phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion'
-  error: string
-  stack?: string
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Main API
 // ─────────────────────────────────────────────────────────────────────────────
@@ -55,96 +30,100 @@ export interface ExtractionError {
  *
  * @param componentPath - Path to the TypeScript source file
  * @param compiledEntryPath - Path to the built JS entry file of the component's package (e.g. dist/index.js)
- * @returns The manifest result containing components and non-fatal warnings
+ * @param options.onError - Called for each non-fatal extraction error as it occurs
  * @errors
  * - {@link NotFoundError} — Source file does not exist (phase: `compile`)
  * - {@link ParseError} — TypeScript config or component types could not be parsed (phase: `compile` | `extract`)
  */
+export interface ExtractComponentManifestOptions extends RunExtractorsOptions {
+  onError?: (error: ExtractionError) => void
+}
+
 export function extractComponentManifest(
   componentPath: string,
   compiledEntryPath: string,
-  options?: RunExtractorsOptions,
+  options?: ExtractComponentManifestOptions,
 ): ResultAsync<ManifestResult, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError>> {
-  // Step 1: Load the compiled package module (non-fatal)
-  return loadModule(compiledEntryPath)
-    .map((moduleExports) => ({
-      moduleExports,
-      loaderError: null as string | null,
-      loaderStack: undefined as string | undefined,
-    }))
-    .orElse((err) =>
-      ResultAsync.fromSafePromise(
-        Promise.resolve({
-          moduleExports: null as Record<string, unknown> | null,
-          loaderError: err.message,
-          loaderStack: err.stack,
-        }),
-      ),
-    )
-    .andThen(({ moduleExports, loaderError, loaderStack }) => {
-      const loadComponent: (componentName: string) => ComponentType<unknown> | null = moduleExports
-        ? (name) => findComponent(moduleExports, name)
-        : () => null
-
-      // Step 2: Compile TypeScript (fatal)
-      return compileTsFile(componentPath)
-        .andThen((program) => {
-          // Step 3: Extract default-exported component types (fatal)
-          const safeExtract = Result.fromThrowable(
-            (prog: typeof program) => {
-              const componentInfo = extractDefaultComponentInfo(prog, componentPath)
-              if (!componentInfo) {
-                throw new Error(`No default export found in "${componentPath}"`)
-              }
-              return componentInfo
-            },
-            (thrown) =>
-              new ParseError(
-                `Failed to extract component types from "${componentPath}": ${thrown instanceof Error ? thrown.message : String(thrown)}`,
-                {
-                  cause: thrown as Error,
-                  props: { phase: 'extract' },
-                },
-              ),
-          )
-          const componentInfoResult = safeExtract(program)
-
-          return componentInfoResult.map((componentInfo) => ({ program, componentInfo }))
-        })
-        .map(({ program, componentInfo }) => {
-          const errors: ExtractionError[] = []
-
-          // Surface loader error as a non-fatal error
-          if (loaderError) {
-            errors.push({
-              componentName: componentInfo.componentName,
+  const errors: ExtractionError[] = []
+  const report = (error: ExtractionError): void => {
+    errors.push(error)
+    options?.onError?.(error)
+  }
+
+  // Step 1: Compile TypeScript (fatal)
+  return compileTsFile(componentPath)
+    .andThen((program) => {
+      // Step 2: Extract default-exported component types (fatal)
+      const safeExtract = Result.fromThrowable(
+        (prog: typeof program) => {
+          const componentInfo = extractDefaultComponentInfo(prog, componentPath)
+          if (!componentInfo) {
+            throw new Error(`No default export found in "${componentPath}"`)
+          }
+          return componentInfo
+        },
+        (thrown) =>
+          new ParseError(
+            `Failed to extract component types from "${componentPath}": ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+            { cause: thrown as Error, props: { phase: 'extract' } },
+          ),
+      )
+      return safeExtract(program).map((componentInfo) => ({ program, componentInfo }))
+    })
+    .andThen(({ program, componentInfo }) => {
+      const { componentName } = componentInfo
+
+      // Step 3: Load the compiled package module (non-fatal) — done after TS extraction
+      // so componentName is known when reporting failures
+      return loadModule(compiledEntryPath)
+        .map((moduleExports) => ({
+          loadComponent: (name: string) => findComponent(moduleExports, name),
+          failure: null as LoadModuleFailure | null,
+        }))
+        .orElse((failure) => okAsync({ loadComponent: () => null as ComponentType<unknown> | null, failure }))
+        .map(({ loadComponent, failure }) => {
+          if (failure) {
+            if (failure.esmError) {
+              report({
+                componentName,
+                phase: 'loader',
+                error: new IoError('ESM import failed', { cause: failure.esmError, props: { phase: 'loader' } }),
+              })
+            }
+            report({
+              componentName,
               phase: 'loader',
-              error: loaderError,
-              stack: loaderStack,
+              error: new IoError('CJS require failed', { cause: failure.cjsError, props: { phase: 'loader' } }),
             })
           }
 
           // Step 4: Extract CSS imports (non-fatal)
           let cssImportPaths: string[] = []
-          const safeCssImports = Result.fromThrowable(extractCssImports, (thrown) => thrown)
-          const cssResult = safeCssImports(program)
+          const cssResult = Result.fromThrowable(extractCssImports, (thrown) => thrown)(program)
           if (cssResult.isOk()) {
             cssImportPaths = cssResult.value
           } else {
             const thrown = cssResult.error
-            errors.push({
-              componentName: componentPath,
+            report({
+              componentName,
               phase: 'css',
-              error: `Failed to extract CSS imports: ${thrown instanceof Error ? (thrown as Error).message : String(thrown)}`,
-              stack: thrown instanceof Error ? (thrown as Error).stack : undefined,
+              error: new ParseError(
+                `Failed to extract CSS imports: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+                { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'css' } },
+              ),
             })
           }
 
           // Step 5: Process the default-exported component (non-fatal)
-          const processResult = processComponent(componentInfo, loadComponent, cssImportPaths, !!loaderError, options)
-          errors.push(...processResult.warnings)
+          const processResult = processComponent(
+            componentInfo,
+            loadComponent,
+            cssImportPaths,
+            !!failure,
+            report,
+            options,
+          )
           const component = toEditorReactComponent(processResult.component)
-
           return { component, errors }
         })
     })
@@ -171,6 +150,9 @@ export function extractComponentManifest(
 
 // ── Tier 1: High-Level API ──────────────────────────────────────────────────
 // extractComponentManifest() is exported above as a named function declaration.
+export type { ExtractionError } from './extraction-types'
+export type { EditorReactComponent } from '@wix/zero-config-schema'
+export type { ComponentInfoWithCss, ExtractedCssInfo, ProcessComponentResult } from './manifest-pipeline'
 
 // ── Tier 2: Pipeline Building Blocks ────────────────────────────────────────
 
@@ -187,6 +169,7 @@ export type {
 } from './information-extractors/ts/types'
 
 /** React render-time extraction */
+export type { RunExtractorsOptions } from './information-extractors/react'
 export {
   runExtractors,
   ExtractorStore,
@@ -204,8 +187,6 @@ export type {
   PropTrackerData,
   PropTrackerExtractorState,
   CssPropertiesData,
-} from './information-extractors/react'
-export type {
   CoupledComponentInfo,
   CoupledProp,
   DOMBinding,
@@ -231,6 +212,7 @@ export {
 
 /** Module loader primitives */
 export { loadModule, findComponent } from './module-loader'
+export type { LoadModuleFailure } from './module-loader'
 
 // ── Tier 3: Low-Level Renderer ──────────────────────────────────────────────
 

package/src/information-extractors/react/extractors/core/tree-builder.ts

@@ -12,6 +12,7 @@ import { findPreferredSemanticClass } from '../../../../utils/css-class'
 import { PRESETS_WRAPPER_CLASS_NAME } from '../../utils/mock-generator'
 import type { CssPropertiesData } from '../css-properties'
 import { addTextProperties } from '../css-properties'
+import type { PropTrackerData } from '../prop-tracker'
 import type { ExtractorStore } from './store'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -150,7 +151,7 @@ function getElementNamePart(element: Element, getElementById: (id: string) => El
   const id = getAttribute(element, 'id')
   // Skip spy-instrumented ids (mock_propName_XXXXXX) — they are runtime mock values,
   // not semantic identifiers, and would produce garbage element names.
-  if (id && !id.startsWith('mock_')) {
+  if (id && !id.includes('mock_')) {
     return pascalCase(id)
   }
 
@@ -179,6 +180,28 @@ function getElementNamePart(element: Element, getElementById: (id: string) => El
   return normalizeTagName(element.tagName)
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Element Filtering
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the element should be included in the tree:
+ * - has a BEM-semantic CSS class, OR
+ * - has a className prop propagated from the component's props
+ */
+function hasClassNameCriteria(element: Element, extractorData: Map<string, unknown>): boolean {
+  const classAttr = getAttribute(element, 'class')
+  if (classAttr) {
+    const semanticClass = findPreferredSemanticClass(classAttr.split(' '))
+    if (semanticClass) return true
+  }
+
+  const propTrackerData = extractorData.get('prop-tracker') as PropTrackerData | undefined
+  if (propTrackerData?.boundProps.includes('className')) return true
+
+  return false
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tree Building
 // ─────────────────────────────────────────────────────────────────────────────
@@ -234,15 +257,20 @@ export function buildElementTree(html: string, store: ExtractorStore): Extracted
 
     // If this element has a traceId, it's a traced element
     if (traceId) {
+      // Get extractor data from store
+      const extractorData = store.getAll(traceId) ?? new Map()
+
+      // Filter: only include non-root elements with semantic or propagated className
+      if (!isRoot && !hasClassNameCriteria(node, extractorData)) {
+        return node.childNodes.flatMap((child) => walkTree(child, ancestorPath, false))
+      }
+
       // Compute this element's name part
       const namePart = isRoot ? 'root' : getElementNamePart(node, getElementById)
 
       // Full name is ancestor path + this element's name (no separator)
       const name = isRoot ? 'root' : ancestorPath + namePart
 
-      // Get extractor data from store
-      const extractorData = store.getAll(traceId) ?? new Map()
-
       // Check for text content
       const hasText = hasDirectTextContent(node)
 

package/src/manifest-pipeline.ts

@@ -19,18 +19,13 @@ import { compileSass } from './information-extractors/css/sass-adapter'
 
 import type { ComponentType } from 'react'
 
+import { IoError, NotFoundError, ParseError } from './errors'
+import type { ExtractionError } from './extraction-types'
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** A non-fatal issue encountered during component processing. */
-export interface ExtractionWarning {
-  componentName: string
-  phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion'
-  error: string
-  stack?: string
-}
-
 export interface ExtractedCssInfo {
   filePath: string
   api: CSSParserAPI
@@ -47,7 +42,6 @@ export interface ComponentInfoWithCss extends CoupledComponentInfo {
 /** The result of processing a single component through the manifest pipeline. */
 export interface ProcessComponentResult {
   component: ComponentInfoWithCss
-  warnings: ExtractionWarning[]
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -66,29 +60,34 @@ export function processComponent(
   componentInfo: ComponentInfo,
   loadComponent: (componentName: string) => ComponentType<unknown> | null,
   cssImportPaths: string[],
-  loaderHasError?: boolean,
+  loaderHasError: boolean,
+  report: (error: ExtractionError) => void,
   options?: RunExtractorsOptions,
 ): ProcessComponentResult {
-  const warnings: ExtractionWarning[] = []
+  const { componentName } = componentInfo
 
   // Load the actual component
   let Component: ComponentType<unknown> | null = null
   try {
-    Component = loadComponent(componentInfo.componentName)
+    Component = loadComponent(componentName)
     if (!Component && !loaderHasError) {
-      warnings.push({
-        componentName: componentInfo.componentName,
+      report({
+        componentName,
         phase: 'loader',
-        error: `Component "${componentInfo.componentName}" not found in package exports`,
+        error: new NotFoundError(`Component "${componentName}" not found in package exports`, {
+          props: { phase: 'loader' },
+        }),
       })
     }
-  } catch (error) {
+  } catch (thrownError) {
     if (!loaderHasError) {
-      warnings.push({
-        componentName: componentInfo.componentName,
+      report({
+        componentName,
         phase: 'loader',
-        error: `Failed to load "${componentInfo.componentName}": ${error instanceof Error ? error.message : String(error)}`,
-        stack: error instanceof Error ? error.stack : undefined,
+        error: new IoError(
+          `Failed to load "${componentName}": ${thrownError instanceof Error ? thrownError.message : String(thrownError)}`,
+          { cause: thrownError instanceof Error ? thrownError : undefined, props: { phase: 'loader' } },
+        ),
       })
     }
   }
@@ -110,18 +109,20 @@ export function processComponent(
 
       const { props: coupledProps, innerElementProps } = buildCoupledProps(componentInfo, state.stores)
       coupledInfo = {
-        componentName: componentInfo.componentName,
+        componentName,
         props: coupledProps,
         elements: convertElements(extractedElements),
         innerElementProps: innerElementProps.size > 0 ? innerElementProps : undefined,
         propUsages: state.stores.propUsages,
       }
-    } catch (error) {
-      warnings.push({
-        componentName: componentInfo.componentName,
+    } catch (thrownError) {
+      report({
+        componentName,
         phase: 'render',
-        error: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
+        error: new IoError(thrownError instanceof Error ? thrownError.message : String(thrownError), {
+          cause: thrownError instanceof Error ? thrownError : undefined,
+          props: { phase: 'render' },
+        }),
       })
     }
   }
@@ -133,7 +134,7 @@ export function processComponent(
   } else {
     // Fallback: create minimal info without DOM coupling
     enhancedInfo = {
-      componentName: componentInfo.componentName,
+      componentName,
       props: Object.fromEntries(
         Object.entries(componentInfo.props).map(([name, info]) => [
           name,
@@ -146,8 +147,7 @@ export function processComponent(
   }
 
   // Read and parse CSS imports
-  const { cssInfos: css, warnings: cssWarnings } = extractCssInfo(cssImportPaths, componentInfo.componentName)
-  warnings.push(...cssWarnings)
+  const css = extractCssInfo(cssImportPaths, componentName, report)
 
   // Match CSS selectors to elements
   let varUsedByTraceId = new Map<string, Set<string>>()
@@ -159,12 +159,14 @@ export function processComponent(
         elements: convertElements(matchResult.elements),
       }
       varUsedByTraceId = matchResult.varUsedByTraceId
-    } catch (error) {
-      warnings.push({
-        componentName: componentInfo.componentName,
+    } catch (thrownError) {
+      report({
+        componentName,
         phase: 'css',
-        error: `CSS selector matching failed: ${error instanceof Error ? error.message : String(error)}`,
-        stack: error instanceof Error ? error.stack : undefined,
+        error: new IoError(
+          `CSS selector matching failed: ${thrownError instanceof Error ? thrownError.message : String(thrownError)}`,
+          { cause: thrownError instanceof Error ? thrownError : undefined, props: { phase: 'css' } },
+        ),
       })
     }
   }
@@ -175,7 +177,6 @@ export function processComponent(
       css,
       varUsedByTraceId,
     },
-    warnings,
   }
 }
 
@@ -327,14 +328,14 @@ function convertElements(elements: ExtractedElement[]): CoupledComponentInfo['el
 
 /**
  * Reads and parses CSS files, extracting standard and custom properties.
- * Returns the parsed CSS info alongside any warnings from files that failed to parse.
+ * Non-fatal parse failures are reported via `reportError`.
  */
 function extractCssInfo(
   cssImportPaths: string[],
   componentName: string,
-): { cssInfos: ExtractedCssInfo[]; warnings: ExtractionWarning[] } {
+  report: (error: ExtractionError) => void,
+): ExtractedCssInfo[] {
   const cssInfos: ExtractedCssInfo[] = []
-  const warnings: ExtractionWarning[] = []
 
   for (const cssPath of cssImportPaths) {
     try {
@@ -343,11 +344,13 @@ function extractCssInfo(
       if (cssPath.endsWith('.scss') || cssPath.endsWith('.sass')) {
         const compiledCssResult = compileSass(cssPath)
         if (compiledCssResult.isErr()) {
-          warnings.push({
+          report({
             componentName,
             phase: 'css',
-            error: `Failed to parse ${cssPath}: ${compiledCssResult.error.message}`,
-            stack: compiledCssResult.error.stack,
+            error: new ParseError(`Failed to compile ${cssPath}`, {
+              cause: compiledCssResult.error,
+              props: { phase: 'css' },
+            }),
           })
           continue
         }
@@ -381,15 +384,17 @@ function extractCssInfo(
         customProperties,
         isCssModule: /\.module\.(css|scss|sass)$/.test(cssPath),
       })
-    } catch (error) {
-      warnings.push({
+    } catch (thrownError) {
+      report({
         componentName,
         phase: 'css',
-        error: `Failed to parse ${cssPath}: ${error instanceof Error ? error.message : String(error)}`,
-        stack: error instanceof Error ? error.stack : undefined,
+        error: new ParseError(
+          `Failed to parse ${cssPath}: ${thrownError instanceof Error ? thrownError.message : String(thrownError)}`,
+          { cause: thrownError instanceof Error ? thrownError : undefined, props: { phase: 'css' } },
+        ),
       })
     }
   }
 
-  return { cssInfos, warnings }
+  return cssInfos
 }