Skip to content

UI Library for Design Engineers. Animated components and effects you can copy and paste into your apps. Free. Open Source.

19.3 KB
Raw Blame
import { promises as fs } from "node:fs"
import path from "node:path"
import process from "node:process"
import { fileURLToPath } from "node:url"

import { CodeBlockWriter, Node, Project, SyntaxKind } from "ts-morph"

const MAGICUI_IMPORT_PREFIX = "@/registry/magicui/"
const MAGICUI_PACKAGE_PREFIX = "@magicui/"
const EXAMPLE_IMPORT_PREFIX = "@/registry/example/"
const REGISTRY_IMPORT_PREFIX = "@/registry/"

const scriptPath = fileURLToPath(import.meta.url)
const appRoot = path.resolve(path.dirname(scriptPath), "..")
const registryRoot = path.join(appRoot, "registry")
const registryExamplesPath = path.join(registryRoot, "registry-examples.ts")
const registryUiPath = path.join(registryRoot, "registry-ui.ts")

type SyncMode = "check" | "fix"

type SyncOptions = {
  mode: SyncMode
}

type ExampleIssue = {
  exampleName: string
  exampleFiles: string[]
  extraDependencies: string[]
  missingDependencies: string[]
  missingFiles: string[]
}

// Detect direct CLI execution so this module can also be imported by builds.
function isMainModule() {
  return process.argv[1]
    ? path.resolve(process.argv[1]) === scriptPath
    : false
}

// Read plain string values from string literals and template literals.
function getStringLiteralValue(node: Node | undefined) {
  if (!node) {
    return null
  }

  if (
    Node.isStringLiteral(node) ||
    Node.isNoSubstitutionTemplateLiteral(node)
  ) {
    return node.getLiteralText()
  }

  return null
}

// Resolve a named object property when it exists as a simple assignment.
function getObjectPropertyAssignment(
  node: Node,
  propertyName: string
): Node | undefined {
  if (!Node.isObjectLiteralExpression(node)) {
    return undefined
  }

  const property = node.getProperty(propertyName)
  if (!property || !Node.isPropertyAssignment(property)) {
    return undefined
  }

  return property
}

// Extract string items from array properties like registryDependencies.
function getStringArrayValues(node: Node | undefined) {
  if (!node || !Node.isPropertyAssignment(node)) {
    return []
  }

  const initializer = node.getInitializer()
  if (!initializer || !Node.isArrayLiteralExpression(initializer)) {
    return []
  }

  return initializer
    .getElements()
    .flatMap((element) => {
      const value = getStringLiteralValue(element)
      return value ? [value] : []
    })
}

// Collect referenced .tsx files from an example's files array.
function getExampleFilePaths(node: Node) {
  const filesProperty = getObjectPropertyAssignment(node, "files")
  if (!filesProperty || !Node.isPropertyAssignment(filesProperty)) {
    return []
  }

  const initializer = filesProperty.getInitializer()
  if (!initializer || !Node.isArrayLiteralExpression(initializer)) {
    return []
  }

  return initializer
    .getElements()
    .flatMap((element) => {
      const stringPath = getStringLiteralValue(element)
      if (stringPath) {
        return [stringPath]
      }

      if (!Node.isObjectLiteralExpression(element)) {
        return []
      }

      const pathProperty = getObjectPropertyAssignment(element, "path")
      if (!pathProperty || !Node.isPropertyAssignment(pathProperty)) {
        return []
      }

      const filePath = getStringLiteralValue(pathProperty.getInitializer())
      return filePath ? [filePath] : []
    })
    .filter((filePath) => filePath.endsWith(".tsx"))
}

// Read the registry item name for reporting.
function getRegistryItemName(node: Node) {
  const nameProperty = getObjectPropertyAssignment(node, "name")
  if (!nameProperty || !Node.isPropertyAssignment(nameProperty)) {
    return "unknown"
  }

  return getStringLiteralValue(nameProperty.getInitializer()) ?? "unknown"
}

