chore(ci): fail CI when defaults/main.yml drifts from argument_specs.yml

Adds scripts/check_argspecs.py — for every role that ships a
meta/argument_specs.yml, compare the set of top-level (non-underscored)
variables in defaults/main.yml against the options declared in the
spec. Any mismatch either way (var in defaults but not spec, option in
spec but no longer in defaults) exits non-zero with the offending names
and a pointer to scripts/gen_argspecs.py for regeneration.

Wired into test_linting.yml as the last step of the whole-collection
lint job (skipped for the per-role invocation so we do not run five
duplicate checks per PR).

Also promotes gen_argspecs.py from /tmp/ into scripts/ so the fix path
is self-contained, and uncomments elasticstack_cert_pass in defaults
(one commented line the initial argument_specs PR left as spec-only
drift — flipping to elasticstack_cert_pass: "" matches the actual
role behaviour and clears the check).

Author: Oddly

.github/workflows/test_linting.yml

@@ -84,3 +84,11 @@ jobs:
         env:
           ROLENAME: ${{ inputs.rolename }}
         if: ${{ inputs.rolename != '' }}
+
+      # Fails if a role's meta/argument_specs.yml is out of sync with its
+      # defaults/main.yml — catches "I added a var but forgot to update the
+      # spec" and its inverse. See scripts/gen_argspecs.py for regeneration.
+      - name: Check argument_specs drift.
+        run: |
+          python3 scripts/check_argspecs.py
+        if: ${{ inputs.rolename == '' }}

roles/elasticstack/defaults/main.yml

@@ -42,7 +42,7 @@ elasticstack_ca_pass: PleaseChangeMe
 #   logstash_tls_key_passphrase, and beats_tls_key_passphrase.
 #   Leave empty to use the per-role passphrases.
 # @end
-# elasticstack_cert_pass:
+elasticstack_cert_pass: ""
 # @var elasticstack_ca_validity_period:description: Validity period in days for the CA certificate
 elasticstack_ca_validity_period: 1095
 # === General Settings ===

