0.4.0: Add match clustering

1 files changed, 20 insertions, 9 deletions

diff --git a/README.md b/README.md
index 4d1ffbc..f3d6cc9 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,8 @@ previous run (tracked per-file, per-inode) and then exits.
 - INI-style configuration (`pylogsentinel.conf`).
 - Multiple named log sets (e.g. [logs.default], [logs.errors]) with per-set discovery via static paths or shell command
 - Per-rule regular expressions with optional flags (`/pattern/i` style).
-- Per-rule or actions executed as shell commands with rich contextual environment variables.
+- Per-rule actions executed as shell commands with rich contextual environment variables.
+- Intelligent match clustering: nearby matches for the same rule are grouped into a single event to avoid redundant alerts.
 - Reliable state tracking via inode-based files (`<inode>` in `state_dir`).
 - Safe handling of truncation & rotation (offset reset if file shrinks).
 - Strict lock file (`LOCK`) prevents concurrent overlapping runs.
@@ -128,14 +129,16 @@ Each action defines a shell `cmd` executed when a matching rule triggers. The sp
 
 Environment variables available to the command:
 
-| Variable           | Description                                                            |
-| ------------------ | ---------------------------------------------------------------------- |
-| `RULE_ID`          | The rule identifier (e.g. `error`).                                    |
-| `RULE_PATTERN`     | The normalized pattern string (e.g. `/error/i`).                       |
-| `RULE_DESCRIPTION` | Description text or placeholder string if not provided.                |
-| `FILE`             | Absolute path of the log file where the match occurred.                |
-| `LINE`             | 1-based absolute line number within the file at time of scan.          |
-| `CONTEXT`          | Concatenated lines around the match (default radius 2 before & after). |
+| Variable           | Description                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `RULE_ID`          | The rule identifier (e.g. `error`).                                                                  |
+| `RULE_PATTERN`     | The normalized pattern string (e.g. `/error/i`).                                                     |
+| `RULE_DESCRIPTION` | Description text or placeholder string if not provided.                                              |
+| `FILE`             | Absolute path of the log file where the match occurred.                                              |
+| `LINE`             | 1-based absolute line number of the first match in the cluster.                                      |
+| `CONTEXT`          | Contiguous block of lines spanning the cluster with surrounding context (default radius 5).           |
+| `MATCH_COUNT`      | Number of matching lines in the cluster (e.g. `1` for a single match, `3` for three grouped matches). |
+| `MATCHED_LINES`    | Comma-separated 1-based line numbers of all matches in the cluster (e.g. `42` or `42,44,47`).        |
 
 Your `cmd` can reference these with typical shell expansion, for example:
 
@@ -144,6 +147,14 @@ Your `cmd` can reference these with typical shell expansion, for example:
 cmd = printf "%s\n%s\n" "$RULE_DESCRIPTION" "$CONTEXT" | mail -s "Alert $RULE_ID: $FILE:$LINE" ops@example.com
 ```
 
+### Match Clustering
+
+When multiple lines match the same rule within a short span, they are grouped into a single cluster rather than triggering separate actions for each match. This avoids redundant alerts for cascading errors.
+
+Two matches are merged into the same cluster if the number of non-matching lines between them is at most the context radius (default 5). The cluster's context block spans from `context_radius` lines before the first match to `context_radius` lines after the last match — one contiguous block including any non-matching lines in between.
+
+Example with `context_radius = 5`: if errors appear on lines 10, 13, and 16 of a file, they form a single cluster (gaps of 2 and 2, both ≤ 5). The action fires once with `CONTEXT` covering lines 5–21, `MATCH_COUNT=3`, and `MATCHED_LINES=10,13,16`.
+
 ## State Tracking
 
 For each processed file: