Why this project exists and what problem does it solve: @CHARTER.md # Usage Rules **IMPORTANT**: Consult these usage rules early and often when working with the packages listed below. Before attempting to use any of these packages or to discover if you should use them, review their usage rules to understand the correct patterns, conventions, and best practices. ## usage_rules usage _A dev tool for Elixir projects to gather LLM usage rules from dependencies_ ## Using Usage Rules Many packages have usage rules, which you should *thoroughly* consult before taking any action. These usage rules contain guidelines and rules *directly from the package authors*. They are your best source of knowledge for making decisions. ## Modules & functions in the current app and dependencies When looking for docs for modules & functions that are dependencies of the current project, or for Elixir itself, use `mix usage_rules.docs` ``` # Search a whole module mix usage_rules.docs Enum # Search a specific function mix usage_rules.docs Enum.zip # Search a specific function & arity mix usage_rules.docs Enum.zip/1 ``` ## Searching Documentation You should also consult the documentation of any tools you are using, early and often. The best way to accomplish this is to use the `usage_rules.search_docs` mix task. Once you have found what you are looking for, use the links in the search results to get more detail. For example: ``` # Search docs for all packages in the current application, including Elixir mix usage_rules.search_docs Enum.zip # Search docs for specific packages mix usage_rules.search_docs Req.get -p req # Search docs for multi-word queries mix usage_rules.search_docs "making requests" -p req # Search only in titles (useful for finding specific functions/modules) mix usage_rules.search_docs "Enum.zip" --query-by title ``` ## usage_rules:elixir usage # Elixir Core Usage Rules ## Pattern Matching - Use pattern matching over conditional logic when possible - Prefer to match on function heads instead of using `if`/`else` or `case` in function bodies - `%{}` matches ANY map, not just empty maps. Use `map_size(map) == 0` guard to check for truly empty maps ## Error Handling - Use `{:ok, result}` and `{:error, reason}` tuples for operations that can fail - Avoid raising exceptions for control flow - Use `with` for chaining operations that return `{:ok, _}` or `{:error, _}` ## Common Mistakes to Avoid - Elixir has no `return` statement, nor early returns. The last expression in a block is always returned. - Don't use `Enum` functions on large collections when `Stream` is more appropriate - Avoid nested `case` statements - refactor to a single `case`, `with` or separate functions - Don't use `String.to_atom/1` on user input (memory leak risk) - Lists and enumerables cannot be indexed with brackets. Use pattern matching or `Enum` functions - Prefer `Enum` functions like `Enum.reduce` over recursion - When recursion is necessary, prefer to use pattern matching in function heads for base case detection - Using the process dictionary is typically a sign of unidiomatic code - Only use macros if explicitly requested - There are many useful standard library functions, prefer to use them where possible ## Function Design - Use guard clauses: `when is_binary(name) and byte_size(name) > 0` - Prefer multiple function clauses over complex conditional logic - Name functions descriptively: `calculate_total_price/2` not `calc/2` - Predicate function names should not start with `is` and should end in a question mark. - Names like `is_thing` should be reserved for guards ## Data Structures - Use structs over maps when the shape is known: `defstruct [:name, :age]` - Prefer keyword lists for options: `[timeout: 5000, retries: 3]` - Use maps for dynamic key-value data - Prefer to prepend to lists `[new | list]` not `list ++ [new]` ## Mix Tasks - Use `mix help` to list available mix tasks - Use `mix help task_name` to get docs for an individual task - Read the docs and options fully before using tasks ## Testing - Run tests in a specific file with `mix test test/my_test.exs` and a specific test with the line number `mix test path/to/test.exs:123` - Limit the number of failed tests with `mix test --max-failures n` - Use `@tag` to tag specific tests, and `mix test --only tag` to run only those tests - Use `assert_raise` for testing expected exceptions: `assert_raise ArgumentError, fn -> invalid_function() end` - Use `mix help test` to for full documentation on running tests ## Debugging - Use `dbg/1` to print values while debugging. This will display the formatted value and other relevant information in the console. ## usage_rules:otp usage # OTP Usage Rules ## GenServer Best Practices - Keep state simple and serializable - Handle all expected messages explicitly - Use `handle_continue/2` for post-init work - Implement proper cleanup in `terminate/2` when necessary ## Process Communication - Use `GenServer.call/3` for synchronous requests expecting replies - Use `GenServer.cast/2` for fire-and-forget messages. - When in doubt, use `call` over `cast`, to ensure back-pressure - Set appropriate timeouts for `call/3` operations ## Fault Tolerance - Set up processes such that they can handle crashing and being restarted by supervisors - Use `:max_restarts` and `:max_seconds` to prevent restart loops ## Task and Async - Use `Task.Supervisor` for better fault tolerance - Handle task failures with `Task.yield/2` or `Task.shutdown/2` - Set appropriate task timeouts - Use `Task.async_stream/3` for concurrent enumeration with back-pressure ## igniter usage _A code generation and project patching framework_ [igniter usage rules](deps/igniter/usage-rules.md) ## Development Workflow - Trunk-based development: `main` is the only long-lived branch. - All work lands on `main` via direct commit. - Feature branches are not pushed to `origin`. - Pull requests are not used. - Short-lived local working branches (e.g. from hopper worktrees) are merged to `main` and deleted locally before work is considered complete. ## Quality Guidelines ### MANDATORY Pre-Commit Quality Gates **STOP**: Before considering ANY work complete or committing code, you MUST run ALL quality checks: ```bash # Complete quality gate check (run this EVERY TIME) mix format --check-formatted && \ mix credo --strict && \ mix test && \ mix audit ``` **Why this matters**: Examples and tests must pass compilation and linting. When examples fail, users cannot learn from them. Always validate the entire project, not just the code you changed. **If any check fails**: - STOP immediately - Fix the root cause (don't suppress warnings) - Re-run all checks - Only proceed when all pass ### Additional Quality Practices - Write unit tests for new functions - Ensure existing tests pass when updating code - Run `mix test` after writing/updating tests - Run `mix test --cover` on task completion (coverage above threshold) - Run `mix credo --strict` on task completion and fix issues ## Security Guidelines - Run `mix deps.audit` and `mix hex.audit` after dependency changes - Run `mix hex.outdated` to check outdated dependencies - Run `mix sobelow --config` on task completion and fix issues ## Release Process ### Versioning - Follow semantic versioning (semver): MAJOR.MINOR.PATCH - Update version in `mix.exs` - Update `CHANGELOG.md` with release notes ### Publishing a Release **The release pipeline is fully automated.** When you create a GitHub release, the CI/CD workflow will: 1. Run all quality checks (format, credo, test, security audit) 2. Build and publish the package to Hex.pm 3. Deploy documentation to GitHub Pages #### Steps to Release ```bash # 1. Update version in mix.exs (e.g., @version "1.1.0") # 2. Update CHANGELOG.md # - Add new version section with date: ## [1.1.0] - YYYY-MM-DD # - Document all changes under appropriate headers (Added, Changed, Fixed, etc.) # 3. Commit and push git add mix.exs CHANGELOG.md git commit -m "chore: prepare v1.1.0 release" git push origin main # 4. Create GitHub release (this triggers the publish) gh release create v1.1.0 \ --title "v1.1.0 - Release Title" \ --notes "## What's New - Feature 1 - Feature 2 See [CHANGELOG.md](CHANGELOG.md) for full details." ``` The pipeline will automatically publish to Hex.pm using the `HEX_API_KEY` secret configured in the repository. ### CI/CD Pipeline The GitHub Actions workflow (`.github/workflows/build.yml`) runs: | Trigger | Quality Checks | Docs Deploy | Hex Publish | |---------|---------------|-------------|-------------| | Push to main | ✅ | ❌ | ❌ | | Pull request | ✅ | ❌ | ❌ | | Release published | ✅ | ✅ | ✅ | **Required GitHub Secrets:** - `HEX_API_KEY` - Hex.pm API key for publishing (generate with `mix hex.user key generate`) ### Pre-Release Checklist Before creating a release: - [ ] All tests pass: `mix test` - [ ] Format check passes: `mix format --check-formatted` - [ ] Credo passes: `mix credo --strict` - [ ] Security audit clean: `mix audit` - [ ] Docs build: `mix docs` - [ ] Version updated in `mix.exs` - [ ] CHANGELOG.md updated - [ ] Changes committed and pushed to main ### Version Synchronization All mojentic ports (mojentic-py, mojentic-ts, mojentic-ex, mojentic-ru) share synchronized major and minor version numbers. When releasing: - Patch releases (X.Y.Z → X.Y.Z+1) can be made independently per port - Minor releases (X.Y.0 → X.Y+1.0) must be coordinated — all four ports bump together - Major releases (X.0.0 → X+1.0.0) must be coordinated — all four ports bump together Before tagging a minor or major release, verify the other three ports are also ready to release at the same version. Current ports: - mojentic-py (Python) — pyproject.toml - mojentic-ts (TypeScript) — package.json - mojentic-ex (Elixir) — mix.exs - mojentic-ru (Rust) — Cargo.toml ## Useful Commands ### Development ```bash mix deps.get # Install dependencies mix compile # Compile project ``` ### Testing ```bash mix test # All tests mix test test/path/to/test.exs # Specific file mix test test/path/to/test.exs:42 # Specific line mix test --cover # With coverage ``` ### Quality Checks ```bash mix format # Format code mix format --check-formatted # Check formatting mix credo --strict # Linting mix audit # Security audit ``` ### Documentation ```bash mix docs # Generate documentation ``` ### Before Committing ```bash mix format --check-formatted && mix credo --strict && mix test && mix audit ```