banhaten 0.1.3 → 0.2.0

package/src/cli/doctor.js

@@ -0,0 +1,399 @@
+import { createHash } from "node:crypto"
+import fs from "node:fs/promises"
+import path from "node:path"
+
+const RECEIPT_FILE = ".banhaten/installed.json"
+const GUIDANCE_FILE = ".banhaten/USAGE.md"
+const SOURCE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx"])
+const IGNORED_DIRECTORIES = new Set([
+  ".banhaten",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".turbo",
+  ".vercel",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+])
+const BANHATEN_CONTROL_TAG =
+  /<(Input|Select|DatePicker|DateRangePicker|Button|ButtonGroup|ToggleGroup|SegmentedControl|ToolbarSearch|ToolbarSelect|ToolbarButton)(?=\s|\/?>)[\s\S]*?>/g
+const GEOMETRY_ATTRIBUTE =
+  /(?:className|controlClassName|inputClassName|surfaceClassName|triggerClassName)\s*=\s*(?:["']([^"']*)["']|\{\s*["']([^"']*)["']\s*\})/g
+const RAW_GEOMETRY_CLASS =
+  /(?:^|\s)(?:h-|min-h-|max-h-|p(?:x|y|s|e|t|r|b|l)?-|rounded(?:-|$)|text-\[)/
+
+export async function inspectBanhatenProject({ cwd, registryVersion }) {
+  const projectRoot = path.resolve(cwd)
+  const diagnostics = []
+  const receiptPath = path.join(projectRoot, RECEIPT_FILE)
+  const guidancePath = path.join(projectRoot, GUIDANCE_FILE)
+  const receipt = await readJsonIfExists(receiptPath, diagnostics, projectRoot)
+
+  if (!receipt) {
+    diagnostics.push(
+      diagnostic({
+        code: "setup-not-initialized",
+        message: "No Banhaten install receipt was found.",
+        recommendation: "Run `banhaten init` before installing components.",
+        severity: "warning",
+      })
+    )
+  } else {
+    inspectReceiptVersion(receipt, registryVersion, diagnostics)
+    await inspectManagedFiles(projectRoot, receipt, diagnostics)
+  }
+
+  if (!(await exists(guidancePath))) {
+    diagnostics.push(
+      diagnostic({
+        code: "agent-guidance-missing",
+        file: GUIDANCE_FILE,
+        message: "The installed coding-agent usage rules are missing.",
+        recommendation: "Run `banhaten init` to install .banhaten/USAGE.md.",
+        severity: "warning",
+      })
+    )
+  }
+
+  const sourceFiles = await collectSourceFiles(projectRoot)
+  for (const filePath of sourceFiles) {
+    await inspectSourceFile(projectRoot, filePath, diagnostics)
+  }
+
+  diagnostics.sort(compareDiagnostics)
+  const summary = diagnostics.reduce(
+    (counts, item) => {
+      const key =
+        item.severity === "error"
+          ? "errors"
+          : item.severity === "warning"
+            ? "warnings"
+            : "info"
+      counts[key] += 1
+      return counts
+    },
+    { errors: 0, info: 0, warnings: 0 }
+  )
+
+  return {
+    cwd: projectRoot,
+    registryVersion,
+    installedVersion: receipt?.registryVersion ?? null,
+    installedComponents: Object.keys(receipt?.components || {}).sort(),
+    scannedFiles: sourceFiles.length,
+    summary,
+    diagnostics,
+  }
+}
+
+export function printBanhatenDoctor(report, { json = false, silent = false } = {}) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2))
+    return
+  }
+  if (silent) return
+
+  console.log("Banhaten doctor")
+  console.log(`Project: ${report.cwd}`)
+  console.log(
+    `Registry: ${report.installedVersion ?? "not installed"} -> ${report.registryVersion}`
+  )
+  console.log(
+    `Scanned ${report.scannedFiles} source files and ${report.installedComponents.length} installed components.`
+  )
+
+  if (report.diagnostics.length === 0) {
+    console.log("No design-system adoption issues found.")
+    return
+  }
+
+  for (const item of report.diagnostics) {
+    const location = item.file
+      ? ` ${item.file}${item.line ? `:${item.line}` : ""}`
+      : ""
+    console.log(`${item.severity.toUpperCase()} ${item.code}${location}`)
+    console.log(`  ${item.message}`)
+    console.log(`  ${item.recommendation}`)
+  }
+
+  console.log(
+    `${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info.`
+  )
+}
+
+function inspectReceiptVersion(receipt, registryVersion, diagnostics) {
+  if (receipt.schemaVersion !== 1 || typeof receipt.components !== "object") {
+    diagnostics.push(
+      diagnostic({
+        code: "install-receipt-invalid",
+        file: RECEIPT_FILE,
+        message: "The Banhaten install receipt has an unsupported shape.",
+        recommendation: "Re-run an explicit `banhaten add <component> --force` after reviewing local changes.",
+        severity: "error",
+      })
+    )
+    return
+  }
+
+  if (receipt.registryVersion !== registryVersion) {
+    diagnostics.push(
+      diagnostic({
+        code: "registry-version-drift",
+        file: RECEIPT_FILE,
+        message: `Installed registry version ${receipt.registryVersion ?? "unknown"} differs from CLI version ${registryVersion}.`,
+        recommendation: "Run `banhaten diff`, then update reviewed components with `banhaten update`.",
+        severity: "warning",
+      })
+    )
+  }
+}
+
+async function inspectManagedFiles(projectRoot, receipt, diagnostics) {
+  for (const [target, record] of Object.entries(receipt.managedFiles || {})) {
+    const resolved = path.resolve(projectRoot, target)
+    const relative = path.relative(projectRoot, resolved)
+
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      diagnostics.push(
+        diagnostic({
+          code: "managed-target-unsafe",
+          file: target,
+          message: "The install receipt points outside the project.",
+          recommendation: "Remove the unsafe receipt entry and re-run `banhaten init`.",
+          severity: "error",
+        })
+      )
+      continue
+    }
+
+    let content
+    try {
+      content = await fs.readFile(resolved)
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        diagnostics.push(
+          diagnostic({
+            code: "managed-file-missing",
+            file: normalizePath(relative),
+            message: `The ${record.owner || "Banhaten"}-managed file is missing.`,
+            recommendation: "Run `banhaten diff`, then restore it with `banhaten update`.",
+            severity: "error",
+          })
+        )
+        continue
+      }
+      throw error
+    }
+
+    const actualHash = createHash("sha256").update(content).digest("hex")
+    if (record.sha256 && actualHash !== record.sha256) {
+      diagnostics.push(
+        diagnostic({
+          code: "managed-file-modified",
+          file: normalizePath(relative),
+          message: `The ${record.owner || "Banhaten"}-managed file differs from its install receipt.`,
+          recommendation: "Run `banhaten diff` and either keep the intentional extension or update the registry copy after review.",
+          severity: "warning",
+        })
+      )
+    }
+  }
+}
+
+async function inspectSourceFile(projectRoot, filePath, diagnostics) {
+  const source = await fs.readFile(filePath, "utf8")
+  if (source.length > 1024 * 1024) return
+  const file = normalizePath(path.relative(projectRoot, filePath))
+
+  for (const match of source.matchAll(BANHATEN_CONTROL_TAG)) {
+    const [tagSource, tagName] = match
+    const line = getLine(source, match.index)
+
+    for (const attribute of tagSource.matchAll(GEOMETRY_ATTRIBUTE)) {
+      const classes = attribute[1] ?? attribute[2] ?? ""
+      if (!RAW_GEOMETRY_CLASS.test(classes)) continue
+      diagnostics.push(
+        diagnostic({
+          code: "raw-control-geometry",
+          file,
+          line,
+          message: `${tagName} overrides control geometry with ${JSON.stringify(classes)}.`,
+          recommendation: "Use density for height and component tokens for padding, radius, and typography; keep classes for width and layout only.",
+          severity: "warning",
+        })
+      )
+    }
+
+    if (tagName === "Input") {
+      if (hasTruthyBooleanProp(tagSource, "hasLeadingIcon") &&
+          !hasProp(tagSource, "leadingIcon") &&
+          !hasProp(tagSource, "showAtSign")) {
+        diagnostics.push(
+          diagnostic({
+            code: "ambiguous-input-leading-icon",
+            file,
+            line,
+            message: "Input uses the deprecated hasLeadingIcon flag without an explicit icon.",
+            recommendation: "Pass leadingIcon={<Icon />} or use showAtSign for the literal @ affordance.",
+            severity: "warning",
+          })
+        )
+      }
+
+      if (hasTruthyBooleanProp(tagSource, "hasInformationIcon") &&
+          !hasProp(tagSource, "trailingIcon") &&
+          !hasProp(tagSource, "showInfo")) {
+        diagnostics.push(
+          diagnostic({
+            code: "ambiguous-input-information-icon",
+            file,
+            line,
+            message: "Input uses the deprecated hasInformationIcon flag without an explicit icon.",
+            recommendation: "Pass trailingIcon={<Icon />} or use showInfo for the literal information affordance.",
+            severity: "warning",
+          })
+        )
+      }
+
+      if (hasProp(tagSource, "shortcut") && !hasProp(tagSource, "shortcutKeys")) {
+        diagnostics.push(
+          diagnostic({
+            code: "legacy-input-shortcut",
+            file,
+            line,
+            message: "Input uses a single legacy shortcut keycap.",
+            recommendation: "Use shortcutKeys={[\"Mod\", \"K\"]} for platform-aware, multi-key rendering.",
+            severity: "warning",
+          })
+        )
+      }
+    }
+  }
+
+  inspectNativeTags(source, file, diagnostics)
+}
+
+function inspectNativeTags(source, file, diagnostics) {
+  for (const match of source.matchAll(/<select(?=\s|>)[\s\S]*?>/g)) {
+    diagnostics.push(
+      diagnostic({
+        code: "native-select-control",
+        file,
+        line: getLine(source, match.index),
+        message: "A native select bypasses the Banhaten Select contract.",
+        recommendation: "Use Select for product UI, unless native platform behavior is an explicit requirement.",
+        severity: "warning",
+      })
+    )
+  }
+
+  for (const match of source.matchAll(/<input(?=\s|>)[\s\S]*?>/g)) {
+    if (!/\btype\s*=\s*["']date["']/.test(match[0])) continue
+    diagnostics.push(
+      diagnostic({
+        code: "native-date-control",
+        file,
+        line: getLine(source, match.index),
+        message: "A native date input bypasses the Banhaten calendar and density contracts.",
+        recommendation: "Use DatePicker or DateRangePicker.",
+        severity: "warning",
+      })
+    )
+  }
+}
+
+async function collectSourceFiles(projectRoot) {
+  const files = []
+  await visit(projectRoot)
+  return files.sort()
+
+  async function visit(directory) {
+    const entries = await fs.readdir(directory, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") && entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) continue
+      }
+      if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name)) continue
+
+      const target = path.join(directory, entry.name)
+      if (entry.isDirectory()) {
+        await visit(target)
+      } else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+        files.push(target)
+      }
+    }
+  }
+}
+
+function hasProp(tagSource, prop) {
+  return new RegExp(`\\b${prop}(?:\\s*=|(?=\\s|\\/?>))`).test(tagSource)
+}
+
+function hasTruthyBooleanProp(tagSource, prop) {
+  return new RegExp(
+    `\\b${prop}(?:\\s*=\\s*\\{\\s*true\\s*\\})?(?=\\s|\\/?>)`
+  ).test(tagSource)
+}
+
+function getLine(source, index = 0) {
+  return source.slice(0, index).split("\n").length
+}
+
+function diagnostic({ code, file, line, message, recommendation, severity }) {
+  return {
+    code,
+    severity,
+    ...(file ? { file } : {}),
+    ...(line ? { line } : {}),
+    message,
+    recommendation,
+  }
+}
+
+function compareDiagnostics(left, right) {
+  const severityOrder = { error: 0, warning: 1, info: 2 }
+  return (
+    severityOrder[left.severity] - severityOrder[right.severity] ||
+    (left.file || "").localeCompare(right.file || "") ||
+    (left.line || 0) - (right.line || 0) ||
+    left.code.localeCompare(right.code)
+  )
+}
+
+function normalizePath(value) {
+  return value.replaceAll("\\", "/")
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function readJsonIfExists(filePath, diagnostics, projectRoot) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"))
+  } catch (error) {
+    if (error.code === "ENOENT") return null
+    if (error instanceof SyntaxError) {
+      diagnostics.push(
+        diagnostic({
+          code: "install-receipt-invalid-json",
+          file: normalizePath(path.relative(projectRoot, filePath)),
+          message: "The Banhaten install receipt is not valid JSON.",
+          recommendation: "Review the file, then rebuild it with an explicit `banhaten add <component> --force`.",
+          severity: "error",
+        })
+      )
+      return null
+    }
+    throw error
+  }
+}

