# presubmit v0.2.2 - Table of Contents

> A linter for git commits, with Elixir-aware models of what changed

## Pages

- [presubmit](readme.md)
- [Changelog](changelog.md)

## Modules

- [Presubmit.Runner.Report](Presubmit.Runner.Report.md): Every rule's outcome for one change set.
- [Presubmit.Runner.Result](Presubmit.Runner.Result.md): The outcome of one rule against one change set.

- Running
  - [Presubmit](Presubmit.md): Assertions over the shape and contents of git commits, run as a linter.
  - [Presubmit.CLI](Presubmit.CLI.md): The logic behind `mix presubmit`, separated from Mix so it can be
driven from tests: parse arguments, load configuration and change sets,
run, render, and return an exit status.

  - [Presubmit.Config](Presubmit.Config.md): Loads the rule configuration from `.presubmit.exs`, or builds a
default one from what the examined tree and the VM contain.
  - [Presubmit.Formatter](Presubmit.Formatter.md): Renders runner reports as text or JSON.
  - [Presubmit.Hooks](Presubmit.Hooks.md): Installs and removes the git hooks that run `mix presubmit`.
  - [Presubmit.Runner](Presubmit.Runner.md): Runs rules against change sets and collects the outcomes.

- Rules
  - [Presubmit.Rule](Presubmit.Rule.md): One named check over a change set.
  - [Presubmit.RuleSet](Presubmit.RuleSet.md): A module that groups related rules, so a configuration can enable a whole
area of policy with one entry.
  - [Presubmit.Rules.Changelog](Presubmit.Rules.Changelog.md): Changelog: API changes and releases are recorded. Option `path:` (default `CHANGELOG.md`).
  - [Presubmit.Rules.Ecto](Presubmit.Rules.Ecto.md): Ecto: migrations are ordered, immutable, safe, reversible, and back every schema change.
  - [Presubmit.Rules.Elixir](Presubmit.Rules.Elixir.md): Elixir source hygiene: specs, docs, deprecation before removal, pure moves.
  - [Presubmit.Rules.ExUnit](Presubmit.Rules.ExUnit.md): ExUnit: new modules and behaviour changes come with tests.
  - [Presubmit.Rules.Hygiene](Presubmit.Rules.Hygiene.md): Things that should never be committed. Options
  - [Presubmit.Rules.Message](Presubmit.Rules.Message.md): Commit message conventions. All of these skip for change sets without a message.
  - [Presubmit.Rules.Mix](Presubmit.Rules.Mix.md): Mix: mix.lock moves with mix.exs.
  - [Presubmit.Rules.OTP](Presubmit.Rules.OTP.md): OTP: every added process is started by a supervisor.
  - [Presubmit.Rules.Phoenix](Presubmit.Rules.Phoenix.md): Phoenix: every added controller and LiveView is routed.
  - [Presubmit.Rules.Shape](Presubmit.Rules.Shape.md): Commit size. Options `max_files:` (default 50) and `max_additions:` (default 1000).

- Assertions
  - [Presubmit.Assertions](Presubmit.Assertions.md): ExUnit assertion verbs over a `Presubmit.Commit`.
  - [Presubmit.Assertions.Changelog](Presubmit.Assertions.Changelog.md): Assertions over `CHANGELOG.md`, built on `Presubmit.Changelog`.

  - [Presubmit.Assertions.Ecto](Presubmit.Assertions.Ecto.md): Assertions over Ecto schemas and migrations, built on
`Presubmit.Adapters.EctoSchema` and `Presubmit.Adapters.EctoMigration`.
  - [Presubmit.Assertions.ExUnit](Presubmit.Assertions.ExUnit.md): Assertions over test coverage of a change, built on
`Presubmit.Adapters.ExUnitCase`.

  - [Presubmit.Assertions.Mix](Presubmit.Assertions.Mix.md): Assertions over `mix.exs` and `mix.lock`, built on `Presubmit.MixFile`.

  - [Presubmit.Assertions.OTP](Presubmit.Assertions.OTP.md): Assertions over OTP processes and supervision trees, built on
`Presubmit.Adapters.OtpProcess`.

  - [Presubmit.Assertions.Phoenix](Presubmit.Assertions.Phoenix.md): Assertions over Phoenix routers, controllers, and LiveViews, built on
`Presubmit.Adapters.PhoenixRouter` and `Presubmit.Adapters.PhoenixHandler`.

  - [Presubmit.Query](Presubmit.Query.md): Functions that read facts out of a `Presubmit.Commit` for use in
assertions or directly in tests.
  - [Presubmit.Violation](Presubmit.Violation.md): Raised by an assertion verb when a change set does not satisfy it.

- Adapters
  - [Presubmit.Adapter](Presubmit.Adapter.md): Behaviour for library-aware adapters that turn a module's facts into a
domain model: an Ecto schema's fields, a Phoenix router's routes, a
supervisor's children.
  - [Presubmit.Adapters.EctoMigration](Presubmit.Adapters.EctoMigration.md): Models `use Ecto.Migration` modules as a list of schema operations.
  - [Presubmit.Adapters.EctoSchema](Presubmit.Adapters.EctoSchema.md): Models `use Ecto.Schema` modules.
  - [Presubmit.Adapters.EctoSchema.Field](Presubmit.Adapters.EctoSchema.Field.md): One `field`, association, or embed declaration.
  - [Presubmit.Adapters.ExUnitCase](Presubmit.Adapters.ExUnitCase.md): Models test modules: `use ExUnit.Case`, or `use` of any module whose name
