@wix/zero-config-implementation 1.5.0

package/src/information-extractors/ts/components.ts

@@ -0,0 +1,300 @@
+import { type ComponentDoc, type PropItem, withCompilerOptions } from 'react-docgen-typescript'
+import ts from 'typescript'
+import type { ComponentInfo, DefaultValue, PropInfo } from './types'
+import { resolveType } from './utils/semantic-type-resolver'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared parser options
+// ─────────────────────────────────────────────────────────────────────────────
+
+const sharedPropFilter = (prop: PropItem) => {
+  // Exclude props inherited from node_modules (e.g. HTMLAttributes)
+  if (prop.declarations && prop.declarations.length > 0) {
+    return !prop.declarations.every((d) => d.fileName.includes('node_modules'))
+  }
+  return true
+}
+
+const sharedParserOptions = {
+  shouldRemoveUndefinedFromOptional: true,
+  shouldIncludePropTagMap: true,
+  skipChildrenPropWithoutDoc: true,
+  propFilter: sharedPropFilter,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main API
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function extractAllComponentInfo(program: ts.Program, filePath: string): ComponentInfo[] {
+  const checker = program.getTypeChecker()
+  const options = program.getCompilerOptions()
+
+  const parser = withCompilerOptions(options, sharedParserOptions)
+
+  const docs = parser.parseWithProgramProvider([filePath], () => program)
+
+  return docs.map((doc) => convertComponentDoc(doc, program, checker))
+}
+
+/**
+ * Extracts component info for only the default-exported component in a file.
+ * Returns `undefined` if the file has no default export or if the default export
+ * is not a recognized React component.
+ */
+export function extractDefaultComponentInfo(program: ts.Program, filePath: string): ComponentInfo | undefined {
+  const defaultName = findDefaultExportName(program, filePath)
+  if (!defaultName) return undefined
+
+  const all = extractAllComponentInfo(program, filePath)
+  return all.find((c) => c.componentName === defaultName)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default export resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolves the name of the default-exported symbol in a file using the
+ * TypeScript type checker.
+ *
+ * Returns `undefined` for anonymous default exports (e.g. `export default () => ...`)
+ * where no stable name can be determined.
+ */
+function findDefaultExportName(program: ts.Program, filePath: string): string | undefined {
+  const checker = program.getTypeChecker()
+  const sourceFile = program.getSourceFile(filePath)
+  if (!sourceFile) return undefined
+
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile)
+  if (!moduleSymbol) return undefined
+
+  const defaultSymbol = checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === 'default')
+  if (!defaultSymbol) return undefined
+
+  // For `export default Foo` the symbol is an alias — resolve it to get 'Foo'
+  if (defaultSymbol.getFlags() & ts.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(defaultSymbol)
+    const name = aliased.getName()
+    // 'default' means the alias resolved back to an anonymous default export
+    return name !== 'default' ? name : undefined
+  }
+
+  return undefined
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ComponentDoc → ComponentInfo conversion
+// ─────────────────────────────────────────────────────────────────────────────
+
+function convertComponentDoc(doc: ComponentDoc, program: ts.Program, checker: ts.TypeChecker): ComponentInfo {
+  const propsType = findPropsType(doc.displayName, doc.filePath, program, checker)
+  const props: Record<string, PropInfo> = {}
+
+  for (const [propName, propItem] of Object.entries(doc.props)) {
+    // Skip props marked with @ignore or @private
+    const tags = propItem.tags as Record<string, string> | undefined
+    if (tags?.ignore !== undefined || tags?.private !== undefined) {
+      continue
+    }
+
+    // Look up the ts.Symbol from the props type for deep resolution
+    const propSymbol = propsType?.getProperty(propName)
+    const propType = propSymbol ? checker.getTypeOfSymbol(propSymbol) : undefined
+
+    // Resolve the type deeply
+    let declaredTypeInfo: DeclaredTypeInfo | undefined
+    if (propSymbol) {
+      const decl = propSymbol.getDeclarations()?.[0]
+      if (decl) {
+        declaredTypeInfo = getDeclaredTypeInfo(propSymbol, decl.getSourceFile(), checker)
+      }
+    }
+
+    const typeString = declaredTypeInfo?.name ?? propItem.type.name
+    const resolvedType = propType
+      ? resolveType(propType, checker, 0, typeString, declaredTypeInfo?.symbol)
+      : { kind: 'primitive' as const, value: propItem.type.name }
+
+    // Convert default value
+    let defaultValue: DefaultValue | undefined
+    if (propItem.defaultValue != null) {
+      defaultValue = convertDefaultValue(propItem.defaultValue)
+    }
+
+    // If no runtime default, check @default JSDoc tag
+    if (!defaultValue && tags?.default) {
+      defaultValue = parseDefaultValueFromString(tags.default)
+    }
+
+    props[propName] = {
+      name: propName,
+      type: typeString,
+      required: propItem.required,
+      defaultValue,
+      resolvedType,
+      description: propItem.description || undefined,
+      deprecated: tags?.deprecated !== undefined ? true : undefined,
+    }
+  }
+
+  return { componentName: doc.displayName, props }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Find the props ts.Type for a component (needed for resolveType)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function findPropsType(
+  componentName: string,
+  filePath: string,
+  program: ts.Program,
+  checker: ts.TypeChecker,
+): ts.Type | undefined {
+  const sourceFile = program.getSourceFile(filePath)
+  if (!sourceFile) return undefined
+
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile)
+  if (!moduleSymbol) return undefined
+
+  const exports = checker.getExportsOfModule(moduleSymbol)
+  const componentSymbol = exports.find((s) => s.getName() === componentName)
+  if (!componentSymbol) return undefined
+
+  const componentType = checker.getTypeOfSymbol(componentSymbol)
+
+  // Function component: call signatures → first parameter is props
+  const callSigs = componentType.getCallSignatures()
+  if (callSigs.length > 0) {
+    const params = callSigs[0].getParameters()
+    if (params.length > 0) {
+      return checker.getTypeOfSymbol(params[0])
+    }
+  }
+
+  // Class component: construct signatures → first type argument is props
+  const constructSigs = componentType.getConstructSignatures()
+  if (constructSigs.length > 0) {
+    const params = constructSigs[0].getParameters()
+    if (params.length > 0) {
+      const propsParam = checker.getTypeOfSymbol(params[0])
+      return propsParam
+    }
+  }
+
+  // memo / forwardRef: check for the underlying call signature
+  // The type of memo(...) or forwardRef(...) wraps the inner component
+  const properties = componentType.getProperties()
+  for (const prop of properties) {
+    if (prop.getName() === 'type' || prop.getName() === 'render') {
+      const innerType = checker.getTypeOfSymbol(prop)
+      const innerSigs = innerType.getCallSignatures()
+      if (innerSigs.length > 0) {
+        const params = innerSigs[0].getParameters()
+        if (params.length > 0) {
+          return checker.getTypeOfSymbol(params[0])
+        }
+      }
+    }
+  }
+
+  return undefined
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default value conversion
+// ─────────────────────────────────────────────────────────────────────────────
+
+function convertDefaultValue(rdtDefault: { value: unknown } | null): DefaultValue | undefined {
+  if (!rdtDefault || rdtDefault.value == null) return undefined
+
+  const val = rdtDefault.value
+
+  // Already a primitive — react-docgen-typescript sometimes returns non-string values
+  if (typeof val === 'boolean') return { kind: 'boolean', value: val }
+  if (typeof val === 'number') return { kind: 'number', value: val }
+  if (typeof val !== 'string') return { kind: 'unresolved', value: String(val) }
+
+  // react-docgen-typescript strips quotes from string literal defaults,
+  // so 'ltr' becomes "ltr". Try parsing as a well-known literal first
+  // (true/false/null/number), otherwise treat as a string value.
+  return parseDefaultValueFromString(val, /* fallbackToString */ true)
+}
+
+/**
+ * Parses a string value (typically from JSDoc @default or react-docgen-typescript) into a DefaultValue.
+ * Attempts to parse as JSON-like literals, falls back to unresolved (or string if fallbackToString is true).
+ *
+ * @param fallbackToString — when true, unquoted non-literal values become `{ kind: 'string' }`
+ *   instead of `{ kind: 'unresolved' }`. Used for react-docgen-typescript defaults which are
+ *   always literals but arrive without surrounding quotes.
+ */
+function parseDefaultValueFromString(text: string, fallbackToString = false): DefaultValue {
+  const trimmed = text.trim()
+
+  // Boolean literals
+  if (trimmed === 'true') {
+    return { kind: 'boolean', value: true }
+  }
+  if (trimmed === 'false') {
+    return { kind: 'boolean', value: false }
+  }
+
+  // Null literal
+  if (trimmed === 'null') {
+    return { kind: 'null', value: null }
+  }
+
+  // Number literals (including negative)
+  const num = Number(trimmed)
+  if (!Number.isNaN(num) && trimmed !== '') {
+    return { kind: 'number', value: num }
+  }
+
+  // String literals: 'hello' or "hello"
+  if ((trimmed.startsWith("'") && trimmed.endsWith("'")) || (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+    return { kind: 'string', value: trimmed.slice(1, -1) }
+  }
+
+  // react-docgen-typescript strips quotes from string defaults, so treat as string
+  if (fallbackToString) {
+    return { kind: 'string', value: trimmed }
+  }
+
+  // Everything else is unresolved (e.g. JSDoc @default with a reference)
+  return { kind: 'unresolved', value: trimmed }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface DeclaredTypeInfo {
+  name: string
+  symbol?: ts.Symbol
+}
+
+function getDeclaredTypeInfo(
+  prop: ts.Symbol,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): DeclaredTypeInfo | undefined {
+  const declaration = prop.getDeclarations()?.[0]
+  if (!declaration) return undefined
+
+  if (
+    (ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration) || ts.isParameter(declaration)) &&
+    declaration.type &&
+    ts.isTypeReferenceNode(declaration.type)
+  ) {
+    const typeName = declaration.type.typeName
+    const identifier = ts.isIdentifier(typeName) ? typeName : typeName.right
+
+    return {
+      name: identifier.getText(sourceFile),
+      symbol: checker.getSymbolAtLocation(identifier),
+    }
+  }
+
+  return undefined
+}

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

@@ -0,0 +1,26 @@
+import * as path from 'node:path'
+import ts, { type Program } from 'typescript'
+
+export function extractCssImports(program: Program): string[] {
+  const cssFiles = new Set<string>()
+
+  for (const sourceFile of program.getSourceFiles()) {
+    // Skip external libraries
+    if (sourceFile.isDeclarationFile || sourceFile.fileName.includes('node_modules')) continue
+
+    ts.forEachChild(sourceFile, (node) => {
+      // Look for: import './style.css' or import x from './style.css'
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+        const importPath = node.moduleSpecifier.text
+
+        if (importPath.endsWith('.css')) {
+          // Resolve relative path to an absolute disk path
+          const fullPath = path.resolve(path.dirname(sourceFile.fileName), importPath)
+          cssFiles.add(fullPath)
+        }
+      }
+    })
+  }
+
+  return Array.from(cssFiles)
+}

package/src/information-extractors/ts/index.ts

@@ -0,0 +1,3 @@
+export { extractAllComponentInfo, extractDefaultComponentInfo } from './components'
+export { extractCssImports } from './css-imports'
+export type { ComponentInfo } from './types'

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

@@ -0,0 +1,56 @@
+/**
+ * API to extract component props with full TypeScript type resolution
+ */
+
+export type ResolvedKind =
+  | 'primitive'
+  | 'semantic'
+  | 'array'
+  | 'object'
+  | 'union'
+  | 'intersection'
+  | 'enum'
+  | 'literal'
+  | 'function'
+
+export interface ResolvedType {
+  kind: ResolvedKind
+  value?: unknown
+  /** For semantic types, the package the symbol came from */
+  source?: string
+  properties?: Record<string, PropInfo>
+  elementType?: ResolvedType
+  types?: ResolvedType[] // For unions and intersections
+}
+
+/**
+ * Resolved default value with its type.
+ * For literals (string, number, boolean, null), the value is the actual JavaScript value.
+ * For unresolvable values (references, expressions), we store the raw source text.
+ */
+export type DefaultValue =
+  | { kind: 'string'; value: string }
+  | { kind: 'number'; value: number }
+  | { kind: 'boolean'; value: boolean }
+  | { kind: 'null'; value: null }
+  | { kind: 'unresolved'; value: string } // For references like MY_CONST or complex expressions
+
+export interface PropInfo {
+  name: string
+  // The unresolved type. For example "string", "User".
+  type: string
+  required: boolean
+  // The resolved default value of the prop
+  defaultValue?: DefaultValue
+  // Describes the resolved type of the prop, recursively down to the primitive type.
+  resolvedType: ResolvedType
+  // Description extracted from JSDoc comment
+  description?: string
+  // Whether the prop is marked as deprecated via @deprecated JSDoc tag
+  deprecated?: boolean
+}
+
+export interface ComponentInfo {
+  componentName: string
+  props: Record<string, PropInfo>
+}