// Read the registry item type so only examples are processed.
function getRegistryItemType(node: Node) {
  const typeProperty = getObjectPropertyAssignment(node, "type")
  if (!typeProperty || !Node.isPropertyAssignment(typeProperty)) {
    return null
  }

  return getStringLiteralValue(typeProperty.getInitializer())
}

// Read a registry array declaration like examples/ui so items can be inspected.
function getRegistryItemsDeclaration(sourceFile: Node, declarationName: string) {
  if (!Node.isSourceFile(sourceFile)) {
    return null
  }

  const declaration = sourceFile.getVariableDeclaration(declarationName)
  const initializer = declaration?.getInitializer()
  if (!initializer || !Node.isArrayLiteralExpression(initializer)) {
    return null
  }

  return initializer
}

// Preserve insertion order while removing duplicates.
function dedupe(values: string[]) {
  const seen = new Set<string>()

  return values.filter((value) => {
    if (seen.has(value)) {
      return false
    }

    seen.add(value)
    return true
  })
}

// Convert local registry imports into namespaced registry dependency ids.
function getRegistryDependencyName(moduleSpecifier: string) {
  const prefix = [MAGICUI_IMPORT_PREFIX, EXAMPLE_IMPORT_PREFIX].find((value) =>
    moduleSpecifier.startsWith(value)
  )

  if (!prefix) {
    return null
  }

  const itemName = moduleSpecifier.slice(prefix.length)
  if (!itemName) {
    return null
  }

  return `${MAGICUI_PACKAGE_PREFIX}${itemName}`
}

// Map registry source files back to their published registry dependency ids.
function getRegistryDependencyNameFromFilePath(filePath: string) {
  const registryItemRoots = [
    path.join(registryRoot, "magicui"),
    path.join(registryRoot, "example"),
  ]

  const matchingRoot = registryItemRoots.find((rootPath) => {
    const relativePath = path.relative(rootPath, filePath)
    return !relativePath.startsWith("..") && !path.isAbsolute(relativePath)
  })

  if (!matchingRoot) {
    return null
  }

  const relativePath = path.relative(matchingRoot, filePath)

  if (
    !/\.(ts|tsx)$/.test(relativePath)
  ) {
    return null
  }

  const packageName = relativePath
    .replace(/\.(ts|tsx)$/, "")
    .split(path.sep)
    .join("/")

  return `${MAGICUI_PACKAGE_PREFIX}${packageName}`
}

// Limit exact matching to magicui package entries and leave other deps alone.
function isMagicUiPackage(dependency: string) {
  return dependency.startsWith(MAGICUI_PACKAGE_PREFIX)
}

// Infer the primary UI package from example naming conventions like confetti-fireworks.
function inferRegistryDependenciesFromExampleName(
  exampleName: string,
  registryUiNames: string[]
) {
  const matchingUiNames = registryUiNames
    .filter((uiName) => {
      return exampleName === uiName || exampleName.startsWith(`${uiName}-`)
    })
    .sort((left, right) => right.length - left.length || left.localeCompare(right))

  const longestMatch = matchingUiNames.at(0)
  if (!longestMatch) {
    return []
  }

  return [`${MAGICUI_PACKAGE_PREFIX}${longestMatch}`]
}

// Collect static and dynamic module specifiers from a source file.
function collectModuleSpecifiersFromSourceFile(sourceFile: Node) {
  const importSpecifiers = sourceFile
    .getDescendantsOfKind(SyntaxKind.ImportDeclaration)
    .map((importDeclaration) => importDeclaration.getModuleSpecifierValue())

  const dynamicImportSpecifiers = sourceFile
    .getDescendantsOfKind(SyntaxKind.CallExpression)
    .flatMap((callExpression) => {
      if (callExpression.getExpression().getKind() !== SyntaxKind.ImportKeyword) {
        return []
      }

      return [getStringLiteralValue(callExpression.getArguments().at(0))]
    })
    .filter((specifier): specifier is string => specifier !== null)

  return dedupe([...importSpecifiers, ...dynamicImportSpecifiers])
}

