use nimble_options to document schema

Author: the-mikedavis

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a
 Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.0.7 - 2021-01-25
+
+### Added
+
+- The schema is now validated and documented by `:nimble_options`
+
 ## 0.0.6 - 2020-12-22
 
 ### Changed

fixture/harness.lock

@@ -0,0 +1,3 @@
+%{
+  "nimble_options": {:hex, :nimble_options, "0.3.5", "a4f6820cdcb4ee444afd78635f323e58e8a5ddf2fbbe9b9d283a99f972034bae", [:mix], [], "hexpm", "f5507cc90033a8d12769522009c80aa9164af6bab245dbd4ad421d008455f1e1"},
+}

lib/harness_dotfiles.ex

@@ -1,25 +1,112 @@
 defmodule HarnessDotfiles do
+  @schema [
+    coveralls_skip_files: [
+      doc: """
+      A list of file regex patterns to ignore for coveralls coverage checking.
+      """,
+      type: {:list, :string},
+      default: ["^test", "^deps", "^.harness"]
+    ],
+    coveralls_minimum_coverage: [
+      doc: """
+      The minimum percentage of coverage to require for a successful coveralls
+      coverage report.
+      """,
+      type: {:custom, __MODULE__, :parse_number, []},
+      default: 100
+    ],
+    explicit_credo_checks: [
+      doc: """
+      A list of explicit checks to pass to the credo `:checks` configuration.
+      Checks in this list will merge on top of the defaults provided in the
+      `.credo.exs` template provided by this harness package. To disable a
+      check, add an element to the list: `{CheckName, false}`.
+      """,
+      type: {:list, {:custom, __MODULE__, :parse_tuple, []}},
+      default: []
+    ],
+    excluded_paths_for_modulename_matches_filename: [
+      doc: """
+      A list of elixir Regexs used to ignore files and directories from the
+      Convene ModulenameMatchesFilename check. Useful for ignoring directories
+      containing modules with Phoenix naming conventions.
+      """,
+      type: {:list, {:custom, __MODULE__, :parse_regex, []}},
+      default: []
+    ],
+    asdf_elixir_version: [
+      doc: """
+      The version of elixir to use, as passed to `asdf`.
+      """,
+      type: :string,
+      default: "1.11.2-otp-23"
+    ],
+    asdf_erlang_version: [
+      doc: """
+      The version of erlang to use, as passed to `asdf`.
+      """,
+      type: :string,
+      default: "23.2"
+    ],
+    asdf_other_versions: [
+      doc: """
+      Other versions to include in the local `.tool-versions` file used by
+      `asdf`. E.g. `["nodejs 12.13.1"]` will add Node to the local `asdf`
+      requirements.
+      """,
+      type: {:list, :string},
+      default: []
+    ],
+    formatter_deps: [
+      doc: """
+      The list of dependencies from which to import formatter config. Some
+      dependencies like `:projection` or `:phoenix` export formatter
+      configuration, like which functions or macros should be allowed to not
+      have parentheses.
+      """,
+      type: {:list, :atom},
+      default: []
+    ],
+    formatter_locals_without_parens: [
+      doc: """
+      A keyword list of function/macro names and arities allowed to not have
+      parentheses in the local project. E.g. `[foo: 2]` will allow calls to
+      `foo/2` to not need parentheses, as in `foo :bar, :baz`.
+      """,
+      type: :keyword_list,
+      default: []
+    ]
+  ]
+
   @moduledoc """
   A harness for a common collection of dotfiles
+
+  The options are:
+
+  #{NimbleOptions.docs(@schema)}
   """
 
   @behaviour Harness.Pkg
 
-  defstruct coveralls_skip_files: ["^test", "^deps", "^.harness"],
-            coveralls_minimum_coverage: 100,
-            explicit_credo_checks: [],
-            excluded_paths_for_modulename_matches_filename: [],
-            asdf_elixir_version: "1.11.2-otp-23",
-            asdf_erlang_version: "23.2",
-            asdf_other_versions: [],
-            formatter_deps: [],
-            formatter_locals_without_parens: []
+  defstruct ~w[
+    coveralls_skip_files
+    coveralls_minimum_coverage
+    explicit_credo_checks
+    excluded_paths_for_modulename_matches_filename
+    asdf_elixir_version
+    asdf_erlang_version
+    asdf_other_versions
+    formatter_deps
+    formatter_locals_without_parens
+  ]a
 
