Module Litany.Config_file

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

Positioned atoms

type atom = {
  1. value : string;
  2. line : int;
  3. col : int;
}

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.

S-expressions

module Sexp = Sexp

Positioned s-expression values (Sexp, re-exported).

Globs

module Glob : sig ... end

Anchored workspace-relative byte globs — per-path's paths entries.

Errors

module Error = Sexp.Error

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

Configurations

module Rule_options : sig ... end

One (rule <name> <options>...) form.

module Per_path : sig ... end

One (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.

type t

The type for parsed configurations.

val empty : t

empty 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 -> int

version c is the schema version from the (litany-config <n>) header, or 1 when the header is absent. This litany reads version 1 only.

val select : t -> atom list

select c is lint's select tokens in order. Empty when absent — the driver's resolution treats that as default.

val extend : t -> atom list

extend c is lint's extend tokens in order; empty when absent.

val ignored : t -> atom list

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 -> bool

closed_world c is lint's closed-world, defaulting to false: public library exports stay dead-code roots.

val rules : t -> Rule_options.t list

rules c is the (rule ...) forms in file order, at most one per rule name.

val per_paths : t -> Per_path.t list

per_paths c is the (per-path ...) forms in file order.

Parsing and validation

val parse : string -> (t, Error.t) Stdlib.result

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.

val check_names : t -> selection:string list -> rules:string list -> (unit, Error.t) Stdlib.result

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.