feat: ci mode

Adds a ci flag which does the following:

- ensures INFO level logging at a minimum
- --no-cache
- --fail-on-change

This also adds a delay on startup which is intended to ensure we do not start doing anything until we have moved into the second after the one in which the process started. This helps to ensure accurate comparisons of `modtime` using truncated second-level precision for change detection.

This is only an issue in scenarios in which treefmt is being executed quickly in succession or directly after an automatic checkout, such as in CI.

Signed-off-by: Brian McGee <brian@bmcgee.ie>

cli/cli.go

@@ -37,6 +37,8 @@ type Format struct {
 
 	CpuProfile string `optional:"" help:"The file into which a cpu profile will be written."`
 
+	Ci bool `help:"Runs treefmt in a CI mode, enabling --no-cache, --fail-on-change and adjusting some other settings best suited to a CI use case."`
+
 	formatters     map[string]*format.Formatter
 	globalExcludes []glob.Glob
 

cli/format.go

@@ -34,6 +34,37 @@ func (f *Format) Run() (err error) {
 	// set log level and other options
 	f.configureLogging()
 
+	// ci mode
+	if f.Ci {
+		f.NoCache = true
+		f.FailOnChange = true
+
+		// ensure INFO level
+		if f.Verbosity < 1 {
+			f.Verbosity = 1
+		}
+		// reconfigure logging
+		f.configureLogging()
+
+		log.Info("ci mode enabled")
+
+		startAfter := time.Now().
+			// truncate to second precision
+			Truncate(time.Second).
+			// add one second
+			Add(1 * time.Second).
+			// a little extra to ensure we don't start until the next second
+			Add(10 * time.Millisecond)
+
+		log.Debugf("waiting until %v before continuing", startAfter)
+
+		// Wait until we tick over into the next second before processing to ensure our EPOCH level modtime comparisons
+		// for change detection are accurate.
+		// This can fail in CI between checkout and running treefmt if everything happens too quickly.
+		// For humans, the second level precision should not be a problem as they are unlikely to run treefmt in sub-second succession.
+		<-time.After(time.Until(startAfter))
+	}
+
 	// cpu profiling
 	if f.CpuProfile != "" {
 		cpuProfile, err := os.Create(f.CpuProfile)

docs/usage.md

@@ -31,6 +31,7 @@ Flags:
                                      <debug|info|warn|error|fatal>.
       --stdin                        Format the context passed in via stdin.
       --cpu-profile=STRING           The file into which a cpu profile will be written.
+      --ci                           Runs treefmt in a CI mode, enabling --no-cache, --fail-on-change and adjusting some other settings best suited to a CI use case.
 ```
 
 ## Arguments
@@ -112,13 +113,22 @@ Format the context passed in via stdin.
 
 The file into which a cpu profile will be written.
 
+### `--ci`
+
+Runs treefmt in a CI mode which does the following:
+
+-   ensures `INFO` level logging at a minimum
+-   enables `--no-cache` and `--fail-on-change`
+-   introduces a small startup delay so we do not start processing until the second after the process started, thereby
+    ensuring the accuracy of our change detection based on second-level `modtime`.
+
 ### `-V, --version`
 
 Print version.
 
 ## CI integration
 
-Typically, you would use `treefmt` in CI with the `--fail-on-change` and `--no-cache flags`.
+Typically, you would use `treefmt` in CI with the `--ci` flag.
 
 You can configure a `treefmt` job in a GitHub pipeline for Ubuntu with `nix-shell` like this:
 
@@ -141,5 +151,5 @@ jobs:
                   name: nix-community
                   authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
             - name: treefmt
-              run: nix-shell -p treefmt --run "treefmt --fail-on-change --no-cache"
+              run: nix-shell -p treefmt --run "treefmt --ci"
 ```