ci: add python-based validation workflow for actions, shell, and python files (#274)

Signed-off-by: Ahmed Al-Nassif <mr.ahmed.nassif@gmail.com>

.github/scripts/validate_python.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+
+import ast
+import concurrent.futures
+import pathlib
+import sys
+
+EXCLUDE_DIRS = {".git", "venv", ".venv"}
+
+
+def find_python_files(root="."):
+    for path in pathlib.Path(root).rglob("*.py"):
+        if any(part in EXCLUDE_DIRS for part in path.parts):
+            continue
+        yield path
+
+
+def check_file(path):
+    try:
+        source = path.read_text(encoding="utf-8")
+        ast.parse(source, filename=str(path))
+        return path, None
+    except SyntaxError as error:
+        location = f"line {error.lineno}, col {error.offset}"
+        return path, f"{location}: {error.msg}"
+    except UnicodeDecodeError as error:
+        return path, f"encoding error: {error}"
+
+
+def main():
+    files = sorted(find_python_files())
+    if not files:
+        print("No Python files found.")
+        return 0
+
+    status = 0
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        results = executor.map(check_file, files)
+        for path, error in results:
+            if error:
+                print(f"Syntax error in: {path}")
+                print(f"  {error}")
+                status = 1
+
+    print(f"Checked {len(files)} Python file(s).")
+    return status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/validate_shell.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+
+import concurrent.futures
+import pathlib
+import subprocess
+import sys
+
+EXCLUDE_DIRS = {".git"}
+
+
+def find_shell_files(root="."):
+    for path in pathlib.Path(root).rglob("*.sh"):
+        if any(part in EXCLUDE_DIRS for part in path.parts):
+            continue
+        yield path
+
+
+def check_file(path):
+    result = subprocess.run(
+        ["bash", "-n", str(path)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return path, result.stderr.strip()
+    return path, None
+
+
+def main():
+    files = sorted(find_shell_files())
+    if not files:
+        print("No shell scripts found.")
+        return 0
+
+    status = 0
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        results = executor.map(check_file, files)
+        for path, error in results:
+            if error:
+                print(f"Syntax error in: {path}")
+                print(f"  {error}")
+                status = 1
+
+    print(f"Checked {len(files)} shell script(s).")
+    return status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/validate_workflows.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+
+import pathlib
+import sys
+
+import yaml
+
+WORKFLOW_DIR = pathlib.Path(".github/workflows")
+
+
+def find_workflow_files():
+    if not WORKFLOW_DIR.exists():
+        return []
+    return sorted(
+        list(WORKFLOW_DIR.glob("*.yml")) + list(WORKFLOW_DIR.glob("*.yaml"))
+    )
+
+
+def check_jobs(data):
+    errors = []
+    jobs = data.get("jobs")
+
+    if jobs is None:
+        errors.append("missing top-level 'jobs' key")
+        return errors
+
+    if not isinstance(jobs, dict) or not jobs:
+        errors.append("'jobs' must be a non-empty mapping")
+        return errors
+
+    for job_name, job in jobs.items():
+        if not isinstance(job, dict):
+            errors.append(f"job '{job_name}': must be a mapping")
+            continue
+
+        if "runs-on" not in job and "uses" not in job:
+            errors.append(f"job '{job_name}': missing 'runs-on' (or 'uses' for reusable workflows)")
+
+        steps = job.get("steps")
+        if steps is None:
+            if "uses" not in job:
+                errors.append(f"job '{job_name}': missing 'steps'")
+            continue
+
+        if not isinstance(steps, list):
+            errors.append(f"job '{job_name}': 'steps' must be a list")
+            continue
+
+        for index, step in enumerate(steps, start=1):
+            if not isinstance(step, dict):
+                errors.append(f"job '{job_name}', step {index}: must be a mapping")
+                continue
+            if "run" not in step and "uses" not in step:
+                name = step.get("name", f"step {index}")
+                errors.append(f"job '{job_name}', '{name}': missing 'run' or 'uses'")
+
+    return errors
+
+
+def check_file(path):
+    errors = []
+    try:
+        with path.open(encoding="utf-8") as handle:
+            data = yaml.safe_load(handle)
+    except yaml.YAMLError as error:
+        mark = getattr(error, "problem_mark", None)
+        if mark is not None:
+            errors.append(f"YAML error at line {mark.line + 1}, column {mark.column + 1}: {error}")
+        else:
+            errors.append(f"YAML error: {error}")
+        return errors
+
+    if not isinstance(data, dict):
+        errors.append("file does not parse to a mapping at the top level")
+        return errors
+
+    # PyYAML parses the unquoted key 'on' as boolean True in YAML 1.1.
+    if "on" not in data and True not in data:
+        errors.append("missing top-level 'on' trigger key")
+
+    errors.extend(check_jobs(data))
+    return errors
+
+
+def main():
+    files = find_workflow_files()
+    if not files:
+        print(f"No workflow files found in {WORKFLOW_DIR}.")
+        return 0
+
+    status = 0
+    for path in files:
+        errors = check_file(path)
+        if errors:
+            status = 1
+            print(f"Issues in: {path}")
+            for error in errors:
+                print(f"  {error}")
+
+    print(f"Checked {len(files)} workflow file(s).")
+    return status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/validate.yml

@@ -0,0 +1,33 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Validate workflows, shell scripts, and Python syntax
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install PyYAML
+        run: pip install pyyaml
+
+      - name: Validate GitHub workflows
+        run: python3 .github/scripts/validate_workflows.py
+
+      - name: Validate shell scripts
+        run: python3 .github/scripts/validate_shell.py
+
+      - name: Validate Python syntax
+        run: python3 .github/scripts/validate_python.py