// Check whether an import points at another source file under apps/www/registry.
function getRegistryImportBasePath(
  fromFilePath: string,
  moduleSpecifier: string
) {
  if (moduleSpecifier.startsWith(REGISTRY_IMPORT_PREFIX)) {
    return path.join(registryRoot, moduleSpecifier.slice(REGISTRY_IMPORT_PREFIX.length))
  }

  if (!moduleSpecifier.startsWith(".")) {
    return null
  }

  const resolvedPath = path.resolve(path.dirname(fromFilePath), moduleSpecifier)
  const relativePath = path.relative(registryRoot, resolvedPath)

  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
    return null
  }

  return resolvedPath
}

// Resolve registry-local imports without needing a full tsconfig module resolver.
async function resolveRegistryImportPath(
  fromFilePath: string,
  moduleSpecifier: string
) {
  const basePath = getRegistryImportBasePath(fromFilePath, moduleSpecifier)
  if (!basePath) {
    return null
  }

  const candidates = /\.[mc]?[jt]sx?$/.test(basePath)
    ? [basePath]
    : [
        `${basePath}.tsx`,
        `${basePath}.ts`,
        path.join(basePath, "index.tsx"),
        path.join(basePath, "index.ts"),
      ]

  for (const candidate of candidates) {
    try {
      await fs.access(candidate)
      return candidate
    } catch {
      continue
    }
  }

  return {
    missingImport: moduleSpecifier,
    sourceFile: path.relative(registryRoot, fromFilePath),
  }
}

// Walk the local registry import graph and collect all reachable @magicui/* packages.
async function collectRegistryDependenciesFromFile(
  project: Project,
  filePath: string,
  dependencies: Set<string>,
  missingFiles: string[],
  excludedDependencies: Set<string>,
  visitedFiles = new Set<string>()
) {
  const absolutePath = path.resolve(filePath)
  if (visitedFiles.has(absolutePath)) {
    return
  }

  visitedFiles.add(absolutePath)

  const sourceFile =
    project.getSourceFile(absolutePath) ??
    project.addSourceFileAtPathIfExists(absolutePath)

  if (!sourceFile) {
    missingFiles.push(path.relative(registryRoot, absolutePath))
    return
  }

  const fileDependency = getRegistryDependencyNameFromFilePath(absolutePath)
  if (fileDependency && !excludedDependencies.has(fileDependency)) {
    dependencies.add(fileDependency)
  }

  for (const moduleSpecifier of collectModuleSpecifiersFromSourceFile(sourceFile)) {
    const directDependency = getRegistryDependencyName(moduleSpecifier)
    if (directDependency && !excludedDependencies.has(directDependency)) {
      dependencies.add(directDependency)
    }

    const resolvedImport = await resolveRegistryImportPath(
      absolutePath,
      moduleSpecifier
    )

    if (!resolvedImport) {
      continue
    }

    if (typeof resolvedImport !== "string") {
      missingFiles.push(
        `${resolvedImport.sourceFile} -> ${resolvedImport.missingImport}`
      )
      continue
    }

    await collectRegistryDependenciesFromFile(
      project,
      resolvedImport,
      dependencies,
      missingFiles,
      excludedDependencies,
      visitedFiles
    )
  }
}

// Aggregate magicui dependencies across all files referenced by one example.
async function collectExampleRegistryDependencies(
  project: Project,
  filePaths: string[]
) {
  const missingFiles: string[] = []
  const dependencies = new Set<string>()
  const visitedFiles = new Set<string>()
  const excludedDependencies = new Set(
    filePaths
      .filter((filePath) => filePath.startsWith("example/"))
      .map((filePath) => {
        return getRegistryDependencyNameFromFilePath(path.join(registryRoot, filePath))
      })
      .filter((dependency): dependency is string => dependency !== null)
  )

  for (const filePath of filePaths) {
    const absolutePath = path.join(registryRoot, filePath)

    try {
      await fs.access(absolutePath)
    } catch {
      missingFiles.push(filePath)
      continue
    }

    await collectRegistryDependenciesFromFile(
      project,
      absolutePath,
      dependencies,
      missingFiles,
      excludedDependencies,
      visitedFiles
    )
  }

  return {
    dependencies: Array.from(dependencies).sort((left, right) =>
      left.localeCompare(right)
    ),
    missingFiles,
  }
}

