@spec ash_domains_rule() :: GgenIgniter.DoctorFixes.Rule.t()

Builds the Rule that scans project_dir's lib/ tree for modules that use Ash.Domain (a real textual scan -- these fixture/consumer trees are not necessarily compiled, so this deliberately does not require Code.ensure_loaded?/1) and registers any that are missing from config :OTP_APP, ash_domains: [...] in config/config.exs, where OTP_APP is project_dir's own mix.exs app: value.

The predicate returns {:unrecognized, message} (never guesses) if config :OTP_APP, ...ash_domains: ... is present but its value isn't a simple literal list this rule can safely merge into.

@spec check_ash_domains(Path.t()) ::
  {:ok, String.t()} | {:fixable, String.t()} | {:unrecognized, String.t()}

Read-only check for ash_domains_rule/0. See GgenIgniter.DoctorFixes.Rule.

@spec check_dcatr_env_config(Path.t()) :: {:ok, String.t()} | {:fixable, String.t()}

Read-only check for dcatr_env_rule/0. See GgenIgniter.DoctorFixes.Rule.

@spec check_dep_only(Path.t(), atom()) ::
  {:ok, String.t()} | {:fixable, String.t()} | {:unrecognized, String.t()}

Read-only check for dep_only_rule/1. See GgenIgniter.DoctorFixes.Rule.

@spec check_version_policy(Path.t()) ::
  {:ok, String.t()} | {:fixable, String.t()} | {:unrecognized, String.t()}

Checks whether project_dir's mix.exs version: literal matches the version this project's REAL, observed convention says it should be.

The real convention, confirmed empirically from this project's own git history and CHANGELOG.md (not assumed): every release version is a calendar-ish YY.M.D string (26.8.27 = 2026-08-27, no leading zeros, no v prefix in mix.exs itself), and CHANGELOG.md's topmost ## vX entry header is the single source of truth for "what the current release version is" -- mix.exs's version: is a manually-reconciled projection of that header today, not the other way around, and there is no separate authority (no git tag exists in this repo's history at all -- confirmed via git tag --list returning empty -- so CHANGELOG.md's own top heading is the only real, standing record of "the current version").

