From 49494c3aedf3f1b40c6ee36cb4de5615f097274c Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 18 Aug 2026 13:16:53 +0200 Subject: feat(cli): colitur check and colitur new-overlay Writing a local calendar had no feedback loop. An overlay is applied, not validated -- that stays true, and the five test layers still cannot vouch for a user's file -- but before this the only way to learn whether yours did what you meant was to generate a year of output and grep for your own slug, and the only way to see that a directive matched nothing was to notice a warning scroll past among 365 lines. `check` loads each overlay, applies it to the real shipped calendar, and reports the directive counts, the slug each one targets, and any directive that found no target. It exits 2 when a file fails to load or a directive matched nothing, so it composes into a Makefile or a pre-commit hook rather than merely being readable. It is applied to the SHIPPED calendar and not to an empty layer on purpose: against an empty one every Suppress would fail trivially and the check would be worthless. It answers three narrow questions -- does the file parse, does every directive find its target, what does the merged result contain. It does not validate a calendar against the rubrics and cannot, and both the help text and the man page say so rather than letting the name imply more than it does. `new-overlay` prints a starter to stdout for redirection, rather than writing a file where it likes. Every value in it is a placeholder that will appear in `day` output if left unedited, so a half-finished overlay is visible rather than silently inert, and it documents the three date shapes and the legal values for each closed field inline. load_ef_layer now returns its diagnostics instead of printing them: day and readings still want them on stderr beside a year of output, while check wants them on stdout, attributed to the overlay that produced them, and counted. Printing at the source made the second impossible. The cram test round-trips new-overlay through check rather than pinning the template line by line -- editing its prose should not fail a test, but a syntax error in it still must. --- man/colitur.1 | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'man') diff --git a/man/colitur.1 b/man/colitur.1 index 8a52858..a637f19 100644 --- a/man/colitur.1 +++ b/man/colitur.1 @@ -65,6 +65,27 @@ occurrence, commemoration and transfer. .BI readings " YEAR" The Mass reading citations, one line per day. .TP +.B new\-overlay +Print a starter overlay file to standard output, for redirection. Every value +in it is a placeholder that will appear in +.B day +output if left unedited, so a half\-finished overlay is visible rather than +silently inert. +.TP +.BI check " FILE" ... +Load each overlay, apply it to the shipped calendar, and report what it does: +the directive counts, the slug each targets, and any directive that matched +nothing. Exits +.B 2 +if a file fails to load or a directive found no target, so it composes into a +Makefile or a pre\-commit hook. It answers three narrow questions \(em does +the file parse, does every directive find its target, and what does the merged +result contain. It does +.I not +validate a calendar against the rubrics, and cannot: see +.B OVERLAYS +below. +.TP .BI \-\-overlay " FILE" Apply a user calendar on top of the shipped one. Repeatable and ordered; .B day -- cgit v1.3