Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/lukebennett88/luke-ui. ui.lukebennett.dev
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677import { existsSync, readFileSync } from 'node:fs';import { dirname, resolve, sep } from 'node:path';import { parseSync } from 'oxc-parser';import type { ComponentGuideInventory } from './component-guide-inventory.js';
const EXPORTS_PREFIX = 'packages/@luke-ui/react/src/exports/';
interface AstNode { readonly type: string; readonly [key: string]: unknown;}
interface ParsedModule { path: string; program: AstNode;}
interface PublicExports { types: Map<string, Set<string>>; values: Map<string, Set<string>>;}
/** Checks a guide's `## API` component-props-table tags against object contracts from a public entry point and its local re-export chain. */export function findComponentPropsContractIssues( inventory: ComponentGuideInventory, reactPackageDir: string,): Array<string> { const issues: Array<string> = [];
for (const guide of inventory.guides) { if (guide.source === undefined || !guide.source.startsWith(EXPORTS_PREFIX)) continue;
const entryPath = resolve( reactPackageDir, 'src', 'exports', guide.source.slice(EXPORTS_PREFIX.length), ); if (!existsSync(entryPath)) continue;
issues.push(...findGuideIssues(guide.relativePath, guide.props, guide.source, entryPath)); }
return issues;}
function findGuideIssues( guidePath: string, documentedProps: ReadonlyArray<{ name: string }>, source: string, entryPath: string,): Array<string> { const entryModule = parseModule(entryPath); if (entryModule === undefined) return [];
const modules = localContractModules(entryModule); const publicTypes = publicTypeNames(modules); const modulesByPath = new Map(modules.map((module) => [module.module.path, module])); const required = new Set<string>(); const unsupported = new Set<string>();
for (const { module, values } of modules) { for (const signature of exportedSignatures(module.program, values)) { if (signature.unsupported) { for (const name of values.get(signature.name) ?? []) unsupported.add(name); continue; } for (const type of signature.types) { for (const name of publicObjectContract(module, type, modulesByPath)) required.add(name); } } }
const entryPoint = source; const documented = new Set(documentedProps.map((entry) => entry.name)); const issues: Array<string> = [];
for (const type of required) { if (documented.has(type)) continue; issues.push( `${guidePath}: entry point "${entryPoint}" requires public object contract "${type}" in the API section`, ); }
for (const type of documented) { if (publicTypes.has(type)) continue; issues.push( `${guidePath}: entry point "${entryPoint}" does not export API section type "${type}"`, ); }
for (const name of unsupported) { issues.push( `${guidePath}: entry point "${entryPoint}" has an unsupported exported signature "${name}"`, ); }
return issues;}
// Entries live under `src/exports/` (some nested, such as `src/exports/primitives/button.ts`), so// the traversal boundary is the `src/core` directory that sits alongside `exports` in the source// tree, found by walking up from the entry module to the `exports` segment.function srcDir(entryPath: string): string { const segments = entryPath.split(sep); const exportsIndex = segments.lastIndexOf('exports'); if (exportsIndex === -1) { throw new Error(`Expected an entry path under "src/exports/", received "${entryPath}".`); } return segments.slice(0, exportsIndex).join(sep);}
// Public names may be imported and re-exported by an intermediate file. Follow the public module// and implementation modules so the callable signature that is inspected is the one consumers// actually import. Do not follow other local modules such as generated data.function localContractModules( entryModule: ParsedModule,): Array<{ module: ParsedModule } & PublicExports> { const modules = new Map<string, { module: ParsedModule } & PublicExports>(); const entryExports = exportedNames(entryModule.program); modules.set(entryModule.path, { module: entryModule, ...entryExports }); const pending = [entryModule.path]; const coreDir = resolve(srcDir(entryModule.path), 'core');
while (pending.length > 0) { const path = pending.pop(); if (path === undefined) continue; const current = modules.get(path); if (current === undefined) continue;
for (const target of localReexports(current.module, current)) { if (modules.has(target.path)) { const existing = modules.get(target.path); if (existing !== undefined && mergePublicExports(existing, target)) pending.push(target.path); continue; }
const targetPath = target.path; if (targetPath.endsWith('.css.ts') || !isInsideDirectory(targetPath, coreDir)) continue;
const module = parseModule(targetPath); if (module === undefined) continue; modules.set(targetPath, { module, types: target.types, values: target.values }); pending.push(targetPath); } }
return [...modules.values()];}
function localReexports( module: ParsedModule, publicExports: PublicExports,): Array<{ path: string } & PublicExports> { const importedLocals = new Map<string, { name: string; source: string }>();
for (const statement of body(module.program)) { if (statement.type !== 'ImportDeclaration') continue; const source = literalString(statement.source); if (source === undefined || !source.startsWith('.')) continue;
for (const specifier of nodes(statement.specifiers)) { const local = identifierName(specifier.local); const imported = identifierName(specifier.imported); if (local !== undefined && imported !== undefined) { importedLocals.set(local, { name: imported, source }); } } }
const reexports = new Map<string, { path: string } & PublicExports>();
for (const statement of body(module.program)) { if (statement.type === 'ExportAllDeclaration') { const source = literalString(statement.source); if (source === undefined || !source.startsWith('.')) continue; addWildcardReexport(reexports, resolveLocalModule(module.path, source)); continue; } if (statement.type !== 'ExportNamedDeclaration') continue; const source = literalString(statement.source);
if (source !== undefined) { if (!source.startsWith('.')) continue; addReexportedNames( reexports, resolveLocalModule(module.path, source), statement, publicExports, ); continue; }
for (const specifier of nodes(statement.specifiers)) { const local = identifierName(specifier.local); if (local === undefined) continue; const imported = importedLocals.get(local); if (imported === undefined) continue; addReexportedName( reexports, resolveLocalModule(module.path, imported.source), imported.name, specifier, publicExports, statement, ); } }
return [...reexports.values()];}
function addWildcardReexport( reexports: Map<string, { path: string } & PublicExports>, path: string,): void { const module = parseModule(path); if (module === undefined) return;
const exported = exportedNames(module.program); const reexport = reexports.get(path) ?? { path, types: new Map(), values: new Map() }; mergePublicExports(reexport, exported); reexports.set(path, reexport);}
function addReexportedNames( reexports: Map<string, { path: string } & PublicExports>, path: string, statement: AstNode, publicExports: PublicExports,): void { for (const specifier of nodes(statement.specifiers)) { const local = identifierName(specifier.local); if (local === undefined) continue; addReexportedName(reexports, path, local, specifier, publicExports, statement); }}
function addReexportedName( reexports: Map<string, { path: string } & PublicExports>, path: string, targetName: string, specifier: AstNode, publicExports: PublicExports, statement: AstNode,): void { const local = identifierName(specifier.local); const exported = identifierName(specifier.exported); if (local === undefined || exported === undefined) return; const kind = exportKind(statement, specifier); const provenance = kind === 'type' ? publicExports.types : publicExports.values; const names = provenance.get(exported) ?? provenance.get(local); if (names === undefined) return;
const reexport = reexports.get(path) ?? { path, types: new Map(), values: new Map() }; for (const name of names) addPublicName(reexport[kind === 'type' ? 'types' : 'values'], targetName, name); reexports.set(path, reexport);}
function resolveLocalModule(entryPath: string, specifier: string): string { const base = resolve(dirname(entryPath), specifier.replace(/\.js$/, '')); for (const extension of ['.ts', '.tsx', '.css.ts', '.css.tsx']) { const path = `${base}${extension}`; if (existsSync(path)) return path; } return `${base}.ts`;}
function mergePublicExports(target: PublicExports, source: PublicExports): boolean { const typesChanged = mergePublicNames(target.types, source.types); const valuesChanged = mergePublicNames(target.values, source.values); return typesChanged || valuesChanged;}
function mergePublicNames( target: Map<string, Set<string>>, source: ReadonlyMap<string, ReadonlySet<string>>,): boolean { let changed = false; for (const [local, exported] of source) { for (const name of exported) { if (addPublicName(target, local, name)) changed = true; } } return changed;}
function addPublicName(names: Map<string, Set<string>>, local: string, exported: string): boolean { const existing = names.get(local); if (existing !== undefined) { if (existing.has(exported)) return false; existing.add(exported); return true; } names.set(local, new Set([exported])); return true;}
function exportKind(statement: AstNode, specifier: AstNode): 'type' | 'value' { return stringValue(statement.exportKind) === 'type' || stringValue(specifier.exportKind) === 'type' ? 'type' : 'value';}
function parseModule(path: string): ParsedModule | undefined { if (!existsSync(path)) return; const result = parseSync(path, readFileSync(path, 'utf8')); if (result.errors.length > 0) return; return { path, program: result.program as unknown as AstNode };}
function exportedNames(program: AstNode): PublicExports { const types = new Map<string, Set<string>>(); const values = new Map<string, Set<string>>();
for (const statement of body(program)) { if (statement.type !== 'ExportNamedDeclaration') continue;
const declaration = astNode(statement.declaration); if (declaration !== undefined) { const name = declarationName(declaration); if (name !== undefined) addPublicName(declarationKind(declaration) === 'type' ? types : values, name, name); }
for (const specifier of nodes(statement.specifiers)) { const local = identifierName(specifier.local); const exported = identifierName(specifier.exported); if (local !== undefined && exported !== undefined) { addPublicName( exportKind(statement, specifier) === 'type' ? types : values, local, exported, ); } } }
return { types, values };}
function publicTypeNames(modules: ReadonlyArray<PublicExports>): Set<string> { const names = new Set<string>(); for (const { types } of modules) { for (const exported of types.values()) { for (const name of exported) names.add(name); } } return names;}
function publicObjectContract( module: ParsedModule, name: string, modules: ReadonlyMap<string, { module: ParsedModule } & PublicExports>, seen: Set<string> = new Set(),): ReadonlySet<string> { const key = `${module.path}:${name}`; if (seen.has(key)) return new Set(); seen.add(key);
const publicNames = modules.get(module.path)?.types.get(name); const declarations = typeDeclarations(module); const declaration = declarations.get(name); if (publicNames !== undefined && declaration !== undefined) { return isObjectType(declaration, name, declarations) ? publicNames : new Set(); }
const imported = importedType(module, name); if (imported !== undefined) { const target = modules.get(resolveLocalModule(module.path, imported.source)); if (target !== undefined) return publicObjectContract(target.module, imported.name, modules, seen); }
const reexported = reexportedType(module, name); if (reexported !== undefined) { const target = modules.get(resolveLocalModule(module.path, reexported.source)); if (target !== undefined) return publicObjectContract(target.module, reexported.name, modules, seen); }
return new Set();}
function importedType( module: ParsedModule, name: string,): { name: string; source: string } | undefined { for (const statement of body(module.program)) { if (statement.type !== 'ImportDeclaration') continue; const source = literalString(statement.source); if (source === undefined || !source.startsWith('.')) continue;
for (const specifier of nodes(statement.specifiers)) { if (identifierName(specifier.local) !== name) continue; const imported = identifierName(specifier.imported); if (imported !== undefined) return { name: imported, source }; } }}
function reexportedType( module: ParsedModule, name: string,): { name: string; source: string } | undefined { for (const statement of body(module.program)) { if (statement.type !== 'ExportNamedDeclaration') continue; const source = literalString(statement.source); if (source === undefined || !source.startsWith('.')) continue;
for (const specifier of nodes(statement.specifiers)) { if ( exportKind(statement, specifier) !== 'type' || identifierName(specifier.exported) !== name ) { continue; } const local = identifierName(specifier.local); if (local !== undefined) return { name: local, source }; } }}
function typeDeclarations(module: ParsedModule): Map<string, AstNode> { const declarations = new Map<string, AstNode>();
for (const statement of body(module.program)) { const declaration = statement.type === 'ExportNamedDeclaration' ? astNode(statement.declaration) : statement; if (declaration === undefined || declarationKind(declaration) !== 'type') continue; const name = declarationName(declaration); if (name !== undefined) declarations.set(name, declaration); }
return declarations;}
function isObjectType( declaration: AstNode, name: string, declarations: ReadonlyMap<string, AstNode>, seen: Set<string> = new Set(), substitutions: ReadonlyMap<string, AstNode> = new Map(),): boolean { if (name.endsWith('RecipeVariants')) return false; if (declaration.type === 'TSInterfaceDeclaration') return true; if (declaration.type !== 'TSTypeAliasDeclaration') return false; if (seen.has(name)) return false; seen.add(name);
return isObjectAnnotation(astNode(declaration.typeAnnotation), declarations, substitutions, seen);}
// Follow a local alias, substituting type parameters. Names outside this module stay object-shaped.function isObjectAnnotation( annotation: AstNode | undefined, declarations: ReadonlyMap<string, AstNode>, substitutions: ReadonlyMap<string, AstNode>, seen: Set<string>,): boolean { if (annotation === undefined) return false; if ( annotation.type === 'TSTypeLiteral' || annotation.type === 'TSIntersectionType' || annotation.type === 'TSMappedType' ) { return true; } if (annotation.type !== 'TSTypeReference') return false;
const name = identifierName(annotation.typeName); if (name === undefined) return true;
if (!hasTypeArguments(annotation)) { const substituted = substitutions.get(name); if (substituted !== undefined) { return isObjectAnnotation(substituted, declarations, substitutions, seen); } }
const target = declarations.get(name); if (target === undefined) return true; return isObjectType( target, name, declarations, seen, bindTypeParameters(target, annotation, substitutions), );}
function bindTypeParameters( declaration: AstNode, reference: AstNode, substitutions: ReadonlyMap<string, AstNode>,): Map<string, AstNode> { const names = typeParameterNames(declaration); const args = nodes(astNode(reference.typeArguments)?.params); const bound = new Map<string, AstNode>();
for (const [index, name] of names.entries()) { const argument = args[index]; if (argument === undefined) continue; bound.set(name, resolveSubstitutions(argument, substitutions)); }
return bound;}
function typeParameterNames(declaration: AstNode): ReadonlyArray<string> { return nodes(astNode(declaration.typeParameters)?.params).flatMap((parameter) => { const name = identifierName(parameter.name); return name === undefined ? [] : [name]; });}
function resolveSubstitutions( annotation: AstNode, substitutions: ReadonlyMap<string, AstNode>,): AstNode { const seen = new Set<string>(); let current = annotation;
while (current.type === 'TSTypeReference' && !hasTypeArguments(current)) { const name = identifierName(current.typeName); if (name === undefined || seen.has(name)) break; seen.add(name); const next = substitutions.get(name); if (next === undefined) break; current = next; }
return current;}
function hasTypeArguments(node: AstNode): boolean { const typeArguments = astNode(node.typeArguments); return typeArguments !== undefined && nodes(typeArguments.params).length > 0;}
function exportedSignatures( program: AstNode, publicValues: ReadonlyMap<string, ReadonlySet<string>>,): Array<{ name: string; types: ReadonlySet<string>; unsupported: boolean;}> { const signatures: Array<{ name: string; types: ReadonlySet<string>; unsupported: boolean }> = [];
for (const statement of body(program)) { if (statement.type !== 'ExportNamedDeclaration') continue; const declaration = astNode(statement.declaration); if (declaration === undefined) continue;
if (declaration.type === 'FunctionDeclaration') { const name = declarationName(declaration); if (name !== undefined && publicValues.has(name)) { signatures.push({ name, types: signatureTypeNames(declaration), unsupported: false }); } continue; }
if (declaration.type !== 'VariableDeclaration') continue; for (const declarator of nodes(declaration.declarations)) { const name = identifierName(declarator.id); if (name === undefined || !publicValues.has(name)) continue; const initializer = astNode(declarator.init); if ( initializer?.type === 'ArrowFunctionExpression' || initializer?.type === 'FunctionExpression' ) { signatures.push({ name, types: signatureTypeNames(initializer), unsupported: false }); } else if (isFunctionType(typeAnnotation(astNode(declarator.id)))) { signatures.push({ name, types: new Set(), unsupported: true }); } } }
return signatures;}
function signatureTypeNames(signature: AstNode): Set<string> { const names = new Set<string>();
for (const parameter of nodes(astNode(signature.typeParameters)?.params)) { addTypeReferences(names, astNode(parameter.constraint)); } for (const parameter of nodes(signature.params)) { addTypeReferences(names, typeAnnotation(parameter)); } addTypeReferences(names, typeAnnotation(astNode(signature.returnType)));
return names;}
function isFunctionType(node: AstNode | undefined): boolean { return node?.type === 'TSFunctionType' || node?.type === 'TSConstructorType';}
function isInsideDirectory(filePath: string, directory: string): boolean { const dir = resolve(directory); const file = resolve(filePath); return file === dir || file.startsWith(`${dir}${sep}`);}
function typeAnnotation(node: AstNode | undefined): AstNode | undefined { if (node === undefined) return; if (node.type === 'AssignmentPattern') return typeAnnotation(astNode(node.left)); if (node.type === 'RestElement') return typeAnnotation(astNode(node.argument)); const annotation = astNode(node.typeAnnotation); if (annotation?.type === 'TSTypeAnnotation') return astNode(annotation.typeAnnotation); return annotation;}
function addTypeReferences(names: Set<string>, node: AstNode | undefined): void { if (node === undefined) return; if (node.type === 'TSTypeReference') { const name = identifierName(node.typeName); if (name !== undefined) names.add(name); }
for (const value of Object.values(node)) { if (Array.isArray(value)) { for (const child of value) addTypeReferences(names, astNode(child)); } else { addTypeReferences(names, astNode(value)); } }}
function declarationKind(declaration: AstNode): 'type' | 'value' { return declaration.type === 'TSInterfaceDeclaration' || declaration.type === 'TSTypeAliasDeclaration' ? 'type' : 'value';}
function declarationName(declaration: AstNode): string | undefined { if (declaration.type === 'VariableDeclaration') return; return identifierName(declaration.id);}
function body(program: AstNode): ReadonlyArray<AstNode> { return nodes(program.body);}
function nodes(value: unknown): ReadonlyArray<AstNode> { return Array.isArray(value) ? value.flatMap((entry) => (astNode(entry) === undefined ? [] : [entry])) : [];}
function astNode(value: unknown): AstNode | undefined { if (typeof value !== 'object' || value === null || !('type' in value)) return; const candidate = value as { type?: unknown }; return typeof candidate.type === 'string' ? (value as AstNode) : undefined;}
function identifierName(value: unknown): string | undefined { const node = astNode(value); return node?.type === 'Identifier' ? stringValue(node.name) : undefined;}
function literalString(value: unknown): string | undefined { const node = astNode(value); return node?.type === 'Literal' ? stringValue(node.value) : undefined;}
function stringValue(value: unknown): string | undefined { return typeof value === 'string' ? value : undefined;}