@hivehub/rulebook 1.2.0

package/templates/languages/ELIXIR.md

@@ -0,0 +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 -->
+