# Surfex v0.6.2 - Table of Contents

> Keep a specification, its tests and its code aligned: a log of which versions were confirmed to belong together, checked from source without compiling it

## Pages

- [Surfex](readme.md)

- Using surfex
  - [Using surfex](using-surfex.md)
  - [Working as an agent](usage-rules.md)
  - [Adoption: trust or re-evaluate](adoption.md)
  - [Completeness](completeness.md)
  - [Configuration: .surfex.exs](config.md)
  - [Handing off found work](drafts.md)
  - [Goldens](goldens.md)
  - [Marks: the spec itself is wrong](marks.md)
  - [The model](model.md)
  - [The process](process.md)
  - [Recording relations](recording.md)
  - [Reading the status](status.md)
  - [Validation](validation.md)

- Guides
  - [Writing specs Surfex can use](writing-specs.md)
  - [Adopting an existing suite](adopting-an-existing-suite.md)
  - [Using surfex as a library](using-surfex-as-a-library.md)

- Reference
  - [Surfex specification {#surfex}](spec.md)
  - [Changelog](changelog.md)

## Modules

- [Surfex.ExUnitFormatter](Surfex.ExUnitFormatter.md): An ExUnit formatter that records test evidence (`Surfex.Evidence`): for each test that
ran, whether it passed, at its exact version, with the versions of the code it calls.
- [Surfex.Golden](Surfex.Golden.md): The ONE renderer for a project's surface goldens.
- [Surfex.Item](Surfex.Item.md): One item a scanner found in the code: the unit a spec citation resolves to, and the
source of a code record (`Surfex.Scan.code/1`).
- [Surfex.Scanner](Surfex.Scanner.md): Finds the items the code declares: the code records the relation log relates
(`Surfex.Scan.code/1`), and what the spec's citations resolve to. A scanner knows one
language's declarations; it knows nothing about any spec, and `Surfex.Cite` knows
nothing about any language.
- [Surfex.SourceScan](Surfex.SourceScan.md): Generic, dependency-free primitives for reading Elixir source **without compiling it**:
find a project root, enumerate `lib` sources, extract `defmodule` nodes, and version a
definition by its content.

## Mix Tasks

- [mix surfex.annotate](Mix.Tasks.Surfex.Annotate.md): Gives a current relation a new note (`Surfex.Record.annotate/6`, §14): a re-review that
found nothing to change still belongs in the log, not a commit message.
- [mix surfex.baseline](Mix.Tasks.Surfex.Baseline.md): Takes the one-shot baseline (`Surfex.Record.baseline/4`, §18.1): every test version the
project's `adoption:` trusts counts as if it had discriminated, and its `verifies:` tags
become `verifies` relations with basis `baseline`.
- [mix surfex.completeness](Mix.Tasks.Surfex.Completeness.md): Prints the completeness report (`Surfex.Completeness`, §20): a score per kind (spec
units, tests, code) and overall, and every incomplete item with what it lacks and where.
- [mix surfex.confirm](Mix.Tasks.Surfex.Confirm.md): Confirms **one** relation, named by its ends and type, with a note saying what was
judged (`Surfex.Record.confirm/7`)
- [mix surfex.draft](Mix.Tasks.Surfex.Draft.md): Prints a change draft (`Surfex.Change`, §19) for every open mark, unmet id and triangle
gap, or for the ids given: what's wrong, what it touches, and the steps the process
implies. It prints and changes nothing
- [mix surfex.goldens](Mix.Tasks.Surfex.Goldens.md): Gates every golden the project lists in `.surfex.exs` (`Surfex.Goldens`): the relation
status (`RELATIONS.md`) and any project goldens (`Surfex.Surface`). One CI line for all
of them.
- [mix surfex.history](Mix.Tasks.Surfex.History.md): Lists every log entry touching an id, oldest first (`Surfex.Record.history/2`): what it
was related to, at which versions, when, by whom, and why. It reads only the log, so it
answers from any checkout, however the git history was rewritten.
- [mix surfex.info](Mix.Tasks.Surfex.Info.md): Tells an agent (or anyone) how Surfex works, from the installed version (§21).
- [mix surfex.log](Mix.Tasks.Surfex.Log.md): Looks after the relation log in `.surfex/` (`Surfex.Log`).
- [mix surfex.mark](Mix.Tasks.Surfex.Mark.md): Records that a spec unit itself needs to change (`Surfex.Record.mark/5`, §12.1): the
tests reflect it and the code passes them, but the result is wrong or clearly
sub-optimal. The mark is recorded at the unit's current version, and the note says what
is wrong
- [mix surfex.move](Mix.Tasks.Surfex.Move.md): Moves every live relation of `OLD` onto `NEW` (`Surfex.Record.move/5`): for each, a
`retire` of the old relation and a `relate` of the same type with `NEW` in its place.
- [mix surfex.relate](Mix.Tasks.Surfex.Relate.md): Records a relation between two scanned ids, at their current hashes
(`Surfex.Record.relate/6`).
- [mix surfex.resolve](Mix.Tasks.Surfex.Resolve.md): A relation is conflicted when two entries were recorded without seeing each other,
typically on two branches that were then merged. `mix surfex.status` lists the tips'
ids; this records the picked one again with both as parents (`Surfex.Record.resolve/7`).
- [mix surfex.retire](Mix.Tasks.Surfex.Retire.md): Retires a relation (`Surfex.Record.retire/6`): an entry saying it no longer applies. It
is appended like any other, and the relation's history stays in the log.
- [mix surfex.status](Mix.Tasks.Surfex.Status.md): Scans the spec and the code, reads the relation log, and reports the state of every
relation (`Surfex.Status`).
- [mix surfex.suggest](Mix.Tasks.Surfex.Suggest.md): Lists what the spec already implies (`Surfex.Suggest.all/5`)
- [mix surfex.validate](Mix.Tasks.Surfex.Validate.md): Records a **review** (`Surfex.Record.validate/6`, §18): the test was examined against the
spec unit, judged to validate it, and passes against the code.