Merge pull request #17 from ep-linden/add-link-mapping

parthpp · web-flow · commit 5dc1edac4204 · 2022-01-19T10:00:36.000-05:00
Add link mapping functionality.
diff --git a/README.md b/README.md
@@ -49,8 +49,9 @@ textlint --rule textlint-rule-no-dead-relative-link README.md
 
 ### resolve-as-markdown
 
-This option takes an array of file extension values and treats files with those extension as if they are markdown files.  
-For eg. With the following configuration
+This option takes an array of file extension values and treats files with those extensions as if they are markdown files.  
+
+For e.g. With the following configuration
 ```json
 {
     "rules": {
@@ -61,7 +62,60 @@ For eg. With the following configuration
 }
 ```
 
-and `[README](README.html)` as input, this rule will check for the existance of `README.md` file.
+and `[README](README.html)` as input, this rule will check for the existence of `README.md` file.
+
+### route-map
+Use this option when relative links need to be validated using an alternate file path. 
+
+This option takes an array of source and destination pairs. The source value is a `Regex`, and the destination value is 
+a `String` that can include capture groups from the `source` using the `$` notation. 
+
+For e.g. With the following configuration
+```json
+{
+    "rules": {
+        "no-dead-relative-link": {
+            "route-map": [
+                {
+                    "source": "^../javadocs/(\\d+\\.\\d+\\.\\w+)", 
+                    "destination": "../../static/javadocs/$1"
+                }
+            ]
+        }
+    }
+}
+```
+
+and `../javadocs/1.0.x/overview-summary.html` as the link being checked, this rule checks for the existence of the 
+`overview-summary.html` file at `../../static/javadocs/1.0.x/overview-summary.html`.
+
+##### Note #####
+Ensure each `route-map` pair is specific because the route-map option will validate relative links using the first 
+matching regex found in the configuration.
+
+For e.g. With the following configuration
+```json
+{
+    "rules": {
+        "no-dead-relative-link": {
+            "route-map": [
+                {
+                    "source": "../../javadocs/",
+                    "destination": "../website/static/javadocs/"
+                },
+                {
+                    "source": "../javadocs/1.0.x/",
+                    "destination": "../../static/javadocs/1.0.x/"
+                }
+            ]
+        }
+    }
+}
+```
+
+and `../../javadocs/1.0.x/overview-summary.html` as the link being checked, this rule checks for the existence of the
+`overview-summary.html` file at the first destination `../website/static/javadocs/1.0.x/overview-summary.html` instead 
+of the second destination `../../static/javadocs/1.0.x/overview-summary.html`.
 
 ## License
 
diff --git a/src/no-dead-relative-link.js b/src/no-dead-relative-link.js
@@ -8,7 +8,6 @@ import GithubSlugger from 'github-slugger';
 import util from 'util';
 import { wrapReportHandler} from 'textlint-rule-helper';
 
-const fileExists = util.promisify(fs.exists);
 const fileRead = util.promisify(fs.readFile);
 
 //https://stackoverflow.com/a/31991870
@@ -39,21 +38,58 @@ async function validateLinkNode(linkNode, context, options) {
 }
 
 async function validateRelativeLink(linkNode, context, options) {
-    let linkAbsoutePath = path.resolve(path.dirname(context.getFilePath()), linkNode.url);
-    let linkURL = new URL("file://" + linkAbsoutePath);
-    let linkedFileExtension = path.extname(linkURL.pathname);
+    let linkURL = getLinkURL(linkNode.url, context, options);
+    if (!await fileExists(url.fileURLToPath(linkURL))) {
+        if (options["route-map"]) {
+            linkURL = await getRoutedLink(linkNode, context, options);
+            if (linkURL && !await fileExists(url.fileURLToPath(linkURL))) {
+                reportError(linkNode, context, `${path.basename(linkURL.pathname)} does not exist`);
+                return;
+            }
+        } else {
+            reportError(linkNode, context, `${path.basename(linkURL.pathname)} does not exist`);
+            return;
+        }
+    }
 
+    if (linkURL && linkURL.hash && path.extname(linkURL.pathname) === ".md") {
+        return validateAnchorLink(url.fileURLToPath(linkURL), linkURL.hash.slice(1), linkNode, context);
+    }
+}
 
