Update CI checker script

strickvl · strickvl · commit 55283cb8adbe · 2025-03-19T13:27:11.000+01:00
diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml
@@ -10,7 +10,7 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 jobs:
-  check:
+  check-absolute-links:
     if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     steps:
@@ -19,14 +19,60 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: '3.11'
       - name: Install dependencies
         run: pip install requests
       - name: Check Absolute Links
+        id: check-absolute
         run: |
           # Only check absolute links (http/https), not relative links
-          python docs/link_checker.py --dir docs/book --substring "http" --validate-links --timeout 15
+          python docs/link_checker.py --dir docs/book --substring "http" --validate-links --timeout 15 --ci-mode
+        # Continue on error so both checks can run to completion
+        continue-on-error: true
+  check-relative-links:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
       - name: Check Relative Links
+        id: check-relative
         run: |-
           # Check if relative links resolve within the repository
           python scripts/check_relative_links.py --dir docs/book
+        # Continue on error so both checks can run to completion
+        continue-on-error: true
+  summary:
+    needs: [check-absolute-links, check-relative-links]
+    if: always() && github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create Summary
+        run: |-
+          echo "# Documentation Link Check Results" >> $GITHUB_STEP_SUMMARY
+
+          # Check for failures in absolute links job
+          if [[ "${{ needs.check-absolute-links.result }}" == "failure" ]]; then
+            echo "❌ **Absolute links check failed**" >> $GITHUB_STEP_SUMMARY
+            echo "There are broken absolute links in the documentation. Please check the job logs for details." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "✅ **Absolute links check passed**" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          # Check for failures in relative links job
+          if [[ "${{ needs.check-relative-links.result }}" == "failure" ]]; then
+            echo "❌ **Relative links check failed**" >> $GITHUB_STEP_SUMMARY
+            echo "There are broken relative links in the documentation. Please check the job logs for details." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "✅ **Relative links check passed**" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          # Set job status based on both child jobs
+          if [[ "${{ needs.check-absolute-links.result }}" == "failure" || "${{ needs.check-relative-links.result }}" == "failure" ]]; then
+            echo "::error::One or more link checks failed. Please fix the broken links."
+            exit 1
+          fi
diff --git a/docs/link_checker.py b/docs/link_checker.py
@@ -48,6 +48,7 @@
     --validate-links: Check if links are valid by making HTTP requests
     --timeout: Timeout for HTTP requests in seconds (default: 10)
     --url-mapping: Path segment mappings in format old=new (can be used multiple times)
+    --ci-mode: CI mode: only report broken links and exit with error code on failures
 
 Note:
     The 'requests' package is required for link validation. Install it with:
@@ -640,6 +641,11 @@ def main():
         action="append",
         help="Path segment mappings in format old=new (can be used multiple times)",
     )
+    parser.add_argument(
+        "--ci-mode",
+        action="store_true",
+        help="CI mode: only report broken links and exit with error code on failures",
+    )
     args = parser.parse_args()
 
     # Check for requests module if validation is enabled
@@ -666,12 +672,14 @@ def main():
     files_to_scan = []
     if args.dir:
         files_to_scan = find_markdown_files(args.dir)
-        print(
-            f"Found {len(files_to_scan)} markdown files in directory: {args.dir}"
-        )
+        if not args.ci_mode:
+            print(
+                f"Found {len(files_to_scan)} markdown files in directory: {args.dir}"
+            )
     else:
         files_to_scan = args.files
-        print(f"Scanning {len(files_to_scan)} specified markdown files")
+        if not args.ci_mode:
+            print(f"Scanning {len(files_to_scan)} specified markdown files")
 
     if args.replace_links:
         # Replace links mode
@@ -689,7 +697,8 @@ def main():
                     url_mappings,
                 )
                 if replacements:
