@herb-tools/rewriter 0.8.0

package/dist/types/ast-rewriter.d.ts

@@ -0,0 +1,64 @@
+import type { Node } from "@herb-tools/core";
+import type { RewriteContext } from "./context.js";
+/**
+ * Base class for AST rewriters that transform AST nodes before formatting
+ *
+ * AST rewriters receive a Node and can mutate it in place or return a modified Node.
+ * They run before the formatting step.
+ *
+ * @example
+ * ```typescript
+ * import { ASTRewriter, asMutable } from "@herb-tools/rewriter"
+ * import { Visitor } from "@herb-tools/core"
+ *
+ * class MyRewriter extends ASTRewriter {
+ *   get name() { return "my-rewriter" }
+ *   get description() { return "My custom AST rewriter" }
+ *
+ *   async initialize(context) {
+ *     // Load config, initialize dependencies, etc.
+ *   }
+ *
+ *   rewrite(node, context) {
+ *     // Use visitor pattern to traverse and modify AST
+ *     const visitor = new MyVisitor()
+ *     visitor.visit(node)
+ *
+ *     return node
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ASTRewriter {
+    /**
+     * Unique identifier for this rewriter
+     * Used in configuration and error messages
+     */
+    abstract get name(): string;
+    /**
+     * Human-readable description of what this rewriter does
+     */
+    abstract get description(): string;
+    /**
+     * Optional async initialization hook
+     *
+     * Called once before the first rewrite operation. Use this to:
+     * - Load configuration files
+     * - Initialize dependencies
+     * - Perform expensive setup operations
+     *
+     * @param context - Context with baseDir and optional filePath
+     */
+    initialize(_context: RewriteContext): Promise<void>;
+    /**
+     * Transform the AST node
+     *
+     * This method is called synchronously for each file being formatted.
+     * Modify the AST in place or return a new Node.
+     *
+     * @param node - The AST node from @herb-tools/core
+     * @param context - Context with filePath and baseDir
+     * @returns The modified Node (can be the same object mutated in place)
+     */
+    abstract rewrite<T extends Node>(node: T, context: RewriteContext): T;
+}

package/dist/types/built-ins/index.d.ts

@@ -0,0 +1,14 @@
+import type { RewriterClass } from "../type-guards.js";
+export { TailwindClassSorterRewriter } from "./tailwind-class-sorter.js";
+/**
+ * All built-in rewriters available in the package
+ */
+export declare const builtinRewriters: RewriterClass[];
+/**
+ * Get a built-in rewriter by name
+ */
+export declare function getBuiltinRewriter(name: string): RewriterClass | undefined;
+/**
+ * Get all built-in rewriter names
+ */
+export declare function getBuiltinRewriterNames(): string[];

package/dist/types/built-ins/tailwind-class-sorter.d.ts

@@ -0,0 +1,13 @@
+import { ASTRewriter } from "../ast-rewriter.js";
+import type { RewriteContext } from "../context.js";
+import type { Node } from "@herb-tools/core";
+/**
+ * Built-in rewriter that sorts Tailwind CSS classes in class and className attributes
+ */
+export declare class TailwindClassSorterRewriter extends ASTRewriter {
+    private sorter?;
+    get name(): string;
+    get description(): string;
+    initialize(context: RewriteContext): Promise<void>;
+    rewrite<T extends Node>(node: T, _context: RewriteContext): T;
+}

package/dist/types/context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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/dist/types/custom-rewriter-loader.d.ts

@@ -0,0 +1,67 @@
+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;
+}
+/**
+ * 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 declare class CustomRewriterLoader {
+    private baseDir;
+    private patterns;
+    private silent;
+    constructor(options?: CustomRewriterLoaderOptions);
+    /**
+     * Discovers custom rewriter files in the project
+     */
+    discoverRewriterFiles(): Promise<string[]>;
+    /**
+     * Loads a single rewriter file
+     */
+    loadRewriterFile(filePath: string): Promise<RewriterClass[]>;
+    /**
+     * Loads all custom rewriters from the project
+     */
+    loadRewriters(): Promise<RewriterClass[]>;
+    /**
+     * Loads all custom rewriters and returns detailed information about each rewriter
+     */
+    loadRewritersWithInfo(): Promise<{
+        rewriters: RewriterClass[];
+        rewriterInfo: Array<{
+            name: string;
+            path: string;
+        }>;
+        duplicateWarnings: string[];
+    }>;
+    /**
+     * Static helper to check if custom rewriters exist in a project
+     */
+    static hasCustomRewriters(baseDir?: string): Promise<boolean>;
+    /**
+     * Static helper to load custom rewriters and merge with built-in rewriters
+     */
+    static loadAndMergeRewriters(builtinRewriters: RewriterClass[], options?: CustomRewriterLoaderOptions): Promise<RewriterClass[]>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+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/dist/types/loader.d.ts

