blockwatch 0.5.0

Language agnostic linter that keeps your code and documentation in sync and valid
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# `affects`

Forces linked blocks to be edited together. If you change this block and leave the block it points at untouched, the run
fails.

## Syntax

| Attribute | Value                                     | Default |
|-----------|-------------------------------------------|---------|
| `affects` | `file:name`, or `:name` for the same file | —       |

Separate multiple targets with commas:

```rust
// <block affects="README.md:supported-langs, docs/api.md:languages">
```

## Example

**src/lib.rs**:

```rust
// <block affects="README.html:supported-langs">
pub enum Language {
    Rust,
    Python,
}
// </block>
```

**README.html**:

```html
<!-- <block name="supported-langs"> -->
<ul>
    <li>Rust</li>
    <li>Python</li>
</ul>
<!-- </block> -->
```

Modify the enum and BlockWatch fails until you also touch `supported-langs` in `README.html`.

## Direction

`affects` is one-way. The example above catches "code changed, docs didn't" — but not the reverse. For two-way drift
detection, name both blocks and point each at the other:

```rust
// <block name="languages-code" affects="README.html:supported-langs">
```

```html
<!-- <block name="supported-langs" affects="src/lib.rs:languages-code"> -->
```

## Notes

- **The co-editing check needs a diff.** Without one every block counts as unmodified, so the "were both edited
  together" check reports nothing at all — not a pass, but no check. `blockwatch` on its own is therefore blind to it;
  run `git diff --patch | blockwatch --diff` to audit the whole tree with `affects` enforced, or add `--only-changed` to
  check just the changed blocks. On a run without a diff, `blockwatch --verbosity summary` prints a `needs --diff` count
  naming how many blocks were skipped for this reason; under a diff those rules can fire, so the count is not reported.
  Reference integrity (below) is checked either way. If you want a value comparison that also works on a bare full-tree
  run, use [`same-as`](same-as.md).
- **Co-editing, not agreement.** `affects` only checks that both sides were touched — it does not compare their
  contents. Touching the target with an unrelated edit satisfies it. When the two blocks should hold the same *value*, [
  `same-as`](same-as.md) is the stronger check.
- **Missing targets are violations.** A reference to a block `name` that does not exist (renamed or deleted) is reported
  as a violation, even without a diff. A reference to a target *file* that does not exist fails the run.
- **Targets are read, not reported.** Under `--only-changed`, a target the diff did not touch is still resolved and
  compared, but it does not appear in a `--verbosity` run report. See
  [Reports Under a Diff](../cli.md#reports-under-a-diff).
- **Globs do not narrow target resolution.** `blockwatch --diff --only-changed "src/**/*.rs"` still resolves a target
  living under `docs/`, so narrowing a run to one language does not report every rule that spans two of them as
  unsatisfied. An excluded target file is read to answer the reference and is never validated.
- Combining `affects` with [`check-lua`](check-lua.md) gives a script access to the affected blocks' contents through
  `ctx.affects`, which is a way to compare them without file IO.

---

← [Validators](README.md) · [README](../../README.md)