Update

.credo.exs

@@ -0,0 +1,73 @@
+%{
+  configs: [
+    %{
+      name: "default",
+      files: %{
+        included: ["lib/", "src/"],
+        excluded: []
+      },
+      plugins: [],
+      requires: [],
+      strict: false,
+      parse_timeout: 5000,
+      color: true,
+      checks: %{
+        disabled: [
+          # Styler Rewrites
+          #
+          # The following rules are automatically rewritten by Styler and so disabled here to save time
+          # Some of the rules have `priority: :high`, meaning Credo runs them unless we explicitly disable them
+          # (removing them from this file wouldn't be enough, the `false` is required)
+          #
+          # Some rules have a comment before them explaining ways Styler deviates from the Credo rule.
+          #
+          # always expands `A.{B, C}`
+          # {Credo.Check.Consistency.MultiAliasImportRequireUse, false},
+          # including `case`, `fn` and `with` statements
+          {Credo.Check.Consistency.ParameterPatternMatching, false},
+          # Styler implements this rule with a depth of 3 and minimum repetition of 2
+          {Credo.Check.Design.AliasUsage, false},
+          {Credo.Check.Readability.AliasOrder, false},
+          {Credo.Check.Readability.BlockPipe, false},
+          # goes further than formatter - fixes bad underscores, eg: `100_00` -> `10_000`
+          {Credo.Check.Readability.LargeNumbers, false},
+          # adds `@moduledoc false`
+          {Credo.Check.Readability.ModuleDoc, false},
+          {Credo.Check.Readability.MultiAlias, false},
+          {Credo.Check.Readability.OneArityFunctionInPipe, false},
+          # removes parens
+          {Credo.Check.Readability.ParenthesesOnZeroArityDefs, false},
+          {Credo.Check.Readability.PipeIntoAnonymousFunctions, false},
+          {Credo.Check.Readability.PreferImplicitTry, false},
+          {Credo.Check.Readability.SinglePipe, false},
+          # **potentially breaks compilation** - see **Troubleshooting** section below
+          {Credo.Check.Readability.StrictModuleLayout, false},
+          {Credo.Check.Readability.StringSigils, false},
+          {Credo.Check.Readability.UnnecessaryAliasExpansion, false},
+          {Credo.Check.Readability.WithSingleClause, false},
+          {Credo.Check.Refactor.CaseTrivialMatches, false},
+          {Credo.Check.Refactor.CondStatements, false},
+          # in pipes only
+          {Credo.Check.Refactor.FilterCount, false},
+          # in pipes only
+          {Credo.Check.Refactor.MapInto, false},
+          # in pipes only
+          {Credo.Check.Refactor.MapJoin, false},
+          # {Credo.Check.Refactor.NegatedConditionsInUnless, false},
+          # {Credo.Check.Refactor.NegatedConditionsWithElse, false},
+          # allows ecto's `from
+          {Credo.Check.Refactor.PipeChainStart, false},
+          {Credo.Check.Refactor.RedundantWithClauseResult, false},
+          {Credo.Check.Refactor.UnlessWithElse, false},
+          {Credo.Check.Refactor.WithClauses, false},
+
+          # custom ext_fit rules
+          {Credo.Check.Refactor.Nesting, false},
+          {Credo.Check.Refactor.CyclomaticComplexity, false},
+          {Credo.Check.Design.TagFIXME, false},
+          {Credo.Check.Design.TagTODO, false}
+        ]
+      }
+    }
+  ]
+}

.dialyzer_ignore.exs

@@ -0,0 +1 @@
+[]

.github/actions/elixir-setup/action.yml

