Herb Formatter (#192)

This pull request introduces a new package, `@herb-tools/formatter`,
which provides utilities for formatting HTML+ERB templates.

It includes the implementation of the formatter logic, adds a CLI to
test the formatting using `bin/herb-formatter [file]`, implements the
Formatter into the language-server for format-on-save support, and adds
a new tab to the playground to play with the formatter in the
browser-based playground.

Note: the current state of this is not 100% ready yet, as it formats a lot of
documents in a sub-optimal way.

![CleanShot 2025-06-29 at 18 23
56@2x](https://github.com/user-attachments/assets/2c04f652-605c-46fd-91c2-df0e102a1b4d)


https://github.com/user-attachments/assets/e1c22310-38dd-4fd8-8702-3a1ca06c7659

![CleanShot 2025-06-29 at 18 19
52@2x](https://github.com/user-attachments/assets/651f6a4f-719d-4f37-a15a-95b59e263ba2)

![CleanShot 2025-06-29 at 18 20
52@2x](https://github.com/user-attachments/assets/65999cba-ff72-4e41-bbf2-f1bfcedaf195)

---------

Signed-off-by: Marco Roth <marco.roth@intergga.ch>

Author: marcoroth

javascript/packages/core/src/parse-result.ts

@@ -61,16 +61,16 @@ export class ParseResult extends Result {
    * @returns `true` if there are errors, otherwise `false`.
    */
   get failed(): boolean {
-    // TODO: this should probably be recursive as noted in the Ruby version
-    return this.errors.length > 0 || this.value.errors.length > 0
+    // Consider errors on this result and recursively in the document tree
+    return this.recursiveErrors().length > 0
   }
 
   /**
    * Determines if the parsing was successful.
    * @returns `true` if there are no errors, otherwise `false`.
    */
   get successful(): boolean {
-    return this.errors.length === 0
+    return !this.failed
   }
 
   /**

javascript/packages/formatter/README.md

@@ -29,9 +29,26 @@ bun add @herb-tools/formatter
 ```
 :::
 
-<!-- ### Usage -->
+### Usage
 
-<!-- TODO -->
+
+#### Format a file
+
+```bash
+# relative path
+herb-formatter templates/index.html.erb
+
+# absolute path
+herb-formatter /full/path/to/template.html.erb
+```
+
+#### Format from stdin
+
+```bash
+cat template.html.erb | herb-formatter
+# or explicitly use "-" for stdin
+herb-formatter - < template.html.erb
+```
 
 <!-- #### Configuration Options -->
 

javascript/packages/formatter/bin/herb-formatter

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import("../dist/herb-formatter.js")

javascript/packages/formatter/format-result.ts

@@ -0,0 +1,15 @@
+import { Result, HerbError, HerbWarning } from "@herb-tools/core"
+
+export class FormatResult extends Result {
+  readonly value: string
+
+  constructor(
+    value: string,
+    source: string,
+    warnings: HerbWarning[] = [],
+    errors: HerbError[] = [],
+  ) {
+    super(source, warnings, errors)
+    this.value = value
+  }
+}

javascript/packages/formatter/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@herb-tools/formatter",
+  "version": "0.3.1",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://herb-tools.dev",
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/formatter%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/formatter"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.esm.js",
+  "require": "./dist/index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "herb-formatter": "bin/herb-formatter"
+  },
+  "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"
+    }
+  },
+  "dependencies": {
+    "@herb-tools/core": "0.3.1"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "dist/",
+    "src/",
+    "bin/"
+  ]
+}

javascript/packages/formatter/rollup.config.mjs

@@ -0,0 +1,65 @@
+import typescript from "@rollup/plugin-typescript"
+import { nodeResolve } from "@rollup/plugin-node-resolve"
+import json from "@rollup/plugin-json"
+
+const external = [
+  // ...
+]
+
+export default [
+  // CLI build
+  {
+    input: "src/herb-formatter.ts",
+    output: {
+      file: "dist/herb-formatter.js",
+      format: "esm",
+      sourcemap: true,
+    },
+    external,
+    plugins: [
+      nodeResolve(),
+      json(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        rootDir: "src/",
+        module: "esnext",
+      }),
+    ],
+  },
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/index.esm.js",
+      format: "esm",
+      sourcemap: true,
+    },
+    external,
+    plugins: [
+      nodeResolve(),
+      json(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: true,
+        declarationDir: "./dist/types",
+        rootDir: "src/",
+      }),
+    ],
+  },
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/index.cjs",
+      format: "cjs",
+      sourcemap: true,
+    },
+    external,
+    plugins: [
+      nodeResolve(),
+      json(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        rootDir: "src/",
+      }),
+    ],
+  },
+]

javascript/packages/formatter/src/cli.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from "fs"
+import { Herb } from "@herb-tools/node-wasm"
+import { Formatter } from "./formatter.js"
+import { name, version } from "../package.json"
+
+export class CLI {
+  private usage = `
+  Usage: herb-formatter [file] [options]
+
+  Arguments:
+    file             File to format (use '-' or omit for stdin)
+
+  Options:
+    -h, --help       show help
+    -v, --version    show version
+
+  Examples:
+    herb-formatter templates/index.html.erb
+    cat template.html.erb | herb-formatter
+    herb-formatter - < template.html.erb
+`
+
+  async run() {
+    const args = process.argv.slice(2)
+
+    if (args.includes("--help") || args.includes("-h")) {
+      console.log(this.usage)
+      process.exit(0)
+    }
+
+    try {
+      await Herb.load()
+
+      if (args.includes("--version") || args.includes("-v")) {
+        console.log("Versions:")
+        console.log(`  ${name}@${version}, ${Herb.version}`.split(", ").join("\n  "))
+        process.exit(0)
+      }
+
+      let source: string
+
+      // Find the first non-flag argument (the file)
+      const file = args.find(arg => !arg.startsWith("-"))
+
+      // Read from file or stdin
+      if (file && file !== "-") {
+        source = readFileSync(file, "utf-8")
+      } else {
+        source = await this.readStdin()
+      }
+
+      const formatter = new Formatter(Herb)
+      const result = formatter.format(source)
+      process.stdout.write(result)
+    } catch (error) {
+      console.error(error)
+      process.exit(1)
+    }
+  }
+
+  private async readStdin(): Promise<string> {
+    const chunks: Buffer[] = []
+
+    for await (const chunk of process.stdin) {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk)
+    }
+
+    return Buffer.concat(chunks).toString("utf8")
+  }
+}

javascript/packages/formatter/src/formatter.ts

@@ -0,0 +1,36 @@
+import { Printer } from "./printer.js"
+import { resolveFormatOptions } from "./options.js"
+
+import type { FormatOptions } from "./options.js"
+import type { HerbBackend, ParseResult } from "@herb-tools/core"
+
+/**
+ * Formatter uses a Herb Backend to parse the source and then
+ * formats the resulting AST into a well-indented, wrapped string.
+ */
+export class Formatter {
+  private herb: HerbBackend
+  private options: Required<FormatOptions>
+
+  constructor(herb: HerbBackend, options: FormatOptions = {}) {
+    this.herb = herb
+    this.options = resolveFormatOptions(options)
+  }
+
+  /**
+   * Format a source string, optionally overriding format options per call.
+   */
+  format(source: string, options: FormatOptions = {}): string {
+    const result = this.parse(source)
+    if (result.failed) return source
+
+    const resolvedOptions = resolveFormatOptions({ ...this.options, ...options })
+
+    return new Printer(source, resolvedOptions).print(result.value)
+  }
+
+  private parse(source: string): ParseResult {
+    this.herb.ensureBackend()
+    return this.herb.parse(source)
+  }
+}

javascript/packages/formatter/src/herb-formatter.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { CLI } from "./cli.js"
+
+const cli = new CLI()
+cli.run()

javascript/packages/formatter/src/index.ts

@@ -0,0 +1,5 @@
+export { Formatter } from "./formatter.js"
+export { defaultFormatOptions, resolveFormatOptions } from "./options.js"
+// export { CLI } from "./cli.js"
+
+export type { FormatOptions } from "./options.js"