LitanyThe library's interface, and the rule-author SDK.
litany is one wrapped library: every domain is a module of this one, so Litany.Engine is the engine and Litany.Driver the check driver. The first two sections below are the SDK — what a rule author sees and what carries a compatibility promise; Driver machinery is the driver machinery, exposed for bin/ and the test suites and promised to nobody.
open Litany is a rule file's single open: it re-exports Litany's own modules alongside the compiler's Typedtree, Parsetree, Asttypes, Longident, Types, Location, Path, Ident, Predef, Shape, and Tast_iterator — the closure the trees lean on, plus the iterator for bounded subtree walks — so rules compile against the real trees with one dependency — litany — in their dune stanza, warning-free under dune's default warning set. Strict sets (-w +40+42) additionally qualify Litany's policy constructors (Rule.Perf, Rule.Never) and tree labels. The compiler-libs pin is Litany's, stated once.
A rule is one value in one file: declare Rule.meta, build the match with Pat, return Finding values, attach a Fix when the edit is provable. The built-in catalog lives beside it in Litany_rules — one module per rule plus Litany_rules.all, each rule a client of exactly this facade.
Third parties extend by recompiling: a custom bin/ that passes Litany_rules.all @ My_rules.all where the stock composition root passes the catalog is the whole extension model — no dynlink, which keeps the cache's binary-digest key honest. The packaged recipe is the documented thin composition root — some 25 lines against Driver and a stock adapter, in A custom binary. There is deliberately no cli library: the recipe serves the need.
The rule-author vocabulary: the seven domains a rule is written against.
module Span : sig ... endHalf-open byte spans.
module Fix : sig ... endSource fixes attached to findings.
module Finding : sig ... endFindings: one diagnostic at one owned location.
module Source : sig ... endEditable source text of one unit.
module Unit : sig ... endAdmitted units: a source file joined with the artifact the compiler proved against it.
module Pat : sig ... endTyped-pattern combinators over the compiler's trees.
module Rule : sig ... endRules: one declaration, one pure callback.
Re-exported, not wrapped. Rules see the compiler's own trees; a compiler minor is absorbed by Litany's release stream, not by a façade.
Not SDK vocabulary and no rule-author compatibility promise: these are the domains the check driver, bin/, and the test suites compose. open Litany does put them in scope — the price of one wrapped library — but a rule that names one is out of contract, and test/rules/ freezes that discipline by grep the way it used to freeze the Litany_* spelling.
module Adapter : sig ... endAdapters: how build systems reach the core.
module Apply : sig ... endSingle-file fix application: one pass, verified writes.
module Cache : sig ... endContent-addressed per-unit result cache.
module Config_file : sig ... endThe litany configuration file.
module Digest0 : sig ... endmodule Driver : sig ... endThe check driver: the engine pass, the --fix convergence loop, the admission listing, the report surfaces, and their supporting lanes (the result-cache wiring and the process workers).
module Engine : sig ... endThe pure analysis core: findings = f(rules, roster, load).
module Naming : sig ... endCanonical names and their resolution to declaration UIDs.
module Progress : sig ... endThe run's progress meter: one rewritten line on standard error.
module Render : sig ... endRenderers: derived views of one report.
module Roster : sig ... endThe adapter-supplied enumeration of units.
module Sexp : sig ... endPositioned s-expressions — the configuration surface's neutral payload vocabulary.
module Suggest : sig ... endThe did-you-mean metric.
module Suppress : sig ... endAttribute suppression: the allow/expect directives one unit's pre-PPX parse declares.
module Write : sig ... endAtomic file publication.