Introduce @herb-tools/config and .herb.yml configuration file

docs/.vitepress/config/theme.mts

@@ -6,6 +6,7 @@ const defaultSidebar = [
     collapsed: false,
     items: [
       { text: "Overview", link: "/overview" },
+      { text: "Configuration", link: "/configuration" },
       { text: "Projects", link: "/projects" },
     ],
   },
@@ -28,6 +29,7 @@ const defaultSidebar = [
       { text: "Highlighter", link: "/projects/highlighter" },
       { text: "Syntax Tree Printer", link: "/projects/printer" },
       { text: "Minifier", link: "/projects/minifier" },
+      { text: "Config", link: "/projects/config" },
       { text: "Core", link: "/projects/core" },
     ],
   },

docs/docs/configuration.md

@@ -0,0 +1,155 @@
+# Configuration <Badge type="tip" text="^0.8.0" />
+
+Herb uses a `.herb.yml` configuration file to customize how the tools behave in your project. This configuration is shared across all Herb tools including the linter, formatter, and language server.
+
+## Configuration File Location
+
+The configuration file should be placed in your project root as `.herb.yml`:
+
+```
+your-project/
+├── .herb.yml    # Herb configuration
+├── Gemfile
+├── app/
+└── ...
+```
+
+## Configuration Priority
+
+Configuration settings are applied in the following order (highest to lowest priority):
+
+1. **Project configuration** (`.herb.yml` file)
+2. **Editor settings** (VS Code workspace/user settings)
+3. **Default settings**
+
+## Basic Configuration
+
+### Default Behavior (No Config File)
+
+If no `.herb.yml` file exists in your project:
+
+- **Language Server**: Uses built-in defaults and works out-of-the-box
+- **Linter**: Enabled with all rules (automatic exclusion of `parser-no-errors` in language server only)
+- **Formatter**: Disabled by default (experimental feature)
+- **Editor settings**: VS Code user/workspace settings are respected
+
+::: tip Recommended for Projects
+If you're using Herb in a project with multiple developers, it's highly recommended to create a `.herb.yml` configuration file and commit it to your repository. This ensures all team members use consistent linting rules and formatting settings, preventing configuration drift and maintaining code quality standards across the project.
+:::
+
+### Creating a Configuration File
+
+To create a `.herb.yml` configuration file in your project, run either CLI tool with the `--init` flag:
+
+```bash
+# Create config using the linter
+herb-lint --init
+
+# Or create config using the formatter
+herb-format --init
+```
+
+This will generate a configuration file with sensible defaults:
+
+<<< @/../../javascript/packages/config/src/config-template.yml{yaml}
+
+
+## Command Line Overrides
+
+The CLIs support a `--force` flag to override project configuration:
+
+```bash
+# Force linting even if disabled in .herb.yml
+herb-lint --force app/views/
+
+# Force formatting even if disabled in .herb.yml
+herb-format --force --check app/views/
+```
+
+## Linter Configuration
+
+Configure the linter behavior and rules:
+
+```yaml [.herb.yml]
+linter:
+  enabled: true  # Enable/disable linter globally
+  rules:
+    erb-no-extra-newline:
+      enabled: false # Disable a specific rule
+
+    # Override rule severity
+    html-tag-name-lowercase:
+      severity: warning  # Options: error, warning, info, hint
+
+    # File patterns to include for linting
+    patterns:
+      - app/views/**/*.html.erb
+
+    # File patterns to exclude from linting
+    exclude:
+      - vendor/**/*
+      - node_modules/**/*
+
+    # File patterns and extensions
+    extensions:
+      - .xml.erb
+      - .rhtml
+```
+
+### Rule Configuration Options
+
+Each rule can be configured with the following options:
+
+- **`enabled`**: `true` or `false` - Enable or disable the rule
+- **`severity`**: `error`, `warning`, `info`, or `hint` - Set the severity level
+
+## Formatter Configuration
+
+Configure the formatter behavior:
+
+```yaml [.herb.yml]
+formatter:
+  enabled: false     # Disabled by default (experimental)
+  indentWidth: 2     # Number of spaces for indentation
+  maxLineLength: 80  # Maximum line length before wrapping
+
+  # File patterns to exclude from formatting
+  exclude:
+    - app/views/generated/**/*
+
+  # File patterns and extensions
+  patterns:
+    - app/views/**/*.html.erb
+```
+
+### Formatter Options
+
+- **`enabled`**: `true` or `false` - Enable or disable the formatter
+- **`indentWidth`**: Number (default: `2`) - Spaces per indent level
+- **`maxLineLength`**: Number (default: `80`) - Maximum line length
+
+::: warning Experimental Feature
+The formatter is currently experimental. Enable it in `.herb.yml` and test thoroughly before using in production.
+:::
+
+## File Configuration
+
+Global file configuration that applies to both linter and formatter:
+
+```yaml [.herb.yml]
+files:
+  # Additional file extensions to process
+  extensions:
+    - .xml.erb
+    - .rss.erb
+
+  # Global exclude patterns
+  exclude:
+    - public/**/*
+    - tmp/**/*
+    - vendor/**/*
+```
+
+::: warning Tool-specific Configurations
+The configurations under `files:` have no effect if you also define `extensions`, `exclude`, or `patterns` under `linter:` or `formatter:` too.
+:::