@@ -0,0 +1,132 @@
+name: Setup Elixir Project
+description: Checks out the code, configures Elixir, fetches dependencies, and manages build caching.
+inputs:
+  elixir-version:
+    required: true
+    type: string
+    description: Elixir version to set up
+  otp-version:
+    required: true
+    type: string
+    description: OTP version to set up
+  #################################################################
+  # Everything below this line is optional.
+  #
+  # It's designed to make compiling a reasonably standard Elixir
+  # codebase "just work," though there may be speed gains to be had
+  # by tweaking these flags.
+  #################################################################
+  build-deps:
+    required: false
+    type: boolean
+    default: true
+    description: True if we should compile dependencies
+  build-app:
+    required: false
+    type: boolean
+    default: true
+    description: True if we should compile the application itself
+  build-flags:
+    required: false
+    type: string
+    default: '--all-warnings'
+    description: Flags to pass to mix compile
+  install-rebar:
+    required: false
+    type: boolean
+    default: true
+    description: By default, we will install Rebar (mix local.rebar --force).
+  install-hex:
+    required: false
+    type: boolean
+    default: true
+    description: By default, we will install Hex (mix local.hex --force).
+  cache-key:
+    required: false
+    type: string
+    default: 'v1'
+    description: If you need to reset the cache for some reason, you can change this key.
+outputs:
+  otp-version:
+    description: "Exact OTP version selected by the BEAM setup step"
+    value: ${{ steps.beam.outputs.otp-version }}
+  elixir-version:
+    description: "Exact Elixir version selected by the BEAM setup step"
+    value: ${{ steps.beam.outputs.elixir-version }}
+runs:
+  using: "composite"
+  steps:
+    - name: Setup elixir
+      uses: erlef/setup-beam@v1
+      id: beam
+      with:
+        elixir-version: ${{ inputs.elixir-version }}
+        otp-version: ${{ inputs.otp-version }}
+
+    - name: Get deps cache
+      uses: actions/cache@v2
+      with:
+        path: deps/
+        key: deps-${{ inputs.cache-key }}-${{ runner.os }}-${{ hashFiles('**/mix.lock') }}
+        restore-keys: |
+          deps-${{ inputs.cache-key }}-${{ runner.os }}-
+
+    - name: Get build cache
+      uses: actions/cache@v2
+      id: build-cache
+      with:
+        path: _build/${{env.MIX_ENV}}/
+        key: build-${{ inputs.cache-key }}-${{ runner.os }}-${{ inputs.otp-version }}-${{ inputs.elixir-version }}-${{ env.MIX_ENV }}-${{ hashFiles('**/mix.lock') }}
+        restore-keys: |
+          build-${{ inputs.cache-key }}-${{ runner.os }}-${{ inputs.otp-version }}-${{ inputs.elixir-version }}-${{ env.MIX_ENV }}-
+
+    - name: Get Hex cache
+      uses: actions/cache@v2
+      id: hex-cache
+      with:
+        path: ~/.hex
+        key: build-${{ runner.os }}-${{ inputs.otp-version }}-${{ inputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}
+        restore-keys: |
+          build-${{ runner.os }}-${{ inputs.otp-version }}-${{ inputs.elixir-version }}-
+
+    # In my experience, I have issues with incremental builds maybe 1 in 100
+    # times that are fixed by doing a full recompile.
+    # In order to not waste dev time on such trivial issues (while also reaping
+    # the time savings of incremental builds for *most* day-to-day development),
+    # I force a full recompile only on builds that we retry.
+    - name: Clean to rule out incremental build as a source of flakiness
+      if: github.run_attempt != '1'
+      run: |
+        mix deps.clean --all
+        mix clean
+      shell: sh
+
+    - name: Install Rebar
+      run: mix local.rebar --force
+      shell: sh
+      if: inputs.install-rebar == 'true'
+
+    - name: Install Hex
+      run: mix local.hex --force
+      shell: sh
+      if: inputs.install-hex == 'true'
+
+    - name: Install Dependencies
+      run: mix deps.get
+      shell: sh
+
+    # Normally we'd use `mix deps.compile` here, however that incurs a large
+    # performance penalty when the dependencies are already fully compiled:
+    # https://elixirforum.com/t/github-action-cache-elixir-always-recompiles-dependencies-elixir-1-13-3/45994/12
+    #
+    # Accoring to Jose Valim at the above link `mix loadpaths` will check and
+    # compile missing dependencies
+    - name: Compile Dependencies
+      run: mix loadpaths
+      shell: sh
+      if: inputs.build-deps == 'true'
+
+    - name: Compile Application
+      run: mix compile ${{ inputs.build-flags }}
+      shell: sh
+      if: inputs.build-app == 'true'

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+- package-ecosystem: mix
+  directory: "/"
+  schedule:
+    interval: weekly
+    time: "12:00"
+  open-pull-requests-limit: 3

.github/workflows/elixir-build-and-test.yml

@@ -0,0 +1,35 @@
+name: Build and Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  build:
+    name: Build and test
+    runs-on: ubuntu-latest
+    env:
+      MIX_ENV: test
+    strategy:
+      matrix:
+        elixir: ["1.16.2"]
+        otp: ["25.3.2"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Setup Elixir Project
+        uses: ./.github/actions/elixir-setup
+        with:
+          elixir-version: ${{ matrix.elixir }}
+          otp-version: ${{ matrix.otp }}
+          build-flags: --all-warnings --warnings-as-errors
+
+      - name: Run Tests
+        run: mix coveralls.json --warnings-as-errors
+        if: always()

.github/workflows/elixir-dialyzer.yml

@@ -0,0 +1,56 @@
+name: Elixir Type Linting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  build:
+    name: Run Dialyzer
+    runs-on: ubuntu-latest
+    env:
+      MIX_ENV: dev
+    strategy:
+      matrix:
+        elixir: ["1.16.2"]
+        otp: ["25.3.2"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Setup Elixir Project
+        uses: ./.github/actions/elixir-setup
+        id: beam
+        with:
+          elixir-version: ${{ matrix.elixir }}
+          otp-version: ${{ matrix.otp }}
+          build-app: false
+
+      # Don't cache PLTs based on mix.lock hash, as Dialyzer can incrementally update even old ones
+      # Cache key based on Elixir & Erlang version (also useful when running in matrix)
+      - name: Restore PLT cache
+        uses: actions/cache@v3
+        id: plt_cache
+        with:
+          key: plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}-${{ hashFiles('**/*.ex') }}
+          restore-keys: |
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}-${{ hashFiles('**/*.ex') }}
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('**/mix.lock') }}-
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-
+            plt-${{ runner.os }}-${{ steps.beam.outputs.otp-version }}-
+          path: priv/plts
+
+      # Create PLTs if no cache was found.
+      # Always rebuild PLT when a job is retried
+      # (If they were cached at all, they'll be updated when we run mix dialyzer with no flags.)
+      - name: Create PLTs
+        if: steps.plt_cache.outputs.cache-hit != 'true' || github.run_attempt != '1'
+        run: mix dialyzer --plt
+
+      - name: Run Dialyzer
+        run: mix dialyzer --format github

