@wix/zero-config-implementation 1.25.0 → 1.27.0

package/dist/information-extractors/css/types.d.ts

@@ -1,6 +1,8 @@
 export interface CSSProperty {
     name: string;
     value: string;
+    /** CSS variable names referenced via var() in this property's value */
+    varRefs?: string[];
 }
 export interface CssSelectorMatch {
     selector: string;

package/dist/manifest-pipeline.d.ts

@@ -2,18 +2,13 @@ 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;
     properties: Map<string, string>;
     customProperties: Map<string, string>;
+    isCssModule: boolean;
 }
 export interface ComponentInfoWithCss extends CoupledComponentInfo {
     css: ExtractedCssInfo[];
@@ -22,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:
@@ -32,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.25.0",
+  "version": "1.27.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -83,5 +83,5 @@
       ]
     }
   },
-  "falconPackageHash": "e76e4e02feadede0d8c9d011d32118218b349b5ab948a12605907e98"
+  "falconPackageHash": "2e095856ec4492a70d52bef24a3f7ac22639454039660a7869423748"
 }

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/css/parse.ts

@@ -345,7 +345,8 @@ function extractPropertyNameAndValue(decl: LightningDecl): CSSProperty | null {
       if (name) {
         const value = propertyValueToString(decl)
         if (value) {
-          return { name, value }
+          const varRefs = extractVarNamesFromTokens(unparsedValue.value ?? [])
+          return { name, value, ...(varRefs.length > 0 && { varRefs }) }
         }
       }
       return null
@@ -412,7 +413,7 @@ function serializeCustomPropertyValue(valueArray: unknown[]): string {
       } else if (tokenValue.type === 'dimension') {
         parts.push(`${tokenValue.value}${tokenValue.unit}`)
       } else if (tokenValue.type === 'white-space') {
-        parts.push(tokenValue.value as string)
+        // skip — parts.join(' ') already handles separation
       }
     }
   }

package/src/information-extractors/css/selector-matcher.ts

@@ -4,6 +4,45 @@ import type { ExtractedCssInfo } from '../../index'
 import type { ExtractedElement } from '../react/extractors/core/tree-builder'
 import type { CSSProperty, CssSelectorMatch, MatchedCssData } from './types'
 
+/**
+ * Matches selectors composed entirely of one or more class selectors with no combinators,
+ * pseudo-classes, tag names, or IDs — e.g. `.wrapper`, `.wrapper.active`.
+ * Used to identify selectors eligible for CSS module prefix matching.
+ */
+const SIMPLE_CLASS_SELECTOR_PATTERN = /^(\.[a-zA-Z][\w-]*)+$/
+
+/**
+ * Finds DOM elements matching a CSS selector, with special handling for CSS module files.
+ *
+ * For CSS module files, class names in the source CSS (e.g. `.wrapper`) are hashed at build
+ * time into names like `wrapper_AbCdE`. When the selector is a simple class selector
+ * (e.g. `.wrapper` or `.wrapper.active`), this function matches elements whose class list
+ * contains a class that exactly equals the local name OR starts with `localName_` /
+ * `_localName_` (the two most common Vite CSS module hash patterns).
+ *
+ * For non-module files, or for selectors that contain combinators or non-class parts
+ * (e.g. `div .wrapper`, `#id`), falls back to a direct Cheerio query.
+ */
+function findMatchingElements($: cheerio.CheerioAPI, domSelector: string, isCssModule: boolean) {
+  if (isCssModule && SIMPLE_CLASS_SELECTOR_PATTERN.test(domSelector)) {
+    const classNames = domSelector.split('.').filter(Boolean)
+    return $('[class]').filter((_index, element) => {
+      const classAttr = $(element).attr('class')
+      if (!classAttr) return false
+      const elementClasses = classAttr.trim().split(/\s+/)
+      return classNames.every((localName) =>
+        elementClasses.some(
+          (elementClass) =>
+            elementClass === localName ||
+            elementClass.startsWith(`${localName}_`) ||
+            elementClass.startsWith(`_${localName}_`),
+        ),
+      )
+    })
+  }
+  return $(domSelector)
+}
+
 export function matchCssSelectors(
   html: string,
   elements: ExtractedElement[],
@@ -28,8 +67,8 @@ export function matchCssSelectors(
       if (!domSelector) continue
 
       try {
-        $(domSelector).each((_, elem) => {
-          const traceId = $(elem).attr(TRACE_ATTR)
+        findMatchingElements($, domSelector, cssInfo.isCssModule).each((_index, element) => {
+          const traceId = $(element).attr(TRACE_ATTR)
           if (!traceId) return
 
           // Use reduce to separate regular and custom properties in one pass
@@ -37,13 +76,13 @@ export function matchCssSelectors(
             regular: CSSProperty[]
             custom: Record<string, string>
           }>(
-            (acc, prop) => {
+            (accumulator, prop) => {
               if (prop.name.startsWith('--')) {
-                acc.custom[prop.name] = prop.value
+                accumulator.custom[prop.name] = prop.value
               } else {
-                acc.regular.push(prop)
+                accumulator.regular.push(prop)
               }
-              return acc
+              return accumulator
             },
             { regular: [], custom: {} },
           )
@@ -55,7 +94,7 @@ export function matchCssSelectors(
 
             // Track which CSS custom properties are used (via var()) by this element
             for (const regularProp of regular) {
-              for (const varName of extractVarRefs(regularProp.value)) {
+              for (const varName of regularProp.varRefs ?? []) {
                 const traceIdSet = varUsedByTraceId.get(varName) ?? new Set()
                 traceIdSet.add(traceId)
                 varUsedByTraceId.set(varName, traceIdSet)
@@ -81,20 +120,6 @@ export function matchCssSelectors(
   }
 }
 
-/**
- * Extracts all CSS custom property names referenced via var() in a property value string.
- */
-function extractVarRefs(value: string): string[] {
-  const varNames: string[] = []
-  const varPattern = /var\(\s*(--[\w-]+)/g
-  let varMatch = varPattern.exec(value)
-  while (varMatch !== null) {
-    varNames.push(varMatch[1])
-    varMatch = varPattern.exec(value)
-  }
-  return varNames
-}
-
 function enrichElements(
   elements: ExtractedElement[],
   matchesByTraceId: Map<string, CssSelectorMatch[]>,

package/src/information-extractors/css/types.ts

@@ -1,6 +1,8 @@
 export interface CSSProperty {
   name: string
   value: string
+  /** CSS variable names referenced via var() in this property's value */
+  varRefs?: string[]
 }
 
 export interface CssSelectorMatch {