Add workflow to check for broken links

Signed-off-by: Alexandr Demicev <[email protected]>

Author: alexander-demicev

.github/workflows/verify-broken-links.yaml

@@ -0,0 +1,15 @@
+name: Verify Broken Links
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened, labeled, unlabeled]
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - name: Run broken links checker
+        run: go run tools/verifybrokenlinks/main.go -docs-dir=docs -max-parallel=10

tools/verifybrokenlinks/main.go

@@ -0,0 +1,197 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io/fs"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+type LinkOccurrence struct {
+	URL  string
+	File string
+}
+
+type CheckResult struct {
+	URL        string
+	IsValid    bool
+	StatusCode int
+	ErrorMsg   string
+}
+
+func main() {
+	docsDir := flag.String("docs-dir", "docs", "directory to scan for .adoc files")
+	maxParallel := flag.Int("max-parallel", 10, "maximum number of parallel link checks")
+	exitOnError := flag.Bool("exit-on-error", true, "exit with non-zero code if broken links are found")
+	flag.Parse()
+
+	allLinks, uniqueLinks := extractLinks(*docsDir)
+
+	results := checkLinks(uniqueLinks, *maxParallel, len(uniqueLinks))
+
+	brokenLinks := make(map[string]CheckResult)
+	for _, result := range results {
+		if !result.IsValid {
+			brokenLinks[result.URL] = result
+		}
+	}
+
+	for url, result := range brokenLinks {
+		var errorCode string
+		if result.StatusCode != 0 {
+			errorCode = fmt.Sprintf("HTTP %d", result.StatusCode)
+		} else {
+			errorCode = result.ErrorMsg
+		}
+
+		fmt.Printf("❌ %s %s\n", errorCode, url)
+		fmt.Println("Found in:")
+
+		for _, occurrence := range allLinks {
+			if occurrence.URL == url {
+				relativePath := strings.TrimPrefix(occurrence.File, *docsDir+"/")
+				fmt.Printf("- %s\n", relativePath)
+			}
+		}
+		fmt.Println()
+	}
+
+	if len(brokenLinks) > 0 {
+		fmt.Printf("Found %d broken links out of %d total links\n", len(brokenLinks), len(uniqueLinks))
+		fmt.Println("Done")
+
+		if *exitOnError {
+			os.Exit(1)
+		}
+	} else {
+		fmt.Printf("Success: All %d links are valid\n", len(uniqueLinks))
+		fmt.Println("Done")
+	}
+}
+
+func extractLinks(docsDir string) ([]LinkOccurrence, []string) {
+	var allLinks []LinkOccurrence
+	uniqueLinksMap := make(map[string]bool)
+
+	githubLinkRegex := regexp.MustCompile(`https?://github\.com[-a-zA-Z0-9@:%._\+~#=/]*`)
+	issuesPRRegex := regexp.MustCompile(`/(?:issues|pull)/[0-9]+`)
+
+	filepath.WalkDir(docsDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if !d.IsDir() && strings.HasSuffix(path, ".adoc") {
+			content, err := os.ReadFile(path)
+			if err != nil {
+				return err
+			}
+
+			links := githubLinkRegex.FindAllString(string(content), -1)
+
+			for _, link := range links {
+				cleanedLink := trimTrailingPunctuation(link)
+				if !issuesPRRegex.MatchString(cleanedLink) {
+					allLinks = append(allLinks, LinkOccurrence{
+						URL:  cleanedLink,
+						File: path,
+					})
+					uniqueLinksMap[cleanedLink] = true
+				}
+			}
+		}
+		return nil
+	})
+
+	uniqueLinks := make([]string, 0, len(uniqueLinksMap))
+	for link := range uniqueLinksMap {
+		uniqueLinks = append(uniqueLinks, link)
+	}
+
+	return allLinks, uniqueLinks
+}
+
+func trimTrailingPunctuation(url string) string {
+	for _, punct := range []string{".", ",", ")", "]", ">"} {
+		if strings.HasSuffix(url, punct) {
+			return url[:len(url)-len(punct)]
+		}
+	}
+	return url
+}
+
+func checkLinks(links []string, maxParallel int, totalLinks int) []CheckResult {
+	results := make([]CheckResult, 0, len(links))
+	resultsChan := make(chan CheckResult, len(links))
+	sem := make(chan struct{}, maxParallel)
+	var wg sync.WaitGroup
+	var progress int32
+
+	client := &http.Client{
+		Timeout: 10 * time.Second,
+		CheckRedirect: func(req *http.Request, via []*http.Request) error {
+			return nil
+		},
+	}
+
+	for _, link := range links {
+		wg.Add(1)
+		sem <- struct{}{}
+
+		go func(url string) {
+			defer wg.Done()
+			defer func() { <-sem }()
+
+			result := CheckResult{URL: url, IsValid: false}
+
+			req, err := http.NewRequest("HEAD", url, nil)
+			if err != nil {
+				result.ErrorMsg = err.Error()
+				resultsChan <- result
+				return
+			}
+
+			resp, err := client.Do(req)
+			if err != nil {
+				getResp, getErr := client.Get(url)
+				if getErr != nil {
+					result.ErrorMsg = "Connection failed or timed out"
+					resultsChan <- result
+					return
+				}
+				resp = getResp
+			}
+
+			defer resp.Body.Close()
+			result.StatusCode = resp.StatusCode
+
+			if resp.StatusCode >= 200 && resp.StatusCode < 400 {
+				result.IsValid = true
+			}
+
+			resultsChan <- result
+
+			current := atomic.AddInt32(&progress, 1)
+			fmt.Fprintf(os.Stderr, "\rProgress: %d/%d links checked", current, totalLinks)
+		}(link)
+	}
+
+	go func() {
+		wg.Wait()
+		close(resultsChan)
+	}()
+
+	for result := range resultsChan {
+		results = append(results, result)
+	}
+
+	fmt.Fprintln(os.Stderr)
+	return results
+}