ends in `Case` (`MyApp.DataCase`, `MyAppWeb.ConnCase`).
  - [Presubmit.Adapters.OtpProcess](Presubmit.Adapters.OtpProcess.md): Models OTP behaviours and the children they start.
  - [Presubmit.Adapters.PhoenixHandler](Presubmit.Adapters.PhoenixHandler.md): Models the modules a Phoenix router can route to: controllers, LiveViews,
and LiveComponents, plus channels.
  - [Presubmit.Adapters.PhoenixRouter](Presubmit.Adapters.PhoenixRouter.md): Models Phoenix routers (`use Phoenix.Router`, or `use MyAppWeb, :router`)
as a flat list of routes with plug modules fully resolved.
  - [Presubmit.Adapters.PhoenixRouter.Route](Presubmit.Adapters.PhoenixRouter.Route.md): One route: verb, full path, resolved plug module, and action.

- Source analysis
  - [Presubmit.Changelog](Presubmit.Changelog.md): Reads a Markdown changelog as a list of sections keyed by heading.
  - [Presubmit.MixFile](Presubmit.MixFile.md): Reads dependency and version declarations from `mix.exs` and `mix.lock`
without evaluating them.
  - [Presubmit.Source](Presubmit.Source.md): Entry points for the Elixir-aware layers: the structural diff of a commit
and the adapter models derived from it.
  - [Presubmit.Source.Cache](Presubmit.Source.Cache.md): The shared cache of extracted facts: a public ETS table keyed by
`{blob_oid, path}`, so a range of commits parses each distinct file
version once.
  - [Presubmit.Source.Diff](Presubmit.Source.Diff.md): The structural difference between the Elixir source before and after a
change set: modules and functions added, removed, renamed, or changed.
  - [Presubmit.Source.Facts](Presubmit.Source.Facts.md): Structural facts about one Elixir source file, extracted from its AST.
  - [Presubmit.Source.Facts.Function](Presubmit.Source.Facts.Function.md): One function or macro, folded across its clauses.
  - [Presubmit.Source.Facts.Module](Presubmit.Source.Facts.Module.md): One `defmodule`, including nested ones (named `Outer.Inner`).
  - [Presubmit.Source.Index](Presubmit.Source.Index.md): Tree-wide discovery of modules, for invariants that need to look beyond the
files a commit changed: "some router routes this controller", "some
supervisor starts this server", "a test module exists for this module".

- Change sets
  - [Presubmit.Commit](Presubmit.Commit.md): A change set: the trees before and after, the per-file changes between
them, and (for real commits) the metadata and message.
  - [Presubmit.FileChange](Presubmit.FileChange.md): One file's change between the before and after trees.
  - [Presubmit.Git](Presubmit.Git.md): Thin adapter over the `git` plumbing commands presubmit relies on.
  - [Presubmit.Hunk](Presubmit.Hunk.md): A contiguous run of changed lines within one file, with zero context.
  - [Presubmit.Message](Presubmit.Message.md): A parsed commit message: subject, body, and trailers.
  - [Presubmit.Paths](Presubmit.Paths.md): Path patterns for the conventional directories, anchored so they work at
the repository root and inside umbrella apps or subdirectory projects
(`apps/foo/lib/`, `services/bar/test/`).

  - [Presubmit.Pattern](Presubmit.Pattern.md): Path patterns accepted by every query and assertion.
  - [Presubmit.Tree](Presubmit.Tree.md): A snapshot of every file in the repository at one point in history.

- Errors
  - [Presubmit.Config.Error](Presubmit.Config.Error.md): Raised when the configuration file is missing, invalid, or names unknown rules.
  - [Presubmit.GitError](Presubmit.GitError.md): Raised when a git command fails or its output cannot be interpreted.

  - [Presubmit.MergeCommitError](Presubmit.MergeCommitError.md): Raised when the revision under test is a merge commit.
  - [Presubmit.NoMessageError](Presubmit.NoMessageError.md): Raised when a message assertion runs against a change set that has no
commit message, such as the staged index.

  - [Presubmit.RuleTimeoutError](Presubmit.RuleTimeoutError.md): Reported (never raised) when a rule does not finish within the runner's
timeout; the rule is killed and the run continues.

  - [Presubmit.ShallowCloneError](Presubmit.ShallowCloneError.md): Raised when the parent of the revision under test is not present locally.

## Mix Tasks

- [mix presubmit](Mix.Tasks.Presubmit.md): Runs the rules in `.presubmit.exs` (or the built-in defaults) against a
change set and reports each rule as passed, failed, or skipped.
- [mix presubmit.install](Mix.Tasks.Presubmit.Install.md): Installs a `commit-msg` hook that runs `mix presubmit --staged
--message-file "$1"`, so the staged changes and the message are checked
together before the commit is created, and a `prepare-commit-msg` hook that
tells it when the commit amends `HEAD`, so the amended commit (`HEAD^` to
the index) is what gets checked rather than the delta since `HEAD`.

