From 19bf1b3eb17a16f614329ba449ecf01b05b4df39 Mon Sep 17 00:00:00 2001 From: Fredrik Teschke Date: Mon, 16 Nov 2026 12:41:55 +0100 Subject: [PATCH] docs: document `mix usage_rules.sync --check` for CI --- README.md | 12 +++++++++++- lib/mix/tasks/usage_rules.sync.ex | 9 +++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index de5ff4c..9cfc14e 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,16 @@ mix usage_rules.sync That's it. The config is the source of truth — packages in the file but not in config are automatically removed on each sync. +### Checking in CI + +`mix usage_rules.sync` is an Igniter task, so it accepts Igniter's global flags, such as `--check`. With `--check`, it writes nothing and exits nonzero when a sync would change any file, e.g. after a dependency update changed its usage rules: + +```sh +mix usage_rules.sync --check +``` + +Content outside the managed sections is not checked. + ## Configuration Reference ```elixir @@ -437,7 +447,7 @@ Make sure your `usage-rules/skills/` directory is included in your hex package's mix usage_rules.validate usage-rules.md usage-rules/*.md ``` -Run with no arguments, it validates the files `mix usage_rules.sync` manages in the current project instead: the composed file from the `:file` config option, and `*.md` files under skills whose `SKILL.md` contains `managed-by: usage-rules`. +Run with no arguments, it validates the files `mix usage_rules.sync` manages in the current project instead: the composed file from the `:file` config option, and `*.md` files under skills whose `SKILL.md` contains `managed-by: usage-rules`. This checks references only; to check that those files are up to date, see [Checking in CI](#checking-in-ci). The check is deliberately conservative: the warnings are exactly what a docs build emits, so `ex_doc` skips fenced code blocks, and stays silent about plain code span mentions that never resolve — such as `mix task` names and bare undefined module names — just like it does inside moduledocs. diff --git a/lib/mix/tasks/usage_rules.sync.ex b/lib/mix/tasks/usage_rules.sync.ex index 82612a0..65ca020 100644 --- a/lib/mix/tasks/usage_rules.sync.ex +++ b/lib/mix/tasks/usage_rules.sync.ex @@ -39,6 +39,15 @@ defmodule Mix.Tasks.UsageRules.Sync.Docs do The config is the source of truth — packages present in the file but absent from config are automatically removed on each sync. + + ## Checking in CI + + Igniter's global flags apply. With `--check`, the task writes nothing and + exits nonzero when a sync would change any file: + + ```sh + mix usage_rules.sync --check + ``` """ end