amlint 0.1.0__tar.gz

amlint-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: amlint
+Version: 0.1.0
+Summary: Semantic linter for Prometheus Alertmanager configs
+Author: danikdanik2013
+License: MIT
+Project-URL: Homepage, https://github.com/danikdanik2013/amlint
+Project-URL: Repository, https://github.com/danikdanik2013/amlint
+Project-URL: Bug Tracker, https://github.com/danikdanik2013/amlint/issues
+Keywords: alertmanager,prometheus,linter,devops,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=5.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# amlint
+
+Semantic linter for Prometheus Alertmanager configs.
+
+`amtool check-config` validates syntax. **amlint validates semantics:**
+will alerts actually reach a receiver, does the inhibition rule do anything,
+are there unreachable routing branches? These are the bugs that burn teams —
+config is valid, alerts silently vanish.
+
+## Why
+
+Alertmanager configs are YAML routing trees with inhibition rules and receivers.
+The most painful mistakes are syntactically valid:
+
+- route references a receiver that doesn't exist → **alerts are dropped**
+- inhibition without `equal` → silences unrelated alerts, you think it's quiet, there's actually a fire
+- catch-all branch before specific ones → specific branches **are unreachable**
+- `match_re` that doesn't compile
+- `group_by` that doesn't behave the way you think
+
+`amtool` won't catch any of this. amlint will.
+
+## Install
+
+```bash
+pip install pyyaml
+pip install -e .
+```
+
+## Usage
+
+```bash
+amlint check alertmanager.yml
+amlint check alertmanager.yml --strict   # WARN also exits non-zero
+amlint check alertmanager.yml --format json
+```
+
+Example output:
+
+```
+  ERROR  Route references receiver 'pager-team' which is not defined in receivers. Alerts matched here will be dropped.
+  ↳ route.routes[1]  [undefined-receiver]
+
+  WARN   Catch-all route (no matchers) with continue:false will intercept all alerts — 2 subsequent sibling(s) are unreachable.
+  ↳ route.routes[0]  [unreachable-route]
+
+  2 error · 3 warn · 1 info
+```
+
+Exit code `1` on ERROR — ready for CI. `--strict` makes WARN block too.
+
+## CI example
+
+```yaml
+# .github/workflows/lint.yml
+- name: Lint Alertmanager config
+  run: amlint check alertmanager.yml --strict
+```
+
+## Checks
+
+| code | level | what it catches |
+|------|-------|-----------------|
+| `undefined-receiver` | error | route references a receiver that doesn't exist |
+| `bad-regex` | error | `match_re` pattern fails to compile |
+| `no-root-route` | error | no root `route` defined |
+| `inhibit-no-equal` | warn | inhibition without `equal` silences too broadly |
+| `unreachable-route` | warn | catch-all hides subsequent sibling routes |
+| `groupby-ellipsis` | warn | `...` mixed with explicit labels in `group_by` |
+| `inhibit-same-match` | info | source and target match the same label value |
+| `unused-receiver` | info | receiver defined but not used in any route |
+
+## Tests
+
+```bash
+python3 -m pytest test_linter.py -v
+```
+
+## License
+
+MIT

amlint-0.1.0/README.md