@@ -0,0 +1,6 @@
+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/dist/types/mutable.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare function asMutable<T>(node: T): Mutable<T>;

package/dist/types/rewrite.d.ts

@@ -0,0 +1,77 @@
+import { ASTRewriter } from "./ast-rewriter.js";
+import { StringRewriter } from "./string-rewriter.js";
+import type { HerbBackend, Node } from "@herb-tools/core";
+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 declare function rewrite<T extends Node>(node: T, rewriters: Rewriter[], options?: RewriteOptions): RewriteResult & {
+    node: T;
+};
+/**
+ * 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 declare function rewriteString(herb: HerbBackend, template: string, rewriters: Rewriter[], options?: RewriteOptions): string;

package/dist/types/rewriter-factories.d.ts

@@ -0,0 +1,28 @@
+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 declare function tailwindClassSorter(options?: TailwindClassSorterOptions): Promise<TailwindClassSorterRewriter>;

package/dist/types/string-rewriter.d.ts

@@ -0,0 +1,54 @@
+import type { RewriteContext } from "./context.js";
+/**
+ * Base class for string rewriters that transform the formatted output
+ *
+ * String rewriters receive the formatted string and can modify it before
+ * returning the final output. They run after the formatting step.
+ *
+ * @example
+ * ```typescript
+ * import { StringRewriter } from "@herb-tools/rewriter"
+ *
+ * class AddTrailingNewline extends StringRewriter {
+ *   get name() { return "add-trailing-newline" }
+ *   get description() { return "Ensures file ends with a newline" }
+ *
+ *   rewrite(formatted, context) {
+ *     return formatted.endsWith("\n") ? formatted : formatted + "\n"
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StringRewriter {
+    /**
+     * Unique identifier for this rewriter
+     * Used in configuration and error messages
+     */
+    abstract get name(): string;
+    /**
+     * Human-readable description of what this rewriter does
+     */
+    abstract get description(): string;
+    /**
+     * Optional async initialization hook
+     *
+     * Called once before the first rewrite operation. Use this to:
+     * - Load configuration files
+     * - Initialize dependencies
+     * - Perform expensive setup operations
+     *
+     * @param context - Context with baseDir and optional filePath
+     */
+    initialize(_context: RewriteContext): Promise<void>;
+    /**
+     * Transform the formatted string
+     *
+     * This method is called synchronously for each file being formatted.
+     * Return the modified string.
+     *
+     * @param formatted - The formatted string output from the formatter
+     * @param context - Context with filePath and baseDir
+     * @returns The modified string
+     */
+    abstract rewrite(formatted: string, context: RewriteContext): string;
+}

package/dist/types/type-guards.d.ts

