Litany.Config_fileThe litany configuration file.
One file, one closed schema. A litany file at the workspace root is dune-style s-expressions — ; comments, bare and "quoted" atoms, parenthesized forms — and the grammar is closed: an unknown form, unknown key, or duplicate is an error with a position and a did-you-mean suggestion, never a warning and never a silent fallback.
(litany-config 1) ; optional version header, first form only (lint (select default) ; groups or rule names; default | all (extend style unused-export) (ignore manual-eta-lambda) (closed-world false)) (rule line-length (max 100)) ; options are the rule's own, opaque here (per-path (paths vendor/** third-party/*.ml) (ignore all) (reason "vendored code"))
The domain is pure and IO-free: the driver reads the file and calls parse, which validates everything the schema states on its own — form shapes, the closed key sets, the glob grammar. Rule and group names live in the rule catalog, which this domain does not depend on: check_names validates them against caller-supplied vocabularies with the same positioned errors, and each (rule ...) form's options stay opaque positioned Sexp.t values, handed later to the owning rule's declared option schema.
Positions are 1-based lines and 1-based byte columns into the parsed string, the renderer's convention.
The type for positioned atoms — a name with the position of its first byte in the parsed string. Quoted and bare spellings are equivalent; value is the unescaped text.
module Glob : sig ... endAnchored workspace-relative byte globs — per-path's paths entries.
module Error = Sexp.ErrorPositioned configuration errors (Sexp.Error, re-exported): a position and one actionable message — e.g. unknown rule "styel" (did you mean "style"?). The same type carries a rule option schema's refusals (Rule.Options.error), so the driver renders every config-file error with Error.to_string whichever side produced it.
module Rule_options : sig ... endOne (rule <name> <options>...) form.
module Per_path : sig ... endOne (per-path ...) form: report selection by path — selection of reports, never of analysis. It is not audited and needs no per-site reason; the reason key documents intent.
val empty : tempty is the zero-configuration default — what an absent file means: version 1, no selection tokens, closed_world false, no rule options, no per-path selections.
val version : t -> intversion c is the schema version from the (litany-config <n>) header, or 1 when the header is absent. This litany reads version 1 only.
select c is lint's select tokens in order. Empty when absent — the driver's resolution treats that as default.
ignored c is lint's ignore tokens in order; empty when absent. (The schema key is ignore; the accessor steps aside for Stdlib.ignore.)
val closed_world : t -> boolclosed_world c is lint's closed-world, defaulting to false: public library exports stay dead-code roots.
val rules : t -> Rule_options.t listrules c is the (rule ...) forms in file order, at most one per rule name.
val per_paths : t -> Per_path.t listper_paths c is the (per-path ...) forms in file order.
parse src reads a whole litany file from src — the driver does the IO. It is Error e on the first problem, top to bottom: lexical errors, then per form the closed schema — an unknown form or key (with a did-you-mean suggestion when one is within edit distance 2), a duplicate (lint ...) form, key, or (rule <name>) name, a malformed value, an invalid glob. parse never raises and touches no catalog: rule and group names are validated by check_names.
check_names c ~selection ~rules resolves c's names against the caller's vocabularies and is Error e on the first unknown one, with a positioned did-you-mean over the same vocabulary — e.g. litany:4:10: unknown rule or group "styel" (did you mean "style"?).
selection is every token valid in select/extend/ignore — set names (all, default), stability tiers (nursery), group names, rule names, and tombstone aliases; checked over lint's three lists and every per-path's ignore, in that order.rules is every rule name and alias valid as a (rule <name>) head.The caller builds both from the catalog (Rule.name, Rule.renamed_from, Rule.Group.to_string); precedence and tombstone warnings stay with Rule.select.