Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (67 loc) · 3.71 KB

AGENTS.md

File metadata and controls

87 lines (67 loc) · 3.71 KB
Raw

AGENTS.md

Guidance for AI agents working on the DecimalEnv library.

Project overview

DecimalEnv is a small Elixir library (~2 modules, ~830 LOC) that provides a decimal macro for running a block of code with Decimal arithmetic under regular Elixir operators. It depends on Decimal ~> 3.0.

  • lib/decimal_env.ex — public decimal/1 and decimal/2 macros plus the get_context/1 and convert_type/2 helpers.
  • lib/decimal_env/operators.ex — operator overloads (arithmetic, comparison, abs, min, max, div, rem, round, ceil, floor, sqrt, inf, inf?, number?, integer?) imported via use DecimalEnv.Operators.

Toolchain

  • Erlang/OTP 29, Elixir 1.20 (see .tool-versions).
  • Minimum supported: Elixir 1.15 / OTP 26 (see mix.exs and CI matrix).
  • Use mix for all tasks.

Verification commands

Run all of these before considering work complete. CI runs the same set (.github/workflows/checks.yml) and any one of them can fail independently.

mix format --dry-run --check-formatted   # formatting
mix credo --strict                        # lint
mix test                                  # doctests + unit tests
mix dialyzer                              # type checks

mix compile --warnings-as-errors is also enforced in CI; run it if you change lib/.

Testing conventions

The library has very few traditional unit tests; doctests are the primary test mechanism. Most functions in DecimalEnv.Operators carry iex> blocks that double as both documentation and tests.

  • test/decimal_env_test.exs — unit tests for the decimal macros and the get_context/1 / convert_type/2 helpers.
  • test/decimal_env/operators_test.exs — additional unit tests for cases the doctests don't cover (e.g. all round/3 strategies, +Inf/-Inf/NaN edge cases). It begins with doctest DecimalEnv.Operators.

When adding a new operator or function, prefer extending its @doc with iex> examples over writing a separate unit test — doctest DecimalEnv.Operators will pick them up automatically.

Operator-specific gotchas

  • Operators cannot be invoked remotely. DecimalEnv.Operators.+(a, b) is a syntax error. Inside the decimal block the operators are imported; in tests outside the block, call the underlying named function (DecimalEnv.Operators.round/3, .div/2, .inf?/1, .>(a, b), etc.) instead. The comparison operators >, <, >=, <=, ==, != can be called remotely because they parse as atoms, but the arithmetic operators (+, -, *, /, unary +, unary -) cannot.
  • use DecimalEnv.Operators is a compile-time macro and cannot be invoked inside a test body. If a test genuinely needs the import (e.g. to exercise the unary + operator), define a small defmodule inside the test module that does use DecimalEnv.Operators and expose a wrapper. Avoid this unless strictly necessary — prefer calling the named function directly.
  • __using__/1 is implicitly covered by every iex> block in DecimalEnv.Operators (each one starts with use DecimalEnv.Operators).

Formatting

  • mix format is the source of truth. Line length is 80 (see .formatter.exs).
  • decimal/1 and decimal/2 are listed under locals_without_parens, so write decimal do: ... / decimal as: :integer do: ... without parens.
  • Never hand-align code to satisfy the formatter; run mix format and commit its output.

Conventions

  • No comments unless explicitly requested (matches the rest of the codebase).
  • Keep @spec annotations on every public and private function — they are load-bearing for mix dialyzer.
  • Public API changes deserve a CHANGELOG.md entry under the current @version in mix.exs.