@@ -0,0 +1,81 @@
+# amlint
+
+Semantic linter for Prometheus Alertmanager configs.
+
+`amtool check-config` validates syntax. **amlint validates semantics:**
+will alerts actually reach a receiver, does the inhibition rule do anything,
+are there unreachable routing branches? These are the bugs that burn teams —
+config is valid, alerts silently vanish.
+
+## Why
+
+Alertmanager configs are YAML routing trees with inhibition rules and receivers.
+The most painful mistakes are syntactically valid:
+
+- route references a receiver that doesn't exist → **alerts are dropped**
+- inhibition without `equal` → silences unrelated alerts, you think it's quiet, there's actually a fire
+- catch-all branch before specific ones → specific branches **are unreachable**
+- `match_re` that doesn't compile
+- `group_by` that doesn't behave the way you think
+
+`amtool` won't catch any of this. amlint will.
+
+## Install
+
+```bash
+pip install pyyaml
+pip install -e .
+```
+
+## Usage
+
+```bash
+amlint check alertmanager.yml
+amlint check alertmanager.yml --strict   # WARN also exits non-zero
+amlint check alertmanager.yml --format json
+```
+
+Example output:
+
+```
+  ERROR  Route references receiver 'pager-team' which is not defined in receivers. Alerts matched here will be dropped.
+  ↳ route.routes[1]  [undefined-receiver]
+
+  WARN   Catch-all route (no matchers) with continue:false will intercept all alerts — 2 subsequent sibling(s) are unreachable.
+  ↳ route.routes[0]  [unreachable-route]
+
+  2 error · 3 warn · 1 info
+```
+
+Exit code `1` on ERROR — ready for CI. `--strict` makes WARN block too.
+
+## CI example
+
+```yaml
+# .github/workflows/lint.yml
+- name: Lint Alertmanager config
+  run: amlint check alertmanager.yml --strict
+```
+
+## Checks
+
+| code | level | what it catches |
+|------|-------|-----------------|
+| `undefined-receiver` | error | route references a receiver that doesn't exist |
+| `bad-regex` | error | `match_re` pattern fails to compile |
+| `no-root-route` | error | no root `route` defined |
+| `inhibit-no-equal` | warn | inhibition without `equal` silences too broadly |
+| `unreachable-route` | warn | catch-all hides subsequent sibling routes |
+| `groupby-ellipsis` | warn | `...` mixed with explicit labels in `group_by` |
+| `inhibit-same-match` | info | source and target match the same label value |
+| `unused-receiver` | info | receiver defined but not used in any route |
+
+## Tests
+
+```bash
+python3 -m pytest test_linter.py -v
+```
+
+## License
+
+MIT