package/src/cli/file-transaction.js

@@ -0,0 +1,295 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+import process from "node:process"
+
+let activeFileTransaction = null
+let transactionFileCounter = 0
+
+export async function runFileTransaction(action) {
+  if (activeFileTransaction) {
+    throw new Error("nested file transactions are not supported")
+  }
+
+  const transaction = {
+    writes: new Map(),
+    preconditions: new Map(),
+    afterApply: [],
+  }
+  activeFileTransaction = transaction
+
+  try {
+    const result = await action()
+    await commitFileTransaction(transaction)
+    activeFileTransaction = null
+
+    for (const callback of transaction.afterApply) {
+      await callback()
+    }
+
+    return result
+  } catch (error) {
+    activeFileTransaction = null
+    throw error
+  }
+}
+
+export function deferUntilApplied(callback) {
+  if (!activeFileTransaction) {
+    return callback()
+  }
+
+  activeFileTransaction.afterApply.push(callback)
+}
+
+async function commitFileTransaction(transaction) {
+  const staged = []
+  const committed = []
+  const createdDirectories = new Set()
+  let failed = false
+
+  try {
+    await assertTransactionPreconditions(transaction)
+
+    for (const entry of transaction.writes.values()) {
+      await ensureDirectory(
+        path.dirname(entry.targetPath),
+        createdDirectories
+      )
+      const tempPath = `${entry.targetPath}.banhaten-${process.pid}-${transactionFileCounter += 1}.tmp`
+      const previous = await readFileSnapshot(entry.targetPath)
+
+      await fs.writeFile(tempPath, entry.content)
+      if (previous?.mode !== undefined) {
+        await fs.chmod(tempPath, previous.mode)
+      }
+      staged.push({ ...entry, tempPath, previous })
+    }
+
+    await assertTransactionPreconditions(transaction)
+
+    for (const entry of staged) {
+      await fs.rename(entry.tempPath, entry.targetPath)
+      committed.push(entry)
+    }
+  } catch (error) {
+    failed = true
+    for (const entry of [...committed].reverse()) {
+      await restoreFileSnapshot(entry.targetPath, entry.previous)
+    }
+
+    throw new Error(`file transaction failed and was rolled back: ${error.message}`)
+  } finally {
+    await Promise.all(
+      staged.map((entry) => fs.rm(entry.tempPath, { force: true }).catch(() => {}))
+    )
+    if (failed) {
+      await removeCreatedDirectories(createdDirectories)
+    }
+  }
+}
+
+async function ensureDirectory(targetPath, createdDirectories) {
+  const missing = []
+  let directory = targetPath
+
+  while (!(await exists(directory))) {
+    missing.push(directory)
+    const parent = path.dirname(directory)
+    if (parent === directory) break
+    directory = parent
+  }
+
+  for (const missingDirectory of missing.reverse()) {
+    try {
+      await fs.mkdir(missingDirectory)
+      createdDirectories.add(missingDirectory)
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error
+    }
+  }
+}
+
+async function removeCreatedDirectories(createdDirectories) {
+  for (const directory of [...createdDirectories].reverse()) {
+    await fs.rmdir(directory).catch(() => {})
+  }
+}
+
+async function assertTransactionPreconditions(transaction) {
+  for (const [targetPath, expectedCurrent] of transaction.preconditions) {
+    const current = await readFileSnapshot(targetPath)
+    assertExpectedCurrent(targetPath, current?.content ?? null, expectedCurrent)
+  }
+}
+
+async function readFileSnapshot(targetPath) {
+  try {
+    const [content, stats] = await Promise.all([
+      fs.readFile(targetPath),
+      fs.stat(targetPath),
+    ])
+    return { content, mode: stats.mode }
+  } catch (error) {
+    if (error.code === "ENOENT") return null
+    throw error
+  }
+}
+
+async function restoreFileSnapshot(targetPath, snapshot) {
+  if (!snapshot) {
+    await fs.rm(targetPath, { force: true })
+    return
+  }
+
+  const tempPath = `${targetPath}.banhaten-rollback-${process.pid}-${transactionFileCounter += 1}.tmp`
+  await fs.writeFile(tempPath, snapshot.content)
+  await fs.chmod(tempPath, snapshot.mode)
+  await fs.rename(tempPath, targetPath)
+}
+
+export async function writeFile(targetPath, content, options) {
+  const alreadyExists = await exists(targetPath)
+  const isBinary = Buffer.isBuffer(content)
+  const contentBuffer = isBinary ? content : Buffer.from(content, "utf8")
+  const current = alreadyExists ? await fs.readFile(targetPath) : null
+  const isEqual = current?.equals(contentBuffer) || false
+  if (options.expectedCurrent !== undefined) {
+    const expectedCurrent = toExpectedBuffer(options.expectedCurrent)
+    assertExpectedCurrent(targetPath, current, expectedCurrent)
+    registerPrecondition(targetPath, expectedCurrent)
+  }
+
+  if (options.dryRun) {
+    if (!alreadyExists) return "would write"
+    if (isEqual) return "would keep"
+
+    return "would update"
+  }
+
+  if (alreadyExists && isEqual) {
+    return "kept"
+  }
+
+  if (!activeFileTransaction) {
+    throw new Error(`refusing non-transactional write to ${targetPath}`)
+  }
+
+  const existingPlan = activeFileTransaction.writes.get(targetPath)
+  if (existingPlan && !existingPlan.content.equals(contentBuffer)) {
+    throw new Error(`conflicting planned writes for ${targetPath}`)
+  }
+  activeFileTransaction.writes.set(targetPath, {
+    targetPath,
+    content: contentBuffer,
+  })
+
+  return alreadyExists ? "updated" : "wrote"
+}
+
+export async function assertFileUnchanged(targetPath, expectedCurrent) {
+  if (!activeFileTransaction) {
+    throw new Error(`refusing non-transactional precondition for ${targetPath}`)
+  }
+
+  const expectedBuffer = toExpectedBuffer(expectedCurrent)
+  const current = await readFileContent(targetPath)
+  assertExpectedCurrent(targetPath, current, expectedBuffer)
+  registerPrecondition(targetPath, expectedBuffer)
+}
+
+function registerPrecondition(targetPath, expectedCurrent) {
+  if (!activeFileTransaction) {
+    throw new Error(`refusing non-transactional precondition for ${targetPath}`)
+  }
+
+  const existing = activeFileTransaction.preconditions.get(targetPath)
+  if (existing !== undefined) {
+    assertExpectedCurrent(targetPath, existing, expectedCurrent)
+    return
+  }
+  activeFileTransaction.preconditions.set(targetPath, expectedCurrent)
+}
+
+function assertExpectedCurrent(targetPath, current, expected) {
+  const matches = expected === null
+    ? current === null
+    : current?.equals(expected) || false
+  if (!matches) {
+    throw new Error(
+      `${targetPath} changed while Banhaten was preparing the install plan`
+    )
+  }
+}
+
+function toExpectedBuffer(expectedCurrent) {
+  return expectedCurrent === null
+    ? null
+    : Buffer.from(expectedCurrent)
+}
+
+async function readFileContent(targetPath) {
+  try {
+    return await fs.readFile(targetPath)
+  } catch (error) {
+    if (error.code === "ENOENT") return null
+    throw error
+  }
+}
+
+export function formatUnifiedDiff(fileLabel, currentContent, nextContent) {
+  const current = toDiffLines(currentContent)
+  const next = toDiffLines(nextContent)
+  let prefix = 0
+
+  while (
+    prefix < current.length &&
+    prefix < next.length &&
+    current[prefix] === next[prefix]
+  ) {
+    prefix += 1
+  }
+
+  let currentSuffix = current.length
+  let nextSuffix = next.length
+  while (
+    currentSuffix > prefix &&
+    nextSuffix > prefix &&
+    current[currentSuffix - 1] === next[nextSuffix - 1]
+  ) {
+    currentSuffix -= 1
+    nextSuffix -= 1
+  }
+
+  const context = 3
+  const start = Math.max(0, prefix - context)
+  const currentEnd = Math.min(current.length, currentSuffix + context)
+  const nextEnd = Math.min(next.length, nextSuffix + context)
+  const currentCount = currentEnd - start
+  const nextCount = nextEnd - start
+  const output = [
+    `--- a/${fileLabel}`,
+    `+++ b/${fileLabel}`,
+    `@@ -${start + 1},${currentCount} +${start + 1},${nextCount} @@`,
+  ]
+
+  for (const line of current.slice(start, prefix)) output.push(` ${line}`)
+  for (const line of current.slice(prefix, currentSuffix)) output.push(`-${line}`)
+  for (const line of next.slice(prefix, nextSuffix)) output.push(`+${line}`)
+  for (const line of current.slice(currentSuffix, currentEnd)) output.push(` ${line}`)
+
+  return output.join("\n")
+}
+
+function toDiffLines(content) {
+  if (Buffer.isBuffer(content)) return [`Binary content (${content.byteLength} bytes)`]
+  return String(content).replace(/\r\n/g, "\n").split("\n")
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}