// Upsert registryDependencies while keeping the property near files.
function setRegistryDependencies(node: Node, dependencies: string[]) {
  if (!Node.isObjectLiteralExpression(node)) {
    return
  }

  const normalizedDependencies = dedupe(dependencies)
  const existingProperty = getObjectPropertyAssignment(
    node,
    "registryDependencies"
  )
  const filesPropertyIndex = node
    .getProperties()
    .findIndex((property) => {
      return Node.isPropertyAssignment(property) && property.getName() === "files"
    })

  const initializer = (writer: CodeBlockWriter) => {
    writer.write("[")

    if (normalizedDependencies.length === 0) {
      writer.write("]")
      return
    }

    writer.newLine()
    writer.indent(() => {
      for (const dependency of normalizedDependencies) {
        writer.writeLine(`${JSON.stringify(dependency)},`)
      }
    })
    writer.write("]")
  }

  if (existingProperty && Node.isPropertyAssignment(existingProperty)) {
    existingProperty.setInitializer(initializer)
    return
  }

  const insertIndex =
    filesPropertyIndex >= 0 ? filesPropertyIndex : node.getProperties().length

  node.insertPropertyAssignment(insertIndex, {
    name: "registryDependencies",
    initializer,
  })
}

// Format one mismatch entry for CLI output.
function formatIssue(issue: ExampleIssue) {
  const fileList =
    issue.exampleFiles.length > 0 ? issue.exampleFiles.join(", ") : "no files"
  const extraDependencies =
    issue.extraDependencies.length > 0
      ? issue.extraDependencies.join(", ")
      : "none"
  const missingDependencies =
    issue.missingDependencies.length > 0
      ? issue.missingDependencies.join(", ")
      : "none"
  const missingFiles =
    issue.missingFiles.length > 0 ? issue.missingFiles.join(", ") : "none"

  return [
    `- ${issue.exampleName}`,
    `  files: ${fileList}`,
    `  extra registryDependencies: ${extraDependencies}`,
    `  missing registryDependencies: ${missingDependencies}`,
    `  missing files: ${missingFiles}`,
  ].join("\n")
}

// Treat missing files or missing dependencies as failures that need action.
function hasBlockingIssue(issue: ExampleIssue) {
  return issue.missingDependencies.length > 0 || issue.missingFiles.length > 0
}

// Treat extra dependencies as non-blocking warnings to avoid destructive churn.
function hasWarningIssue(issue: ExampleIssue) {
  return issue.extraDependencies.length > 0 && !hasBlockingIssue(issue)
}

// Raise a hard failure when an example points at files that cannot be read.
export function assertNoMissingExampleFiles(issues: ExampleIssue[]) {
  const missingFileIssues = issues.filter((issue) => issue.missingFiles.length > 0)
  if (missingFileIssues.length === 0) {
    return
  }

  const issueSummary = missingFileIssues.map(formatIssue).join("\n")
  throw new Error(
    [
      "registry example dependency sync failed because some example files are missing:",
      issueSummary,
    ].join("\n")
  )
}