amlint-0.1.0/amlint/cli.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""amlint CLI."""
+
+import argparse
+import json
+import os
+import sys
+
+try:
+    import yaml
+except ImportError:
+    print("pyyaml is required:  pip install pyyaml", file=sys.stderr)
+    sys.exit(2)
+
+from .linter import lint, ERROR, WARN, INFO
+
+_COLOR = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def _c(code, s):
+    return f"\033[{code}m{s}\033[0m" if _COLOR else s
+
+
+BADGE = {
+    ERROR: _c("31", "ERROR"),
+    WARN: _c("33", "WARN "),
+    INFO: _c("36", "INFO "),
+}
+
+
+def load(path):
+    if not os.path.exists(path):
+        print(f"File not found: {path}", file=sys.stderr)
+        sys.exit(2)
+    with open(path) as f:
+        try:
+            return yaml.safe_load(f) or {}
+        except yaml.YAMLError as e:
+            print(f"Failed to parse YAML: {e}", file=sys.stderr)
+            sys.exit(2)
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(
+        prog="amlint",
+        description="Semantic linter for Alertmanager configs. Catches what amtool misses.",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+    pc = sub.add_parser("check", help="validate a config file")
+    pc.add_argument("file", help="path to alertmanager.yml")
+    pc.add_argument("--format", choices=["text", "json"], default="text")
+    pc.add_argument("--strict", action="store_true", help="exit non-zero on WARN as well")
+
+    args = p.parse_args(argv)
+    cfg = load(args.file)
+    findings = lint(cfg)
+
+    if args.format == "json":
+        print(json.dumps(
+            [{"level": f.level, "code": f.code, "message": f.msg, "where": f.where} for f in findings],
+            ensure_ascii=False, indent=2,
+        ))
+    else:
+        if not findings:
+            print(_c("32", "  \u2713 Проблем не знайдено.\n"))
+        else:
+            print()
+            for f in findings:
+                loc = _c("2", f"  {f.where}") if f.where else ""
+                print(f"  {BADGE[f.level]}  {f.msg}")
+                if loc:
+                    arrow = "\u21b3 "
+                    print(f"  {_c('2', arrow + f.where)}  {_c('2', '[' + f.code + ']')}")
+                print()
+            errs = sum(1 for f in findings if f.level == ERROR)
+            warns = sum(1 for f in findings if f.level == WARN)
+            infos = sum(1 for f in findings if f.level == INFO)
+            print(f"  {errs} error \u00b7 {warns} warn \u00b7 {infos} info\n")
+
+    has_err = any(f.level == ERROR for f in findings)
+    has_warn = any(f.level == WARN for f in findings)
+    if has_err or (args.strict and has_warn):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

amlint-0.1.0/amlint/linter.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""
+amlint - semantic linter for Prometheus Alertmanager configs.
+
+amtool check-config validates syntax. amlint validates SEMANTICS:
+whether alerts will actually be delivered, whether inhibition rules
+fire correctly, whether routing branches are reachable.
+
+Usage:
+    amlint check alertmanager.yml
+    amlint check alertmanager.yml --format json
+"""
+
+import re
+import sys
+
+
+ERROR = "error"      # config is broken: alerts will be lost
+WARN = "warn"        # almost certainly not what you intended
+INFO = "info"        # suspicious, worth a look
+
+
+class Finding:
+    __slots__ = ("level", "code", "msg", "where")
+
+    def __init__(self, level, code, msg, where=""):
+        self.level = level
+        self.code = code
+        self.msg = msg
+        self.where = where
+
+
+def _defined_receivers(cfg):
+    return {r.get("name") for r in cfg.get("receivers", []) if r.get("name")}
+
+
+def _walk_routes(node, path="route"):
+    """Yields (route_node, path) for the root and all nested routes."""
+    yield node, path
+    for i, child in enumerate(node.get("routes", []) or []):
+        yield from _walk_routes(child, f"{path}.routes[{i}]")
+
+
+# CHECK 1: route references a receiver that doesn't exist
+def check_undefined_receivers(cfg):
+    out = []
+    defined = _defined_receivers(cfg)
+    route = cfg.get("route")
+    if not route:
+        out.append(Finding(ERROR, "no-root-route", "No root 'route' defined.", "route"))
+        return out
+    for node, path in _walk_routes(route):
+        rcv = node.get("receiver")
+        if rcv and rcv not in defined:
+            out.append(Finding(
+                ERROR, "undefined-receiver",
+                f"Route references receiver '{rcv}' which is not defined in receivers. "
+                f"Alerts matched here will be dropped.",
+                path,
+            ))
+    return out
+
+
+# CHECK 2: receiver is defined but never used in any route
+def check_unused_receivers(cfg):
+    out = []
+    defined = _defined_receivers(cfg)
+    used = set()
+    route = cfg.get("route")
+    if route:
+        for node, _ in _walk_routes(route):
+            if node.get("receiver"):
+                used.add(node["receiver"])
+    for name in defined - used:
+        out.append(Finding(
+            INFO, "unused-receiver",
+            f"Receiver '{name}' is defined but not referenced by any route.",
+            "receivers",
+        ))
+    return out
+
+
+# CHECK 3: inhibition rule that can never fire
+def check_dead_inhibitions(cfg):
+    """
+    An inhibition rule silences target alerts when a source alert fires,
+    but only when labels in 'equal' match. Missing 'equal' means the rule
+    will silence across unrelated alerts — almost never intentional.
+    """
+    out = []
+    for i, rule in enumerate(cfg.get("inhibit_rules", []) or []):
+        where = f"inhibit_rules[{i}]"
+        src = {**(rule.get("source_match") or {}), **(rule.get("source_matchers_map") or {})}
+        tgt = {**(rule.get("target_match") or {}), **(rule.get("target_matchers_map") or {})}
+        equal = rule.get("equal", []) or []
+
+        if not equal and (src or tgt):
+            out.append(Finding(
+                WARN, "inhibit-no-equal",
+                "Inhibition rule has no 'equal' field: it will silence alerts across "
+                "unrelated firing sources (no shared label binding them). Almost always a mistake.",
+                where,
+            ))
+
+        for key in set(src) & set(tgt):
+            if src[key] == tgt[key]:
+                out.append(Finding(
+                    INFO, "inhibit-same-match",
+                    f"source_match and target_match both have '{key}={src[key]}'. "
+                    f"Check that the rule is not silencing its own source alert.",
+                    where,
+                ))
+    return out
+
+
+# CHECK 4: match_re / matchers: patterns that fail to compile
+_MATCHER_RE = re.compile(r'^([^=!~]+)(=~|!~)(.+)$')
+
+
+def _regex_patterns(node):
+    """Yield (label, pattern) for all regex matchers in a route node."""
+    for label, pattern in (node.get("match_re") or {}).items():
+        yield label, pattern
+    for m in node.get("matchers") or []:
+        hit = _MATCHER_RE.match(str(m))
+        if hit:
+            yield hit.group(1).strip(), hit.group(3)
+
+
+def check_bad_regex(cfg):
+    out = []
+    route = cfg.get("route")
+    if not route:
+        return out
+    for node, path in _walk_routes(route):
+        for label, pattern in _regex_patterns(node):
+            try:
+                re.compile(pattern)
+            except re.error as e:
+                out.append(Finding(
+                    ERROR, "bad-regex",
+                    f"Regex for '{label}' does not compile: {e}",
+                    path,
+                ))
+    return out
+
+
+# CHECK 5: unreachable sibling routes behind a catch-all
+def check_unreachable_routes(cfg):
+    """
+    Alertmanager evaluates sibling routes in order. If a route matches
+    and continue is not true, subsequent siblings won't receive the alert.
+    A catch-all route (no matchers) with continue:false makes all following
+    siblings unreachable.
+    """
+    out = []
+    route = cfg.get("route")
+    if not route:
+        return out
+
+    def scan_siblings(routes, parent_path):
+        for i, child in enumerate(routes or []):
+            path = f"{parent_path}.routes[{i}]"
+            has_matcher = bool(
+                child.get("match") or child.get("match_re") or child.get("matchers")
+            )
+            is_catch_all = not has_matcher
+            cont = child.get("continue", False)
+            if is_catch_all and not cont and i < len(routes) - 1:
+                out.append(Finding(
+                    WARN, "unreachable-route",
+                    f"Catch-all route (no matchers) with continue:false will intercept all alerts "
+                    f"— {len(routes) - i - 1} subsequent sibling(s) are unreachable.",
+                    path,
+                ))
+            scan_siblings(child.get("routes"), path)
+
+    scan_siblings(route.get("routes"), "route")
+    return out
+
+
+# CHECK 6: group_by with '...' mixed with explicit labels
+def check_groupby(cfg):
+    out = []
+    route = cfg.get("route")
+    if not route:
+        return out
+    for node, path in _walk_routes(route):
+        gb = node.get("group_by") or []
+        if "..." in gb and len(gb) > 1:
+            out.append(Finding(
+                WARN, "groupby-ellipsis",
+                "group_by contains '...' alongside other labels — '...' already groups by all "
+                "labels, making the others redundant. Remove either '...' or the explicit labels.",
+                path,
+            ))
+    return out
+
+
+ALL_CHECKS = [
+    check_undefined_receivers,
+    check_unused_receivers,
+    check_dead_inhibitions,
+    check_bad_regex,
+    check_unreachable_routes,
+    check_groupby,
+]
+
+
+def lint(cfg):
+    findings = []
+    for check in ALL_CHECKS:
+        findings.extend(check(cfg))
+    order = {ERROR: 0, WARN: 1, INFO: 2}
+    findings.sort(key=lambda f: order[f.level])
+    return findings

