import fs from 'node:fs'; import path from 'node:path'; import { escapePath, globSync } from 'tinyglobby'; import ts from 'typescript'; import { ELEMENT_INTERFACES, originOf, registerPropSet, unwrapParens, } from '../extract/components.js'; import { projectFiles, type ProjectConfig } from '../extract/program.js'; import type { ComponentInfo, InheritedProps, PropInfo, VariantInfo } from '../types.js'; import { isInside, relativePath } from '../util/paths.js'; import { truncate, unique } from '../util/strings.js'; import type { DeclarationsAdapter } from './index.js'; export interface ExtractLibraryOptions { root: string; adapter: DeclarationsAdapter; /** The installed package's folder, as found (it may be a link, as pnpm installs it). */ dir: string; project: ProjectConfig; /** The app's files that augment the library's types, read with its declarations. */ augmentations: string[]; } export interface LibraryExtraction { components: ComponentInfo[]; propSets: Record; /** Every value the package exports, components or not (`createTheme`, `ButtonGroupContext`). */ exports: string[]; warnings: string[]; /** Project files read: the augmentations and the modules they import. */ dependencies: string[]; } /** A component's name: a capitalised identifier (`Button`, `ButtonBase`, `Unstable_Grid2`). */ const COMPONENT_NAME = /^[A-Z][\w$]*$/; /** Packages contributing more props than this are summarised, as in source extraction. */ const MAX_LISTED_INHERITED = 40; /** * Reads a published library's components from its type declarations with the TypeScript * checker: every value its entry exports under a capitalised name whose type takes props and * renders (function and class components, `forwardRef` and MUI's `OverridableComponent`), with * the props of each call signature, their string-literal values (custom ones the app declares by * module augmentation included), JSDoc, the element it renders, and the module that * default-exports it. A signature generic over the element to render (MUI's `component`) marks * that prop as polymorphic instead of adding its props. */ export function extractLibrary(options: ExtractLibraryOptions): LibraryExtraction { const { root, adapter, dir } = options; const warnings: string[] = []; const empty = (warning: string): LibraryExtraction => ({ components: [], propSets: {}, exports: [], warnings: [warning], dependencies: [], }); // As TypeScript spells the files it resolves: the path the file system returns, with Windows' // long names for short ones (`RUNNER~1`) and the case on disk. let real: string; try { real = fs.realpathSync.native(dir); } catch { return empty(`${adapter.package}: ${dir} could not be read`); } // The declarations the app's own imports resolve to, through the package's `exports`: MUI // ships `.d.mts` for `import` beside `.d.ts`, and augmentations apply to the ones resolved. const resolve = (specifier: string) => ts.resolveModuleName( specifier, path.join(root, '__onsystem__.tsx'), options.project.options, ts.sys, ).resolvedModule?.resolvedFileName; // The package's entry; without one (`exports` with only `./button` and `./card`), each subpath's. const main = resolve(adapter.package) ?? path.join(real, typesEntry(real)); const entries = isDeclarations(main) ? [{ specifier: adapter.package, file: main }] : subpathEntries(real, adapter.package, resolve); if (!entries.length) { return empty(`${adapter.package}: no type declarations at ${relativePath(root, main)}`); } const program = ts.createProgram({ rootNames: [...entries.map((e) => e.file), ...options.augmentations], options: options.project.options, host: declarationsHost(options.project.options), }); const checker = program.getTypeChecker(); const modules = entries.flatMap((e) => { const file = program.getSourceFile(e.file); const symbol = file ? checker.getSymbolAtLocation(file) : undefined; return symbol ? [{ ...e, symbol }] : []; }); if (!modules.length) { return empty(`${adapter.package}: ${entries[0]?.file ?? main} has no exports`); } // Where a file is, as the app sees the package (`node_modules/@mui/material/…`). const shown = (file: string) => { const absolute = path.resolve(file); return relativePath( root, isInside(real, absolute) ? path.join(dir, path.relative(real, absolute)) : absolute, ); }; const context: Context = { checker, adapter, propSets: new Map(), scope: adapter.package.startsWith('@') ? `${adapter.package.split('/')[0] ?? ''}/` : adapter.package, icons: new Set(), }; const exportNames = new Set(); const bySymbol = new Map(); const components: ComponentInfo[] = []; for (const module of modules) { const subpath = module.specifier !== adapter.package; for (const exported of checker.getExportsOfModule(module.symbol)) { const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported; if (!(symbol.flags & ts.SymbolFlags.Value)) continue; const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0]; // A subpath's default export goes by the name it is declared with: `Button` for // `export default Button` in `@acme/ui/button`. Unnamed, it is no component to offer. const isDefault = exported.getName() === 'default'; const name = isDefault && subpath && declaration ? (ts.getNameOfDeclaration(declaration)?.getText() ?? 'default') : exported.getName(); if (isDefault && !COMPONENT_NAME.test(name)) continue; exportNames.add(name); // A component's name is a capitalised identifier, as JSX writes it. An export under a string // name (`export { Other as "Any text" }`, ES2022) can hold any text, a line break too: no // component, since JSX cannot name it, and its name would start lines of the answers. if (!COMPONENT_NAME.test(name)) continue; const known = bySymbol.get(symbol); if (known) { if (known.name !== name && !known.aliases.includes(name)) known.aliases.push(name); continue; } if (!declaration) continue; const component = buildComponent(context, name, symbol); if (!component) continue; const file = declaration.getSourceFile(); const line = file.getLineAndCharacterOfPosition(declaration.getStart(file)).line + 1; component.source = { file: shown(file.fileName), line }; if (subpath) component.importPath = module.specifier; const defaultImport = isDefault ? module.specifier : defaultModule(program, checker, resolve, adapter.package, file, symbol); if (defaultImport) component.defaultImport = defaultImport; bySymbol.set(symbol, component); components.push(component); } } linkSlots(components, context.icons); return { components, propSets: Object.fromEntries(context.propSets), exports: [...exportNames].sort(), warnings, dependencies: unique(projectFiles(program)), }; } interface Context { checker: ts.TypeChecker; adapter: DeclarationsAdapter; propSets: Map; /** Props declared by these packages are the component's own: `@mui/`. */ scope: string; /** The components that render an SVG element: icons, which are no part of another component. */ icons: Set; } /** * A compiler host that resolves what the app's own resolution leaves unresolved in a package's * declarations by path, as Node.js's old resolution does. A bundler emits declarations that * import a dependency's file by its path (`class-variance-authority/dist/types`, for the * `ClassProp` behind every `cva()` variant), which that dependency's `exports` do not name: with * `"moduleResolution": "bundler"` the import is `any`, and a component's variants and props go * with it. The app's own files resolve as they do for tsc. */ function declarationsHost(options: ts.CompilerOptions): ts.CompilerHost { const host = ts.createCompilerHost(options); const cache = ts.createModuleResolutionCache( host.getCurrentDirectory(), (file) => host.getCanonicalFileName(file), options, ); const byPath: ts.CompilerOptions = { ...options, // eslint-disable-next-line @typescript-eslint/no-deprecated -- the resolution by path that such an import needs; TypeScript 6 still has it. moduleResolution: ts.ModuleResolutionKind.Node10, }; host.resolveModuleNameLiterals = (literals, containingFile, redirected, compilerOptions, file) => literals.map((literal) => { const resolved = ts.resolveModuleName( literal.text, containingFile, compilerOptions, host, cache, redirected, ts.getModeForUsageLocation(file, literal, compilerOptions), ); if ( resolved.resolvedModule || !/[\\/]node_modules[\\/].*\.d\.[cm]?ts$/.test(containingFile) ) { return resolved; } const fallback = ts.resolveModuleName(literal.text, containingFile, byPath, host); return fallback.resolvedModule && /\.d\.[cm]?ts$/.test(fallback.resolvedModule.resolvedFileName) ? fallback : resolved; }); return host; } /** The declaration entry of an installed package: its `types`, else `index.d.ts`. */ function typesEntry(dir: string): string { try { const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) as { types?: unknown; typings?: unknown; }; const types = typeof pkg.types === 'string' ? pkg.types : pkg.typings; if (typeof types === 'string' && types.endsWith('.d.ts')) return types; } catch { // No readable package.json: the conventional entry. } return 'index.d.ts'; } /** A type declarations file on disk: `.d.ts`, `.d.mts` or `.d.cts`. */ function isDeclarations(file: string): boolean { return /\.d\.[cm]?ts$/.test(file) && fs.existsSync(file); } /** Packages exporting more subpaths than this are read from the first ones, sorted. */ const MAX_SUBPATHS = 500; /** * The declarations of each subpath a package without an entry of its own exports (`./button`, * `./card`, or the files a `./*` pattern maps), with the specifier apps import it by * (`@acme/ui/button`): as the app's own imports resolve it, else through the `types` condition * its `exports` give it. Subpaths that name no declarations (`./theme.css`) are left out. */ function subpathEntries( dir: string, name: string, resolve: (specifier: string) => string | undefined, ): { specifier: string; file: string }[] { let exports: unknown; try { exports = ( JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) as { exports?: unknown; } ).exports; } catch { return []; } if (!exports || typeof exports !== 'object' || Array.isArray(exports)) return []; const found = new Map(); const add = (subpath: string, target: string | undefined) => { const specifier = `${name}/${subpath}`; const file = resolve(specifier) ?? (target ? path.resolve(dir, target) : undefined); if (file && isInside(dir, path.resolve(file)) && isDeclarations(file)) { found.set(specifier, file); } }; for (const [key, value] of Object.entries(exports as Record)) { if (!key.startsWith('./') || key === './package.json') continue; const target = typesTarget(value); const star = key.indexOf('*'); if (star === -1) { add(key.slice(2), target); continue; } // A pattern: each declarations file its `types` target matches, by what `*` stands for. const at = target?.indexOf('*') ?? -1; if (!target || at === -1) continue; const prefix = path.posix.normalize(target.slice(0, at)).replace(/^\.\//, ''); const suffix = target.slice(at + 1); // `*` stands for any path, folders included: every file below the folder the prefix is in. const folder = prefix.slice(0, prefix.lastIndexOf('/') + 1); const files = globSync(`${escapePath(folder)}**/*${escapePath(suffix)}`, { cwd: dir, ignore: ['**/node_modules/**'], expandDirectories: false, }); for (const file of files.sort()) { if (!file.startsWith(prefix) || !file.endsWith(suffix)) continue; const middle = file.slice(prefix.length, file.length - suffix.length); add(`${key.slice(2, star)}${middle}${key.slice(star + 1)}`, path.join(dir, file)); } } return [...found] .sort(([a], [b]) => a.localeCompare(b)) .slice(0, MAX_SUBPATHS) .map(([specifier, file]) => ({ specifier, file })); } /** The first `types` target an `exports` value gives, through nested conditions. */ function typesTarget(value: unknown): string | undefined { if (Array.isArray(value)) { for (const item of value) { const found = typesTarget(item); if (found) return found; } return undefined; } if (!value || typeof value !== 'object') return undefined; for (const [condition, nested] of Object.entries(value)) { if (condition === 'types' && typeof nested === 'string') return nested; const found = typesTarget(nested); if (found) return found; } return undefined; } /** * Call and construct signatures that take props and render, across a union * (`React.ComponentType`): a call that returns an element, and a class whose instances have * `render`. A capitalised function that returns anything else (`Format(value): string`) is no * component. */ function propSignatures(checker: ts.TypeChecker, type: ts.Type): ts.Signature[] { const members = type.isUnion() ? type.types : [type]; return members .flatMap((member) => [ ...member .getCallSignatures() .filter((s) => rendersElement(checker, checker.getReturnTypeOfSignature(s))), ...member .getConstructSignatures() .filter( (s) => checker.getPropertyOfType(checker.getReturnTypeOfSignature(s), 'render') !== undefined, ), ]) .filter((signature) => signature.getParameters().length >= 1); } /** * Whether a call's return type is what a component returns: a React element (`JSX.Element`, * `ReactElement`), a `ReactNode` that can be one, a promise of one (a server component), or * nothing (`null`). `any`, where React's types do not resolve, counts. */ function rendersElement(checker: ts.TypeChecker, type: ts.Type): boolean { if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Null)) return true; const members = (type.isUnion() ? type.types : [type]).filter( (member) => !(member.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)), ); if (!members.length) return true; return members.some((member) => { if (member.flags & ts.TypeFlags.Any) return true; if ( checker.getPropertyOfType(member, 'props') !== undefined && checker.getPropertyOfType(member, 'type') !== undefined ) { return true; } const awaited = checker.getPropertyOfType(member, 'then') ? checker.getAwaitedType(member) : undefined; return awaited !== undefined && awaited !== member && rendersElement(checker, awaited); }); } /** A conditional type the checker cannot resolve yet, or a union or intersection with one. */ function hasConditional(type: ts.Type): boolean { if (type.flags & ts.TypeFlags.Conditional) return true; return type.isUnionOrIntersection() && type.types.some((member) => hasConditional(member)); } /** A React context (`ButtonGroupContext`): callable in React 19's types, but not a component to offer. */ function isContext(checker: ts.TypeChecker, type: ts.Type): boolean { return ( checker.getPropertyOfType(type, 'Provider') !== undefined && checker.getPropertyOfType(type, 'Consumer') !== undefined ); } /** * The prop a generic signature renders in the component's place (`component: RootComponent` * where `RootComponent extends React.ElementType`), which then takes that element's props. */ function polymorphicProp( checker: ts.TypeChecker, signature: ts.Signature, ): { name: string; symbol: ts.Symbol } | undefined { const parameters = signature.getTypeParameters(); if (!parameters?.length) return undefined; const props = signature.getParameters()[0]; if (!props) return undefined; for (const prop of checker.getPropertiesOfType(checker.getTypeOfSymbol(props))) { const type = checker.getNonNullableType(checker.getTypeOfSymbol(prop)); if (!(type.flags & ts.TypeFlags.TypeParameter)) continue; const declaration = type.symbol.declarations?.find(ts.isTypeParameterDeclaration); if ( parameters.includes(type) && declaration?.constraint && /\bElementType\b/.test(declaration.constraint.getText()) ) { return { name: prop.getName(), symbol: prop }; } } return undefined; } interface PropEntry { symbols: ts.Symbol[]; required: number; origin: string; } function buildComponent( context: Context, name: string, symbol: ts.Symbol, ): ComponentInfo | undefined { const { checker, adapter } = context; const type = checker.getTypeOfSymbol(symbol); if (isContext(checker, type)) return undefined; const signatures = propSignatures(checker, type); if (!signatures.length) return undefined; let polymorphic: { name: string; symbol: ts.Symbol } | undefined; const plain: ts.Signature[] = []; for (const signature of signatures) { const prop = polymorphicProp(checker, signature); if (prop) polymorphic ??= prop; else plain.push(signature); } const used = plain.length ? plain : signatures; // Every prop any of its signatures takes: `