// Compare imported magicui components with declared registryDependencies.
export async function syncExampleRegistryDependencies({
  mode,
}: SyncOptions): Promise<ExampleIssue[]> {
  const project = new Project({
    skipAddingFilesFromTsConfig: true,
  })
  const registryExamplesSourceFile =
    project.addSourceFileAtPath(registryExamplesPath)
  const registryUiSourceFile = project.addSourceFileAtPath(registryUiPath)

  const initializer = getRegistryItemsDeclaration(
    registryExamplesSourceFile,
    "examples"
  )
  const uiInitializer = getRegistryItemsDeclaration(registryUiSourceFile, "ui")

  if (!initializer) {
    throw new Error("Could not find the examples array in registry-examples.ts.")
  }

  if (!uiInitializer) {
    throw new Error("Could not find the ui array in registry-ui.ts.")
  }

  const registryUiNames = uiInitializer
    .getElements()
    .flatMap((item) => {
      if (!Node.isObjectLiteralExpression(item)) {
        return []
      }

      if (getRegistryItemType(item) !== "registry:ui") {
        return []
      }

      return [getRegistryItemName(item)]
    })
    .sort((left, right) => right.length - left.length || left.localeCompare(right))

  const issues: ExampleIssue[] = []

  for (const item of initializer.getElements()) {
    if (!Node.isObjectLiteralExpression(item)) {
      continue
    }

    if (getRegistryItemType(item) !== "registry:example") {
      continue
    }

    const exampleName = getRegistryItemName(item)
    const exampleFiles = getExampleFilePaths(item)
    const currentDependencies = getStringArrayValues(
      getObjectPropertyAssignment(item, "registryDependencies")
    )
    const { dependencies: importedDependencies, missingFiles } =
      await collectExampleRegistryDependencies(project, exampleFiles)
    const inferredDependencies = inferRegistryDependenciesFromExampleName(
      exampleName,
      registryUiNames
    )
    const expectedDependencies = dedupe([
      ...importedDependencies,
      ...inferredDependencies,
    ]).sort((left, right) => left.localeCompare(right))

    const normalizedCurrentDependencies = dedupe(currentDependencies)
    const currentMagicUiDependencies = normalizedCurrentDependencies.filter(
      isMagicUiPackage
    )
    const extraDependencies = currentMagicUiDependencies.filter((dependency) => {
      return !expectedDependencies.includes(dependency)
    })
    const missingDependencies = expectedDependencies.filter((dependency) => {
      return !currentMagicUiDependencies.includes(dependency)
    })
    const nextDependencies = [...normalizedCurrentDependencies, ...missingDependencies]
    const dependenciesChanged =
      nextDependencies.length !== currentDependencies.length ||
      nextDependencies.some(
        (dependency, index) => dependency !== currentDependencies[index]
      )

    if (dependenciesChanged || missingFiles.length > 0) {
      issues.push({
        exampleName,
        exampleFiles,
        extraDependencies,
        missingDependencies,
        missingFiles,
      })
    }

    if (mode === "fix" && dependenciesChanged) {
      setRegistryDependencies(item, nextDependencies)
    }
  }

  if (mode === "fix" && registryExamplesSourceFile.isSaved() === false) {
    await registryExamplesSourceFile.save()
  }

  return issues
}

// Expose a small check/fix CLI for local runs and package scripts.
async function main() {
  const mode = process.argv.includes("--check") ? "check" : "fix"
  const issues = await syncExampleRegistryDependencies({ mode })
  const blockingIssues = issues.filter(hasBlockingIssue)
  const warningIssues = issues.filter(hasWarningIssue)

  if (issues.length === 0) {
    console.log("registry example dependencies are in sync")
    return
  }

  const blockingIssueSummary = blockingIssues.map(formatIssue).join("\n")
  const warningIssueSummary = warningIssues.map(formatIssue).join("\n")

  if (mode === "check") {
    if (blockingIssues.length > 0) {
      console.error("registry example dependency mismatches found:")
      console.error(blockingIssueSummary)
      console.error("Run: pnpm registry-deps:fix && pnpm build:registry")
      console.error("Then commit registry-examples.ts and the generated files.")
      process.exit(1)
    }

    console.warn("registry example dependencies have non-blocking warnings:")
    console.warn(warningIssueSummary)
    return
  }

  try {
    assertNoMissingExampleFiles(issues)
  } catch (error) {
    console.error("registry example dependency sync completed with missing files:")
    console.error(error instanceof Error ? error.message : error)
    process.exit(1)
  }

  if (blockingIssues.length > 0) {
    console.log("updated registry example dependencies:")
    console.log(blockingIssueSummary)
  } else {
    console.log("registry example dependencies are in sync")
  }

  if (warningIssues.length > 0) {
    console.warn("registry example dependencies have non-blocking warnings:")
    console.warn(warningIssueSummary)
  }
}

if (isMainModule()) {
  await main()
}