erbfmt v0.3.0

erbfmt v0.3.0

erbfmt v0.3.0 is a large formatter-safety and tooling release. It expands Ruby helper wrapping, introduces assist actions, adds AI/editor-friendly JSON output, and reorganizes the parser architecture so future ERB, HTML, and Ruby work can continue more safely.

Highlights

• Added a lightweight Ruby AST parser used as a safety gate for wrapping ERB Ruby expressions.
• Improved wrapping for common Rails helper calls, including render, form_with, link_to, image_tag, video_tag, content_tag, tag.*, and nested helper arguments.
• Added conservative formatter safeguards for inline text, inline elements, SVG/math, raw text elements, and cross-ERB-block HTML.
• Added --assist with safe mechanical actions such as attribute quote normalization, self-closing HTML tag fixes, boolean attribute simplification, and empty ERB tag removal.
• Added JSON output for lint and assist commands for AI agents, editor integrations, and scripts.
• Added hosted agent command documentation at https://hinamimi.github.io/erbfmt/commands.md.
• Added parser configuration for unbalanced HTML fragments.
• Reorganized syntax modules into ERB, HTML, Ruby, and template layers.
• Added real-world formatter audits for OpenStreetMap Website and Forem templates.
• Updated release, RubyGems, VS Code, and documentation assets for the 0.3.0 release.

Formatter

This release substantially improves formatting for long Rails helper calls inside ERB tags. erbfmt can now safely wrap more method-call shapes, including:

• parenthesized helper calls;
• command-style helper calls;
• keyword arguments;
• nested hashes and arrays;
• nested helper calls inside keyword values;
• receiver method calls;
• brace block suffixes;
• selected modifier suffixes; and
• multiline continuations that can be preserved safely.

Example:

<%=
  render(
    partial: "profile",
    locals: {
      user: user,
      current_account: current_account,
      status_label: status_label(user)
    }
  )
%>

The formatter is still conservative by design. It avoids rewriting Ruby expressions when the parser cannot make a safe structural decision, and it keeps whitespace-sensitive HTML boundaries intact.

Formatter Safety

v0.3.0 includes many regression fixtures from real Rails templates. The formatter now more carefully preserves:

• inline text next to ERB output;
• inline elements such as a, label, button, span, and i;
• empty inline element boundaries;
• SVG and MathML content;
• pre, textarea, script, and style content;
• elements with contenteditable;
• ERB output inside headings and text nodes;
• raw text in script/style content; and
• cross-ERB-block or fragment-like HTML that cannot be safely balanced.

The goal is to format more real-world Rails views while avoiding rendered HTML changes caused by inserted whitespace.

Assist

This release introduces the first assist actions:

• html.useDoubleQuotedAttributes
• html.fixSelfClosingTags
• html.simplifyBooleanAttributes
• erb.removeEmptyTags

Assist actions can be inspected without modifying files:

erbfmt --assist --assist-format json app/views

They can also be applied explicitly:

erbfmt --assist --write app/views

Assist is intended for safe, mechanical edits that are better treated as fixable suggestions than formatter output.

AI And Editor Integrations

erbfmt now exposes JSON output for lint and assist workflows:

erbfmt --lint --lint-format json app/views
erbfmt --assist --assist-format json app/views

The JSON output is newline-delimited per file and includes file paths, summaries, diagnostics or actions, source locations, ranges, and text edits where applicable.

A concise command reference for agents and integrations is also available:

https://hinamimi.github.io/erbfmt/commands.md

Configuration

erbfmt.json now includes assist configuration:

{
  "assist": {
    "enabled": false,
    "includes": ["**/*.html.erb"],
    "actions": {
      "html.useDoubleQuotedAttributes": true,
      "html.fixSelfClosingTags": true,
      "html.simplifyBooleanAttributes": true,
      "erb.removeEmptyTags": true
    }
  }
}

Parser configuration also includes support for intentionally unbalanced HTML fragments:

{
  "parser": {
    "allowUnbalancedHtmlFragments": false
  }
}

The default remains conservative.

Architecture

The syntax layer was reorganized to make future parser work clearer:

• src/syntax/erb
• src/syntax/html
• src/syntax/ruby
• src/syntax/template

Formatter, linter, assist, and ignore logic now consume these syntax modules instead of mixing parsing responsibilities into formatting policy.

Distribution

The release includes:

• standalone Linux, macOS, and Windows binaries;
• SHA-256 checksum files;
• RubyGems platform gems;
• a RubyGems fallback gem; and
• a VS Code .vsix.

For Rails projects, Bundler remains the recommended installation path:

bundle add erbfmt --group development --require false
bundle exec erbfmt --version

For a global install:

gem install erbfmt -v 0.3.0
erbfmt --version

Notes

v0.3.0 changes formatter output in many cases, especially long ERB helper calls. Review formatting diffs before committing the first run on an existing project.

erbfmt is still pre-1.0 software. Configuration, formatting behavior, lint rules, and assist actions may continue to evolve before a stable release.