.github/workflows/elixir-quality-checks.yml

@@ -0,0 +1,47 @@
+name: Elixir Quality Checks
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  quality_checks:
+    name: Formatting, and Unused Deps
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        elixir: ["1.16.2"]
+        otp: ["25.3.2"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Setup Elixir Project
+        uses: ./.github/actions/elixir-setup
+        with:
+          elixir-version: ${{ matrix.elixir }}
+          otp-version: ${{ matrix.otp }}
+          build-app: false
+
+      - name: Check for unused deps
+        run: mix deps.unlock --check-unused
+      - name: Check code formatting
+        run: mix format --check-formatted
+        # Check formatting even if there were unused deps so that
+        # we give devs as much feedback as possible & save some time.
+        if: always()
+      - name: Run Credo
+        run: mix credo suggest --min-priority=normal
+        # Run Credo even if formatting or the unused deps check failed
+        if: always()
+      # - name: Check for compile-time dependencies
+      #   run: mix xref graph --label compile-connected --fail-above 0
+      #   if: always()
+      # - name: Check for security vulnerabilities in Phoenix project
+      #   run: mix sobelow
+      #   if: always()

.gitignore

@@ -24,3 +24,5 @@ nimrag-*.tar
 
 # Temporary files, for example, from tests.
 /tmp/
+
+priv/plts

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+<!-- ### Bug fixes -->
+<!-- ### Enhancements -->
+<!-- ### Backwards incompatible changes -->
+
+## 0.1.0 (2024-03-29)
+
+Init release

LICENSE.md

@@ -0,0 +1,22 @@
+# MIT License
+
+Copyright (c) 2024 Michal Forys
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.