Bylaw.Credo.Check.Phoenix.UseVerifiedRoutes (bylaw_credo v0.4.0)

Basics

This check is disabled by default.

Learn how to enable it via .credo.exs.

This check has a base priority of higher and works with any version of Elixir.

Explanation

Enforces Phoenix verified routes (~p) for application routes in the web layer.

Verified routes validate path structure and route parameters at compile time, so renames and malformed paths fail near their source instead of becoming runtime navigation or test failures. They also keep route construction tied to the router that owns the route.

Examples

Configure the Phoenix web boundary and one or more routers that define the routes to match:

{Bylaw.Credo.Check.Phoenix.UseVerifiedRoutes,
 [
   web_paths: ["lib/my_app_web/"],
   endpoint_paths: ["lib/my_app_web/endpoint.ex"],
   router_paths: ["lib/my_app_web/router.ex"],
   conn_case_modules: [MyAppWeb.ConnCase],
   routers: [MyAppWeb.Router, MyAppWeb.AdminRouter]
 ]}

Avoid:

  conn |> get("/api/v1/openapi")

  defp workspace_path(tenant_id, workspace_id) do
    "/api/v1/tenants/#{tenant_id}/workspaces/#{workspace_id}"
  end

  assert location == "/api/v1/tenants/#{tenant.id}/workspaces/#{workspace.id}"

Prefer:

  conn |> get(~p"/api/v1/openapi")

  defp workspace_path(tenant_id, workspace_id) do
    ~p"/api/v1/tenants/#{tenant_id}/workspaces/#{workspace_id}"
  end

  assert location == ~p"/api/v1/tenants/#{tenant.id}/workspaces/#{workspace.id}"

  params = %{filters: %{0 => %{field: "name", op: "==", value: "Staging"}}}
  conn |> get(~p"/api/v1/tenants/#{tenant_id}/workspaces?#{params}")

Notes

The check only runs in configured web paths and tests using configured ConnCase modules. It only flags path strings that normalize to a route exposed by one of the configured routers or :fallback_router_paths. It ignores OpenAPI URI templates like "/api/v1/tenants/{tenant_id}/..." and HEEx route attributes for now.

This check uses static AST analysis, so it favors clear source-level patterns over runtime behavior. Configure :fallback_router_paths when router modules are unavailable during Credo analysis.

Options

Configure options in .credo.exs with the check tuple:

%{
  configs: [
    %{
      name: "default",
      checks: [
        {Bylaw.Credo.Check.Phoenix.UseVerifiedRoutes,
         [
           web_paths: ["lib/my_app_web/"],
           endpoint_paths: ["lib/my_app_web/endpoint.ex"],
           router_paths: ["lib/my_app_web/router.ex"],
           conn_case_modules: [MyAppWeb.ConnCase],
           routers: [MyAppWeb.Router, MyAppWeb.AdminRouter],
           fallback_router_paths: [
             "/api/v1/openapi",
             "/admin/users/:id"
           ]
         ]}
      ]
    }
  ]
}

:web_paths - Paths containing files where route strings should be checked.
:endpoint_paths - Endpoint files to skip even when they match :web_paths.
:router_paths - Router files to skip even when they match :web_paths.
:conn_case_modules - Test case modules that identify request/controller tests.
:routers - Phoenix router modules whose route paths should be matched.
:fallback_router_paths - Route path patterns to use when router modules are unavailable.

Usage

Add this check to Credo's checks: list in .credo.exs:

%{
  configs: [
    %{
      name: "default",
      checks: [
        {Bylaw.Credo.Check.Phoenix.UseVerifiedRoutes,
         [
           web_paths: ["lib/my_app_web/"],
           conn_case_modules: [MyAppWeb.ConnCase],
           routers: [MyAppWeb.Router]
         ]}
      ]
    }
  ]
}