banhaten 0.3.0 → 0.5.0

package/src/cli/doctor.js

@@ -1,399 +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
-  }
-}
+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
+  }
+}