docs/docs/projects.md

@@ -28,4 +28,5 @@ These specialized libraries provide additional functionality for working with HT
 * [Highlighter](/projects/highlighter)
 * [Syntax Tree Printer](/projects/minifier)
 * [Printer](/projects/printer)
+* [Config](/projects/config)
 * [Core](/projects/core)

docs/docs/projects/config.md

@@ -0,0 +1 @@
+<!-- @include: ../../../javascript/packages/config/README.md -->

javascript/packages/config/README.md

@@ -0,0 +1,58 @@
+# Herb Configuration
+
+**Package**: [`@herb-tools/config`](https://www.npmjs.com/package/@herb-tools/config)
+
+---
+
+Shared configuration utilities for Herb. Provides a unified way to load, validate, and manage configuration across the Herb ecosystem including the linter, formatter, and language server.
+
+## Installation
+
+:::code-group
+```shell [npm]
+npm add @herb-tools/config
+```
+
+```shell [pnpm]
+pnpm add @herb-tools/config
+```
+
+```shell [yarn]
+yarn add @herb-tools/config
+```
+
+```shell [bun]
+bun add @herb-tools/config
+```
+:::
+
+## Usage
+
+### `.herb.yml`
+
+The configuration is stored in a `.herb.yml` file in the project root:
+
+```yaml [.herb.yml]
+version: 0.7.5
+
+linter:
+  enabled: true
+  rules:
+    erb-no-extra-newline:
+      enabled: false
+
+formatter:
+  enabled: true
+  indentWidth: 2
+  maxLineLength: 120
+```
+
+## Configuration Hierarchy
+
+The Herb tools follow this configuration priority:
+
+1. **Project configuration** (`.herb.yml` file) - Highest priority
+2. **Editor settings** (VS Code workspace/user settings)
+3. **Default settings** - Fallback when no other configuration exists
+
+This allows teams to share consistent settings via `.herb.yml` while still allowing individual developer preferences when no project configuration exists.

javascript/packages/config/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@herb-tools/config",
+  "version": "0.7.5",
+  "description": "Shared configuration utilities for Herb tools",
+  "license": "MIT",
+  "homepage": "https://herb-tools.dev",
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/config%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/config"
+  },
+  "main": "./dist/herb-config.cjs",
+  "module": "./dist/herb-config.esm.js",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "yarn clean && tsc -b && rollup -c",
+    "dev": "tsc -b -w",
+    "test": "vitest run",
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/herb-config.esm.js",
+      "require": "./dist/herb-config.cjs",
+      "default": "./dist/herb-config.esm.js"
+    }
+  },
+  "dependencies": {
+    "@herb-tools/core": "0.7.5",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "zod": "^4.1.12",
+    "zod-validation-error": "^4.0.2"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "src/",
+    "dist/"
+  ]
+}

javascript/packages/config/project.json

@@ -0,0 +1,36 @@
+{
+  "name": "@herb-tools/config",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "javascript/packages/config/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "build"
+      },
+      "dependsOn": [
+        "@herb-tools/core:build"
+      ]
+    },
+    "test": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "test"
+      }
+    },
+    "clean": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "clean"
+      }
+    },
+    "dev": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "dev"
+      }
+    }
+  },
+  "tags": []
+}

javascript/packages/config/rollup.config.mjs

@@ -0,0 +1,47 @@
+import typescript from "@rollup/plugin-typescript"
+import json from "@rollup/plugin-json"
+import { nodeResolve } from "@rollup/plugin-node-resolve"
+import { readFileSync } from "fs"
+import { yaml } from "./yaml-plugin.mjs"
+
+export default [
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/herb-config.esm.js",
+      format: "esm",
+      sourcemap: true,
+    },
+    external: ["yaml", "fs", "path"],
+    plugins: [
+      nodeResolve(),
+      json(),
+      yaml(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: true,
+        declarationDir: "./dist/types",
+        rootDir: "src/",
+      }),
+    ],
+  },
+
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/herb-config.cjs",
+      format: "cjs",
+      sourcemap: true,
+    },
+    external: ["yaml", "fs", "path"],
+    plugins: [
+      nodeResolve(),
+      json(),
+      yaml(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        rootDir: "src/",
+      }),
+    ],
+  },
+]