feat(docs-linter): add lint for local links

.github/workflows/docs-404-checker.yml → .github/workflows/docs-linter.yml

@@ -1,4 +1,4 @@
-name: "docs / 404 checker"
+name: "docs / lint"
 
 on:
   push:

docs/how-to-guides/connecting-from-go.md

@@ -50,7 +50,7 @@ The `gnoclient` package exposes a `Client` struct containing a `Signer` and
 `RPCClient` connector. `Client` exposes all available functionality for talking
 to a Gno.land chain.
 
-```go 
+```go
 type Client struct {
     Signer    Signer           // Signer for transaction authentication
     RPCClient rpcclient.Client // gnolang/gno/tm2/pkg/bft/rpc/client
@@ -101,8 +101,9 @@ func main() {
 A few things to note:
 - You can view keys in your local keybase by running `gnokey list`.  
 - You can get the password from a user input using the IO package.
-- `Signer` can also be initialized in-memory from a BIP39 mnemonic, using the 
-[`SignerFromBip39`](../reference/gnoclient/signer.md#func-signerfrombip39) function.
+- `Signer` can also be initialized in-memory from a BIP39 mnemonic, using the
+[`SignerFromBip39`](https://gnolang.github.io/gno/github.com/gnolang/gno@v0.0.0/gno.land/pkg/gnoclient.html#SignerFromBip39)
+function. function.
 
 ## Initialize the RPC connection & Client
 
@@ -116,7 +117,7 @@ if err != nil {
 ```
 
 A list of Gno.land network endpoints & chain IDs can be found in the [Gno RPC 
-endpoints](../reference/rpc-endpoints.md#network-configurations) page. 
+endpoints](../reference/network-config.md) page. 
 
 With this, we can initialize the `gnoclient.Client` struct: 
 

docs/reference/gnoclient/gnoclient.md

@@ -30,5 +30,5 @@ To see the full reference documentation for the `gnoclient` package, we recommen
 visiting the [`gnoclient godoc page`](https://gnolang.github.io/gno/github.com/gnolang/gno@v0.0.0/gno.land/pkg/gnoclient.html).
 
 For a tutorial on how to use the `gnoclient` package, check out 
-["How to connect a Go app to Gno.land"](../../how-to-guides/connecting-from-go.md.)
+["How to connect a Go app to Gno.land"](../../how-to-guides/connecting-from-go.md)
 

misc/docs-linter/errors.go

@@ -3,9 +3,10 @@ package main
 import "errors"
 
 var (
-	errEmptyPath             = errors.New("you need to pass in a path to scan")
-	err404Link               = errors.New("link returned a 404")
-	errFound404Links         = errors.New("found links resulting in a 404 response status")
-	errFoundUnescapedJSXTags = errors.New("found unescaped JSX tags")
-	errFoundLintItems        = errors.New("found items that need linting")
+	errEmptyPath                  = errors.New("you need to pass in a path to scan")
+	err404Link                    = errors.New("link returned a 404")
+	errFound404Links              = errors.New("found links resulting in a 404 response status")
+	errFoundUnescapedJSXTags      = errors.New("found unescaped JSX tags")
+	errFoundUnreachableLocalLinks = errors.New("found local links that stat fails on")
+	errFoundLintItems             = errors.New("found items that need linting")
 )

misc/docs-linter/jsx.go

@@ -1,12 +1,12 @@
 package main
 
 import (
-	"context"
 	"fmt"
 	"regexp"
 	"strings"
 )
 
+// extractJSX extracts JSX tags from given file content
 func extractJSX(fileContent []byte) []string {
 	text := string(fileContent)
 
@@ -34,10 +34,9 @@ func extractJSX(fileContent []byte) []string {
 	return filteredMatches
 }
 
-func lintJSX(fileUrlMap map[string][]string, ctx context.Context) error {
+func lintJSX(filepathToJSX map[string][]string) error {
 	found := false
-	for filePath, tags := range fileUrlMap {
-		filePath := filePath
+	for filePath, tags := range filepathToJSX {
 		for _, tag := range tags {
 			if !found {
 				fmt.Println("Tags that need checking:")

misc/docs-linter/links.go

@@ -3,105 +3,78 @@ package main
 import (
 	"bufio"
 	"bytes"
-	"context"
 	"fmt"
-	"golang.org/x/sync/errgroup"
-	"io"
-	"mvdan.cc/xurls/v2"
-	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
 	"strings"
-	"sync"
 )
 
-// extractUrls extracts URLs from a file and maps them to the file
-func extractUrls(fileContent []byte) []string {
+// extractLocalLinks extracts links to local files from the given file content
+func extractLocalLinks(fileContent []byte) []string {
 	scanner := bufio.NewScanner(bytes.NewReader(fileContent))
-	urls := make([]string, 0)
+	links := make([]string, 0)
+	// Regular expression to match markdown links
+	re := regexp.MustCompile(`]\((\.\.?/.+?)\)`)
 
 	// Scan file line by line
 	for scanner.Scan() {
 		line := scanner.Text()
 
-		// Extract links
-		rxStrict := xurls.Strict()
-		url := rxStrict.FindString(line)
+		// Find embedmd links
+		if strings.Contains(line, "[embedmd]") {
+			openPar := strings.Index(line, "(")
+			closePar := strings.Index(line, ")")
 
-		// Check for empty links and skip them
-		if url == " " || len(url) == 0 {
+			link := line[openPar+1 : closePar]
+			if pos := strings.Index(link, " "); pos != -1 {
+				link = link[:pos]
+			}
+
+			links = append(links, link)
 			continue
 		}
 
-		// Look for http & https only
-		if strings.HasPrefix(url, "http://") || strings.HasPrefix(url, "https://") {
-			// Ignore localhost
-			if !strings.Contains(url, "localhost") && !strings.Contains(url, "127.0.0.1") {
-				urls = append(urls, url)
+		// Find all matches
+		matches := re.FindAllString(line, -1)
+
+		// Extract and print the local file links
+		for _, match := range matches {
+			// Remove ]( from the beginning and ) from end of link
+			match = match[2 : len(match)-1]
+
+			// Remove markdown headers in links
+			if pos := strings.Index(match, "#"); pos != -1 {
+				match = match[:pos]
 			}
+
+			links = append(links, match)
 		}
 	}
 
-	return urls
+	return links
 }
 
-func lintLinks(fileUrlMap map[string][]string, ctx context.Context) error {
-	// Filter links by prefix & ignore localhost
-	// Setup parallel checking for links
-	g, _ := errgroup.WithContext(ctx)
-
-	var (
-		lock         sync.Mutex
-		notFoundUrls []string
-	)
-
-	for filePath, urls := range fileUrlMap {
-		filePath := filePath
-		for _, url := range urls {
-			url := url
-			g.Go(func() error {
-				if err := checkUrl(url); err != nil {
-					lock.Lock()
-					notFoundUrls = append(notFoundUrls, fmt.Sprintf(">>> %s (found in file: %s)", url, filePath))
-					lock.Unlock()
+func lintLocalLinks(filepathToLinks map[string][]string, docsPath string) error {
+	var found bool
+	for filePath, links := range filepathToLinks {
+		for _, link := range links {
+			path := filepath.Join(docsPath, filepath.Dir(filePath), link)
+
+			if _, err := os.Stat(path); err != nil {
+				if !found {
+					fmt.Println("Could not find files with the following paths:")
+					found = true
 				}
 
-				return nil
-			})
+				fmt.Printf(">>> %s (found in file: %s)\n", link, filePath)
+			}
 		}
 	}
 
-	if err := g.Wait(); err != nil {
-		return err
-	}
-
-	// Print out the URLs that returned a 404 along with the file names
-	if len(notFoundUrls) > 0 {
-		fmt.Println("Links that need checking:")
-		for _, result := range notFoundUrls {
-			fmt.Println(result)
-		}
-
-		return errFound404Links
+	if found {
+		return errFoundUnreachableLocalLinks
 	}
 
 	return nil
 }
-
-// checkUrl checks if a URL is a 404
-func checkUrl(url string) error {
-	// Attempt to retrieve the HTTP header
-	resp, err := http.Get(url)
-	if err != nil || resp.StatusCode == http.StatusNotFound {
-		return err404Link
-	}
-
-	// Ensure the response body is closed properly
-	cleanup := func(Body io.ReadCloser) error {
-		if err := Body.Close(); err != nil {
-			return fmt.Errorf("could not close response properly: %w", err)
-		}
-
-		return nil
-	}
-
-	return cleanup(resp.Body)
-}

misc/docs-linter/main.go

@@ -61,8 +61,9 @@ func execLint(cfg *cfg, ctx context.Context) error {
 	}
 
 	// Make storage maps for tokens to analyze
-	fileUrlMap := make(map[string][]string) // file path > [urls]
-	fileJSXMap := make(map[string][]string) // file path > [JSX items]
+	fileUrlMap := make(map[string][]string)       // file path > [urls]
+	fileJSXMap := make(map[string][]string)       // file path > [JSX items]
+	fileLocalLinkMap := make(map[string][]string) // file path > [local links]
 
 	// Extract tokens from files
 	for _, filePath := range mdFiles {
@@ -72,21 +73,29 @@ func execLint(cfg *cfg, ctx context.Context) error {
 			return err
 		}
 
+		// Execute JSX extractor
 		fileJSXMap[filePath] = extractJSX(fileContents)
 
 		// Execute URL extractor
 		fileUrlMap[filePath] = extractUrls(fileContents)
+
+		// Execute local link extractor
+		fileLocalLinkMap[filePath] = extractLocalLinks(fileContents)
 	}
 
 	// Run linters in parallel
 	g, _ := errgroup.WithContext(ctx)
 
 	g.Go(func() error {
-		return lintJSX(fileJSXMap, ctx)
+		return lintJSX(fileJSXMap)
+	})
+
+	g.Go(func() error {
+		return lintURLs(fileUrlMap, ctx)
 	})
 
 	g.Go(func() error {
-		return lintLinks(fileUrlMap, ctx)
+		return lintLocalLinks(fileLocalLinkMap, cfg.docsPath)
 	})
 
 	if err := g.Wait(); err != nil {

misc/docs-linter/main_test.go

@@ -121,6 +121,42 @@ Returns **Promise<string>**
 	}
 }
 
+func TestExtractLocalLinks(t *testing.T) {
+	t.Parallel()
+
+	// Create mock file content with random local links
+	mockFileContent := `
+Here is some text with a link to a local file: [text](../concepts/file1.md)
+Here is another local link: [another](./path/to/file1.md)
+Here is another local link: [another](./path/to/file2.md#header-1-2)
+And a link to an external website: [example](https://example.com)
+And a websocket link: [websocket](ws://example.com/socket)
+Here's an embedmd link': [embedmd]:# (../assets/how-to-guides/simple-library/tapas.gno go)
+`
+
+	// Expected JSX tags
+	expectedLinks := []string{
+		"../concepts/file1.md",
+		"./path/to/file1.md",
+		"./path/to/file2.md",
+		"../assets/how-to-guides/simple-library/tapas.gno",
+	}
+
+	// Extract local links tags from the mock file content
+	extractedLinks := extractLocalLinks([]byte(mockFileContent))
+
+	if len(expectedLinks) != len(extractedLinks) {
+		t.Fatal("did not extract the correct amount of local links")
+	}
+
+	sort.Strings(extractedLinks)
+	sort.Strings(expectedLinks)
+
+	for i, tag := range expectedLinks {
+		require.Equal(t, tag, extractedLinks[i])
+	}
+}
+
 func TestFindFilePaths(t *testing.T) {
 	t.Parallel()