@herb-tools/rewriter 0.8.0

package/src/built-ins/tailwind-class-sorter.ts

@@ -0,0 +1,278 @@
+import { getStaticAttributeName, isLiteralNode } from "@herb-tools/core"
+import { LiteralNode, Location, Visitor } from "@herb-tools/core"
+
+import { TailwindClassSorter } from "@herb-tools/tailwind-class-sorter"
+import { ASTRewriter } from "../ast-rewriter.js"
+import { asMutable } from "../mutable.js"
+
+import type { RewriteContext } from "../context.js"
+import type {
+  HTMLAttributeNode,
+  HTMLAttributeValueNode,
+  Node,
+  ERBIfNode,
+  ERBUnlessNode,
+  ERBElseNode,
+  ERBBlockNode,
+  ERBForNode,
+  ERBCaseNode,
+  ERBWhenNode,
+  ERBCaseMatchNode,
+  ERBInNode,
+  ERBWhileNode,
+  ERBUntilNode,
+  ERBBeginNode,
+  ERBRescueNode,
+  ERBEnsureNode
+} from "@herb-tools/core"
+
+/**
+ * Visitor that traverses the AST and sorts Tailwind CSS classes in class attributes.
+ */
+class TailwindClassSorterVisitor extends Visitor {
+  private sorter: TailwindClassSorter
+
+  constructor(sorter: TailwindClassSorter) {
+    super()
+
+    this.sorter = sorter
+  }
+
+  visitHTMLAttributeNode(node: HTMLAttributeNode): void {
+    if (!node.name) return
+    if (!node.value) return
+
+    const attributeName = getStaticAttributeName(node.name)
+    if (attributeName !== "class") return
+
+    this.visit(node.value)
+  }
+
+  visitHTMLAttributeValueNode(node: HTMLAttributeValueNode): void {
+    asMutable(node).children = this.formatNodes(node.children, false)
+  }
+
+  visitERBIfNode(node: ERBIfNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+
+    this.visit(node.subsequent)
+  }
+
+  visitERBElseNode(node: ERBElseNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  visitERBUnlessNode(node: ERBUnlessNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+
+    this.visit(node.else_clause)
+  }
+
+  visitERBBlockNode(node: ERBBlockNode): void {
+    asMutable(node).body = this.formatNodes(node.body, true)
+  }
+
+  visitERBForNode(node: ERBForNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  visitERBWhenNode(node: ERBWhenNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  visitERBCaseNode(node: ERBCaseNode): void {
+    this.visitAll(node.children)
+    this.visit(node.else_clause)
+  }
+
+  visitERBCaseMatchNode(node: ERBCaseMatchNode): void {
+    this.visitAll(node.children)
+    this.visit(node.else_clause)
+  }
+
+  visitERBInNode(node: ERBInNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  visitERBWhileNode(node: ERBWhileNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  visitERBUntilNode(node: ERBUntilNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  visitERBBeginNode(node: ERBBeginNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+    this.visit(node.rescue_clause)
+    this.visit(node.else_clause)
+    this.visit(node.ensure_clause)
+  }
+
+  visitERBRescueNode(node: ERBRescueNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+    this.visit(node.subsequent)
+  }
+
+  visitERBEnsureNode(node: ERBEnsureNode): void {
+    asMutable(node).statements = this.formatNodes(node.statements, true)
+  }
+
+  private get spaceLiteral(): LiteralNode {
+    return new LiteralNode({
+      type: "AST_LITERAL_NODE",
+      content: " ",
+      errors: [],
+      location: Location.zero
+    })
+  }
+
+  private startsWithClassLiteral(nodes: Node[]): boolean {
+    return nodes.length > 0 && isLiteralNode(nodes[0]) && !!nodes[0].content.trim()
+  }
+
+  private isWhitespaceLiteral(node: Node): boolean {
+    return isLiteralNode(node) && !node.content.trim()
+  }
+
+  private formatNodes(nodes: Node[], isNested: boolean): Node[] {
+    const { classLiterals, others } = this.partitionNodes(nodes)
+    const preserveLeadingSpace = isNested || this.startsWithClassLiteral(nodes)
+
+    return this.formatSortedClasses(classLiterals, others, preserveLeadingSpace, isNested)
+  }
+
+  private partitionNodes(nodes: Node[]): { classLiterals: LiteralNode[], others: Node[] } {
+    const classLiterals: LiteralNode[] = []
+    const others: Node[] = []
+
+    for (const node of nodes) {
+      if (isLiteralNode(node)) {
+        if (node.content.trim()) {
+          classLiterals.push(node)
+        } else {
+          others.push(node)
+        }
+      } else {
+        this.visit(node)
+        others.push(node)
+      }
+    }
+
+    return { classLiterals, others }
+  }
+
+  private formatSortedClasses(literals: LiteralNode[], others: Node[], preserveLeadingSpace: boolean, isNested: boolean): Node[] {
+    if (literals.length === 0 && others.length === 0) return []
+    if (literals.length === 0) return others
+
+    const fullContent = literals.map(n => n.content).join("")
+    const trimmedClasses = fullContent.trim()
+
+    if (!trimmedClasses) return others.length > 0 ? others : []
+
+    try {
+      const sortedClasses = this.sorter.sortClasses(trimmedClasses)
+
+      if (others.length === 0) {
+        return this.formatSortedLiteral(literals[0], fullContent, sortedClasses, trimmedClasses)
+      }
+
+      return this.formatSortedLiteralWithERB(literals[0], fullContent, sortedClasses, others, preserveLeadingSpace, isNested)
+    } catch (error) {
+      return [...literals, ...others]
+    }
+  }
+
+  private formatSortedLiteral(literal: LiteralNode, fullContent: string, sortedClasses: string, trimmedClasses: string): Node[] {
+    const leadingSpace = fullContent.match(/^\s*/)?.[0] || ""
+    const trailingSpace = fullContent.match(/\s*$/)?.[0] || ""
+    const alreadySorted = sortedClasses === trimmedClasses
+
+    const sortedContent = alreadySorted ? fullContent : (leadingSpace + sortedClasses + trailingSpace)
+
+    asMutable(literal).content = sortedContent
+
+    return [literal]
+  }
+
+  private formatSortedLiteralWithERB(literal: LiteralNode, fullContent: string, sortedClasses: string, others: Node[], preserveLeadingSpace: boolean, isNested: boolean): Node[] {
+    const leadingSpace = fullContent.match(/^\s*/)?.[0] || ""
+    const trailingSpace = fullContent.match(/\s*$/)?.[0] || ""
+
+    const leading = preserveLeadingSpace ? leadingSpace : ""
+    const firstIsWhitespace = this.isWhitespaceLiteral(others[0])
+    const spaceBetween = firstIsWhitespace ? "" : " "
+
+    asMutable(literal).content = leading + sortedClasses + spaceBetween
+
+    const othersWithWhitespace = this.addSpacingBetweenERBNodes(others, isNested, trailingSpace)
+
+    return [literal, ...othersWithWhitespace]
+  }
+
+  private addSpacingBetweenERBNodes(nodes: Node[], isNested: boolean, trailingSpace: string): Node[] {
+    return nodes.flatMap((node, index) => {
+      const isLast = index >= nodes.length - 1
+
+      if (isLast) {
+        return isNested && trailingSpace ? [node, this.spaceLiteral] : [node]
+      }
+
+      const currentIsWhitespace = this.isWhitespaceLiteral(node)
+      const nextIsWhitespace = this.isWhitespaceLiteral(nodes[index + 1])
+      const needsSpace = !currentIsWhitespace && !nextIsWhitespace
+
+      return needsSpace ? [node, this.spaceLiteral] : [node]
+    })
+  }
+}
+
+/**
+ * Built-in rewriter that sorts Tailwind CSS classes in class and className attributes
+ */
+export class TailwindClassSorterRewriter extends ASTRewriter {
+  private sorter?: TailwindClassSorter
+
+  get name(): string {
+    return "tailwind-class-sorter"
+  }
+
+  get description(): string {
+    return "Sorts Tailwind CSS classes in class and className attributes according to the recommended class order"
+  }
+
+  async initialize(context: RewriteContext): Promise<void> {
+    try {
+      this.sorter = await TailwindClassSorter.fromConfig({
+        baseDir: context.baseDir
+      })
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+
+      if (errorMessage.includes('Cannot find module') || errorMessage.includes('ENOENT')) {
+        throw new Error(
+          `Tailwind CSS is not installed in this project. ` +
+          `To use the Tailwind class sorter, install Tailwind CSS itself using: npm install -D tailwindcss, ` +
+          `or remove the "tailwind-class-sorter" rewriter from your .herb.yml config file.\n` +
+          `If "tailwindcss" is already part of your package.json, make sure your NPM dependencies are installed.\n` +
+          `Original error: ${errorMessage}.`
+        )
+      }
+
+      throw error
+    }
+  }
+
+  rewrite<T extends Node>(node: T, _context: RewriteContext): T {
+    if (!this.sorter) {
+      return node
+    }
+
+    const visitor = new TailwindClassSorterVisitor(this.sorter)
+
+    visitor.visit(node)
+
+    return node
+  }
+}

package/src/context.ts

@@ -0,0 +1,21 @@
+/**
+ * Context passed to rewriters during initialization and rewriting
+ *
+ * Provides information about the current file and project being processed
+ */
+export interface RewriteContext {
+  /**
+   * Path to the file being rewritten (if available)
+   */
+  filePath?: string
+
+  /**
+   * Base directory of the project
+   */
+  baseDir: string
+
+  /**
+   * Additional context data that can be added by the framework
+   */
+  [key: string]: any
+}

package/src/custom-rewriter-loader.ts

@@ -0,0 +1,187 @@
+import { pathToFileURL } from "url"
+import { glob } from "glob"
+import { isRewriterClass } from "./type-guards.js"
+
+import type { RewriterClass } from "./type-guards.js"
+
+export interface CustomRewriterLoaderOptions {
+  /**
+   * Base directory to search for custom rewriters
+   * Defaults to current working directory
+   */
+  baseDir?: string
+
+  /**
+   * Glob patterns to search for custom rewriter files
+   * Defaults to looking in .herb/rewriters/
+   */
+  patterns?: string[]
+
+  /**
+   * Whether to suppress errors when loading custom rewriters
+   * Defaults to false
+   */
+  silent?: boolean
+}
+
+const DEFAULT_PATTERNS = [
+  ".herb/rewriters/**/*.mjs",
+]
+
+/**
+ * Loads custom rewriters from the user's project
+ *
+ * Auto-discovers rewriter files in `.herb/rewriters/` by default
+ * and dynamically imports them for use in the formatter.
+ *
+ * @example
+ * ```typescript
+ * const loader = new CustomRewriterLoader({ baseDir: process.cwd() })
+ * const customRewriters = await loader.loadRewriters()
+ * ```
+ */
+export class CustomRewriterLoader {
+  private baseDir: string
+  private patterns: string[]
+  private silent: boolean
+
+  constructor(options: CustomRewriterLoaderOptions = {}) {
+    this.baseDir = options.baseDir || process.cwd()
+    this.patterns = options.patterns || DEFAULT_PATTERNS
+    this.silent = options.silent || false
+  }
+
+  /**
+   * Discovers custom rewriter files in the project
+   */
+  async discoverRewriterFiles(): Promise<string[]> {
+    const allFiles: string[] = []
+
+    for (const pattern of this.patterns) {
+      try {
+        const files = await glob(pattern, {
+          cwd: this.baseDir,
+          absolute: true,
+          nodir: true
+        })
+
+        allFiles.push(...files)
+      } catch (error) {
+        if (!this.silent) {
+          console.warn(`Warning: Failed to search pattern "${pattern}": ${error}`)
+        }
+      }
+    }
+
+    return [...new Set(allFiles)]
+  }
+
+  /**
+   * Loads a single rewriter file
+   */
+  async loadRewriterFile(filePath: string): Promise<RewriterClass[]> {
+    try {
+      const fileUrl = pathToFileURL(filePath).href
+      const cacheBustedUrl = `${fileUrl}?t=${Date.now()}`
+      const module = await import(cacheBustedUrl)
+
+      if (module.default && isRewriterClass(module.default)) {
+        return [module.default]
+      }
+
+      if (!this.silent) {
+        console.warn(`Warning: No valid default export found in "${filePath}". Custom rewriters must use default export.`)
+      }
+
+      return []
+    } catch (error) {
+      if (!this.silent) {
+        console.error(`Error loading rewriter file "${filePath}": ${error}`)
+      }
+      return []
+    }
+  }
+
+  /**
+   * Loads all custom rewriters from the project
+   */
+  async loadRewriters(): Promise<RewriterClass[]> {
+    const rewriterFiles = await this.discoverRewriterFiles()
+
+    if (rewriterFiles.length === 0) {
+      return []
+    }
+
+    const allRewriters: RewriterClass[] = []
+
+    for (const filePath of rewriterFiles) {
+      const rewriters = await this.loadRewriterFile(filePath)
+      allRewriters.push(...rewriters)
+    }
+
+    return allRewriters
+  }
+
+  /**
+   * Loads all custom rewriters and returns detailed information about each rewriter
+   */
+  async loadRewritersWithInfo(): Promise<{rewriters: RewriterClass[], rewriterInfo: Array<{ name: string, path: string }>, duplicateWarnings: string[]}> {
+    const rewriterFiles = await this.discoverRewriterFiles()
+
+    if (rewriterFiles.length === 0) {
+      return { rewriters: [], rewriterInfo: [], duplicateWarnings: [] }
+    }
+
+    const allRewriters: RewriterClass[] = []
+    const rewriterInfo: Array<{ name: string, path: string }> = []
+    const duplicateWarnings: string[] = []
+    const seenNames = new Map<string, string>()
+
+    for (const filePath of rewriterFiles) {
+      const rewriters = await this.loadRewriterFile(filePath)
+
+      for (const RewriterClass of rewriters) {
+        const instance = new RewriterClass()
+        const rewriterName = instance.name
+
+        if (seenNames.has(rewriterName)) {
+          const firstPath = seenNames.get(rewriterName)!
+
+          duplicateWarnings.push(
+            `Custom rewriter "${rewriterName}" is defined in multiple files: "${firstPath}" and "${filePath}". The later one will be used.`
+          )
+        } else {
+          seenNames.set(rewriterName, filePath)
+        }
+
+        allRewriters.push(RewriterClass)
+        rewriterInfo.push({
+          name: rewriterName,
+          path: filePath
+        })
+      }
+    }
+
+    return { rewriters: allRewriters, rewriterInfo, duplicateWarnings }
+  }
+
+  /**
+   * Static helper to check if custom rewriters exist in a project
+   */
+  static async hasCustomRewriters(baseDir: string = process.cwd()): Promise<boolean> {
+    const loader = new CustomRewriterLoader({ baseDir, silent: true })
+    const files = await loader.discoverRewriterFiles()
+
+    return files.length > 0
+  }
+
+  /**
+   * Static helper to load custom rewriters and merge with built-in rewriters
+   */
+  static async loadAndMergeRewriters(builtinRewriters: RewriterClass[], options: CustomRewriterLoaderOptions = {}): Promise<RewriterClass[]> {
+    const loader = new CustomRewriterLoader(options)
+    const customRewriters = await loader.loadRewriters()
+
+    return [...builtinRewriters, ...customRewriters]
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { ASTRewriter } from "./ast-rewriter.js"
+export { StringRewriter } from "./string-rewriter.js"
+
+export { asMutable } from "./mutable.js"
+export { isASTRewriterClass, isStringRewriterClass, isRewriterClass } from "./type-guards.js"
+
+export { rewrite, rewriteString } from "./rewrite.js"
+
+export type { RewriteContext } from "./context.js"
+export type { Mutable } from "./mutable.js"
+export type { RewriterClass } from "./type-guards.js"
+export type { Rewriter, RewriteOptions, RewriteResult } from "./rewrite.js"
+export type { TailwindClassSorterOptions } from "./rewriter-factories.js"

package/src/loader.ts

@@ -0,0 +1,8 @@
+export * from "./index.js"
+
+export { CustomRewriterLoader } from "./custom-rewriter-loader.js"
+export type { CustomRewriterLoaderOptions } from "./custom-rewriter-loader.js"
+
+export { TailwindClassSorterRewriter } from "./built-ins/index.js"
+export { tailwindClassSorter } from "./rewriter-factories.js"
+export { builtinRewriters, getBuiltinRewriter, getBuiltinRewriterNames } from "./built-ins/index.js"

package/src/mutable.ts

@@ -0,0 +1,22 @@
+/**
+ * Utility type for making readonly properties mutable
+ *
+ * This is useful when you need to modify AST nodes which typically have
+ * readonly properties. Use sparingly and only in rewriter contexts.
+ */
+export type Mutable<T> = T extends ReadonlyArray<infer U>
+  ? Array<Mutable<U>>
+  : T extends object
+    ? { -readonly [K in keyof T]: Mutable<T[K]> }
+    : T
+
+/**
+ * Cast a readonly value to a mutable version
+ *
+ * @example
+ * const literalNode = asMutable(node)
+ * literalNode.content = "new value"
+ */
+export function asMutable<T>(node: T): Mutable<T> {
+  return node as Mutable<T>
+}

package/src/rewrite.ts

@@ -0,0 +1,132 @@
+import { IdentityPrinter } from "@herb-tools/printer"
+
+import { ASTRewriter } from "./ast-rewriter.js"
+import { StringRewriter } from "./string-rewriter.js"
+
+import type { HerbBackend, Node } from "@herb-tools/core"
+import type { RewriteContext } from "./context.js"
+
+export type Rewriter = ASTRewriter | StringRewriter
+
+export interface RewriteOptions {
+  /**
+   * Base directory for resolving configuration files
+   * Defaults to process.cwd()
+   */
+  baseDir?: string
+
+  /**
+   * Optional file path for context
+   */
+  filePath?: string
+}
+
+export interface RewriteResult {
+  /**
+   * The rewritten template string
+   */
+  output: string
+
+  /**
+   * The rewritten AST node
+   */
+  node: Node
+}
+
+/**
+ * Rewrite an AST Node using the provided rewriters
+ *
+ * This is the main rewrite function that operates on AST nodes.
+ * For string input, use `rewriteString()` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Herb } from '@herb-tools/node-wasm'
+ * import { rewrite } from '@herb-tools/rewriter'
+ * import { tailwindClassSorter } from '@herb-tools/rewriter/loader'
+ *
+ * await Herb.load()
+ *
+ * const template = '<div class="text-red-500 p-4 mt-2"></div>'
+ * const parseResult = Herb.parse(template)
+ * const { output, node } = rewrite(parseResult.value, [tailwindClassSorter()])
+ * ```
+ *
+ * @param node - The AST Node to rewrite
+ * @param rewriters - Array of rewriter instances to apply
+ * @param options - Optional configuration for the rewrite operation
+ * @returns Object containing the rewritten string and Node
+ */
+export function rewrite<T extends Node>(node: T, rewriters: Rewriter[], options: RewriteOptions = {}): RewriteResult & { node: T } {
+  const { baseDir = process.cwd(), filePath } = options
+
+  const context: RewriteContext = { baseDir, filePath }
+
+  let currentNode = node
+
+  const astRewriters = rewriters.filter(rewriter => rewriter instanceof ASTRewriter)
+  const stringRewriters = rewriters.filter(rewriter => rewriter instanceof StringRewriter)
+
+  for (const rewriter of astRewriters) {
+    try {
+      currentNode = rewriter.rewrite(currentNode, context)
+    } catch (error) {
+      console.error(`AST rewriter "${rewriter.name}" failed:`, error)
+    }
+  }
+
+  let result = IdentityPrinter.print(currentNode)
+
+  for (const rewriter of stringRewriters) {
+    try {
+      result = rewriter.rewrite(result, context)
+    } catch (error) {
+      console.error(`String rewriter "${rewriter.name}" failed:`, error)
+    }
+  }
+
+  return {
+    output: result,
+    node: currentNode
+  }
+}
+
+/**
+ * Rewrite an HTML+ERB template string
+ *
+ * Convenience wrapper around `rewrite()` that parses the string first.
+ *
+ * @example
+ * ```typescript
+ * import { Herb } from '@herb-tools/node-wasm'
+ * import { rewriteString } from '@herb-tools/rewriter'
+ * import { tailwindClassSorter } from '@herb-tools/rewriter/loader'
+ *
+ * await Herb.load()
+ *
+ * const template = '<div class="text-red-500 p-4 mt-2"></div>'
+ * const output = rewriteString(Herb, template, [tailwindClassSorter()])
+ * // output: '<div class="mt-2 p-4 text-red-500"></div>'
+ * ```
+ *
+ * @param herb - The Herb backend instance for parsing
+ * @param template - The HTML+ERB template string to rewrite
+ * @param rewriters - Array of rewriter instances to apply
+ * @param options - Optional configuration for the rewrite operation
+ * @returns The rewritten template string
+ */
+export function rewriteString(herb: HerbBackend, template: string, rewriters: Rewriter[], options: RewriteOptions = {}): string {
+  const parseResult = herb.parse(template, { track_whitespace: true })
+
+  if (parseResult.failed) {
+    return template
+  }
+
+  const { output } = rewrite(
+    parseResult.value,
+    rewriters,
+    options
+  )
+
+  return output
+}

package/src/rewriter-factories.ts

@@ -0,0 +1,37 @@
+import { TailwindClassSorterRewriter } from "./built-ins/tailwind-class-sorter.js"
+
+export interface TailwindClassSorterOptions {
+  /**
+   * Base directory for resolving Tailwind configuration
+   * Defaults to process.cwd()
+   */
+  baseDir?: string
+}
+
+/**
+ * Factory function for creating a Tailwind class sorter rewriter
+ *
+ * Automatically initializes the rewriter before returning it.
+ *
+ * @example
+ * ```typescript
+ * import { rewrite } from '@herb-tools/rewriter'
+ * import { tailwindClassSorter } from '@herb-tools/rewriter/loader'
+ *
+ * const template = '<div class="text-red-500 p-4 mt-2"></div>'
+ * const sorter = await tailwindClassSorter()
+ * const result = rewrite(template, [sorter])
+ * // Result: '<div class="mt-2 p-4 text-red-500"></div>'
+ * ```
+ *
+ * @param options - Optional configuration for the Tailwind class sorter
+ * @returns A configured and initialized TailwindClassSorterRewriter instance
+ */
+export async function tailwindClassSorter(options: TailwindClassSorterOptions = {}): Promise<TailwindClassSorterRewriter> {
+  const rewriter = new TailwindClassSorterRewriter()
+  const baseDir = options.baseDir || process.cwd()
+
+  await rewriter.initialize({ baseDir })
+
+  return rewriter
+}