Config: Add framework and template_engine options (#1658)

This pull request adds `framework` and `template_engine` configuration
options to the `.herb.yml`.

These top-level settings tell Herb what environment it's running in and
what template engine is being used for compilation. This enables
context-aware behavior across the toolchain.

Configuration in `.herb.yml`:

```yml
framework: actionview      # ruby | actionview | hanami | sinatra (default: ruby)
template_engine: herb      # erubi | erb | herb (default: erubi)
```

Valid values are defined once in `config/options.yml` and code-generated
into the relevant configuration files in all bindings.

This allows us in the future to have more specific features tailored for
each target framework and engine. This pull request is meant to lay the
groundwork for:
- Framework-aware linter rules, so that we can automatically
enable/disable rules based on the framework (see
#480)
- Framework-aware compile-time optimizations. Knowing the framework
context determines which helpers are available for optimization (like
#1613)
- Template engine compatibility, surfacing invalid syntax or other
target engine's conventions across the toolchain (for example no ERB
block support)

Author: marcoroth

.gitignore

@@ -104,6 +104,7 @@ javascript/packages/core/src/action-view-helpers.ts
 javascript/packages/core/src/errors.ts
 javascript/packages/core/src/html-entities.json
 javascript/packages/core/src/node-type-guards.ts
+javascript/packages/core/src/config.ts
 javascript/packages/core/src/nodes.ts
 javascript/packages/core/src/visitor.ts
 javascript/packages/node/extension/error_helpers.cpp
@@ -116,6 +117,7 @@ lib/herb/errors.rb
 lib/herb/visitor.rb
 rust/src/action_view_helpers.rs
 rust/src/ast/nodes.rs
+rust/src/config.rs
 rust/src/errors.rs
 rust/src/nodes.rs
 rust/src/union_types.rs

config/options.yml

@@ -0,0 +1,14 @@
+framework:
+  default: ruby
+  values:
+    - ruby
+    - actionview
+    - hanami
+    - sinatra
+
+template_engine:
+  default: erubi
+  values:
+    - erubi
+    - erb
+    - herb

javascript/packages/config/src/config-schema.ts

@@ -50,12 +50,29 @@ export const ValidatorsConfigSchema = z.object({
   accessibility: z.boolean().optional().describe("Enable or disable the accessibility validator (default: true)"),
 }).strict().optional()
 
+export const FrameworkSchema = z.enum(["ruby", "actionview", "hanami", "sinatra"]).optional()
+  .describe("Framework context (default: 'ruby')")
+
+export const TemplateEngineSchema = z.enum(["erubi", "erb", "herb"]).optional()
+  .describe("Template engine used for compilation (default: 'erubi')")
+
+export const ParserOptionsSchema = z.object({
+  strict: z.boolean().optional().describe("Enable strict parsing mode (default: true)"),
+  render_nodes: z.boolean().optional().describe("Enable render node detection"),
+  strict_locals: z.boolean().optional().describe("Enable strict locals detection"),
+}).strict().optional()
+
 export const EngineConfigSchema = z.object({
+  optimize: z.boolean().optional().describe("Enable compile-time optimizations (default: false)"),
+  debug: z.boolean().optional().describe("Enable debug mode (default: false)"),
+  parser_options: ParserOptionsSchema.describe("Parser options passed through to Herb.parse"),
   validators: ValidatorsConfigSchema.describe("Per-validator enable/disable configuration"),
 }).strict().optional()
 
 export const HerbConfigSchema = z.object({
   version: z.string().describe("Configuration file version"),
+  framework: FrameworkSchema,
+  template_engine: TemplateEngineSchema,
   files: FilesConfigSchema.describe("Top-level file configuration"),
   engine: EngineConfigSchema.describe("Engine configuration"),
   linter: LinterConfigSchema,

javascript/packages/config/src/config-template.yml

@@ -13,6 +13,14 @@
 
 version: 0.9.7
 
+# # Framework and template engine configuration
+#
+# # Options: ruby | actionview | hanami | sinatra (default: ruby)
+# framework: ruby
+#
+# # Options: erubi | erb | herb (default: erubi)
+# template_engine: erubi
+
 # files:
 #   # Additional patterns beyond the defaults (**.html, **.rhtml, **.html.erb, etc.)
 #   include:

javascript/packages/core/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./action-view-helpers.js"
+export * from "./config.js"
 export * from "./ast-utils.js"
 export * from "./html-constants.js"
 export * from "./html-character-references.js"

lib/herb/configuration.rb

@@ -5,6 +5,12 @@
 
 module Herb
   class Configuration
+    OPTIONS_PATH = File.expand_path("../../config/options.yml", __dir__ || __FILE__).freeze #: String
+    OPTIONS = YAML.safe_load_file(OPTIONS_PATH).freeze #: Hash[String, untyped]
+
+    VALID_FRAMEWORKS = OPTIONS["framework"]["values"].freeze #: Array[String]
+    VALID_TEMPLATE_ENGINES = OPTIONS["template_engine"]["values"].freeze #: Array[String]
+
     CONFIG_FILENAMES = [".herb.yml"].freeze
 
     PROJECT_INDICATORS = [
@@ -42,6 +48,30 @@ def version
       @config["version"]
     end
 
+    #: () -> String
+    def framework
+      value = @config["framework"] || "ruby"
+
+      unless VALID_FRAMEWORKS.include?(value)
+        warn "[Herb] Unknown framework: #{value.inspect}. Valid values: #{VALID_FRAMEWORKS.join(", ")}. Defaulting to 'ruby'."
+        return "ruby"
+      end
+
+      value
+    end
+
+    #: () -> String
+    def template_engine
+      value = @config["template_engine"] || "erubi"
+
+      unless VALID_TEMPLATE_ENGINES.include?(value)
+        warn "[Herb] Unknown template_engine: #{value.inspect}. Valid values: #{VALID_TEMPLATE_ENGINES.join(", ")}. Defaulting to 'erubi'."
+        return "erubi"
+      end
+
+      value
+    end
+
     def files
       @config["files"] || {}
     end

lib/herb/defaults.yml

@@ -1,3 +1,6 @@
+framework: ruby
+template_engine: erubi
+
 files:
   include:
     - "**/*.herb"

sig/herb/configuration.rbs

@@ -0,0 +1,43 @@
+<%
+  options = YAML.safe_load_file("config/options.yml")
+
+  def camel_case(string)
+    parts = string.split("_")
+    parts[0] + parts[1..].map(&:capitalize).join
+  end
+
+  def pascal_case(string)
+    string.split("_").map(&:capitalize).join
+  end
+-%>
+
+<% options.each do |key, config| -%>
+export type <%= pascal_case(key) %> = <%= config["values"].map { |v| "\"#{v}\"" }.join(" | ") %>
+<% end -%>
+
+<% options.each do |key, config| -%>
+export const VALID_<%= key.upcase %>S: readonly <%= pascal_case(key) %>[] = [<%= config["values"].map { |v| "\"#{v}\"" }.join(", ") %>] as const
+<% end -%>
+
+<% options.each do |key, config| -%>
+export const DEFAULT_<%= key.upcase %>: <%= pascal_case(key) %> = "<%= config["default"] %>"
+<% end -%>
+
+export interface HerbConfig {
+<% options.each do |key, _config| -%>
+  <%= camel_case(key) %>: <%= pascal_case(key) %>
+<% end -%>
+}
+
+export const DEFAULT_CONFIG: HerbConfig = {
+<% options.each do |key, _config| -%>
+  <%= camel_case(key) %>: DEFAULT_<%= key.upcase %>,
+<% end -%>
+}
+
+<% options.each do |key, _config| -%>
+export function isValid<%= pascal_case(key) %>(value: string): value is <%= pascal_case(key) %> {
+  return (VALID_<%= key.upcase %>S as readonly string[]).includes(value)
+}
+
+<% end -%>

templates/javascript/packages/core/src/config.ts.erb

@@ -0,0 +1,50 @@
+<%
+  options = YAML.safe_load_file("config/options.yml")
+
+  def pascal_case(string)
+    string.split("_").map(&:capitalize).join
+  end
+
+  def title_case(string)
+    string.split("_").map(&:capitalize).join("")
+  end
+-%>
+
+use std::fmt;
+
+<% options.each do |key, config| -%>
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum <%= pascal_case(key) %> {
+<% config["values"].each do |value| -%>
+  <%= title_case(value) %>,
+<% end -%>
+}
+
+impl Default for <%= pascal_case(key) %> {
+  fn default() -> Self {
+    <%= pascal_case(key) %>::<%= title_case(config["default"]) %>
+  }
+}
+
+impl fmt::Display for <%= pascal_case(key) %> {
+  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    match self {
+    <% config["values"].each do |value| -%>
+      <%= pascal_case(key) %>::<%= title_case(value) %> => write!(f, "<%= value %>"),
+    <% end -%>
+    }
+  }
+}
+
+impl <%= pascal_case(key) %> {
+  pub fn from_str(string: &str) -> Option<Self> {
+    match string {
+    <% config["values"].each do |value| -%>
+      "<%= value %>" => Some(<%= pascal_case(key) %>::<%= title_case(value) %>),
+    <% end -%>
+      _ => None,
+    }
+  }
+}
+
+<% end -%>