+async function getRoutedLink(linkNode, context, options) {
+    let linkRouteMaps = options["route-map"];
+    let nodeUrl = linkNode.url;
+
+    for (const mapping of linkRouteMaps) {
+        let sourceRegex = new RegExp(mapping["source"], "g");
+        let mappedDestination = mapping["destination"]
+        if (sourceRegex.test(nodeUrl)) {
+            let routedUrl = nodeUrl.replace(sourceRegex, mappedDestination);
+            let linkURL = getLinkURL(routedUrl, context, options);
+            return linkURL;
+        }
+    }
+}
+
+function getLinkURL(nodeURL, context, options) {
+    let linkAbsolutePath = path.resolve(path.dirname(context.getFilePath()), nodeURL);
+    let linkURL = new URL("file://" + linkAbsolutePath);
+    let linkedFileExtension = path.extname(linkURL.pathname);
     if (linkedFileExtension !== ".md" && options["resolve-as-markdown"] && options["resolve-as-markdown"].includes(linkedFileExtension)) {
         linkURL.pathname = linkURL.pathname.replace(linkedFileExtension, ".md");
     }
 
-    if (!await fileExists(url.fileURLToPath(linkURL))) {
-        reportError(linkNode, context, `${path.basename(linkURL.pathname)} does not exist`);
-        return;
-    } 
-    if(linkURL.hash && path.extname(linkURL.pathname) === ".md") {
-        return validateAnchorLink(url.fileURLToPath(linkURL), linkURL.hash.slice(1), linkNode, context);
+    return linkURL;
+}
+
+async function fileExists(url) {
+    let access = util.promisify(fs.access);
+    try {
+        await access(url);
+        return true;
+    } catch (e) {
+        return false;
     }
 }
 
diff --git a/test/fixtures/testFiles/invalidLinkRoutingTest.md b/test/fixtures/testFiles/invalidLinkRoutingTest.md
@@ -0,0 +1,5 @@
+This invalid link to a file with an anchor has no valid routing [invalidAnchorLink](../../invalidLink.md#does-not-exist)
+This invalid link to a file has no valid routing [invalidLink](../../invalidLink.md)
+This invalid link to a html file with an anchor that needs to be resolved as markdown has no valid routing [invalidAnchorLink](../dir/invalidLink.html#does-not-exist)
+This invalid link to html file that needs to be resolved as markdown has no valid routing [invalidLink](../dir/invalidLink.html)
+This invalid link to a file with an anchor is routed to a valid link with an invalid anchor [invalidAnchorLink](../../subdir/linkTestFile.md#header-7)
diff --git a/test/fixtures/testFiles/invalidLinkTest.md b/test/fixtures/testFiles/invalidLinkTest.md
@@ -1,8 +1,8 @@
-This is a link to file that does not exists [invalidLink](invalidLink.md)  
+This is a link to file that does not exist [invalidLink](invalidLink.md)  
 This is an invalid link to txt file in current directory [invalidLink](invalidLink.txt)  
 This is an invalid html link that needs to be resolved as markdown [invalidHtmlLink](invalidHtmlLink.html)
 This is an anchor link to invalid anchor in current file [invalidAnchorCurrentFile](#valid-links)
 This is an anchor link to an invalid anchor [invalidAnchorLink](../linkTestFile.md#header-7)
 This is an anchor link to an invalid anchor in file that needs to resolved as markdown [invalidAnchorLink](../linkTestFile.html#header-7)
-This is an anchor link to a file that does not exist [invalidAnchorLink](invalidLink.md#does-not-exist) 
- > If these property values do not exist in the settings.xml, the source code might not be following the guidelines at [Setup Guide](../setup-introduction.md)
+This is an anchor link to a file that does not exist [invalidAnchorLink](invalidLink.md#does-not-exist)
+> If these property values do not exist in the settings.xml, the source code might not be following the guidelines at [Setup Guide](../setup-introduction.md)
diff --git a/test/fixtures/testFiles/validLinkRoutingTest.md b/test/fixtures/testFiles/validLinkRoutingTest.md
@@ -0,0 +1,8 @@
+This is an invalid link routed to a valid link [invalidLink](../../linkTestFile.md)
+This is an invalid link routed to a valid link with an anchor [invalidAnchorLink](../../linkTestFile.md#fundamentals)
+This is an invalid link routed to a valid link [invalidLink](../dir/linkTestFile.md)
+This is an invalid link routed to a valid link with an anchor [invalidAnchorLink](../dir/linkTestFile.md#fundamentals)
+This is an invalid link routed to a valid link [invalidLink](../../subdir/linkTestFile.md)
+This is an invalid link routed to a valid link with an anchor [invalidAnchorLink](../../subdir/linkTestFile.md)
+This is an invalid html file that needs to be resolved as markdown routed to a valid link [invalidHtmlLink](../../linkTestFile.html)
+This is an invalid html file that needs to be resolved as markdown routed to a valid link with an anchor [invalidHtmlAnchorLink](../../linkTestFile.html#fundamentals)
diff --git a/test/fixtures/testFiles/validLinkTest.md b/test/fixtures/testFiles/validLinkTest.md
@@ -1,5 +1,5 @@
 # Valid Links
-This is an valid empty link [emptyLink]()  
+This is a valid empty link [emptyLink]()  
 This is valid link in the current directory [validLink](linkTestFile.md)  
 This is valid link in the current directory to txt file [validLink](linkTestTxtFile.txt)  
 This is valid link to file in sub directory [validSubLink](./subDir/linkTestFile.md)  
@@ -15,6 +15,6 @@ This is a link to valid anchor [validAnchorLink](../linkTestFile.md#header-6)
 This is a link to valid anchor in same file [validSameFileAnchor](#valid-links)
 This is a link to valid anchor in same file [validSameFileAnchor](#no-paragraph)
 This is a linkt to valid anchor in file to be resolved as markdown [validMDAnchorLink](../linkTestFile.html#header-5)
- >This is valid link in the textlint repo [textlint](https://textlint.github.io)
+>This is valid link in the textlint repo [textlint](https://textlint.github.io)
 
-## No Paragraph
+## No Paragraph
diff --git a/test/no-dead-relative-link-test.js b/test/no-dead-relative-link-test.js
@@ -3,13 +3,23 @@ import validateRelativeLinks from '../src/no-dead-relative-link';
 import path from 'path';
 const tester = new TextLintTester();
 
-tester.run("no-dead-relative-links", validateRelativeLinks, {
+tester.run(
+    "no-dead-relative-links: with resolve-as-markdown option",
+    {
+        rules: [
+            {
+                ruleId: "no-dead-relative-link",
+                rule: validateRelativeLinks,
+                options: {
+                    "resolve-as-markdown": ".html"
+                }
+            }
+        ]
+    },
+    {
     valid: [
         {
             inputPath: path.resolve("./test/fixtures/testFiles/validLinkTest.md"),
-            options: {
-                "resolve-as-markdown": ".html"
-            }
         }
     ],
     invalid: [
@@ -19,7 +29,7 @@ tester.run("no-dead-relative-links", validateRelativeLinks, {
                 {
                     message: "invalidLink.md does not exist",
                     line: 1,
-                    column: 59
+                    column: 58
                 },
                 {
                     message: "invalidLink.txt does not exist",
@@ -34,17 +44,17 @@ tester.run("no-dead-relative-links", validateRelativeLinks, {
                 {
                     message: "Anchor #valid-links does not exist in invalidLinkTest.md",
                     line: 4,
-                    column: 85 
+                    column: 85
                 },
                 {
                     message: "Anchor #header-7 does not exist in linkTestFile.md",
                     line: 5,
-                    column: 65 
+                    column: 65
                 },
                 {
                     message: "Anchor #header-7 does not exist in linkTestFile.md",
                     line: 6,
-                    column: 108 
+                    column: 108
                 },
                 {
                     message: "invalidLink.md does not exist",
@@ -54,12 +64,75 @@ tester.run("no-dead-relative-links", validateRelativeLinks, {
                 {
                     message:"setup-introduction.md does not exist",
                     line: 8,
-                    column: 134
+                    column: 133
+                }
+            ]
+        }
+    ]
+});
+tester.run(
+    "no-dead-relative-links: with route-map and resolve-as-markdown options",
+    {
+        rules: [
+            {
+                ruleId: "no-dead-relative-link",
+                rule: validateRelativeLinks,
+                options: {
+                    "resolve-as-markdown": ".html",
+                    "route-map": [
+                        {
+                            "source": "../../invalidLink.md",
+                            "destination": "../invalidLink.md"
+                        },
+                        {
+                            "source": "../dir/",
+                            "destination": "../"
+                        },
+                        {
+                            "source": "../../(subdir)/",
+                            "destination": "$1/"
+                        }
+                    ]
                 }
-            ],
-            options: {
-                "resolve-as-markdown": ".html"
             }
+        ]
+    },
+    {
+    valid: [
+        {
+            inputPath: path.resolve("./test/fixtures/testFiles/validLinkRoutingTest.md"),
+        }
+    ],
+    invalid: [
+        {
+            inputPath: path.resolve("./test/fixtures/testFiles/invalidLinkRoutingTest.md"),
+            errors: [
+                {
+                    message: "invalidLink.md does not exist",
+                    line: 1,
+                    column: 85
+                },
+                {
+                    message: "invalidLink.md does not exist",
+                    line: 2,
+                    column: 64
+                },
+                {
+                    message: "invalidLink.md does not exist",
+                    line: 3,
+                    column: 128
+                },
+                {
+                    message: "invalidLink.md does not exist",
+                    line: 4,
+                    column: 105
+                },
+                {
+                    message: "Anchor #header-7 does not exist in linkTestFile.md",
+                    line: 5,
+                    column: 113
+                }
+            ]
         }
     ]
 });