This derivation is unambiguous (a single topmost ## vX heading, matched verbatim against mix.exs's version: string) precisely because CHANGELOG.md always has exactly one topmost heading. This convention is specific to ggen_igniter's own release process, not a universal requirement of every consuming project, so a project with no CHANGELOG.md at all (the common case: ggen_igniter.doctor also runs inside arbitrary CONSUMER apps that never opted into this convention) is {:ok, message} -- not applicable, not a problem. It only becomes {:unrecognized, message} when CHANGELOG.md DOES exist but its shape defeats the derivation (no ## v heading found, or mix.exs's version: isn't a simple string literal) -- a real, ambiguous state this module refuses to guess a fallback rule for.

@spec dcatr_env_rule() :: GgenIgniter.DoctorFixes.Rule.t()

Builds the Rule that detects and adds a missing config :dcatr, env: ... entry in project_dir's config/config.exs.

:gno's own Gno.Store.Adapters.Fuseki calls DCATR.Manifest.env/1 at compile time, which raises unless config :dcatr, env: ... (or the DCATR_ENV/MIX_ENV OS environment variable) is set. Only relevant if :gno or :dcatr is actually present in the CURRENT project's own dependency tree (checked the same way ggen_igniter.doctor's existing check_deps/1 checks required deps: Application.ensure_loaded/1 + Application.spec/2).

@spec default_rules() :: [GgenIgniter.DoctorFixes.Rule.t()]

The four real rules mix ggen_igniter.doctor runs through run_rule/3, in the same order it has always run them. Adding a new Igniter/Ash wiring-gap class means appending one more %Rule{} here (data) -- never writing a new check_*/fix_*! function pair, and never touching Mix.Tasks.GgenIgniter.Doctor (it iterates this list generically).

@spec dep_only_rule(atom()) :: GgenIgniter.DoctorFixes.Rule.t()

Builds the Rule that detects and relaxes an :only-restricted dep (e.g. :igniter or :sourceror) in project_dir's own mix.exs -- the same real conflict class this session hit repeatedly: ggen_igniter itself needs :igniter/:sourceror unconditionally (every consuming app, every Mix.env/0), so a consumer's own :only-restricted direct declaration of the same dependency causes Mix's resolver to refuse ("Dependencies have diverged").

Only recognizes a single-line dependency tuple of the shape {:dep, "VERSION_REQ", only: ONLY_VALUE} (the real shape generated by igniter.new/phx.new, and the common hand-written shape); returns :unrecognized rather than guessing for any other shape.

@spec fix_ash_domains!(Path.t()) :: {:ok, String.t()} | {:fixed, String.t()}

Applies ash_domains_rule/0's fix for real. See GgenIgniter.DoctorFixes.Rule.

@spec fix_dcatr_env_config!(Path.t()) :: {:ok, String.t()} | {:fixed, String.t()}

Applies dcatr_env_rule/0's fix for real. See GgenIgniter.DoctorFixes.Rule.

@spec fix_dep_only!(Path.t(), atom()) :: {:ok, String.t()} | {:fixed, String.t()}

Applies dep_only_rule/1's fix for real. See GgenIgniter.DoctorFixes.Rule.

@spec fix_version_policy!(Path.t()) :: {:ok, String.t()} | {:fixed, String.t()}

Applies the fix check_version_policy/1 detects: rewrites project_dir's mix.exs version: literal to match CHANGELOG.md's topmost ## vX entry header, via a structural Sourceror.Zipper rewrite of project/0's real keyword-list AST node (see rewrite_version_literal/2) -- never a full-file text/regex rewrite.

Raises a RuntimeError instead of guessing if the real shape isn't one check_version_policy/1 recognizes (no CHANGELOG.md, no ## v heading, or mix.exs's version: isn't a simple string literal).

@spec hex_publish_rules() :: [GgenIgniter.DoctorFixes.Rule.t()]

The two package[...] metadata rules mix ggen_igniter.doctor's check 16 (--hex-check) runs through run_rule/3, applied to the CURRENT project's mix.exs -- see package_description_rule/0 and package_licenses_rule/0. Kept separate from default_rules/0 because they only matter when --hex-check is passed (check 16 is off by default; see Mix.Tasks.GgenIgniter.Doctor's moduledoc).

@spec package_description_rule() :: GgenIgniter.DoctorFixes.Rule.t()

Builds the Rule that detects a package/0 function in project_dir's mix.exs missing a description: entry, when the file already defines a description/0 function elsewhere (the common shape: a project-level description: description() in project/0, with package/0 simply forgetting to also reference it -- this repo's own mix.exs shows the intended pattern). Only fixable in that exact, unambiguous case: this never invents description text, it only wires up a function this project already declared. Any other shape (no package/0 found, no description/0 function defined anywhere in the file) is {:unrecognized, ...} -- refuses to guess prose.

@spec package_licenses_rule() :: GgenIgniter.DoctorFixes.Rule.t()

Builds the Rule that detects a package/0 function in project_dir's mix.exs missing a licenses: entry, when a real LICENSE/ LICENSE.md/LICENSE.txt file exists at the project root whose first non-empty line is an EXACT, recognized SPDX license header (today: "MIT License" -> ["MIT"]). Never guesses a license from anything less than an exact known header match -- an unrecognized or missing LICENSE file text is {:unrecognized, ...}, not a guessed default.

@spec package_metadata_keys_present(Path.t()) :: %{
  description: boolean(),
  licenses: boolean()
}

Reads project_dir's real, CURRENT mix.exs source text directly (never the possibly-stale in-process Mix.Project.config(), which is loaded once and does not reflect a mix.exs write made later in the same BEAM process) and reports whether package/0's body textually contains a description:/licenses: key. Used by check 16's hex-publish-readiness metadata check so a --fix applied earlier in the SAME mix ggen_igniter.doctor --hex-check --fix invocation is reflected immediately, not only on the next separate invocation.

@spec run_rule(GgenIgniter.DoctorFixes.Rule.t(), Path.t(), boolean()) ::
  {:ok, String.t()}
  | {:fixed, String.t()}
  | {:fixable, String.t()}
  | {:unrecognized, String.t()}

The one generic engine every Rule runs through: read real project state (rule.predicate.(project_dir)), and:

• {:ok, message} -- nothing to do, passed through as-is.
• {:unrecognized, message} -- a real gap exists but this rule refuses to guess how to close it. Returned as data when fix? is false (diagnostic mode); raised as a RuntimeError when fix? is true (matching every existing fix_*!'s "never silently no-op on a real problem" discipline).
• {:fixable, message} -- a real, safely-automatable gap. When fix? is false, returned as-is (diagnostic mode). When fix? is true, rule.transform.(project_dir) is applied for real, then rule.verify.(project_dir) re-reads the real file and confirms the gap is actually gone -- raising a RuntimeError (never reporting a false {:fixed, ...}) if the transform ran but the real post-fix state still shows the same gap.