@hivehub/rulebook 5.4.1 → 5.5.1

package/templates/languages/ELIXIR.md

@@ -1,454 +1,454 @@
-<!-- ELIXIR:START -->
-# Elixir Project Rules
-
-## Agent Automation Commands
-
-**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
-
-```bash
-# Complete quality check sequence:
-mix format --check-formatted  # Format check
-mix credo --strict        # Linting
-mix dialyzer              # Type checking
-mix test                  # All tests (100% pass)
-mix test --cover          # Coverage (95%+ required)
-mix compile --warnings-as-errors  # Build
-
-# Security audit:
-mix hex.audit             # Vulnerability scan
-mix hex.outdated          # Check outdated deps
-```
-
-## Elixir Configuration
-
-**CRITICAL**: Use Elixir 1.16+ with OTP 26+.
-
-- **Version**: Elixir 1.16+
-- **OTP**: 26+
-- **Formatter**: Built-in `mix format`
-- **Linter**: Credo
-- **Type Checker**: Dialyzer
-
-### mix.exs Requirements
-
-```elixir
-defmodule YourProject.MixProject do
-  use Mix.Project
-
-  def project do
-    [
-      app: :your_project,
-      version: "1.0.0",
-      elixir: "~> 1.16",
-      start_permanent: Mix.env() == :prod,
-      deps: deps(),
-      
-      # Documentation
-      name: "Your Project",
-      source_url: "https://github.com/your-org/your-project",
-      docs: [
-        main: "readme",
-        extras: ["README.md", "CHANGELOG.md"]
-      ],
-      
-      # Testing
-      test_coverage: [tool: ExCoveralls],
-      preferred_cli_env: [
-        coveralls: :test,
-        "coveralls.detail": :test,
-        "coveralls.post": :test,
-        "coveralls.html": :test
-      ],
-      
-      # Dialyzer
-      dialyzer: [
-        plt_add_apps: [:mix, :ex_unit],
-        plt_file: {:no_warn, "priv/plts/dialyzer.plt"},
-        flags: [:error_handling, :underspecs]
-      ]
-    ]
-  end
-
-  def application do
-    [
-      extra_applications: [:logger],
-      mod: {YourProject.Application, []}
-    ]
-  end
-
-  defp deps do
-    [
-      # Development & Testing
-      {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
-      {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false},
-      {:excoveralls, "~> 0.18", only: :test},
-      {:ex_doc, "~> 0.31", only: :dev, runtime: false}
-    ]
-  end
-end
-```
-
-## Code Quality Standards
-
-### Mandatory Quality Checks
-
-**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
-
-**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
-
-```bash
-# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
-
-# 1. Format check (matches workflow - use --check-formatted!)
-mix format --check-formatted
-
-# 2. Lint (MUST pass with no warnings - matches workflow)
-mix credo --strict
-
-# 3. Type check with Dialyzer (matches workflow)
-mix dialyzer
-
-# 4. Run all tests (MUST pass 100% - matches workflow)
-mix test --cover
-
-# 5. Check coverage (MUST meet threshold)
-mix test --cover --export-coverage default
-mix test.coverage
-
-# If ANY fails: ❌ DO NOT COMMIT - Fix first!
-```
-
-**If ANY of these fail, you MUST fix the issues before committing.**
-
-**Why This Matters:**
-- CI/CD failures happen when local commands differ from workflows
-- Example: Using `mix format` locally but `mix format --check-formatted` in CI = failure
-- Example: Missing `--cover` flag = CI coverage failures
-
-### Formatting
-
-- Use built-in `mix format`
-- Configuration in `.formatter.exs`
-- Format before committing: `mix format`
-
-Example `.formatter.exs`:
-```elixir
-[
-  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
-  line_length: 100
-]
-```
-
-### Linting
-
-- Use Credo for code analysis
-- Configuration in `.credo.exs`
-- Must pass strict mode: `mix credo --strict`
-
-Example `.credo.exs`:
-```elixir
-%{
-  configs: [
-    %{
-      name: "default",
-      files: %{
-        included: ["lib/", "test/"],
-        excluded: [~r"/_build/", ~r"/deps/"]
-      },
-      strict: true,
-      color: true,
-      checks: %{
-        enabled: [
-          {Credo.Check.Readability.ModuleDoc, []},
-          {Credo.Check.Design.AliasUsage, priority: :low}
-        ]
-      }
-    }
-  ]
-}
-```
-
-### Testing
-
-- **Framework**: ExUnit (built-in)
-- **Location**: `test/` directory
-- **Coverage**: ExCoveralls
-- **Coverage Threshold**: 95%+
-
-Example test structure:
-```elixir
-defmodule YourProject.MyModuleTest do
-  use ExUnit.Case, async: true
-  
-  doctest YourProject.MyModule
-
-  describe "function_name/1" do
-    test "handles valid input" do
-      assert YourProject.MyModule.function_name("input") == {:ok, "result"}
-    end
-
-    test "returns error for invalid input" do
-      assert YourProject.MyModule.function_name("") == {:error, :invalid_input}
-    end
-  end
-end
-```
-
-### Type Specifications
-
-- Use `@spec` for all public functions
-- Use `@type` for custom types
-- Run Dialyzer regularly
-
-Example:
-```elixir
-defmodule YourProject.MyModule do
-  @moduledoc """
-  Documentation for MyModule.
-  """
-
-  @type result :: {:ok, String.t()} | {:error, atom()}
-
-  @spec process(String.t()) :: result()
-  def process(input) when is_binary(input) and input != "" do
-    {:ok, String.upcase(input)}
-  end
-
-  def process(_), do: {:error, :invalid_input}
-end
-```
-
-## Documentation
-
-- Use `@moduledoc` for module documentation
-- Use `@doc` for function documentation
-- Include examples with doctests
-- Generate docs with `mix docs`
-
-Example:
-```elixir
-defmodule YourProject.MyModule do
-  @moduledoc """
-  Provides functionality for processing data.
-
-  ## Examples
-
-      iex> YourProject.MyModule.process("hello")
-      {:ok, "HELLO"}
-  """
-
-  @doc """
-  Processes the input string.
-
-  Returns `{:ok, result}` on success or `{:error, reason}` on failure.
-
-  ## Examples
-
-      iex> YourProject.MyModule.process("test")
-      {:ok, "TEST"}
-
-      iex> YourProject.MyModule.process("")
-      {:error, :invalid_input}
-  """
-  @spec process(String.t()) :: {:ok, String.t()} | {:error, atom()}
-  def process(input) when is_binary(input) and input != "" do
-    {:ok, String.upcase(input)}
-  end
-
-  def process(_), do: {:error, :invalid_input}
-end
-```
-
-## Project Structure
-
-```
-project/
-├── mix.exs             # Project configuration
-├── .formatter.exs      # Formatter configuration
-├── .credo.exs          # Credo configuration
-├── README.md           # Project overview (allowed in root)
-├── CHANGELOG.md        # Version history (allowed in root)
-├── LICENSE             # Project license (allowed in root)
-├── lib/
-│   ├── your_project.ex       # Main module
-│   └── your_project/
-│       ├── application.ex    # OTP application
-│       └── ...
-├── test/
-│   ├── test_helper.exs      # Test configuration
-│   └── your_project/
-│       └── ...
-├── config/
-│   ├── config.exs           # General config
-│   ├── dev.exs              # Development config
-│   ├── test.exs             # Test config
-│   └── prod.exs             # Production config
-├── priv/                    # Private assets
-└── docs/                    # Project documentation
-```
-
-## Error Handling
-
-- Use tagged tuples: `{:ok, value}` and `{:error, reason}`
-- Use `with` for multiple operations
-- Create custom error modules when needed
-
-Example:
-```elixir
-defmodule YourProject.Errors do
-  defmodule ValidationError do
-    defexception [:message, :field]
-  end
-end
-
-defmodule YourProject.MyModule do
-  alias YourProject.Errors.ValidationError
-
-  def validate(data) do
-    with {:ok, cleaned} <- clean_data(data),
-         {:ok, validated} <- check_format(cleaned) do
-      {:ok, validated}
-    else
-      {:error, :empty} -> 
-        raise ValidationError, message: "Data cannot be empty", field: :data
-      
-      {:error, reason} -> 
-        {:error, reason}
-    end
-  end
-end
-```
-
-## OTP Best Practices
-
-- Use Supervisors for fault tolerance
-- Implement GenServers for stateful processes
-- Use Task for concurrent operations
-
-Example Supervisor:
-```elixir
-defmodule YourProject.Application do
-  use Application
-
-  @impl true
-  def start(_type, _args) do
-    children = [
-      {YourProject.MyWorker, []},
-      {Task.Supervisor, name: YourProject.TaskSupervisor}
-    ]
-
-    opts = [strategy: :one_for_one, name: YourProject.Supervisor]
-    Supervisor.start_link(children, opts)
-  end
-end
-```
-
-## CI/CD Requirements
-
-Must include GitHub Actions workflows for:
-
-1. **Testing** (`elixir-test.yml`):
-   - Test on ubuntu-latest
-   - Test on Elixir 1.16, 1.17
-   - Test on OTP 26, 27
-   - Upload coverage reports
-
-2. **Linting** (`elixir-lint.yml`):
-   - Format check: `mix format --check-formatted`
-   - Credo: `mix credo --strict`
-   - Dialyzer: `mix dialyzer`
-
-## Package Publication
-
-### Publishing to Hex.pm
-
-**Prerequisites:**
-1. Create account at https://hex.pm
-2. Generate API key: `mix hex.user auth`
-3. Add `HEX_API_KEY` to GitHub repository secrets
-
-**mix.exs Configuration:**
-
-```elixir
-def project do
-  [
-    app: :your_package,
-    version: "1.0.0",
-    elixir: "~> 1.16",
-    description: "A short description of your package",
-    package: package(),
-    docs: docs()
-  ]
-end
-
-defp package do
-  [
-    name: :your_package,
-    files: ~w(lib .formatter.exs mix.exs README.md LICENSE CHANGELOG.md),
-    licenses: ["MIT"],
-    links: %{
-      "GitHub" => "https://github.com/your-org/your-package",
-      "Changelog" => "https://github.com/your-org/your-package/blob/main/CHANGELOG.md"
-    },
-    maintainers: ["Your Name"]
-  ]
-end
-
-defp docs do
-  [
-    main: "readme",
-    extras: ["README.md", "CHANGELOG.md"],
-    source_url: "https://github.com/your-org/your-package"
-  ]
-end
-```
-
-**Publishing Workflow:**
-
-1. Update version in mix.exs
-2. Update CHANGELOG.md
-3. Run quality checks:
-   ```bash
-   mix format
-   mix credo --strict
-   mix dialyzer
-   mix test
-   mix coveralls
-   ```
-
-4. Build docs: `mix docs`
-5. Build package: `mix hex.build`
-6. Create git tag: `git tag v1.0.0 && git push --tags`
-7. GitHub Actions automatically publishes to Hex
-8. Or manual publish: `mix hex.publish`
-
-**Publishing Checklist:**
-
-- ✅ All tests passing (`mix test`)
-- ✅ Coverage meets threshold (`mix coveralls`)
-- ✅ Credo passes strict mode (`mix credo --strict`)
-- ✅ Dialyzer passes (`mix dialyzer`)
-- ✅ Code formatted (`mix format --check-formatted`)
-- ✅ Version updated in mix.exs
-- ✅ CHANGELOG.md updated
-- ✅ README.md up to date
-- ✅ LICENSE file present
-- ✅ Documentation builds (`mix docs`)
-- ✅ Package metadata complete in mix.exs
-- ✅ Verify with `mix hex.build`
-
-**Semantic Versioning:**
-
-Follow [SemVer](https://semver.org/):
-- **MAJOR**: Breaking API changes
-- **MINOR**: New features (backwards compatible)
-- **PATCH**: Bug fixes (backwards compatible)
-
-**Documentation:**
-
-HexDocs automatically generates documentation from your code:
-- Published at: `https://hexdocs.pm/your_package`
-- Updated automatically when publishing to Hex
-
-<!-- ELIXIR:END -->
-
+<!-- ELIXIR:START -->
+# Elixir Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+mix format --check-formatted  # Format check
+mix credo --strict        # Linting
+mix dialyzer              # Type checking
+mix test                  # All tests (100% pass)
+mix test --cover          # Coverage (95%+ required)
+mix compile --warnings-as-errors  # Build
+
+# Security audit:
+mix hex.audit             # Vulnerability scan
+mix hex.outdated          # Check outdated deps
+```
+
+## Elixir Configuration
+
+**CRITICAL**: Use Elixir 1.16+ with OTP 26+.
+
+- **Version**: Elixir 1.16+
+- **OTP**: 26+
+- **Formatter**: Built-in `mix format`
+- **Linter**: Credo
+- **Type Checker**: Dialyzer
+
+### mix.exs Requirements
+
+```elixir
+defmodule YourProject.MixProject do
+  use Mix.Project
+
+  def project do
+    [
+      app: :your_project,
+      version: "1.0.0",
+      elixir: "~> 1.16",
+      start_permanent: Mix.env() == :prod,
+      deps: deps(),
+      
+      # Documentation
+      name: "Your Project",
+      source_url: "https://github.com/your-org/your-project",
+      docs: [
+        main: "readme",
+        extras: ["README.md", "CHANGELOG.md"]
+      ],
+      
+      # Testing
+      test_coverage: [tool: ExCoveralls],
+      preferred_cli_env: [
+        coveralls: :test,
+        "coveralls.detail": :test,
+        "coveralls.post": :test,
+        "coveralls.html": :test
+      ],
+      
+      # Dialyzer
+      dialyzer: [
+        plt_add_apps: [:mix, :ex_unit],
+        plt_file: {:no_warn, "priv/plts/dialyzer.plt"},
+        flags: [:error_handling, :underspecs]
+      ]
+    ]
+  end
+
+  def application do
+    [
+      extra_applications: [:logger],
+      mod: {YourProject.Application, []}
+    ]
+  end
+
+  defp deps do
+    [
+      # Development & Testing
+      {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
+      {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false},
+      {:excoveralls, "~> 0.18", only: :test},
+      {:ex_doc, "~> 0.31", only: :dev, runtime: false}
+    ]
+  end
+end
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use --check-formatted!)
+mix format --check-formatted
+
+# 2. Lint (MUST pass with no warnings - matches workflow)
+mix credo --strict
+
+# 3. Type check with Dialyzer (matches workflow)
+mix dialyzer
+
+# 4. Run all tests (MUST pass 100% - matches workflow)
+mix test --cover
+
+# 5. Check coverage (MUST meet threshold)
+mix test --cover --export-coverage default
+mix test.coverage
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- CI/CD failures happen when local commands differ from workflows
+- Example: Using `mix format` locally but `mix format --check-formatted` in CI = failure
+- Example: Missing `--cover` flag = CI coverage failures
+
+### Formatting
+
+- Use built-in `mix format`
+- Configuration in `.formatter.exs`
+- Format before committing: `mix format`
+
+Example `.formatter.exs`:
+```elixir
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
+  line_length: 100
+]
+```
+
+### Linting
+
+- Use Credo for code analysis
+- Configuration in `.credo.exs`
+- Must pass strict mode: `mix credo --strict`
+
+Example `.credo.exs`:
+```elixir
+%{
+  configs: [
+    %{
+      name: "default",
+      files: %{
+        included: ["lib/", "test/"],
+        excluded: [~r"/_build/", ~r"/deps/"]
+      },
+      strict: true,
+      color: true,
+      checks: %{
+        enabled: [
+          {Credo.Check.Readability.ModuleDoc, []},
+          {Credo.Check.Design.AliasUsage, priority: :low}
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Testing
+
+- **Framework**: ExUnit (built-in)
+- **Location**: `test/` directory
+- **Coverage**: ExCoveralls
+- **Coverage Threshold**: 95%+
+
+Example test structure:
+```elixir
+defmodule YourProject.MyModuleTest do
+  use ExUnit.Case, async: true
+  
+  doctest YourProject.MyModule
+
+  describe "function_name/1" do
+    test "handles valid input" do
+      assert YourProject.MyModule.function_name("input") == {:ok, "result"}
+    end
+
+    test "returns error for invalid input" do
+      assert YourProject.MyModule.function_name("") == {:error, :invalid_input}
+    end
+  end
+end
+```
+
+### Type Specifications
+
+- Use `@spec` for all public functions
+- Use `@type` for custom types
+- Run Dialyzer regularly
+
+Example:
+```elixir
+defmodule YourProject.MyModule do
+  @moduledoc """
+  Documentation for MyModule.
+  """
+
+  @type result :: {:ok, String.t()} | {:error, atom()}
+
+  @spec process(String.t()) :: result()
+  def process(input) when is_binary(input) and input != "" do
+    {:ok, String.upcase(input)}
+  end
+
+  def process(_), do: {:error, :invalid_input}
+end
+```
+
+## Documentation
+
+- Use `@moduledoc` for module documentation
+- Use `@doc` for function documentation
+- Include examples with doctests
+- Generate docs with `mix docs`
+
+Example:
+```elixir
+defmodule YourProject.MyModule do
+  @moduledoc """
+  Provides functionality for processing data.
+
+  ## Examples
+
+      iex> YourProject.MyModule.process("hello")
+      {:ok, "HELLO"}
+  """
+
+  @doc """
+  Processes the input string.
+
+  Returns `{:ok, result}` on success or `{:error, reason}` on failure.
+
+  ## Examples
+
+      iex> YourProject.MyModule.process("test")
+      {:ok, "TEST"}
+
+      iex> YourProject.MyModule.process("")
+      {:error, :invalid_input}
+  """
+  @spec process(String.t()) :: {:ok, String.t()} | {:error, atom()}
+  def process(input) when is_binary(input) and input != "" do
+    {:ok, String.upcase(input)}
+  end
+
+  def process(_), do: {:error, :invalid_input}
+end
+```
+
+## Project Structure
+
+```
+project/
+├── mix.exs             # Project configuration
+├── .formatter.exs      # Formatter configuration
+├── .credo.exs          # Credo configuration
+├── README.md           # Project overview (allowed in root)
+├── CHANGELOG.md        # Version history (allowed in root)
+├── LICENSE             # Project license (allowed in root)
+├── lib/
+│   ├── your_project.ex       # Main module
+│   └── your_project/
+│       ├── application.ex    # OTP application
+│       └── ...
+├── test/
+│   ├── test_helper.exs      # Test configuration
+│   └── your_project/
+│       └── ...
+├── config/
+│   ├── config.exs           # General config
+│   ├── dev.exs              # Development config
+│   ├── test.exs             # Test config
+│   └── prod.exs             # Production config
+├── priv/                    # Private assets
+└── docs/                    # Project documentation
+```
+
+## Error Handling
+
+- Use tagged tuples: `{:ok, value}` and `{:error, reason}`
+- Use `with` for multiple operations
+- Create custom error modules when needed
+
+Example:
+```elixir
+defmodule YourProject.Errors do
+  defmodule ValidationError do
+    defexception [:message, :field]
+  end
+end
+
+defmodule YourProject.MyModule do
+  alias YourProject.Errors.ValidationError
+
+  def validate(data) do
+    with {:ok, cleaned} <- clean_data(data),
+         {:ok, validated} <- check_format(cleaned) do
+      {:ok, validated}
+    else
+      {:error, :empty} -> 
+        raise ValidationError, message: "Data cannot be empty", field: :data
+      
+      {:error, reason} -> 
+        {:error, reason}
+    end
+  end
+end
+```
+
+## OTP Best Practices
+
+- Use Supervisors for fault tolerance
+- Implement GenServers for stateful processes
+- Use Task for concurrent operations
+
+Example Supervisor:
+```elixir
+defmodule YourProject.Application do
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      {YourProject.MyWorker, []},
+      {Task.Supervisor, name: YourProject.TaskSupervisor}
+    ]
+
+    opts = [strategy: :one_for_one, name: YourProject.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+end
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows for:
+
+1. **Testing** (`elixir-test.yml`):
+   - Test on ubuntu-latest
+   - Test on Elixir 1.16, 1.17
+   - Test on OTP 26, 27
+   - Upload coverage reports
+
+2. **Linting** (`elixir-lint.yml`):
+   - Format check: `mix format --check-formatted`
+   - Credo: `mix credo --strict`
+   - Dialyzer: `mix dialyzer`
+
+## Package Publication
+
+### Publishing to Hex.pm
+
+**Prerequisites:**
+1. Create account at https://hex.pm
+2. Generate API key: `mix hex.user auth`
+3. Add `HEX_API_KEY` to GitHub repository secrets
+
+**mix.exs Configuration:**
+
+```elixir
+def project do
+  [
+    app: :your_package,
+    version: "1.0.0",
+    elixir: "~> 1.16",
+    description: "A short description of your package",
+    package: package(),
+    docs: docs()
+  ]
+end
+
+defp package do
+  [
+    name: :your_package,
+    files: ~w(lib .formatter.exs mix.exs README.md LICENSE CHANGELOG.md),
+    licenses: ["MIT"],
+    links: %{
+      "GitHub" => "https://github.com/your-org/your-package",
+      "Changelog" => "https://github.com/your-org/your-package/blob/main/CHANGELOG.md"
+    },
+    maintainers: ["Your Name"]
+  ]
+end
+
+defp docs do
+  [
+    main: "readme",
+    extras: ["README.md", "CHANGELOG.md"],
+    source_url: "https://github.com/your-org/your-package"
+  ]
+end
+```
+
+**Publishing Workflow:**
+
+1. Update version in mix.exs
+2. Update CHANGELOG.md
+3. Run quality checks:
+   ```bash
+   mix format
+   mix credo --strict
+   mix dialyzer
+   mix test
+   mix coveralls
+   ```
+
+4. Build docs: `mix docs`
+5. Build package: `mix hex.build`
+6. Create git tag: `git tag v1.0.0 && git push --tags`
+7. GitHub Actions automatically publishes to Hex
+8. Or manual publish: `mix hex.publish`
+
+**Publishing Checklist:**
+
+- ✅ All tests passing (`mix test`)
+- ✅ Coverage meets threshold (`mix coveralls`)
+- ✅ Credo passes strict mode (`mix credo --strict`)
+- ✅ Dialyzer passes (`mix dialyzer`)
+- ✅ Code formatted (`mix format --check-formatted`)
+- ✅ Version updated in mix.exs
+- ✅ CHANGELOG.md updated
+- ✅ README.md up to date
+- ✅ LICENSE file present
+- ✅ Documentation builds (`mix docs`)
+- ✅ Package metadata complete in mix.exs
+- ✅ Verify with `mix hex.build`
+
+**Semantic Versioning:**
+
+Follow [SemVer](https://semver.org/):
+- **MAJOR**: Breaking API changes
+- **MINOR**: New features (backwards compatible)
+- **PATCH**: Bug fixes (backwards compatible)
+
+**Documentation:**
+
+HexDocs automatically generates documentation from your code:
+- Published at: `https://hexdocs.pm/your_package`
+- Updated automatically when publishing to Hex
+
+<!-- ELIXIR:END -->
+