mix extla.stamp (ExTLA v0.6.0)

Copy Markdown View Source

Report the state of every spec_version: stamp, and update the stale ones.

mix extla.stamp             # report every mapping's stamp
mix extla.stamp --check     # report, and exit 1 if a stamp is unverified
mix extla.stamp --restamp   # rewrite stale stamps in source

It reads source, and that is not an implementation detail

A stale stamp is a compile error — that is the point of it. So a task that needed the project to compile before it could report or fix a stale stamp would be unusable in exactly the situation it exists for. This reads .ex files directly and loads nothing.

What --restamp is for, and what it is not

A stale stamp means the spec a mapping was written against has changed. The work that resolves it is re-reading the mapping — confirming each variable and action it names still means what it did — and only then recording that you have.

--restamp performs the recording. It cannot perform the judgement, and it is deliberately a separate command rather than a suggestion inside the compile error: an error message offering a one-key fix trains people to take the fix, and a stamp applied without reading is worse than no stamp, because it manufactures assurance.

Run it after the review, never instead of it.

What --check fails on, and when to use it

One question: is this stamp verified by something?

:fresh                              yes, by this task
:stale                              no -- it is checked, and it is WRONG
:unstamped                          there is no stamp; the mechanism is opt-in
:unverifiable, spec not on disk     no. Nothing verifies it
:unverifiable, spec: not an alias   yes, by the COMPILER

--check exits 1 on the two that answer no, and 0 on the rest.

The last row is the one worth stating, because it looks like a finding and is not. A spec: given as @an_attribute cannot be resolved by a task that reads source without compiling — but use ExTLA.GenServer has the attribute's value at expansion, so the compile-time check verifies that stamp completely. Measured: a mapping with an attribute spec: and a wrong stamp raises ExTLA.Spec.CompileError exactly as a literal one does. Failing a build on it would be a false finding about a mapping that is fully checked.

A build that compiles does not need it. A stale stamp is already a compile error, and a spec whose source is not on disk already emits a compile warning — so on any project that compiles with --warnings-as-errors, both failures arrive from the compile step, earlier and with better messages. Running --check there as well adds a second way to learn the same thing.

--check is for the workflow the compiler cannot serve: the project does not compile, and a script wants the list of mappings to re-read rather than one error at a time. That is the situation this task was built for, and the exit code is what lets a script act on it.

Exit codes

0  every stamp is verified by something, or `--check` was not given
1  with `--check`: a stamp is stale, or its spec's source is not on disk,
   so nothing verifies it. Without `--check` the report is a report

Summary

Functions

mappings(index)

Every use ExTLA.GenServer site, as %{module, spec, stamp, path}.

module_index(roots \\ roots())

A module => source path index built by parsing defmodule declarations.

roots()

The directories this scans: the project's own elixirc_paths, and lib as a floor.

sources(roots \\ roots())

Every .ex file under roots.

states(roots \\ roots())

Every mapping's stamp state: %{module, spec, stamp, current, status, path}.

Functions

mappings(index)

Every use ExTLA.GenServer site, as %{module, spec, stamp, path}.

module_index(roots \\ roots())

A module => source path index built by parsing defmodule declarations.

roots()

The directories this scans: the project's own elixirc_paths, and lib as a floor.

elixirc_paths is the project's own answer to "where is my code", so no other directory name is assumed and nothing outside the compiled trees is scanned.

sources(roots \\ roots())

Every .ex file under roots.

states(roots \\ roots())

Every mapping's stamp state: %{module, spec, stamp, current, status, path}.

status is :fresh, :stale, :unstamped or :unverifiable. Read from source, so this answers even when a stale stamp is stopping the project from compiling.