@@ -0,0 +1,20 @@
+import { ASTRewriter } from "./ast-rewriter.js";
+import { StringRewriter } from "./string-rewriter.js";
+/**
+ * Type guard to check if a class is an ASTRewriter
+ * Uses duck typing to work across module boundaries
+ */
+export declare function isASTRewriterClass(obj: any): obj is new () => ASTRewriter;
+/**
+ * Type guard to check if a class is a StringRewriter
+ * Uses duck typing to work across module boundaries
+ */
+export declare function isStringRewriterClass(obj: any): obj is new () => StringRewriter;
+/**
+ * Union type for all rewriter classes
+ */
+export type RewriterClass = (new () => ASTRewriter) | (new () => StringRewriter);
+/**
+ * Type guard to check if a class is any kind of rewriter
+ */
+export declare function isRewriterClass(obj: any): obj is RewriterClass;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@herb-tools/rewriter",
+  "version": "0.8.0",
+  "description": "Rewriter system for transforming HTML+ERB AST nodes and formatted strings",
+  "license": "MIT",
+  "homepage": "https://herb-tools.dev",
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/rewriter%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/rewriter"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.esm.js",
+  "require": "./dist/index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "yarn clean && rollup -c rollup.config.mjs",
+    "dev": "rollup -c rollup.config.mjs -w",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.esm.js"
+    },
+    "./loader": {
+      "types": "./dist/types/loader.d.ts",
+      "import": "./dist/loader.esm.js",
+      "require": "./dist/loader.cjs",
+      "default": "./dist/loader.esm.js"
+    }
+  },
+  "dependencies": {
+    "@herb-tools/core": "0.8.0",
+    "@herb-tools/tailwind-class-sorter": "0.8.0",
+    "glob": "^11.0.3"
+  },
+  "devDependencies": {
+    "@herb-tools/printer": "0.8.0"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "dist/",
+    "src/"
+  ]
+}

package/src/ast-rewriter.ts

@@ -0,0 +1,70 @@
+import type { Node } from "@herb-tools/core"
+import type { RewriteContext } from "./context.js"
+
+/**
+ * Base class for AST rewriters that transform AST nodes before formatting
+ *
+ * AST rewriters receive a Node and can mutate it in place or return a modified Node.
+ * They run before the formatting step.
+ *
+ * @example
+ * ```typescript
+ * import { ASTRewriter, asMutable } from "@herb-tools/rewriter"
+ * import { Visitor } from "@herb-tools/core"
+ *
+ * class MyRewriter extends ASTRewriter {
+ *   get name() { return "my-rewriter" }
+ *   get description() { return "My custom AST rewriter" }
+ *
+ *   async initialize(context) {
+ *     // Load config, initialize dependencies, etc.
+ *   }
+ *
+ *   rewrite(node, context) {
+ *     // Use visitor pattern to traverse and modify AST
+ *     const visitor = new MyVisitor()
+ *     visitor.visit(node)
+ *
+ *     return node
+ *   }
+ * }
+ * ```
+ */
+export abstract class ASTRewriter {
+  /**
+   * Unique identifier for this rewriter
+   * Used in configuration and error messages
+   */
+  abstract get name(): string
+
+  /**
+   * Human-readable description of what this rewriter does
+   */
+  abstract get description(): string
+
+  /**
+   * Optional async initialization hook
+   *
+   * Called once before the first rewrite operation. Use this to:
+   * - Load configuration files
+   * - Initialize dependencies
+   * - Perform expensive setup operations
+   *
+   * @param context - Context with baseDir and optional filePath
+   */
+  async initialize(_context: RewriteContext): Promise<void> {
+    // Override in subclass if needed
+  }
+
+  /**
+   * Transform the AST node
+   *
+   * This method is called synchronously for each file being formatted.
+   * Modify the AST in place or return a new Node.
+   *
+   * @param node - The AST node from @herb-tools/core
+   * @param context - Context with filePath and baseDir
+   * @returns The modified Node (can be the same object mutated in place)
+   */
+  abstract rewrite<T extends Node>(node: T, context: RewriteContext): T
+}

package/src/built-ins/index.ts

@@ -0,0 +1,33 @@
+import type { RewriterClass } from "../type-guards.js"
+
+export { TailwindClassSorterRewriter } from "./tailwind-class-sorter.js"
+import { TailwindClassSorterRewriter } from "./tailwind-class-sorter.js"
+
+/**
+ * All built-in rewriters available in the package
+ */
+export const builtinRewriters: RewriterClass[] = [
+  TailwindClassSorterRewriter
+]
+
+/**
+ * Get a built-in rewriter by name
+ */
+export function getBuiltinRewriter(name: string): RewriterClass | undefined {
+  return builtinRewriters.find(RewriterClass => {
+    const instance = new RewriterClass()
+
+    return instance.name === name
+  })
+}
+
+/**
+ * Get all built-in rewriter names
+ */
+export function getBuiltinRewriterNames(): string[] {
+  return builtinRewriters.map(RewriterClass => {
+    const instance = new RewriterClass()
+
+    return instance.name
+  })
+}