From e0bcf588a969909af565ea8479ef07b9f66aa6fa Mon Sep 17 00:00:00 2001
From: Bradley Lowekamp <blowekamp@mail.nih.gov>
Date: Wed, 11 Mar 2026 16:13:49 +0000
Subject: [PATCH] ENH: Add fix-nightly-warnings skill and CDash query scripts

---
 .github/skills/fix-nightly-warnings/SKILL.md  | 102 +++++++++
 .../scripts/get_build_warnings.py             | 212 ++++++++++++++++++
 .../scripts/list_nightly_warnings.py          | 210 +++++++++++++++++
 3 files changed, 524 insertions(+)
 create mode 100644 .github/skills/fix-nightly-warnings/SKILL.md
 create mode 100755 .github/skills/fix-nightly-warnings/scripts/get_build_warnings.py
 create mode 100755 .github/skills/fix-nightly-warnings/scripts/list_nightly_warnings.py

diff --git a/.github/skills/fix-nightly-warnings/SKILL.md b/.github/skills/fix-nightly-warnings/SKILL.md
new file mode 100644
index 00000000000..07810873c80
--- /dev/null
+++ b/.github/skills/fix-nightly-warnings/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: fix-nightly-warnings
+description: 'Fix ITK nightly build errors or compilation warnings reported on CDash. Use when: addressing CDash nightly failures. Creates a branch, fixes warnings, and opens a PR upstream.'
+argument-hint: What warnings should this skill fix?
+---
+
+# Fix ITK Nightly Build Errors and Warnings
+
+Creates a focused branch containing fixes for errors or warnings reported on the ITK CDash nightly dashboard, then opens a PR upstream.
+
+## When to Use
+
+- CDash nightly build reports new errors, warnings, or Doxygen warnings
+- User says "fix nightly errors", "address CDash warnings", or "there are new Doxygen warnings"
+
+## Available Scripts
+
+- **`scripts/list_nightly_warnings.py`** — Lists CDash builds that have warnings or errors. Defaults to `Nightly` builds from the last 24 hours.
+- **`scripts/get_build_warnings.py`** — Fetches and summarizes warnings (or errors) for a specific CDash build ID, grouped by source file and warning flag.
+
+Run `python3 scripts/<script>.py --help` for full usage.
+
+## Procedure
+
+### 1. Identify the Warnings
+
+Use the provided scripts to fetch the current nightly builds and their warnings from CDash.
+
+**Step 1a — List nightly builds with warnings:**
+
+```bash
+python3 scripts/list_nightly_warnings.py --type Nightly -limit 25 --json | jq '.[] | select(.warnings > 0)'
+```
+
+Note: `list_nightly_warnings.py` returns the builds with the most errors then warnings.
+
+
+**Step 1b — Inspect warnings for a specific build:**
+
+```bash
+python3 scripts/get_build_warnings.py --limit 200 --json BUILD_ID | jq 'group_by(.flag) | .[] | {flag: .[0].flag, count: length}'
+```
+
+---
+
+For each build with errors and warnings, fetch the details and summarize the errors and warnings by type and source file.
+IGNORE ALL errors and warnings originating from `Modules/ThirdParty/` paths.
+
+
+If there are build errors, only fix those. If there are warnings, prioritize fixing the most common warning flag that affects the most files.
+
+
+### 2. Analyze the Root Cause
+
+For each warning or error type identified in step 1, determine the root cause before editing files:
+- Look up the compiler flag (e.g. `-Wthread-safety-negative`) in the compiler documentation.
+- Read the affected source files to understand how they are structured.
+- Identify the minimal fix: a missing annotation, a suppression pragma, a corrected API usage, etc.
+- Confirm that warnings from `Modules/ThirdParty/` are skipped entirely.
+
+### 3. Create a New Branch
+
+```bash
+git fetch upstream
+git checkout -b fix-<warning-type>-warnings upstream/main
+```
+
+Example: `fix-doxygen-group-warnings`
+
+### 4. Fix the Source Files
+
+Determine the root cause of each error or warning. Apply the necessary fixes to the affected files to resolve the warnings. Make the minimal changes needed to fix the warnings, avoid changing unrelated documentation, coding or formatting.
+
+### 5. Verify No New Warnings Introduced
+
+Build and test to confirm that the fixes removed the targeted errors and warnings and did not introduce new ones.
+
+### 6. Commit the Changes
+
+Follow the ITK commit message standards. Include a clear description of the fix and include the error or warning message being addressed.
+
+### 7. Draft a Pull Request
+
+Do the following:
+- Draft a pull request description that includes a summary of the changes, the warnings or errors fixed, and reference the CDash build if applicable.
+- Request the User to review and approve the description before submitting the PR.
+- Push the branch to the user's remote
+- Create a DRAFT pull request against the current `upstream/main` branch.
+
+## Quality Checks
+
+Before declaring done:
+[] All targeted warnings are fixed
+[] No new warnings or errors introduced
+[] Changes are limited to the files affected by the warnings
+[] Commit message clearly describes the fix and references the CDash issue if applicable
+
+## Key Files for Reference
+
+| File | Purpose |
+|------|---------|
+| `Documentation/docs/contributing/index.md` | Contributing guidelines |
diff --git a/.github/skills/fix-nightly-warnings/scripts/get_build_warnings.py b/.github/skills/fix-nightly-warnings/scripts/get_build_warnings.py
new file mode 100755
index 00000000000..6c34f97c964
--- /dev/null
+++ b/.github/skills/fix-nightly-warnings/scripts/get_build_warnings.py
@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# ///
+"""
+get_build_warnings.py — Fetch and summarize warnings or errors for a CDash build.
+
+Queries the CDash GraphQL API for all warning (or error) entries associated with
+a specific build ID, then groups them by source file and warning flag.
+
+Exit codes:
+  0  Success
+  1  Argument error
+  2  Network or API error
+"""
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.request
+
+CDASH_GRAPHQL = "https://open.cdash.org/graphql"
+
+QUERY_TEMPLATE = """
+{
+  build(id: "%s") {
+    name stamp startTime buildWarningsCount buildErrorsCount
+    site { name }
+    buildErrors(filters: { eq: { type: %s } }, first: %d%s) {
+      pageInfo { hasNextPage endCursor }
+      edges {
+        node { sourceFile sourceLine stdError stdOutput }
+      }
+    }
+  }
+}
+"""
+
+WARNING_FLAG_RE = re.compile(r'\[(-W[^\]]+)\]')
+
+
+def graphql(query: str) -> dict:
+    payload = json.dumps({"query": query}).encode()
+    req = urllib.request.Request(
+        CDASH_GRAPHQL,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return json.loads(r.read())
+    except urllib.error.URLError as e:
+        print(f"Error: network request failed: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def extract_flag(text: str) -> str:
+    m = WARNING_FLAG_RE.search(text)
+    return m.group(1) if m else "?"
+
+
+def fetch_entries(build_id: str, error_type: str, limit: int) -> tuple[dict, list]:
+    """Fetch all entries up to limit, following pagination if needed."""
+    all_entries = []
+    cursor = None
+    build_meta = None
+
+    while True:
+        after_clause = f', after: "{cursor}"' if cursor else ""
+        query = QUERY_TEMPLATE % (build_id, error_type, min(limit, 200), after_clause)
+        data = graphql(query)
+
+        if "errors" in data:
+            print(f"Error: GraphQL returned errors: {data['errors']}", file=sys.stderr)
+            sys.exit(2)
+
+        build = data["data"]["build"]
+        if build_meta is None:
+            build_meta = {
+                "name": build["name"],
+                "stamp": build["stamp"],
+                "site": build["site"]["name"],
+                "buildWarningsCount": build["buildWarningsCount"],
+                "buildErrorsCount": build["buildErrorsCount"],
+            }
+
+        page = build["buildErrors"]
+        all_entries.extend(e["node"] for e in page["edges"])
+
+        if not page["pageInfo"]["hasNextPage"] or len(all_entries) >= limit:
+            break
+        cursor = page["pageInfo"]["endCursor"]
+
+    return build_meta, all_entries[:limit]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="get_build_warnings.py",
+        description="Fetch and summarize warnings or errors for a CDash build.",
+        epilog=(
+            "Examples:\n"
+            "  python3 scripts/get_build_warnings.py 11107692\n"
+            "  python3 scripts/get_build_warnings.py 11107692 --raw\n"
+            "  python3 scripts/get_build_warnings.py 11107692 --errors\n"
+            "  python3 scripts/get_build_warnings.py 11107692 --json | jq '.entries[] | select(.flag == \"-Wthread-safety-negative\")'\n"
+            "  python3 scripts/get_build_warnings.py 11107692 --limit 500"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "build_id",
+        metavar="BUILD_ID",
+        help="CDash build ID (integer from list_nightly_warnings.py output or CDash URL)",
+    )
+    parser.add_argument(
+        "--errors",
+        action="store_true",
+        help="Fetch build errors instead of warnings (default: warnings)",
+    )
+    parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Print one entry per line with file:line, flag, and message snippet instead of grouping",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output as JSON: {build: {...}, entries: [...]} for programmatic use",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=200,
+        metavar="N",
+        help="Maximum number of entries to retrieve (default: 200)",
+    )
+    args = parser.parse_args()
+
+    error_type = "ERROR" if args.errors else "WARNING"
+    label = "error" if args.errors else "warning"
+
+    build_meta, entries = fetch_entries(args.build_id, error_type, args.limit)
+    total = build_meta["buildErrorsCount" if args.errors else "buildWarningsCount"] or 0
+
+    if args.json_output:
+        output = {
+            "build": build_meta,
+            "type": error_type,
+            "totalCount": total,
+            "fetchedCount": len(entries),
+            "entries": [
+                {
+                    "sourceFile": n["sourceFile"],
+                    "sourceLine": n["sourceLine"],
+                    "flag": extract_flag(n["stdError"] or n["stdOutput"] or ""),
+                    "stdError": n["stdError"],
+                    "stdOutput": n["stdOutput"],
+                }
+                for n in entries
+            ],
+        }
+        print(json.dumps(output, indent=2))
+        return
+
+    # Diagnostics to stderr so stdout stays parseable
+    print(f"Build: {build_meta['name']}", file=sys.stderr)
+    print(f"Site:  {build_meta['site']}", file=sys.stderr)
+    print(f"Stamp: {build_meta['stamp']}", file=sys.stderr)
+    print(f"Total {label}s: {total}  (fetched: {len(entries)})", file=sys.stderr)
+    if total > len(entries):
+        print(
+            f"Note:  {total - len(entries)} entries not fetched; use --limit to increase.",
+            file=sys.stderr,
+        )
+    print(file=sys.stderr)
+
+    if args.raw:
+        print(f"{'FILE:LINE':<60}  {'FLAG':<35}  SNIPPET")
+        print("-" * 120)
+        for n in entries:
+            loc = f"{n['sourceFile']}:{n['sourceLine']}"
+            text = n["stdError"] or n["stdOutput"] or ""
+            flag = extract_flag(text)
+            # Extract a short message snippet after the flag
+            idx = text.find(flag)
+            if idx >= 0:
+                snippet = text[idx + len(flag):].strip().replace("\n", " ")[:80]
+            else:
+                snippet = text.replace("\n", " ")[:80]
+            print(f"{loc:<60}  {flag:<35}  {snippet}")
+    else:
+        # Group by (sourceFile, flag)
+        groups: dict = {}
+        for n in entries:
+            src = n["sourceFile"] or "<unknown>"
+            text = n["stdError"] or n["stdOutput"] or ""
+            flag = extract_flag(text)
+            key = (src, flag)
+            groups[key] = groups.get(key, 0) + 1
+
+        print(f"{'COUNT':>6}  {'FLAG':<35}  SOURCE FILE")
+        print("-" * 100)
+        for (src, flag), count in sorted(groups.items(), key=lambda x: (-x[1], x[0][0])):
+            print(f"{count:>6}  {flag:<35}  {src}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/skills/fix-nightly-warnings/scripts/list_nightly_warnings.py b/.github/skills/fix-nightly-warnings/scripts/list_nightly_warnings.py
new file mode 100755
index 00000000000..bf72cd8a319
--- /dev/null
+++ b/.github/skills/fix-nightly-warnings/scripts/list_nightly_warnings.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# ///
+"""
+list_nightly_warnings.py — List ITK CDash builds that have warnings or errors.
+
+Queries the CDash GraphQL API for recent builds of a given type in the Insight/ITK project
+and prints those with a non-zero warning or error count. By default, selects Nightly builds
+submitted since the project's nightly start time (CTEST_NIGHTLY_START). When `--since` is
+omitted the script uses a hard-coded ISO time `01:00:00+00:00` (matches CTestConfig.cmake),
+otherwise `--since N` selects builds from the last N hours.
+
+Build types visible on the CDash dashboard (https://open.cdash.org/index.php?project=Insight):
+  Nightly        — scheduled nightly builds (default)
+  Continuous     — CI builds triggered on commits
+  Experimental   — developer-submitted one-off builds
+
+Exit codes:
+  0  Success (results printed, possibly empty)
+  1  Argument error
+  2  Network or API error
+"""
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta, timezone
+
+CDASH_GRAPHQL = "https://open.cdash.org/graphql"
+INSIGHT_PROJECT_ID = "2"
+
+QUERY_TEMPLATE = """
+{
+  project(id: "%s") {
+    name
+    builds(first: %d, filters: { all: [
+      { contains: { stamp: "%s" } }
+      { gt: { startTime: "%s" } }
+    ]}) {
+      edges {
+        node {
+          id name stamp buildType buildWarningsCount buildErrorsCount startTime
+          site { name }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def graphql(query: str) -> dict:
+    payload = json.dumps({"query": query}).encode()
+    req = urllib.request.Request(
+        CDASH_GRAPHQL,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return json.loads(r.read())
+    except urllib.error.URLError as e:
+        print(f"Error: network request failed: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="list_nightly_warnings.py",
+        description="List ITK CDash builds that have warnings or errors.",
+        epilog=(
+            "Examples:\n"
+            "  python3 scripts/list_nightly_warnings.py\n"
+            "  python3 scripts/list_nightly_warnings.py --type Continuous\n"
+            "  python3 scripts/list_nightly_warnings.py --type Experimental --limit 100 --all\n"
+            "  python3 scripts/list_nightly_warnings.py --json | jq '.[] | select(.warnings > 10)'"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--type",
+        default="Nightly",
+        metavar="TYPE",
+        help=(
+            "Build type to filter by: Nightly (default), Continuous, Experimental, etc. "
+            "Matched as a substring of the build stamp (e.g. '20260310-0100-Nightly')."
+        ),
+    )
+    parser.add_argument(
+        "--since",
+        type=float,
+        default=None,
+        metavar="HOURS",
+        help=(
+            "Only show builds submitted in the last N hours. If omitted, uses the "
+            "project nightly start time (hard-coded to 01:00:00+00:00 in this script)."
+        ),
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=100,
+        metavar="N",
+        help="Maximum number of builds to fetch from CDash (default: 100)",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Show all matching builds, not just those with warnings or errors",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output as a JSON array instead of a human-readable table",
+    )
+    args = parser.parse_args()
+
+    if args.since is None:
+        # Hard-coded nightly start time (matches CTestConfig.cmake project-level
+        # setting `CTEST_NIGHTLY_START_TIME` in the repository root). Update here
+        # if that value changes. Use an ISO-like time with UTC offset to simplify
+        # parsing (no manual tz mapping required): `HH:MM:SS+00:00`.
+        CTEST_NIGHTLY_START = "01:00:00+00:00"
+        # Build an aware datetime from today's date + the hard-coded time offset.
+        today = datetime.now(timezone.utc).date()
+        dt = datetime.fromisoformat(f"{today.isoformat()}T{CTEST_NIGHTLY_START}")
+        now_utc = datetime.now(timezone.utc)
+        since_dt = dt if now_utc >= dt else dt - timedelta(days=1)
+    else:
+        since_dt = datetime.now(timezone.utc) - timedelta(hours=args.since)
+
+    since_str = since_dt.strftime("%Y-%m-%dT%H:%M:%S+00:00")
+
+    # Request more builds from the server than we may display so we can
+    # sort by errors/warnings client-side and then apply the display `--limit`.
+    fetch_count = max(args.limit, 500)
+    query = QUERY_TEMPLATE % (INSIGHT_PROJECT_ID, fetch_count, args.type, since_str)
+    data = graphql(query)
+
+    if "errors" in data:
+        print(f"Error: GraphQL returned errors: {data['errors']}", file=sys.stderr)
+        sys.exit(2)
+
+    edges = data["data"]["project"]["builds"]["edges"]
+    project_name = data["data"]["project"]["name"]
+
+    nodes = [e["node"] for e in edges]
+    if not args.all:
+        nodes = [
+            n
+            for n in nodes
+            if (n.get("buildWarningsCount") or 0) > 0
+            or (n.get("buildErrorsCount") or 0) > 0
+        ]
+
+    # Sort by number of errors (desc), then warnings (desc), then startTime (desc).
+    nodes.sort(
+        key=lambda n: (
+            n.get("buildErrorsCount") or 0,
+            n.get("buildWarningsCount") or 0,
+            n.get("startTime", ""),
+        ),
+        reverse=True,
+    )
+
+    # Apply the display limit after sorting
+    displayed_nodes = nodes[: args.limit]
+
+    if args.json_output:
+        output = [
+            {
+                "id": n["id"],
+                "name": n["name"],
+                "stamp": n["stamp"],
+                "buildType": n["buildType"],
+                "warnings": n["buildWarningsCount"] or 0,
+                "errors": n["buildErrorsCount"] or 0,
+                "startTime": n["startTime"],
+                "site": n["site"]["name"],
+            }
+            for n in nodes
+        ]
+        print(json.dumps(output, indent=2))
+        return
+
+    print(
+        f"Project: {project_name}  |  type={args.type!r}  |  since={since_str}  |  "
+        f"Builds fetched: {len(edges)}  |  With warnings/errors: {len(nodes)}",
+        file=sys.stderr,
+    )
+    print(file=sys.stderr)
+    print(
+        f"{'BUILD_ID':>10}  {'W':>4}  {'E':>4}  {'STAMP':<25}  {'SITE':<25}  BUILD_NAME"
+    )
+    print("-" * 110)
+    for n in nodes:
+        warn = n["buildWarningsCount"] or 0
+        err = n["buildErrorsCount"] or 0
+        print(
+            f"{n['id']:>10}  {warn:>4}  {err:>4}  "
+            f"{n['stamp'][:24]:<25}  {n['site']['name'][:24]:<25}  {n['name']}"
+        )
+
+
+if __name__ == "__main__":
+    main()