scripts/check_argspecs.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Verify that every role's meta/argument_specs.yml lists the same variables
+its defaults/main.yml defines. Fails CI when the two drift.
+
+Runs across every role that has a meta/argument_specs.yml. Roles without
+one (e.g. `repos`, which uses variables from `elasticstack` instead) are
+skipped intentionally.
+
+Exit codes:
+  0  All roles in sync
+  1  At least one role has drift (details on stderr)
+  2  Usage / setup error
+
+The parser only looks at the top-level `varname: value` lines in
+defaults/main.yml. Internal-only vars (leading underscore) are ignored
+so vars/main.yml-style facts don't need arg-spec entries.
+"""
+import sys
+import re
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("check_argspecs: PyYAML is required (pip install pyyaml)", file=sys.stderr)
+    sys.exit(2)
+
+
+VAR_LINE = re.compile(r"^([A-Za-z][\w]*)\s*:")
+
+
+def defaults_vars(path):
+    """Top-level variable names in a defaults/main.yml, minus internal underscore vars."""
+    out = set()
+    with open(path) as f:
+        for line in f:
+            m = VAR_LINE.match(line)
+            if m:
+                name = m.group(1)
+                if not name.startswith("_"):
+                    out.add(name)
+    return out
+
+
+def argspec_options(path):
+    """Option names declared under any entry point (main + role-scoped
+    task-file entry points like node_maintenance_start / _end)."""
+    with open(path) as f:
+        spec = yaml.safe_load(f) or {}
+    out = set()
+    for entry in (spec.get("argument_specs") or {}).values():
+        for name in (entry.get("options") or {}).keys():
+            out.add(name)
+    return out
+
+
+def main():
+    repo = Path(__file__).resolve().parent.parent
+    roles = sorted(p for p in (repo / "roles").iterdir() if p.is_dir())
+    exit_code = 0
+
+    for role in roles:
+        defaults = role / "defaults" / "main.yml"
+        specs = role / "meta" / "argument_specs.yml"
+        if not specs.exists():
+            continue  # role opts out
+        if not defaults.exists():
+            print(
+                f"[{role.name}] has meta/argument_specs.yml but no defaults/main.yml",
+                file=sys.stderr,
+            )
+            exit_code = 1
+            continue
+
+        vars_ = defaults_vars(defaults)
+        opts = argspec_options(specs)
+        missing_in_spec = vars_ - opts
+        extra_in_spec = opts - vars_
+
+        if missing_in_spec or extra_in_spec:
+            exit_code = 1
+            print(f"\n[{role.name}] argument_specs drift:", file=sys.stderr)
+            for v in sorted(missing_in_spec):
+                print(f"  - in defaults but missing from spec: {v}", file=sys.stderr)
+            for v in sorted(extra_in_spec):
+                print(f"  - in spec but no longer in defaults: {v}", file=sys.stderr)
+        else:
+            print(f"[{role.name}] ok ({len(vars_)} vars)")
+
+    if exit_code:
+        print(
+            "\nFix by editing meta/argument_specs.yml or regenerating with "
+            "`scripts/gen_argspecs.py <role_path>`.",
+            file=sys.stderr,
+        )
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

scripts/gen_argspecs.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+Generate meta/argument_specs.yml for an Ansible role by parsing @var
+docblocks in defaults/main.yml.
+
+Usage:  gen_argspecs.py <role_path>
+Writes: <role_path>/meta/argument_specs.yml
+"""
+import sys
+import re
+import yaml
+from pathlib import Path
+
+
+def parse_defaults(path):
+    """Returns list of dicts: [{'name': str, 'description': str, 'default': any}]"""
+    with open(path) as f:
+        text = f.read()
+    lines = text.splitlines()
+    entries = []
+    i = 0
+    pending_desc = None
+    pending_var = None
+    while i < len(lines):
+        line = lines[i]
+
+        # Single-line @var: `# @var NAME:description: TEXT`
+        m = re.match(r"^# @var\s+([\w.]+):description:\s*(.*)$", line)
+        if m and not m.group(2).endswith('>'):
+            pending_var = m.group(1)
+            pending_desc = m.group(2).strip()
+            i += 1
+            continue
+
+        # Multi-line @var: `# @var NAME:description: >`  then lines until `# @end`
+        # OR the first non-comment line (some docblocks in this repo omit @end).
+        m = re.match(r"^# @var\s+([\w.]+):description:\s*>\s*$", line)
+        if m:
+            pending_var = m.group(1)
+            desc_lines = []
+            i += 1
+            while i < len(lines):
+                stripped = lines[i].strip()
+                if stripped.startswith("# @end"):
+                    i += 1
+                    break
+                if stripped.startswith("# @var"):
+                    # A new @var starts (typically an :example: sibling) —
+                    # description ends here, leave i pointing at that line.
+                    break
+                if not stripped.startswith("#"):
+                    # Docblock ended without @end — leave i pointing at
+                    # the value line and let the value-line branch handle it.
+                    break
+                desc_lines.append(lines[i].lstrip("# ").rstrip())
+                i += 1
+            pending_desc = " ".join(l for l in desc_lines if l).strip()
+            continue
+
+        # Also skip `# @var ...:example:` blocks
+        if re.match(r"^# @var\s+[\w.]+:example:", line):
+            # skip the example block similarly
+            if line.rstrip().endswith('>'):
+                i += 1
+                while i < len(lines) and not lines[i].strip().startswith("# @end"):
+                    i += 1
+                if i < len(lines):
+                    i += 1
+            else:
+                i += 1
+            continue
+
+        # Value line: NAME: VALUE (or NAME: on its own for multi-line YAML)
+        m = re.match(r"^(\w+):\s*(.*)$", line)
+        if m and pending_var == m.group(1):
+            varname = m.group(1)
+            # Try to YAML-parse the full block (may span lines for lists/dicts)
+            # Simple heuristic: take from here until next blank line or next @var
+            block_end = i + 1
+            while block_end < len(lines):
+                nxt = lines[block_end]
+                if (
+                    nxt.strip() == ""
+                    or nxt.startswith("# @var")
+                    or nxt.startswith("# ==")
+                ):
+                    break
+                block_end += 1
+            block_text = "\n".join(lines[i:block_end])
+            try:
+                parsed = yaml.safe_load(block_text)
+                if isinstance(parsed, dict) and varname in parsed:
+                    default_val = parsed[varname]
+                else:
+                    default_val = None
+            except Exception:
+                default_val = None
+            entries.append(
+                {"name": varname, "description": pending_desc or "", "default": default_val}
+            )
+            pending_var = None
+            pending_desc = None
+            i = block_end
+            continue
+
+        # Also handle: commented-out defaults (# varname:) — skip but record with unset default
+        m = re.match(r"^#\s*(\w+):\s*$", line)
+        if m and pending_var == m.group(1):
+            entries.append(
+                {"name": m.group(1), "description": pending_desc or "", "default": None}
+            )
+            pending_var = None
+            pending_desc = None
+            i += 1
+            continue
+
+        i += 1
+    return entries
+
+
+def infer_type(value):
+    if isinstance(value, bool):
+        return "bool"
+    if isinstance(value, int):
+        return "int"
+    if isinstance(value, float):
+        return "float"
+    if isinstance(value, list):
+        return "list"
+    if isinstance(value, dict):
+        return "dict"
+    if isinstance(value, str):
+        # Jinja-templated strings still get type str
+        return "str"
+    return "str"
+
+
+def build_argument_specs(role_name, entries, short_desc, long_desc):
+    options = {}
+    for e in entries:
+        opt = {"description": e["description"] or f"See defaults/main.yml for {e['name']}."}
+        if e["default"] is not None:
+            opt["type"] = infer_type(e["default"])
+            opt["default"] = e["default"]
+        else:
+            opt["type"] = "raw"
+        options[e["name"]] = opt
+    return {
+        "argument_specs": {
+            "main": {
+                "short_description": short_desc,
+                "description": long_desc,
+                "options": options,
+            }
+        }
+    }
+
+
+ROLE_METADATA = {
+    "elasticsearch": (
+        "Install, configure, and manage Elasticsearch",
+        "Handles cluster formation, TLS certificate management, security setup (users, passwords, HTTPS), rolling upgrades (8.x to 9.x), JVM tuning, and systemd service management.",
+    ),
+    "kibana": (
+        "Install, configure, and manage Kibana",
+        "Handles package install, TLS setup for the Kibana web UI, keystore-managed secrets, integration with an Elasticsearch backend, and systemd service management.",
+    ),
+    "logstash": (
+        "Install, configure, and manage Logstash",
+        "Handles package install, pipeline configuration, TLS certificate management for input/output, JVM tuning, and systemd service management.",
+    ),
+    "beats": (
+        "Install, configure, and manage Elastic Beats (filebeat, metricbeat, auditbeat)",
+        "Handles package install, ECS-schema output configuration to Elasticsearch or Logstash, TLS certificate distribution, and systemd service management per beat.",
+    ),
+    "elasticstack": (
+        "Shared defaults and CA management for the oddly.elasticstack collection",
+        "Provides collection-wide variables (inventory group names, ports, CA host, certificate settings) and the internal certificate authority workflow used by the elasticsearch, kibana, logstash, and beats roles.",
+    ),
+    "repos": (
+        "Manage Elastic package repositories",
+        "Installs the Elastic apt/yum repository configuration matching elasticstack_release and elasticstack_repo_base_url, keeping the elasticsearch/kibana/logstash/beats package installs pointed at the right major version.",
+    ),
+}
+
+
+def main():
+    role_path = Path(sys.argv[1]).resolve()
+    role_name = role_path.name
+    defaults = role_path / "defaults" / "main.yml"
+    if not defaults.exists():
+        print(f"no defaults/main.yml at {defaults}", file=sys.stderr)
+        sys.exit(1)
+
+    entries = parse_defaults(defaults)
+    short_desc, long_desc = ROLE_METADATA.get(
+        role_name, (f"Role {role_name}", f"Role {role_name}.")
+    )
+    spec = build_argument_specs(role_name, entries, short_desc, long_desc)
+
+    (role_path / "meta").mkdir(exist_ok=True)
+    outpath = role_path / "meta" / "argument_specs.yml"
+    with open(outpath, "w") as f:
+        f.write("---\n")
+        yaml.dump(spec, f, sort_keys=False, default_flow_style=False, width=120)
+    print(f"wrote {outpath} with {len(entries)} options")
+
+
+if __name__ == "__main__":
+    main()