banhaten 0.1.3 → 0.2.0

package/src/cli/install-plan.js

@@ -0,0 +1,592 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import {
+  parseJsonc,
+  readViteAliasKeys,
+  readViteAliasSourceRoot,
+  updateJsoncAliasSource,
+  updateViteConfigSource,
+} from "./config-editors.js"
+
+const TYPESCRIPT_CONFIG_CANDIDATES = [
+  "tsconfig.app.json",
+  "tsconfig.json",
+  "jsconfig.json",
+]
+const VITE_CONFIG_CANDIDATES = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.js",
+  "vite.config.mjs",
+]
+
+export async function createInstallPlan(cwd, config) {
+  const projectRoot = path.resolve(cwd)
+  const [typescriptPath, vitePath, hasSrcDirectory] = await Promise.all([
+    findFirstExisting(projectRoot, TYPESCRIPT_CONFIG_CANDIDATES),
+    findFirstExisting(projectRoot, VITE_CONFIG_CANDIDATES),
+    exists(path.join(projectRoot, "src")),
+  ])
+  const [typescriptSource, viteSource] = await Promise.all([
+    typescriptPath ? fs.readFile(typescriptPath, "utf8") : null,
+    vitePath ? fs.readFile(vitePath, "utf8") : null,
+  ])
+  const typescriptConfig = typescriptSource
+    ? parseTypescriptConfig(typescriptSource, typescriptPath, projectRoot)
+    : null
+  const aliasRootNames = collectAliasRootNames(config.aliases)
+  assertTypescriptConfigIsSelfContained(
+    typescriptConfig,
+    typescriptPath,
+    projectRoot,
+    aliasRootNames
+  )
+  const fallbackRoot = hasSrcDirectory
+    ? path.join(projectRoot, "src")
+    : projectRoot
+  const aliasRoots = {}
+
+  for (const aliasRoot of aliasRootNames) {
+    const typescriptRoot = typescriptConfig
+      ? readTypescriptAliasRoot(
+          typescriptConfig,
+          aliasRoot,
+          typescriptPath,
+          projectRoot
+        )
+      : null
+    let viteRoot = null
+
+    if (viteSource) {
+      try {
+        const configuredAlias = readViteAliasSourceRoot(viteSource, { aliasRoot })
+        if (configuredAlias !== null) {
+          viteRoot = resolveStaticAliasRoot(
+            path.dirname(vitePath),
+            configuredAlias
+          )
+          assertInsideProject(
+            projectRoot,
+            viteRoot,
+            `${relative(projectRoot, vitePath)} alias ${JSON.stringify(aliasRoot)}`
+          )
+        }
+      } catch (error) {
+        throw new Error(`${relative(projectRoot, vitePath)}: ${error.message}`)
+      }
+    }
+
+    if (typescriptRoot && viteRoot && !samePath(typescriptRoot, viteRoot)) {
+      throw new Error(
+        `alias conflict for ${JSON.stringify(aliasRoot)}: ` +
+          `${relative(projectRoot, typescriptPath)} resolves to ${formatProjectPath(projectRoot, typescriptRoot)}, ` +
+          `but ${relative(projectRoot, vitePath)} resolves to ${formatProjectPath(projectRoot, viteRoot)}. ` +
+          "Align the aliases before running Banhaten."
+      )
+    }
+
+    const absoluteRoot = typescriptRoot ?? viteRoot ?? fallbackRoot
+    assertInsideProject(
+      projectRoot,
+      absoluteRoot,
+      `alias ${JSON.stringify(aliasRoot)}`
+    )
+    aliasRoots[aliasRoot] = Object.freeze({
+      absolute: absoluteRoot,
+      relative: projectRelative(projectRoot, absoluteRoot),
+      typescriptDeclared: Boolean(typescriptRoot),
+      viteDeclared: Boolean(viteRoot),
+    })
+  }
+
+  assertNoOverlappingAliases({
+    aliases: config.aliases,
+    projectRoot,
+    typescriptConfig,
+    typescriptPath,
+    viteSource,
+    vitePath,
+  })
+
+  const typescript = typescriptSource
+    ? planTypescriptConfig({
+        aliasRoots,
+        currentSource: typescriptSource,
+        parsedConfig: typescriptConfig,
+        projectRoot,
+        targetPath: typescriptPath,
+      })
+    : null
+  const vite = viteSource
+    ? planViteConfig({
+        aliasRoots,
+        currentSource: viteSource,
+        projectRoot,
+        targetPath: vitePath,
+      })
+    : null
+  const destinations = Object.freeze({
+    css: resolveProjectDestination(
+      projectRoot,
+      config.tailwind.css,
+      "tailwind.css"
+    ),
+    hooks: resolveConfiguredAlias(
+      projectRoot,
+      config.aliases.hooks,
+      aliasRoots,
+      "aliases.hooks"
+    ),
+    ui: resolveConfiguredAlias(
+      projectRoot,
+      config.aliases.ui,
+      aliasRoots,
+      "aliases.ui"
+    ),
+    utils: stripExtension(
+      resolveConfiguredAlias(
+        projectRoot,
+        config.aliases.utils,
+        aliasRoots,
+        "aliases.utils"
+      )
+    ),
+  })
+
+  return Object.freeze({
+    aliasRoots: Object.freeze(aliasRoots),
+    config,
+    cwd: projectRoot,
+    destinations,
+    typescript,
+    vite,
+  })
+}
+
+export function resolveInstallTarget(plan, target) {
+  const replacements = {
+    "{{hooks}}": plan.destinations.hooks,
+    "{{ui}}": plan.destinations.ui,
+    "{{utils}}": plan.destinations.utils,
+  }
+  let resolved = target
+
+  for (const [placeholder, destination] of Object.entries(replacements)) {
+    resolved = resolved.replaceAll(placeholder, destination)
+  }
+
+  if (/\{\{[^}]+\}\}/.test(resolved)) {
+    throw new Error(`registry target contains an unknown placeholder: ${target}`)
+  }
+
+  return resolveProjectDestination(plan.cwd, resolved, `registry target ${target}`)
+}
+
+function planTypescriptConfig({
+  aliasRoots,
+  currentSource,
+  parsedConfig,
+  projectRoot,
+  targetPath,
+}) {
+  let nextSource = currentSource
+  const baseDirectory = getTypescriptBaseDirectory(
+    parsedConfig,
+    targetPath,
+    projectRoot
+  )
+
+  for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+    if (rootPlan.typescriptDeclared) continue
+
+    const targetPattern = `${relativeSpecifier(
+      baseDirectory,
+      rootPlan.absolute
+    )}/*`
+    nextSource = updateJsoncAliasSource(nextSource, {
+      aliasPattern: `${aliasRoot}/*`,
+      targetPattern,
+    })
+  }
+
+  try {
+    const verifiedConfig = parseJsonc(nextSource)
+    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+      const verifiedRoot = readTypescriptAliasRoot(
+        verifiedConfig,
+        aliasRoot,
+        targetPath,
+        projectRoot
+      )
+      if (!verifiedRoot || !samePath(verifiedRoot, rootPlan.absolute)) {
+        throw new Error(
+          `failed to produce canonical TypeScript alias ${JSON.stringify(aliasRoot)}`
+        )
+      }
+    }
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
+  }
+
+  return Object.freeze({
+    currentSource,
+    nextSource,
+    targetPath,
+  })
+}
+
+function planViteConfig({ aliasRoots, currentSource, projectRoot, targetPath }) {
+  let nextSource = currentSource
+
+  try {
+    if (Object.keys(aliasRoots).length === 0) {
+      nextSource = updateViteConfigSource(nextSource, {
+        aliasRoot: null,
+        sourceRoot: null,
+      })
+    }
+
+    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+      nextSource = updateViteConfigSource(nextSource, {
+        aliasRoot,
+        sourceRoot: relativeSpecifier(
+          path.dirname(targetPath),
+          rootPlan.absolute
+        ),
+      })
+    }
+
+    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+      const verifiedAlias = readViteAliasSourceRoot(nextSource, { aliasRoot })
+      const verifiedRoot = verifiedAlias
+        ? resolveStaticAliasRoot(path.dirname(targetPath), verifiedAlias)
+        : null
+      if (!verifiedRoot || !samePath(verifiedRoot, rootPlan.absolute)) {
+        throw new Error(
+          `failed to produce canonical Vite alias ${JSON.stringify(aliasRoot)}`
+        )
+      }
+    }
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
+  }
+
+  return Object.freeze({
+    currentSource,
+    nextSource,
+    targetPath,
+  })
+}
+
+function parseTypescriptConfig(source, targetPath, projectRoot) {
+  try {
+    return parseJsonc(source)
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
+  }
+}
+
+function readTypescriptAliasRoot(
+  config,
+  aliasRoot,
+  targetPath,
+  projectRoot
+) {
+  const compilerOptions = config.compilerOptions ?? {}
+  if (!isPlainObject(compilerOptions)) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions must be an object`
+    )
+  }
+
+  const paths = compilerOptions.paths ?? {}
+  if (!isPlainObject(paths)) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions.paths must be an object`
+    )
+  }
+
+  const aliasPattern = `${aliasRoot}/*`
+  if (!(aliasPattern in paths)) return null
+
+  const targets = paths[aliasPattern]
+  if (!Array.isArray(targets) || targets.length !== 1) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript path ${aliasPattern} must contain exactly one static target`
+    )
+  }
+
+  const [target] = targets
+  if (
+    typeof target !== "string" ||
+    !target.endsWith("*") ||
+    target.indexOf("*") !== target.length - 1 ||
+    (target.length > 1 && !/[\\/]/.test(target.at(-2)))
+  ) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript path ${aliasPattern} must contain one terminal *`
+    )
+  }
+
+  const targetPrefix = target.slice(0, -1).replace(/[\\/]$/, "") || "."
+  const absoluteRoot = path.resolve(
+    getTypescriptBaseDirectory(config, targetPath, projectRoot),
+    targetPrefix
+  )
+  assertInsideProject(
+    projectRoot,
+    absoluteRoot,
+    `${relative(projectRoot, targetPath)} path ${aliasPattern}`
+  )
+  return absoluteRoot
+}
+
+function getTypescriptBaseDirectory(config, targetPath, projectRoot) {
+  const baseUrl = config.compilerOptions?.baseUrl
+  if (baseUrl !== undefined && typeof baseUrl !== "string") {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions.baseUrl must be a string`
+    )
+  }
+
+  return path.resolve(path.dirname(targetPath), baseUrl ?? ".")
+}
+
+function collectAliasRootNames(aliases = {}) {
+  const roots = new Set()
+
+  for (const alias of Object.values(aliases)) {
+    if (typeof alias !== "string") continue
+    if (alias === "@" || alias.startsWith("@/")) roots.add("@")
+    if (alias === "~" || alias.startsWith("~/")) roots.add("~")
+  }
+
+  return [...roots].sort()
+}
+
+function assertTypescriptConfigIsSelfContained(
+  config,
+  targetPath,
+  projectRoot,
+  aliasRootNames
+) {
+  if (config?.extends === undefined || aliasRootNames.length === 0) return
+
+  const compilerOptions = config.compilerOptions
+  const hasLocalBaseUrl = isPlainObject(compilerOptions) &&
+    Object.hasOwn(compilerOptions, "baseUrl")
+  const hasLocalPaths = isPlainObject(compilerOptions) &&
+    Object.hasOwn(compilerOptions, "paths")
+
+  if (!hasLocalBaseUrl || !hasLocalPaths) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)} extends another TypeScript config, so its effective aliases cannot be validated safely. ` +
+        "Declare compilerOptions.baseUrl and compilerOptions.paths locally before running Banhaten."
+    )
+  }
+}
+
+function resolveConfiguredAlias(
+  projectRoot,
+  alias,
+  aliasRoots,
+  label
+) {
+  let absoluteTarget
+
+  if (path.isAbsolute(alias)) {
+    absoluteTarget = alias
+  } else if (alias.startsWith("./") || alias.startsWith("../")) {
+    absoluteTarget = path.resolve(projectRoot, alias)
+  } else {
+    const rootPlan = Object.entries(aliasRoots).find(
+      ([aliasRoot]) => alias === aliasRoot || alias.startsWith(`${aliasRoot}/`)
+    )
+
+    if (rootPlan) {
+      const [aliasRoot, plan] = rootPlan
+      const suffix = alias === aliasRoot ? "" : alias.slice(aliasRoot.length + 1)
+      absoluteTarget = path.resolve(plan.absolute, suffix)
+    } else {
+      absoluteTarget = path.resolve(projectRoot, alias)
+    }
+  }
+
+  assertInsideProject(projectRoot, absoluteTarget, label)
+  return projectRelative(projectRoot, absoluteTarget)
+}
+
+function resolveProjectDestination(projectRoot, destination, label) {
+  const absoluteTarget = path.isAbsolute(destination)
+    ? path.normalize(destination)
+    : path.resolve(projectRoot, destination)
+  assertInsideProject(projectRoot, absoluteTarget, label)
+  return projectRelative(projectRoot, absoluteTarget)
+}
+
+function resolveStaticAliasRoot(configDirectory, configuredAlias) {
+  if (configuredAlias.kind === "literal") {
+    if (!path.isAbsolute(configuredAlias.value)) {
+      throw new Error(
+        "unsupported Vite config: a string alias must be absolute; use fileURLToPath(new URL(..., import.meta.url)) for a config-relative path."
+      )
+    }
+    return path.normalize(configuredAlias.value)
+  }
+
+  return path.resolve(configDirectory, configuredAlias.value)
+}
+
+function assertNoOverlappingAliases({
+  aliases,
+  projectRoot,
+  typescriptConfig,
+  typescriptPath,
+  viteSource,
+  vitePath,
+}) {
+  const typescriptPaths = typescriptConfig?.compilerOptions?.paths ?? {}
+  const configuredAliases = Object.values(aliases).filter(
+    (alias) =>
+      typeof alias === "string" &&
+      (alias === "@" ||
+        alias === "~" ||
+        alias.startsWith("@/") ||
+        alias.startsWith("~/"))
+  )
+
+  for (const aliasPattern of Object.keys(typescriptPaths)) {
+    if (
+      configuredAliases.some((alias) =>
+        isOverlappingTypescriptAlias(aliasPattern, alias)
+      )
+    ) {
+      const aliasRoot = aliasPattern[0]
+      throw new Error(
+        `${relative(projectRoot, typescriptPath)}: alias ${JSON.stringify(aliasPattern)} overlaps a configured Banhaten destination. ` +
+          `Use the root ${JSON.stringify(aliasRoot)} alias so TypeScript, Vite, and generated files share one destination plan.`
+      )
+    }
+  }
+
+  if (!viteSource) return
+
+  try {
+    for (const aliasKey of readViteAliasKeys(viteSource)) {
+      if (
+        configuredAliases.some((alias) =>
+          isOverlappingViteAlias(aliasKey, alias)
+        )
+      ) {
+        const aliasRoot = aliasKey[0]
+        throw new Error(
+          `alias ${JSON.stringify(aliasKey)} overlaps a configured Banhaten destination. ` +
+            `Use the root ${JSON.stringify(aliasRoot)} alias so TypeScript, Vite, and generated files share one destination plan.`
+        )
+      }
+    }
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, vitePath)}: ${error.message}`)
+  }
+}
+
+function isOverlappingTypescriptAlias(aliasPattern, configuredAlias) {
+  const aliasRoot = configuredAlias[0]
+  if (aliasPattern === `${aliasRoot}/*` || aliasPattern === aliasRoot) {
+    return false
+  }
+  if (aliasPattern[0] !== aliasRoot) return false
+
+  const wildcardIndex = aliasPattern.indexOf("*")
+  const staticPrefix = (wildcardIndex === -1
+    ? aliasPattern
+    : aliasPattern.slice(0, wildcardIndex)
+  ).replace(/\/$/, "")
+
+  if (staticPrefix === aliasRoot) return true
+  return (
+    configuredAlias === staticPrefix ||
+    configuredAlias.startsWith(`${staticPrefix}/`) ||
+    staticPrefix.startsWith(`${configuredAlias}/`) ||
+    (wildcardIndex !== -1 && configuredAlias.startsWith(staticPrefix))
+  )
+}
+
+function isOverlappingViteAlias(aliasKey, configuredAlias) {
+  const aliasRoot = configuredAlias[0]
+  if (aliasKey === aliasRoot || aliasKey[0] !== aliasRoot) return false
+
+  return (
+    configuredAlias === aliasKey ||
+    configuredAlias.startsWith(`${aliasKey}/`) ||
+    aliasKey.startsWith(`${configuredAlias}/`)
+  )
+}
+
+function assertInsideProject(projectRoot, targetPath, label) {
+  const target = path.resolve(targetPath)
+  const targetRelative = path.relative(projectRoot, target)
+  if (
+    targetRelative === ".." ||
+    targetRelative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(targetRelative)
+  ) {
+    throw new Error(
+      `${label} resolves outside the project: ${target}`
+    )
+  }
+}
+
+async function findFirstExisting(projectRoot, candidates) {
+  for (const candidate of candidates) {
+    const targetPath = path.join(projectRoot, candidate)
+    if (await exists(targetPath)) return targetPath
+  }
+  return null
+}
+
+function relativeSpecifier(fromDirectory, targetPath) {
+  const targetRelative = path
+    .relative(fromDirectory, targetPath)
+    .replaceAll("\\", "/")
+  if (!targetRelative) return "."
+  return targetRelative.startsWith(".")
+    ? targetRelative
+    : `./${targetRelative}`
+}
+
+function projectRelative(projectRoot, targetPath) {
+  const targetRelative = path.relative(projectRoot, targetPath)
+  return (targetRelative || ".").replaceAll("\\", "/")
+}
+
+function formatProjectPath(projectRoot, targetPath) {
+  const targetRelative = projectRelative(projectRoot, targetPath)
+  return targetRelative === "." ? "." : `./${targetRelative}`
+}
+
+function relative(projectRoot, targetPath) {
+  return path.relative(projectRoot, targetPath).replaceAll("\\", "/")
+}
+
+function stripExtension(filePath) {
+  return filePath.replace(/\.(t|j)sx?$/, "")
+}
+
+function samePath(left, right) {
+  return path.resolve(left) === path.resolve(right)
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}