Module Litany

The 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.

Litany modules

The rule-author vocabulary: the seven domains a rule is written against.

module Span : sig ... end

Half-open byte spans.

module Fix : sig ... end

Source fixes attached to findings.

module Finding : sig ... end

Findings: one diagnostic at one owned location.

module Source : sig ... end

Editable source text of one unit.

module Unit : sig ... end

Admitted units: a source file joined with the artifact the compiler proved against it.

module Pat : sig ... end

Typed-pattern combinators over the compiler's trees.

module Rule : sig ... end

Rules: one declaration, one pure callback.

Compiler modules

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.

module Typedtree = Typedtree
module Parsetree = Parsetree
module Asttypes = Asttypes
module Longident = Longident
module Types = Types
module Location = Location
module Path = Path
module Ident = Ident
module Predef = Predef
module Shape = Shape
module Tast_iterator = Tast_iterator

Driver machinery

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 ... end

Adapters: how build systems reach the core.

module Apply : sig ... end

Single-file fix application: one pass, verified writes.

module Cache : sig ... end

Content-addressed per-unit result cache.

module Config_file : sig ... end

The litany configuration file.

module Digest0 : sig ... end
module Driver : sig ... end

The 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 ... end

The pure analysis core: findings = f(rules, roster, load).

module Naming : sig ... end

Canonical names and their resolution to declaration UIDs.

module Progress : sig ... end

The run's progress meter: one rewritten line on standard error.

module Render : sig ... end

Renderers: derived views of one report.

module Roster : sig ... end

The adapter-supplied enumeration of units.

module Sexp : sig ... end

Positioned s-expressions — the configuration surface's neutral payload vocabulary.

module Suggest : sig ... end

The did-you-mean metric.

module Suppress : sig ... end

Attribute suppression: the allow/expect directives one unit's pre-PPX parse declares.

module Write : sig ... end

Atomic file publication.