@hivehub/rulebook 1.2.0

package/templates/languages/ERLANG.md

@@ -0,0 +1,361 @@
+<!-- ERLANG:START -->
+# Erlang Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+rebar3 format --verify    # Format check
+rebar3 dialyzer           # Type analysis
+rebar3 eunit              # Unit tests
+rebar3 ct                 # Common Test
+rebar3 cover              # Coverage check
+rebar3 compile            # Build verification
+
+# Security audit:
+rebar3 tree               # Dependency tree
+```
+
+## Erlang Configuration
+
+**CRITICAL**: Use Erlang/OTP 26+ with rebar3 and proper testing.
+
+- **Version**: Erlang/OTP 26+
+- **Recommended**: Erlang/OTP 27+
+- **Build Tool**: rebar3
+- **Testing**: EUnit, Common Test, PropEr
+- **Linter**: Elvis
+- **Dialyzer**: Type analysis
+- **Documentation**: EDoc
+
+### rebar.config Requirements
+
+```erlang
+{erl_opts, [
+    debug_info,
+    warnings_as_errors,
+    warn_export_all,
+    warn_unused_import,
+    warn_untyped_record
+]}.
+
+{deps, [
+    {jsx, "3.1.0"}
+]}.
+
+{plugins, [
+    rebar3_hex,
+    rebar3_ex_doc,
+    rebar3_proper,
+    rebar3_lint
+]}.
+
+{profiles, [
+    {test, [
+        {erl_opts, [debug_info, export_all, nowarn_export_all]},
+        {deps, [
+            {meck, "0.9.2"},
+            {proper, "1.4.0"}
+        ]}
+    ]},
+    {prod, [
+        {erl_opts, [no_debug_info, warnings_as_errors]},
+        {relx, [
+            {dev_mode, false},
+            {include_erts, true},
+            {include_src, false}
+        ]}
+    ]}
+]}.
+
+{cover_enabled, true}.
+{cover_opts, [verbose]}.
+
+{dialyzer, [
+    {warnings, [
+        error_handling,
+        underspecs,
+        unmatched_returns
+    ]},
+    {get_warnings, true},
+    {plt_apps, top_level_deps},
+    {plt_extra_apps, []},
+    {plt_location, local},
+    {base_plt_apps, [erts, kernel, stdlib]},
+    {base_plt_location, global}
+]}.
+
+{xref_checks, [
+    undefined_function_calls,
+    undefined_functions,
+    locals_not_used,
+    deprecated_function_calls,
+    deprecated_functions
+]}.
+```
+
+## 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)
+rebar3 as test fmt --check
+
+# 2. Lint (matches workflow)
+rebar3 as test lint
+
+# 3. Compile (matches workflow)
+rebar3 compile
+
+# 4. Dialyzer (type analysis - matches workflow)
+rebar3 dialyzer
+
+# 5. Run EUnit tests (MUST pass 100% - matches workflow)
+rebar3 eunit
+
+# 6. Run Common Test (matches workflow)
+rebar3 ct
+
+# 7. Run PropEr properties (matches workflow)
+rebar3 proper
+
+# 8. Coverage (MUST meet threshold - matches workflow)
+rebar3 cover
+
+# 9. Cross-reference check (matches workflow)
+rebar3 xref
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes OTP release failures
+- Dialyzer errors caught in CI but not locally = type safety issues
+- Example: Skipping Dialyzer locally = CI catches type discrepancies
+- Example: Missing xref check = undefined function calls in production
+- Example: Not running PropEr = property violations in production
+
+### Testing
+
+- **EUnit**: Unit testing framework
+- **Common Test**: Integration and system tests
+- **PropEr**: Property-based testing
+- **Location**: `test/` directory
+
+Example EUnit test:
+```erlang
+-module(data_processor_tests).
+-include_lib("eunit/include/eunit.hrl").
+
+process_valid_input_test() ->
+    Input = [1, 2, 3, 4, 5],
+    Result = data_processor:process(Input, 0.5),
+    ?assert(length(Result) > 0).
+
+process_empty_input_test() ->
+    Result = data_processor:process([], 0.5),
+    ?assertEqual([], Result).
+
+process_invalid_threshold_test() ->
+    ?assertError(badarg, data_processor:process([1, 2, 3], -1)).
+
+process_with_options_test() ->
+    Options = #{threshold => 0.5, verbose => true},
+    Result = data_processor:process([1, 2, 3], Options),
+    ?assert(is_list(Result)).
+```
+
+Example Common Test:
+```erlang
+-module(integration_SUITE).
+-include_lib("common_test/include/ct.hrl").
+
+-export([all/0, init_per_suite/1, end_per_suite/1]).
+-export([test_basic_workflow/1, test_error_handling/1]).
+
+all() ->
+    [test_basic_workflow, test_error_handling].
+
+init_per_suite(Config) ->
+    application:ensure_all_started(your_app),
+    Config.
+
+end_per_suite(_Config) ->
+    application:stop(your_app),
+    ok.
+
+test_basic_workflow(_Config) ->
+    {ok, Pid} = data_processor:start_link(),
+    ok = data_processor:process(Pid, [1, 2, 3]),
+    {ok, Result} = data_processor:get_result(Pid),
+    true = length(Result) > 0,
+    ok = data_processor:stop(Pid).
+
+test_error_handling(_Config) ->
+    {ok, Pid} = data_processor:start_link(),
+    {error, badarg} = data_processor:process(Pid, invalid_input),
+    ok = data_processor:stop(Pid).
+```
+
+Example PropEr property:
+```erlang
+-module(prop_data_processor).
+-include_lib("proper/include/proper.hrl").
+-include_lib("eunit/include/eunit.hrl").
+
+prop_process_preserves_length() ->
+    ?FORALL(List, list(integer()),
+        begin
+            Result = data_processor:process(List, 0.5),
+            length(Result) =< length(List)
+        end).
+
+prop_process_filters_correctly() ->
+    ?FORALL({List, Threshold}, {list(number()), number()},
+        begin
+            Result = data_processor:process(List, Threshold),
+            lists:all(fun(X) -> X > Threshold end, Result)
+        end).
+
+% Run properties
+process_properties_test() ->
+    ?assert(proper:quickcheck(prop_process_preserves_length(), 100)),
+    ?assert(proper:quickcheck(prop_process_filters_correctly(), 100)).
+```
+
+## OTP Patterns
+
+**CRITICAL**: Follow OTP principles for robust systems.
+
+```erlang
+-module(data_server).
+-behaviour(gen_server).
+
+%% API
+-export([start_link/0, process/2, stop/1]).
+
+%% gen_server callbacks
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2]).
+
+-record(state, {
+    threshold :: float(),
+    cache :: map()
+}).
+
+%%% API
+
+start_link() ->
+    gen_server:start_link(?MODULE, [], []).
+
+process(Pid, Data) ->
+    gen_server:call(Pid, {process, Data}).
+
+stop(Pid) ->
+    gen_server:stop(Pid).
+
+%%% gen_server callbacks
+
+init([]) ->
+    {ok, #state{threshold = 0.5, cache = #{}}}.
+
+handle_call({process, Data}, _From, State) ->
+    Result = filter_data(Data, State#state.threshold),
+    NewCache = maps:put(Data, Result, State#state.cache),
+    {reply, {ok, Result}, State#state{cache = NewCache}};
+handle_call(_Request, _From, State) ->
+    {reply, {error, unknown_request}, State}.
+
+handle_cast(_Msg, State) ->
+    {noreply, State}.
+
+handle_info(_Info, State) ->
+    {noreply, State}.
+
+terminate(_Reason, _State) ->
+    ok.
+
+%%% Internal functions
+
+filter_data(Data, Threshold) ->
+    [X || X <- Data, X > Threshold].
+```
+
+## Best Practices
+
+### DO's ✅
+
+- **USE** OTP behaviors (gen_server, gen_statem, supervisor)
+- **HANDLE** all error cases with pattern matching
+- **USE** typespecs for all exported functions
+- **TEST** with PropEr for property-based testing
+- **USE** supervisor trees for fault tolerance
+- **VALIDATE** inputs in public APIs
+- **DOCUMENT** with EDoc
+
+### DON'Ts ❌
+
+- **NEVER** ignore Dialyzer warnings
+- **NEVER** use catch-all patterns without logging
+- **NEVER** create processes without supervision
+- **NEVER** skip xref checks
+- **NEVER** use deprecated functions
+- **NEVER** ignore test failures
+- **NEVER** deploy without Dialyzer clean
+
+Example with typespecs:
+```erlang
+-module(calculator).
+-export([add/2, divide/2]).
+
+-spec add(number(), number()) -> number().
+add(A, B) -> A + B.
+
+-spec divide(number(), number()) -> {ok, float()} | {error, divide_by_zero}.
+divide(_A, 0) -> {error, divide_by_zero};
+divide(A, B) -> {ok, A / B}.
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows:
+
+1. **Testing** (`erlang-test.yml`):
+   - OTP versions: 26, 27
+   - Run EUnit, CT, PropEr
+   - Coverage reporting
+
+2. **Linting** (`erlang-lint.yml`):
+   - Elvis linting
+   - Dialyzer type checking
+   - xref verification
+
+3. **Build** (`erlang-build.yml`):
+   - Create OTP release
+   - Verify all applications start
+
+## Publishing to Hex.pm
+
+```bash
+# 1. Update version in src/your_app.app.src
+# 2. Run all quality checks
+rebar3 dialyzer
+rebar3 eunit
+rebar3 ct
+
+# 3. Publish
+rebar3 hex publish
+```
+
+<!-- ERLANG:END -->
+