-                    print(f"\n{file_path}:")
+                    if not args.ci_mode:
+                        print(f"\n{file_path}:")
                     for original, (
                         new,
                         is_valid,
@@ -698,51 +707,62 @@ def main():
                         total_replacements += 1
 
                         if args.validate_links and is_valid is not None:
-                            status = (
-                                "✅ Valid"
-                                if is_valid
-                                else f"❌ Broken: {error}"
-                            )
-                            print(f"  {original} -> {new} [{status}]")
-
                             if is_valid:
                                 valid_links += 1
+                                if not args.ci_mode:
+                                    print(f"  {original} -> {new} [✅ Valid]")
                             else:
                                 broken_links += 1
-                        else:
+                                # Always print broken links even in CI mode
+                                status = f"❌ Broken: {error}"
+                                if args.ci_mode:
+                                    print(f"{file_path}:")
+                                print(f"  {original} -> {new} [{status}]")
+                        elif not args.ci_mode:
                             print(f"  {original} -> {new}")
             except Exception as e:
                 print(f"Error processing {file_path}: {e}", file=sys.stderr)
 
         mode = "Would replace" if args.dry_run else "Replaced"
-        print(
-            f"\n{mode} {total_replacements} links across {len(files_to_scan)} files."
-        )
-
-        if args.validate_links and (valid_links > 0 or broken_links > 0):
+        if not args.ci_mode:
             print(
-                f"Link validation: {valid_links} valid, {broken_links} broken"
+                f"\n{mode} {total_replacements} links across {len(files_to_scan)} files."
             )
 
+            if args.validate_links and (valid_links > 0 or broken_links > 0):
+                print(
+                    f"Link validation: {valid_links} valid, {broken_links} broken"
+                )
+
+        # In CI mode, exit with error code if broken links were found
+        if args.ci_mode and broken_links > 0:
+            print(f"\nFound {broken_links} broken links")
+            sys.exit(1)
+
     elif args.substring:
         # Find links mode
         total_matches = 0
         links_to_validate = []
         file_links_map = {}
+        has_broken_links = False
 
         for file_path in files_to_scan:
             try:
                 matches = check_links_with_substring(file_path, args.substring)
                 if matches:
                     file_links = []
-                    print(f"\n{file_path}:")
+                    if not args.ci_mode:
+                        print(f"\n{file_path}:")
                     for link, line_num, _, _, _ in matches:
                         # Create clickable link to the file at the specific line
                         clickable_path = get_clickable_path(
                             file_path, line_num
                         )
-                        print(f"  Line {line_num}: {link}")
-                        print(f"    ↳ {clickable_path}")
+
+                        if not args.ci_mode:
+                            print(f"  Line {line_num}: {link}")
+                            print(f"    ↳ {clickable_path}")
+
                         total_matches += 1
 
                         if args.validate_links:
@@ -763,7 +783,7 @@ def main():
                                     (link, line_num, link)
                                 )  # Original and transformed are the same
                             # If neither, log it but don't validate
-                            else:
+                            elif not args.ci_mode:
                                 print(
                                     f"    ↳ Skipping validation (not a recognized link format)"
                                 )
@@ -773,26 +793,32 @@ def main():
             except Exception as e:
                 print(f"Error processing {file_path}: {e}", file=sys.stderr)
 
-        print(
-            f"\nFound {total_matches} links containing '{args.substring}' across {len(files_to_scan)} files."
-        )
+        if not args.ci_mode:
+            print(
+                f"\nFound {total_matches} links containing '{args.substring}' across {len(files_to_scan)} files."
+            )
 
         # Validate links if requested
         if args.validate_links and links_to_validate:
-            print(f"\nValidating {len(links_to_validate)} links...")
+            if not args.ci_mode:
+                print(f"\nValidating {len(links_to_validate)} links...")
             validation_results = validate_urls(list(set(links_to_validate)))
 
             valid_count = sum(
                 1 for result in validation_results.values() if result[0]
             )
             broken_count = len(validation_results) - valid_count
 
-            print(
-                f"\nLink validation: {valid_count} valid, {broken_count} broken"
-            )
+            if not args.ci_mode:
+                print(
+                    f"\nLink validation: {valid_count} valid, {broken_count} broken"
+                )
 
             if broken_count > 0:
-                print("\nBroken links:")
+                has_broken_links = True
+                if not args.ci_mode:
+                    print("\nBroken links:")
+
                 for file_path, links in file_links_map.items():
                     broken_in_file = []
                     for transformed_link, line_num, original_link in links:
@@ -822,7 +848,10 @@ def main():
                             # Show the original link in the output, but we validated the transformed one
                             print(f"  Line {line_num}: {original_link}")
                             print(f"    ↳ ❌ {status_info}")
-                            if original_link != transformed_link:
+                            if (
+                                original_link != transformed_link
+                                and not args.ci_mode
+                            ):
                                 print(
                                     f"    ↳ Validated as: {transformed_link}"
                                 )
@@ -831,6 +860,10 @@ def main():
                             )
                             print(f"    ↳ {clickable_path}")
 
+        # In CI mode, exit with error code if broken links were found
+        if args.ci_mode and has_broken_links:
+            sys.exit(1)
+
 
 if __name__ == "__main__":
     main()
