blockwatch-cli 0.14.1__tar.gz → 0.14.2__tar.gz

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/.github/workflows/pypi.yml

@@ -24,9 +24,9 @@ jobs:
             target: x86_64-unknown-linux-gnu
           - runner: ubuntu-24.04-arm
             target: aarch64-unknown-linux-gnu
-          - runner: macos-14
+          - runner: macos-15
             target: aarch64-apple-darwin
-          - runner: macos-14
+          - runner: macos-15
             target: x86_64-apple-darwin
           - runner: windows-latest
             target: x86_64-pc-windows-msvc

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/AGENTS.md

@@ -193,7 +193,8 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    report goes to stdout. The exit code depends on the error-severity violations that are not suppressed.
 
 The `list` subcommand stops after step 6 and writes the blocks it found to stdout as JSON. The `skill` subcommand
-prints `src/skill.md` right after step 1.
+prints `src/skill.md` right after step 1. The `explain` subcommand runs like `--only-block` with the file of its
+address as the only path. It then writes that block to stdout as JSON.
 
 The main modules:
 

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/CHANGELOG.md

@@ -12,6 +12,38 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.14.2] - 2026-10-21
+
+### Added
+
+- `line-count-pattern` makes `line-count` count only the lines that match the regex. For example,
+  `line-count="<=20" line-count-pattern='^"\w+",$'` skips comments and blank lines in a list. See
+  [`line-count`](docs/validators/line-count.md).
+- `blockwatch explain FILE:BLOCK_NAME` checks one named block and prints it as JSON: its attributes, the text its
+  validators read and where that text is. For example: `blockwatch explain package.json:version`. The output also lists
+  the validators the block asks for but the settings turn off (`"disabled"`). Under `"checks"`, it shows what each
+  validator saw:
+  - `same-as`: each record the pattern matched, with its line, on both sides, and the reason of each mismatch.
+  - `keep-sorted` and `keep-unique`: the value each line gives, up to the first line out of order or repeated.
+  - `line-pattern`: what each pattern matched on each line, up to the first line that fails.
+  - `affects`: whether the block changed, and for each target, whether it changed or why it doesn't resolve.
+  - `line-count`: the value each line gives, how many lines count, and the rule they were checked against.
+  - `check-lua`: the `content` and `ctx.affects` the script got, and the message it returned.
+  - `check-ai`: the model, the prompt it was sent and its answer.
+
+  `"with_diff"` says whether `--diff` was given. Without it, no block counts as changed. Violations go to stderr, and
+  the exit code is the same as for a normal run. See [The `explain` Command](docs/cli.md#the-explain-command).
+
+### Changed
+
+- A message of `affects` or `same-as` about a whole-file target shows the path alone, without `file` in front. For
+  example: `Block a.py:b at line 1 is modified, but config.json is not`.
+
+### Fixed
+
+- A `check-lua` script got no `ctx.affects` entry for a block target that the run didn't check, such as with
+  `--only-block` or `--diff --only-changed`. Now `ctx.affects` holds the same targets in every run.
+
 ## [0.14.1] - 2026-10-17
 
 ### Changed

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/CLAUDE.md

@@ -193,7 +193,8 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    report goes to stdout. The exit code depends on the error-severity violations that are not suppressed.
 
 The `list` subcommand stops after step 6 and writes the blocks it found to stdout as JSON. The `skill` subcommand
-prints `src/skill.md` right after step 1.
+prints `src/skill.md` right after step 1. The `explain` subcommand runs like `--only-block` with the file of its
+address as the only path. It then writes that block to stdout as JSON.
 
 The main modules:
 

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/Cargo.lock

@@ -274,7 +274,7 @@ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
 [[package]]
 name = "blockwatch"
-version = "0.14.1"
+version = "0.14.2"
 dependencies = [
  "anyhow",
  "assert-json-diff",

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "blockwatch"
-version = "0.14.1"
+version = "0.14.2"
 edition = "2024"
 repository = "https://github.com/mennanov/blockwatch"
 description = "Language agnostic linter that keeps your code and documentation in sync and valid"

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.14.1
+Version: 0.14.2
 Summary: Language agnostic linter that keeps your code and documentation in sync and valid
 Keywords: linter,sync,drift,comments,agents
 Home-Page: https://github.com/mennanov/blockwatch

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/README.md

@@ -104,7 +104,7 @@ you'd otherwise have to nitpick in code review.
 | [`keep-sorted`](docs/validators/keep-sorted.md)   | Enforces alphabetical or numerical ordering on list items                                    | `keep-sorted`, `keep-sorted-pattern`, `keep-sorted-format`                      |
 | [`keep-unique`](docs/validators/keep-unique.md)   | Prevents duplicate lines within a block                                                      | `keep-unique`                                                                   |
 | [`line-pattern`](docs/validators/line-pattern.md) | Enforces that every line matches a regex, or that no line matches a forbidden one            | `line-pattern`, `line-pattern-forbidden`                                        |
-| [`line-count`](docs/validators/line-count.md)     | Enforces lower or upper bounds on the number of lines in a block                             | `line-count`                                                                    |
+| [`line-count`](docs/validators/line-count.md)     | Enforces lower or upper bounds on the number of lines in a block                             | `line-count`, `line-count-pattern`                                              |
 | [`check-ai`](docs/validators/check-ai.md)         | Validates content against natural language rules using an LLM                                | `check-ai`, `check-ai-pattern`                                                  |
 | [`check-lua`](docs/validators/check-lua.md)       | Runs custom validation logic written in Lua                                                  | `check-lua`, `check-lua-pattern`, `check-lua-timeout`                           |
 
@@ -173,6 +173,9 @@ git diff --patch HEAD | blockwatch --diff --only-changed
 
 # Dump all discovered blocks as JSON
 blockwatch list
+
+# Show what each validator of one named block read
+blockwatch explain src/lib.rs:languages
 ```
 
 Rules live in comments, next to the code they describe. Settings that apply to the whole project, such as ignored
@@ -215,7 +218,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.14.1  # Use latest release
+  rev: v0.14.2  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/dist-workspace.toml

@@ -27,7 +27,7 @@ publish-jobs = ["homebrew"]
 global = "ubuntu-latest"
 
 [dist.github-custom-runners.aarch64-apple-darwin]
-runner = "macos-14"
+runner = "macos-15"
 
 [dist.github-custom-runners.x86_64-unknown-linux-gnu]
 runner = "ubuntu-latest"

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/docs/ci.md

@@ -19,7 +19,7 @@ To use [pre-commit](https://pre-commit.com), add the hook to `.pre-commit-config
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.14.1  # Use latest release
+  rev: v0.14.2  # Use latest release
   hooks:
     - id: blockwatch
 ```
@@ -59,7 +59,7 @@ The `blockwatch` hook runs before the commit message exists, so it cannot see a
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.14.1  # Use latest release
+  rev: v0.14.2  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/docs/cli.md

@@ -14,6 +14,8 @@ For command-line flag documentation directly in your terminal, run `blockwatch -
   every block in the repository.
 - **List Blocks**: `blockwatch list` outputs a JSON report of all discovered blocks. It takes `--diff`,
   `--only-changed`, `--config`, `-E` and `--ignore`.
+- **Explain a Block**: `blockwatch explain FILE:BLOCK_NAME` checks one named block and prints what each of its
+  validators read, as JSON. See [The `explain` Command](#the-explain-command).
 - **Print the Agent Skill**: `blockwatch skill` prints the [skill for AI agents](#the-skill-command), as a `SKILL.md`
 - **Config File**: `blockwatch --config FILE` reads the project's settings from FILE instead of `blockwatch.toml`
 - **Custom Extensions**: Map custom file extensions: `blockwatch -E ino=cpp` (config key: `extensions`)
@@ -555,15 +557,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.14.1",
-          "semanticVersion": "0.14.1",
+          "version": "0.14.2",
+          "semanticVersion": "0.14.2",
           "informationUri": "https://github.com/mennanov/blockwatch",
           "rules": [
             {
               "id": "keep-sorted",
               "name": "keep-sorted",
               "shortDescription": { "text": "Requires the lines of a block to stay in order." },
-              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.14.1/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.14.2/docs/validators/keep-sorted.md"
             }
           ]
         }
@@ -617,7 +619,7 @@ What to expect from the log:
 - **Lines and columns are 1-based, with an exclusive end column.** A column counts characters, which the run declares as
   `"columnKind": "unicodeCodePoints"` so that a consumer does not count UTF-16 code units instead.
 
-`--format` cannot be combined with the `list` subcommand, which reports blocks rather than violations. To upload a log
+`--format` cannot be combined with the `list` and `explain` subcommands, which write JSON of their own. To upload a log
 to GitHub code scanning, see [CI Integration](ci.md#github-code-scanning).
 
 ## The `list` Command
@@ -701,6 +703,104 @@ block's attributes are sorted by name; the files themselves are not ordered, and
 emit them differently. Sort by key downstream if you need to diff one run against another — or use
 [`--verbosity full`](#full-reports), which does order its files.
 
+## The `explain` Command
+
+`blockwatch explain FILE:BLOCK_NAME` checks one named block and prints what each of its validators read, as JSON. Run it
+after you write a rule, to see that the rule matches what you meant. A rule can be wrong and still pass. For example, a
+`same-as-pattern` can take the same wrong part of each line on both sides.
+
+```shell
+blockwatch explain src/colors.py:colors
+blockwatch explain package.json:version                              # a block from blockwatch.toml
+git diff --patch | blockwatch explain --diff src/colors.py:colors   # affects needs the diff
+```
+
+- It takes one address, as `--only-block` does. A block without a `name` can't be explained, so give it one first.
+- It takes `--diff`, `--config`, `-E` and `--ignore`, and rejects the other flags.
+- `only-blocks` and `skip-blocks` in `blockwatch.toml` play no part, because the address already picks the block.
+  `enable` and `disable` still apply.
+- The explanation goes to stdout. Violations go to stderr, and the [exit code](#exit-codes) is the one a normal run
+  gives. `check-ai` calls the API, as in a normal run.
+
+### Explain Output Example
+
+For this block:
+
+```python
+COLORS = [
+    # <block name="colors" keep-sorted="asc" keep-sorted-pattern='"(?P<value>\w+)"'>
+    "blue",
+    "red",
+    # </block>
+]
+```
+
+`blockwatch explain src/colors.py:colors` prints:
+
+[//]: # (<block name="explain-output-example">)
+
+```json
+{
+  "block": {
+    "attributes": {
+      "keep-sorted": "asc",
+      "keep-sorted-pattern": "\"(?P<value>\\w+)\"",
+      "name": "colors"
+    },
+    "column": 7,
+    "is_content_modified": false,
+    "line": 2,
+    "name": "colors"
+  },
+  "checks": {
+    "keep-sorted": {
+      "format": "lexicographic",
+      "lines": [
+        { "line": 3, "text": "\"blue\",", "value": "blue" },
+        { "line": 4, "text": "\"red\",", "value": "red" }
+      ],
+      "order": "asc"
+    }
+  },
+  "content": {
+    "start": { "line": 2, "character": 85 },
+    "end": { "line": 5, "character": 5 },
+    "text": "\n    \"blue\",\n    \"red\",\n    "
+  },
+  "disabled": [],
+  "file": "src/colors.py",
+  "with_diff": false
+}
+```
+
+[//]: # (</block>)
+
+| Key         | What it holds                                                                                                                                                                                                                                                                          |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `block`     | The block, as [`list`](#the-list-command) writes it.                                                                                                                                                                                                                                   |
+| `checks`    | What each validator read, by validator. See [What Each Validator Shows](#what-each-validator-shows).                                                                                                                                                                                   |
+| `content`   | The text the validators read. `start` is its first character, and `end` is the first character after it. The column is `character`, as in the `range` of a violation. For a [virtual block](#blocks-in-the-config-file) around a quoted or escaped value, `text` is the decoded value. |
+| `disabled`  | The validators that the block asks for, but the settings turn off. They have no entry in `checks`.                                                                                                                                                                                     |
+| `file`      | The block's file.                                                                                                                                                                                                                                                                      |
+| `with_diff` | Whether `--diff` was given. Without it, no block counts as changed, so `affects` can't fire.                                                                                                                                                                                           |
+
+### What Each Validator Shows
+
+A trace stops where its validator stops, such as at the first line out of order. A `line` is a line of the block's
+file, and `text` is that line trimmed, as the validator compares it. A key that holds what a violation reports has the
+name the violation's `data` gives it, such as `reason`.
+
+| Validator      | What it shows                                                                                                                                                                                                                                                                                                                                                                          |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `same-as`      | `records`: each match of `same-as-pattern` in the block, with its `line`, the text the regex matched (`match`), and each named group after `same-as-format` (`groups`). `targets`: the `records` of each target, and the `reason` of its violation, or `null` when the two agree. `paths`: with `same-as-paths`, the `glob`, the paths it `matched`, their `records` and the `reason`. |
+| `keep-sorted`  | `lines`: each line read, with the `value` it compares, or `null` when `keep-sorted-pattern` skips the line. `format` and `order`.                                                                                                                                                                                                                                                      |
+| `keep-unique`  | `lines`, as for `keep-sorted`. A repeated value has `duplicate_of`: the line where it first appeared.                                                                                                                                                                                                                                                                                  |
+| `line-pattern` | `lines`: each line read, with the text `line-pattern` matched (`match`). A line that fails has `fails`: the check it fails. `forbidden_match` is the text `line-pattern-forbidden` found.                                                                                                                                                                                              |
+| `line-count`   | `lines`, as for `keep-sorted`. A line counts when its `value` isn't `null`. The number of lines counted (`actual`), and the rule (`op` and `expected`).                                                                                                                                                                                                                                |
+| `affects`      | Whether the diff changed the block (`block_changed`). For each target: whether the diff `changed` it, or the `reason` it doesn't resolve.                                                                                                                                                                                                                                              |
+| `check-lua`    | The `content` and the `affects` the script got, and the message it returned (`lua_error`), or `null` when it passed. `affects` is `ctx.affects` without the content of each target.                                                                                                                                                                                                    |
+| `check-ai`     | The `model`, the `prompt` sent and the `response`. Both are `null` when `check-ai-pattern` matched nothing, so no request was sent.                                                                                                                                                                                                                                                    |
+
 ## Run Reports
 
 By default `blockwatch` prints nothing when a run succeeds. That makes a check that passed look exactly like a check

blockwatch_cli-0.14.2/docs/validators/line-count.md

@@ -0,0 +1,48 @@
+# `line-count`
+
+Constrains how many lines a block may contain. Flags unbounded growth in a public API surface, or pins a switch to the
+size of the enum it maps.
+
+## Syntax
+
+| Attribute            | Value                                      | Default                  |
+|----------------------|--------------------------------------------|--------------------------|
+| `line-count`         | `<N`, `<=N`, `==N`, `>=N`, `>N`            | —                        |
+| `line-count-pattern` | regex; a line counts when it gives a value | every line that has text |
+
+## Example
+
+```python
+# <block line-count="<=5">
+"a",
+"b",
+"c"
+# </block>
+```
+
+## Counting only some lines
+
+`line-count-pattern` counts only the lines it matches:
+
+```python
+# <block line-count="<=2" line-count-pattern='^"\w+",$'>
+"a",
+# a comment
+"b",
+# </block>
+```
+
+The block above counts 2: the comment line doesn't match.
+
+Lines that do not match are skipped, as are lines whose match is empty. So is a line that matches a branch without the
+`value` group: `^(?:none|(?P<value>\w+))$` skips the line `none`. The pattern runs on the trimmed line, so `^` and `$`
+match at the text, not at the indentation.
+
+## Notes
+
+- **Blank lines are not counted.** The block above counts 3.
+- A malformed comparator is a hard error, not a violation.
+
+---
+
+← [Validators](README.md) · [README](../../README.md)

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/setup.py

@@ -6,7 +6,7 @@ setup(
     name='blockwatch-pre-commit-placeholder',
     version='0.0.0',
     # <block name="blockwatch-cli-version" same-as-pattern="blockwatch-cli==(?P<value>\d+\.\d+\.\d+)">
-    install_requires=['blockwatch-cli==0.14.1'],
+    install_requires=['blockwatch-cli==0.14.2'],
     # </block>
     # Without it, setuptools takes the directories under src/ for Python packages.
     packages=[],

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/src/blocks.rs

@@ -184,6 +184,15 @@ impl Content {
         }
     }
 
+    /// Describes the content for JSON. `source` must be the text of the block's file.
+    pub(crate) fn listing<'a>(&'a self, source: &'a str) -> ContentListing<'a> {
+        ContentListing {
+            start: self.positions.start,
+            end: self.positions.end,
+            text: self.text(source),
+        }
+    }
+
     /// Returns the content's text. `source` must be the text of the block's file.
     pub(crate) fn text<'a>(&'a self, source: &'a str) -> &'a str {
         match &self.text {
@@ -424,6 +433,19 @@ pub(crate) struct BlockListing<'a> {
 }
 // </block>
 
+/// The content of a block, as it is written in JSON: its text, and where the block's file writes
+/// it.
+#[derive(Serialize, Debug)]
+pub(crate) struct ContentListing<'a> {
+    /// The position of the content's first character.
+    start: Position,
+    /// The first position after the content.
+    end: Position,
+    /// The text the validators read. For a virtual block around a quoted or escaped value, it is
+    /// the decoded value.
+    text: &'a str,
+}
+
 impl<'a> From<&'a BlockWithContext> for BlockListing<'a> {
     /// Describes the block, with no `checks`.
     fn from(block_with_context: &'a BlockWithContext) -> Self {
@@ -461,6 +483,7 @@ const RECOGNIZED_ATTRIBUTES: &[&str] = &[
     "keep-sorted-pattern",
     "keep-unique",
     "line-count",
+    "line-count-pattern",
     "line-pattern",
     "line-pattern-forbidden",
     "name",

{blockwatch_cli-0.14.1 → blockwatch_cli-0.14.2}/src/cli.rs

@@ -1,9 +1,10 @@
-//! The whole run: reads the flags and the input, runs the validators or `list`, and writes the
-//! output.
+//! The whole run: reads the flags and the input, runs the validators, `list` or `explain`, and
+//! writes the output.
 
-use crate::blocks::BlockSeverity;
+use crate::blocks::{BlockAddress, BlockSeverity};
 use crate::config;
 use crate::diff_parser::{self, DiffChanges};
+use crate::explain::Explanation;
 use crate::flags;
 use crate::fs::FileSystem;
 use crate::language_parsers;
@@ -12,7 +13,7 @@ use crate::repo_path::RepoPath;
 use crate::report;
 use crate::sarif;
 use crate::scan;
-use crate::settings::Settings;
+use crate::settings::{BlockSelection, Settings};
 use crate::validators;
 use crate::validators::Violation;
 use crate::violation_address::ViolationAddress;
@@ -27,7 +28,8 @@ use std::sync::Arc;
 use std::{env, fs};
 
 /// Runs the program with the command-line flags of the process: validates the blocks, lists them
-/// with the `list` subcommand, or prints the agent skill with the `skill` subcommand.
+/// with the `list` subcommand, checks one block with the `explain` subcommand, or prints the agent
+/// skill with the `skill` subcommand.
 ///
 /// Returns the exit code of the process:
 /// - `0` when no violation fails the run.
@@ -41,6 +43,7 @@ pub fn run() -> ExitCode {
     let result = args.validate().and_then(|()| match &args.command {
         Some(flags::Subcommand::List { .. }) => run_list(&args).map(|()| ExitCode::SUCCESS),
         Some(flags::Subcommand::Skill) => run_skill().map(|()| ExitCode::SUCCESS),
+        Some(flags::Subcommand::Explain { address }) => run_explain(&args, address),
         None => run_validators(&args),
     });
     result.unwrap_or_else(|error| {
@@ -65,6 +68,47 @@ fn run_skill() -> anyhow::Result<()> {
     write_line(std::io::stdout(), skill.trim_end())
 }
 
+/// Runs the `explain` subcommand: checks the one block that `address` selects, writes what its
+/// validators saw to stdout as JSON, and writes its violations to stderr.
+///
+/// Returns the exit code of a validation run: 1 when a violation of error severity is found, and 0
+/// otherwise.
+fn run_explain(args: &flags::Args, address: &BlockAddress) -> anyhow::Result<ExitCode> {
+    let Prepared {
+        file_system,
+        settings,
+        mut context,
+        ..
+    } = prepare(args)?;
+    // The address picks the block, so the config's `only-blocks` and `skip-blocks` play no part.
+    context.apply_block_selection(
+        &BlockSelection::Only(vec![address.clone()]),
+        file_system.as_ref(),
+    )?;
+    let (sync_validators, async_validators) = validators::detect_validators(
+        &context,
+        validators::Validator::detect,
+        settings.validator_selection(),
+        &file_system,
+    )?;
+    context.request_traces();
+    let context = Arc::new(context);
+    let log = validators::run(Arc::clone(&context), sync_validators, async_validators)?;
+
+    // Violations are what the run is for, so they are written first, as in `run_validators`. A
+    // failure to write the explanation then can't discard them.
+    let has_error_severity = process_violations(&log.violations, flags::OutputFormat::Json)?;
+    write_json(
+        std::io::stdout(),
+        &Explanation::new(&context, &settings, &log, args.diff),
+    )?;
+    Ok(if has_error_severity {
+        ExitCode::from(1)
+    } else {
+        ExitCode::SUCCESS
+    })
+}
+
 /// Runs the `list` subcommand: parses every block in scope and writes a JSON report to stdout.
 fn run_list(args: &flags::Args) -> anyhow::Result<()> {
     let Prepared { context, .. } = prepare(args)?;

blockwatch_cli-0.14.2/src/explain.rs

@@ -0,0 +1,69 @@
+//! The output of the `explain` subcommand.
+
+use crate::blocks::{BlockListing, ContentListing};
+use crate::repo_path::RepoPath;
+use crate::settings::Settings;
+use crate::validators::{ValidationContext, ValidationLog, Validator, ValidatorTrace};
+use serde::Serialize;
+use std::collections::{BTreeMap, BTreeSet};
+use strum::IntoEnumIterator;
+
+/// What `explain` writes to stdout: one block, the content its validators read, what they saw, and
+/// how the settings treat it.
+///
+/// The fields are declared in alphabetical order, so the keys come out sorted.
+#[derive(Serialize, Debug)]
+pub(crate) struct Explanation<'a> {
+    // <block name="explanation" affects="docs/cli.md:explain-output-example">
+    /// The block, as `list` writes it.
+    block: BlockListing<'a>,
+    /// What each validator saw in the block, by validator.
+    checks: BTreeMap<Validator, &'a ValidatorTrace>,
+    content: ContentListing<'a>,
+    /// The validators that the block's attributes ask for, but the settings turn off.
+    disabled: BTreeSet<Validator>,
+    file: &'a RepoPath,
+    /// Whether the run was given a diff. Without one, no block counts as changed.
+    with_diff: bool,
+    // </block>
+}
+
+impl<'a> Explanation<'a> {
+    /// Describes the one block that `context` keeps, as `settings` treat it, with the traces that
+    /// `log` holds for it. `with_diff` is whether the run was given a diff.
+    ///
+    /// # Panics
+    /// Panics if `context` doesn't keep exactly one block.
+    pub(crate) fn new(
+        context: &'a ValidationContext,
+        settings: &Settings,
+        log: &'a ValidationLog,
+        with_diff: bool,
+    ) -> Self {
+        assert_eq!(context.blocks().len(), 1, "the context keeps one file");
+        let (file, file_blocks) = context.blocks().iter().next().expect("one file");
+        let [block_with_context] = file_blocks.blocks_with_context.as_slice() else {
+            panic!("the context keeps one block");
+        };
+        let block = &block_with_context.block;
+        Self {
+            block: BlockListing::from(block_with_context),
+            checks: log
+                .traces
+                .get(&(file.clone(), block.key()))
+                .into_iter()
+                .flatten()
+                .map(|(validator, trace)| (*validator, trace))
+                .collect(),
+            content: block.content.listing(&file_blocks.file_content),
+            disabled: Validator::iter()
+                .filter(|validator| {
+                    block.attributes.contains_key(validator.as_str())
+                        && !settings.validator_selection().includes(*validator)
+                })
+                .collect(),
+            file,
+            with_diff,
+        }
+    }
+}