amlint-0.1.0/amlint.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: amlint
+Version: 0.1.0
+Summary: Semantic linter for Prometheus Alertmanager configs
+Author: danikdanik2013
+License: MIT
+Project-URL: Homepage, https://github.com/danikdanik2013/amlint
+Project-URL: Repository, https://github.com/danikdanik2013/amlint
+Project-URL: Bug Tracker, https://github.com/danikdanik2013/amlint/issues
+Keywords: alertmanager,prometheus,linter,devops,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=5.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# amlint
+
+Semantic linter for Prometheus Alertmanager configs.
+
+`amtool check-config` validates syntax. **amlint validates semantics:**
+will alerts actually reach a receiver, does the inhibition rule do anything,
+are there unreachable routing branches? These are the bugs that burn teams —
+config is valid, alerts silently vanish.
+
+## Why
+
+Alertmanager configs are YAML routing trees with inhibition rules and receivers.
+The most painful mistakes are syntactically valid:
+
+- route references a receiver that doesn't exist → **alerts are dropped**
+- inhibition without `equal` → silences unrelated alerts, you think it's quiet, there's actually a fire
+- catch-all branch before specific ones → specific branches **are unreachable**
+- `match_re` that doesn't compile
+- `group_by` that doesn't behave the way you think
+
+`amtool` won't catch any of this. amlint will.
+
+## Install
+
+```bash
+pip install pyyaml
+pip install -e .
+```
+
+## Usage
+
+```bash
+amlint check alertmanager.yml
+amlint check alertmanager.yml --strict   # WARN also exits non-zero
+amlint check alertmanager.yml --format json
+```
+
+Example output:
+
+```
+  ERROR  Route references receiver 'pager-team' which is not defined in receivers. Alerts matched here will be dropped.
+  ↳ route.routes[1]  [undefined-receiver]
+
+  WARN   Catch-all route (no matchers) with continue:false will intercept all alerts — 2 subsequent sibling(s) are unreachable.
+  ↳ route.routes[0]  [unreachable-route]
+
+  2 error · 3 warn · 1 info
+```
+
+Exit code `1` on ERROR — ready for CI. `--strict` makes WARN block too.
+
+## CI example
+
+```yaml
+# .github/workflows/lint.yml
+- name: Lint Alertmanager config
+  run: amlint check alertmanager.yml --strict
+```
+
+## Checks
+
+| code | level | what it catches |
+|------|-------|-----------------|
+| `undefined-receiver` | error | route references a receiver that doesn't exist |
+| `bad-regex` | error | `match_re` pattern fails to compile |
+| `no-root-route` | error | no root `route` defined |
+| `inhibit-no-equal` | warn | inhibition without `equal` silences too broadly |
+| `unreachable-route` | warn | catch-all hides subsequent sibling routes |
+| `groupby-ellipsis` | warn | `...` mixed with explicit labels in `group_by` |
+| `inhibit-same-match` | info | source and target match the same label value |
+| `unused-receiver` | info | receiver defined but not used in any route |
+
+## Tests
+
+```bash
+python3 -m pytest test_linter.py -v
+```
+
+## License
+
+MIT

amlint-0.1.0/amlint.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+amlint/__init__.py
+amlint/cli.py
+amlint/linter.py
+amlint.egg-info/PKG-INFO
+amlint.egg-info/SOURCES.txt
+amlint.egg-info/dependency_links.txt
+amlint.egg-info/entry_points.txt
+amlint.egg-info/requires.txt
+amlint.egg-info/top_level.txt

amlint-0.1.0/amlint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

amlint-0.1.0/amlint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+amlint = amlint.cli:main

amlint-0.1.0/amlint.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyyaml>=5.1
+
+[dev]
+pytest>=7

amlint-0.1.0/amlint.egg-info/top_level.txt

@@ -0,0 +1 @@
+amlint

amlint-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "amlint"
+version = "0.1.0"
+description = "Semantic linter for Prometheus Alertmanager configs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "danikdanik2013"}]
+keywords = ["alertmanager", "prometheus", "linter", "devops", "monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = ["pyyaml>=5.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/danikdanik2013/amlint"
+Repository = "https://github.com/danikdanik2013/amlint"
+"Bug Tracker" = "https://github.com/danikdanik2013/amlint/issues"
+
+[project.scripts]
+amlint = "amlint.cli:main"
+
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"

amlint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+