+  @doc false
   @impl Harness.Pkg
   def cast(opts) do
-    struct(__MODULE__, opts)
+    struct(__MODULE__, NimbleOptions.validate!(opts, @schema))
   end
 
+  @doc false
   @impl Harness.Pkg
   def links(_config) do
     ~w[
@@ -29,4 +116,29 @@ defmodule HarnessDotfiles do
       coveralls.json
     ]
   end
+
+  @doc false
+  def parse_number(number) when is_number(number) do
+    {:ok, number}
+  end
+
+  def parse_number(unknown) do
+    {:error, "must be a number (integer or float), got: #{inspect(unknown)}"}
+  end
+
+  @doc false
+  def parse_tuple(tuple) when is_tuple(tuple) do
+    {:ok, tuple}
+  end
+
+  def parse_tuple(unknown) do
+    {:error, "must be a tuple, got: #{inspect(unknown)}"}
+  end
+
+  @doc false
+  def parse_regex(%Regex{} = regex), do: {:ok, regex}
+
+  def parse_regex(unknown) do
+    {:error, "must be a regex, got: #{inspect(unknown)}"}
+  end
 end

mix.exs

@@ -44,6 +44,7 @@ defmodule HarnessDotfiles.MixProject do
 
   defp deps do
     [
+      {:nimble_options, "~> 0.1"},
       # docs
       {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
       # test

mix.lock

@@ -14,6 +14,7 @@
   "makeup_elixir": {:hex, :makeup_elixir, "0.14.1", "4f0e96847c63c17841d42c08107405a005a2680eb9c7ccadfd757bd31dabccfb", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f2438b1a80eaec9ede832b5c41cd4f373b38fd7aa33e3b22d9db79e640cbde11"},
   "metrics": {:hex, :metrics, "1.0.1", "25f094dea2cda98213cecc3aeff09e940299d950904393b2a29d191c346a8486", [:rebar3], [], "hexpm", "69b09adddc4f74a40716ae54d140f93beb0fb8978d8636eaded0c31b6f099f16"},
   "mimerl": {:hex, :mimerl, "1.2.0", "67e2d3f571088d5cfd3e550c383094b47159f3eee8ffa08e64106cdf5e981be3", [:rebar3], [], "hexpm", "f278585650aa581986264638ebf698f8bb19df297f66ad91b18910dfc6e19323"},
+  "nimble_options": {:hex, :nimble_options, "0.3.5", "a4f6820cdcb4ee444afd78635f323e58e8a5ddf2fbbe9b9d283a99f972034bae", [:mix], [], "hexpm", "f5507cc90033a8d12769522009c80aa9164af6bab245dbd4ad421d008455f1e1"},
   "nimble_parsec": {:hex, :nimble_parsec, "0.6.0", "32111b3bf39137144abd7ba1cce0914533b2d16ef35e8abc5ec8be6122944263", [:mix], [], "hexpm", "27eac315a94909d4dc68bc07a4a83e06c8379237c5ea528a9acff4ca1c873c52"},
   "parse_trans": {:hex, :parse_trans, "3.3.0", "09765507a3c7590a784615cfd421d101aec25098d50b89d7aa1d66646bc571c1", [:rebar3], [], "hexpm", "17ef63abde837ad30680ea7f857dd9e7ced9476cdd7b0394432af4bfc241b960"},
   "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.6", "cf344f5692c82d2cd7554f5ec8fd961548d4fd09e7d22f5b62482e5aeaebd4b0", [:make, :mix, :rebar3], [], "hexpm", "bdb0d2471f453c88ff3908e7686f86f9be327d065cc1ec16fa4540197ea04680"},

test/harness_dotfiles_test.exs

@@ -6,8 +6,8 @@ defmodule HarnessDotfilesTest do
       [opts: []]
     end
 
-    test "casting the configuration produces the default struct", c do
-      assert HarnessDotfiles.cast(c.opts) === %HarnessDotfiles{}
+    test "casting the configuration produces a struct", c do
+      assert %HarnessDotfiles{} = HarnessDotfiles.cast(c.opts)
     end
   end