markdown_link_checker_sc 0.0.13 → 0.0.116

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "markdown_link_checker_sc",
-  "version": "0.0.13",
+  "version": "0.0.116",
   "description": "Markdown Link Checker",
   "main": "index.js",
   "scripts": {
     "test": "test"
   },
+  "type": "module",
   "keywords": [
     "link",
     "checker",
     "markdown"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hamishwillee/markdown_link_checker_sc.git"
+  },
   "bin": {
     "markdown_link_checker_sc": "./index.js"
   },

package/src/errors.js

@@ -0,0 +1,148 @@
+import { sharedData } from "./shared_data.js";
+
+class LinkError {
+  constructor({ type, file, link = null }) {
+    if (!type) {
+      throw new Error("LinkError: Type is required!");
+    } else {
+      this.type = type;
+    }
+    if (link) {
+      this.link = link;
+      this.file = this.link.page;
+    } else {
+      this.file = file; // i.e. infer file from link, but if link not specified then can take passed value
+    }
+  }
+
+  output() {
+    console.log(`UNKNOWN ERROR:`);
+    console.log(this);
+  }
+}
+
+// Anchor link in current file does not exist
+class CurrentFileMissingAnchorError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "CurrentFileMissingAnchor" }); // call the super class constructor and pass in the param object
+  }
+  output() {
+    console.log(
+      `- ${this.type}: ` +
+        "`[" +
+        `${this.link.text}](#${this.link.anchor})` +
+        "`: anchor doesn't match any heading id or element id"
+    );
+  }
+}
+
+// Linked file (relative) exists but anchor in it does not
+class LinkedFileMissingAnchorError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "LinkedFileMissingAnchor" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}: #${this.link.anchor} not found in ${
+        this.link.address
+      } (${this.link.getAbsolutePath()})`
+    );
+  }
+}
+
+// A link to a page (markdown, and maybe HTML) that does not exist.
+class LinkedInternalPageMissingError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "LinkedInternalPageMissing" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}: This linked file is missing: ${this.link.address}`
+    );
+  }
+}
+
+// A link to an HTML file probably should be markdown
+class InternalLinkToHTMLError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "InternalLinkToHTML" });
+  }
+  output() {
+    console.log(`- ${this.type}: ${this.link.url} (should be ".md"?)`);
+  }
+}
+
+// A link to a URL that is this site, and should probably be an internal/relative link
+class UrlToLocalSiteError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "UrlToLocalSite" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}: Link is URL to this site. Should it be relative link?: \\[${this.link.text}](${this.link.url}))`
+    );
+  }
+}
+
+// Page is not linked from TOC page - here TOC is the page with most links, or may be explicitly defined.
+class PageNotInTOCError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "PageNotInTOC" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}:  Page not in Table of Contents (${sharedData.options.toc})`
+    );
+  }
+}
+
+// Page is not linked from any other page
+class PageNotLinkedInternallyError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "PageNotLinkedInternally" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}: Page is orphan (not linked by any other page)`
+    );
+  }
+}
+
+// Image is linked from page but not found
+class LocalImageNotFoundError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "LocalImageNotFound" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}: Linked image not found in file system: ${this.link.url}`
+    );
+  }
+}
+
+// Image is linked from page but not found
+class OrphanedImageError extends LinkError {
+  constructor({ file, link }) {
+    super({ file: file, link: link, type: "OrphanedImage" });
+  }
+  output() {
+    console.log(
+      `- ${this.type}: Image not linked from docs: ${this.file}`
+    );
+  }
+}
+
+
+
+export {
+  LinkError,
+  CurrentFileMissingAnchorError,
+  LinkedFileMissingAnchorError,
+  LinkedInternalPageMissingError,
+  InternalLinkToHTMLError,
+  UrlToLocalSiteError,
+  PageNotInTOCError,
+  PageNotLinkedInternallyError,
+  LocalImageNotFoundError,
+  OrphanedImageError
+};

package/src/helpers.js

@@ -0,0 +1,41 @@
+import fs from "fs/promises";
+import path from "path";
+
+// Log data to specified file path, replacing file.
+async function logToFile(filePath, dataString) {
+  try {
+    await fs.writeFile(filePath, dataString);
+    //console.log("Data written to file");
+  } catch (err) {
+    console.error(err);
+  }
+}
+
+const imageExtensions = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".svg",
+  ".gif",
+  ".webm",
+]);
+
+// Return true if file is an image.
+//Just looks at file extension.
+function isImage(file) {
+  const fileExtension = path.extname(file).toLowerCase();
+  return imageExtensions.has(fileExtension) ? true : false;
+}
+
+function isMarkdown(file) {
+  const fileExtension = path.extname(file).toLowerCase();
+  return fileExtension === ".md" ? true : false;
+}
+
+function isHTML(file) {
+  const fileExtension = path.extname(file).toLowerCase();
+  //console.log(`ext: ${fileExtension}`);
+  return fileExtension === ".html" || fileExtension === ".htm" ? true : false;
+}
+
+export { logToFile, isImage, isMarkdown, isHTML };

package/src/links.js

@@ -0,0 +1,194 @@
+import path from "path";
+import { isImage, isMarkdown, isHTML } from "./helpers.js";
+import { sharedData } from "./shared_data.js";
+
+class Link {
+  address = "";
+  anchor = "";
+  params = "";
+  type = "unHandledLinkType";
+  goat = "This is a 2goat";
+  isImage = false;
+  isMarkdown = false;
+  isHTML = false;
+  isRelative = false;
+
+  //isImage = false;
+  static linkTypes;
+  static {
+    this.linkTypes = new Set([
+      "unHandledLinkType",
+      "urlLink", // http(s) link
+      "urlLocalLink", // URL (http) pointing to current site
+      "urlImageLink", // https(s) link to image
+      "relativeImageLink", // relative link to image
+      "relativeLink", // relative link to another page/file
+      "relativeHTMLLink", // relative link to an HTML file.
+      "relativeAnchorLink", // link to anchor in current page
+      //"relativeParamLink", // link that only has params - probably a bug
+      "ftpLink", // FTP URL (i.e. ftp://)
+      "ftpsLink", // FTPS URL (i.e. ftps://)
+      "mailtoLink", // Mailto link (ie mailto whatever)
+    ]);
+  }
+
+  constructor({ page, url, type, text, title }) {
+    sharedData.options.log.includes("functions")
+    ? console.log("Link:constructor")
+    : null;
+
+    if (page) {
+      this.page = page;
+    } else {
+      throw new Error("Link: page argument is required.");
+    }
+
+    if (url) {
+      this.url = url;
+      this.splitURL(this.url);
+    } else {
+      throw new Error("Link: url argument is required.");
+    }
+
+    const linkTypeGuess = this.findType(); // Do to populate the isXxxx values
+    if (type) {
+      if (!Link.linkTypes.has(type)) {
+        console.log("Supported Link Types:");
+        console.log(Link.linkTypes); //This is because having trouble getting the set to print
+        throw new Error(`Link: type ${type} must be in supported link types`);
+      } else {
+        this.type = type;
+      }
+    } else {
+      //No type specified - use type inferred from extension etc.
+      this.type = linkTypeGuess;
+    }
+    text ? (this.text = text) : (this.text = "");
+    title ? (this.title = title) : (this.title = "");
+  }
+
+  // Take a URL and split to address, anchor, params
+  splitURL(url) {
+    //console.log(`Link:SplitUrl(${url})`);
+    const hashIndex = url.indexOf("#");
+    const queryIndex = url.indexOf("?");
+
+    let address = "";
+    let anchor = "";
+    let params = "";
+
+    if (hashIndex >= 0 && queryIndex >= 0) {
+      const splitIndex = hashIndex < queryIndex ? hashIndex : queryIndex;
+      address = url.substring(0, splitIndex);
+      if (hashIndex < queryIndex) {
+        anchor = url.substring(hashIndex + 1, queryIndex);
+        params = url.substring(queryIndex + 1);
+      } else {
+        params = url.substring(queryIndex + 1, hashIndex);
+        anchor = url.substring(hashIndex + 1);
+      }
+    } else if (hashIndex >= 0) {
+      // no queryIndex
+      address = url.substring(0, hashIndex);
+      anchor = url.substring(hashIndex + 1);
+    } else if (queryIndex >= 0) {
+      address = url.substring(0, queryIndex);
+      params = url.substring(queryIndex + 1);
+    } else {
+      address = url;
+    }
+    this.address = address;
+    this.params = params;
+    this.anchor = anchor;
+    //console.log(`url: ${this.url}`);
+    //console.log(`Address: ${this.address}`); //XXX
+    //console.log(`anchor: ${this.anchor}`);
+    //console.log(`param: ${this.params}`);
+  }
+
+  // Assign a guessed type based on other information.
+  // This is only used if the type is not specified as an argument.
+  // Uses file extension etc, so should be run after SplitUrl() which finds the address
+  findType() {
+    sharedData.options.log.includes("functions")
+    ? console.log("Link:findType()")
+    : null;
+    let linkType = "unHandledLinkType";
+
+    this.isImage = this.address && isImage(this.address) ? true : false; //only if address is true.
+    this.isMarkdown =
+      this.address && isMarkdown(this.address) ? true : false; //only if address is true.
+    this.isHTML = this.address && isHTML(this.address) ? true : false; //only if address is true.
+    const regexpTestProtocol = /^[a-z]+:/i;
+
+    //console.log(`Linkcheck1: ${this.address} `);
+    if (!this.address) {
+      //console.log(`Linkcheck2: ${this.address} `);
+      // local/relative link
+      if (this.anchor) {
+        //console.log(`Linkcheck3: ${this.anchor} `);
+        linkType = "relativeAnchorLink";
+      } else if (this.params) {
+        //console.log(`Linkcheck3: ${this.params} `);
+        // no anchor, no address, and has params
+        throw Error("Link: Invalid - only params, no address or anchor");
+      } else {
+        //console.log(`Linkcheck4: should be nothing url: ${this.url} `);
+        // This is the no url case - we already throw on this.
+        //Here we go again
+        throw Error("Link: Invalid - no address, params, anchor");
+      }
+    } else {
+      // We have an address - so it is either a URL or relative of some kind
+
+      if (this.address.startsWith("ftp://")) {
+        linkType = "ftpLink";
+      } else if (this.address.startsWith("ftps://")) {
+        linkType = "ftpsLink";
+      } else if (this.address.startsWith("mailto:")) {
+        linkType = "mailtoLink";
+      } else if (
+        this.address.startsWith("http:") ||
+        this.address.startsWith("https:")
+      ) {
+        linkType = this.isImage ? "urlImageLink" : "urlLink";
+      } else if (regexpTestProtocol.test(this.address)) {
+        // This is a protocol, but not one we handle.
+        // Leave type as unhandled. Should perhaps have a log type for unhandled stuff
+        //console.log("NN The string starts with an unhandled protocol - remove at some point");
+      } else {
+        this.isRelative = true;
+        // Must be a relative link of some kind.
+        //this.absolutePath = this.getAbsolutePath();
+        if (this.isImage) {
+          //console.log(`Linkcheck11 link is relative image : ${isImage} `);
+          linkType = "relativeImageLink";
+        } else if (this.isMarkdown) {
+          //console.log(`Linkcheck12 link is relative image : ${isMarkdown} `);
+          linkType = "relativeLink";
+        } else if (this.isHTML) {
+          //console.log(`Linkcheck13 link is relative image : ${isHTML} `);
+          linkType = "relativeHTMLLink"; //
+        } else {
+          //console.log(`Odd URLS : ${this.url} `);
+          // Its an unhandled relative link that isn't an image or markdown.
+          // Generally these links don't work in markdown. But for now let's leave it as unhandled.
+        }
+      }
+    }
+
+    return linkType; //Return whatever we guessed
+  } // end of file(type)
+
+  //get absolute path to link, if this is a relative URL link.
+  getAbsolutePath() {
+    sharedData.options.log.includes("functions")
+    ? console.log(`Link:getAbsolutePath: page: ${this.page}, address: ${this.address} `)
+    : null;
+    if (!this.isRelative) throw new Error("Link:getAbsolutePath() called on non-relative path");
+    return path.resolve(path.dirname(this.page), this.address);
+  }
+
+}
+
+export { Link };

package/src/output_errors.js

@@ -0,0 +1,49 @@
+//import { /*LinkError,*/ CurrentFileMissingAnchorError, LinkedFileMissingAnchorError, LinkedInternalPageMissingError, InternalLinkToHTMLError, UrlToLocalSiteError} from "./errors.js"
+
+import { sharedData } from "./shared_data.js";
+
+
+//Function that generates console and/or log output from an array of error objects.
+// - `results` is an array of error objects. These will have a `type` and a `page`. They may also have other values, depending on type of error - such as linkurl
+function outputErrors(results) {
+  sharedData.options.log.includes("functions")
+    ? console.log("Function: outputErrors()")
+    : null;
+
+  //Sort results by page and type.
+  // Perhaps next step is to create only get info for particular pages.
+  const sortedByPageErrors = {};
+
+  for (const error of results) {
+    //Report errors for listed pages or all
+    //console.log(error.page);
+    if (!sortedByPageErrors[error.file]) {
+      sortedByPageErrors[error.file] = [];
+    }
+    sortedByPageErrors[error.file].push(error);
+
+    // Sort by type as well.
+    for (const page in sortedByPageErrors) {
+      sortedByPageErrors[page].sort((a, b) => a.type.localeCompare(b.type));
+    }
+  }
+
+  //console.log(sortedByPageErrors);
+  for (const page in sortedByPageErrors) {
+    let pageFromRoot;
+    if (sharedData.options.root) {
+      pageFromRoot = page.split(sharedData.options.root)[1];
+    } else {
+      pageFromRoot = page.split(sharedData.options.directory)[1];
+    }
+    //console.log(`\nXX${page}`); //Root needs to full path - not '.' or whatever
+    console.log(`\n${pageFromRoot}`); //Root needs to full path - not '.' or whatever
+    for (const error of sortedByPageErrors[page]) {
+      if (error.output) {
+        error.output();
+      }
+    }
+  }
+}
+
+export { outputErrors };

package/src/process_image_orphans.js

@@ -0,0 +1,97 @@
+import { logToFile } from "./helpers.js";
+import fs from "fs";
+import path from "path";
+import { sharedData } from "./shared_data.js";
+import { OrphanedImageError } from "./errors.js";
+
+function isImage(file) {
+  const imageExtensions = [".jpg", ".jpeg", ".png", ".svg", ".gif", ".webm"];
+  const fileExtension = path.extname(file).toLowerCase();
+  return imageExtensions.includes(fileExtension) ? true : false;
+}
+
+var otherFileTypes = []; // Just used for logging in function below.
+
+// Gets all image files in a directory.
+async function getAllImageFilesInDirectory(dir) {
+  sharedData.options.log.includes("functions")
+    ? console.log(`Function: getAllImageFilesInDirectory(${dir})`)
+    : null;
+
+  // TODO put this all in a try catch and return a better error.
+  // Or perhaps put around parent.
+
+  const files = await fs.promises.readdir(dir, { withFileTypes: true });
+  const images = [];
+  for (let i = 0; i < files.length; i++) {
+    const file = path.join(dir, files[i].name);
+    if (files[i].isDirectory()) {
+      const subImages = await getAllImageFilesInDirectory(file);
+      images.push(...subImages);
+    } else if (isImage(file)) {
+      images.push(file);
+    } else {
+      const fileExtension = path.extname(file).toLowerCase();
+      otherFileTypes.includes(fileExtension)
+        ? null
+        : otherFileTypes.push(path.extname(file).toLowerCase());
+    }
+  }
+  //console.log(    `XXXX Other file types ${JSON.stringify(otherFileTypes, null, 2)}`  );
+  return images;
+}
+
+// Checks if any images in the options.directory
+async function checkImageOrphansGlobal(results) {
+  sharedData.options.log.includes("functions")
+    ? console.log("Function: checkImageOrphansGlobal")
+    : null;
+  const errors = [];
+  let allImagesFound = [];
+
+  if (sharedData.options.imagedir !== "") {
+    const imagePath = path.resolve(
+      sharedData.options.root,
+      sharedData.options.imagedir
+    );
+
+    allImagesFound = await getAllImageFilesInDirectory(imagePath);
+  }
+
+  sharedData.allImageFiles.forEach((value, valueAgain, set) => {
+    const imagePath = path.resolve(sharedData.options.root, value);
+    //console.log('val: ' + value);
+    allImagesFound.push(imagePath);
+  });
+
+  // Check all image files listed are in the array of local images we have (this is from the options.images directory)
+  const allImagesLinked = [];
+  results.forEach((page) => {
+    page.relativeImageLinks.forEach((link) => {
+      const fullImagePath = link.getAbsolutePath();
+      allImagesLinked.push(fullImagePath);
+    });
+  });
+
+  //console.log(`XXXXallImagesFound ${JSON.stringify(allImagesFound, null, 2)}`);
+  //console.log( `XXXXallImagesLinked ${JSON.stringify(allImagesLinked, null, 2)}`  );
+
+  // Add the image/assets directory to all the files found in the markdown directory.
+  //
+
+  allImagesFound.forEach((image) => {
+    if (!allImagesLinked.includes(image)) {
+      const error = new OrphanedImageError({ file: image });
+      errors.push(error);
+    }
+  });
+  //console.log(`XXXXOrphanedImageErrors ${JSON.stringify(errors, null, 2)}`);
+  return errors;
+}
+
+/*
+Add function to check if supplied images are linked or orphans - i.e. PR that adds an image that isn't used.
+Might not be needed - ie the above should make a filtered image on page.
+*/
+
+export { checkImageOrphansGlobal };

package/src/process_internal_url_links.js

@@ -0,0 +1,20 @@
+import path from "path";
+import { UrlToLocalSiteError} from "./errors.js"
+
+// An array of errors given a results object that contains our array of objects containing urls that link to our current site.
+function processUrlsToLocalSource(results) {
+  const errors = [];
+  results.forEach((page, index, array) => {
+    //console.log(`PAGE: ${page}`);
+
+    page.urlLocalLinks.forEach((link, index, array) => {
+      //console.log(`LINK: ${link}`);
+      
+      const error = new UrlToLocalSiteError({link: link})
+      errors.push(error);
+    });
+  });
+  return errors;
+}
+
+export { processUrlsToLocalSource };

package/src/process_local_image_links.js

@@ -0,0 +1,57 @@
+import path from "path";
+import fs from "fs";
+import { sharedData } from "./shared_data.js";
+import { LocalImageNotFoundError } from "./errors.js";
+
+// Checks if every image in every markdown page (results.page.relativeImageLinks) is present on the file system.
+// - results is the array of information coming out of markdown parsing.
+async function checkLocalImageLinks(results) {
+  sharedData.options.log.includes("functions") ? console.log(`Function: checkLocalImageLinks()`) : null;
+  const errors = [];
+  const promises = [];
+
+  results.forEach((page /*, index, array*/) => {
+    //console.log(`PAGE: ${page}`);
+
+    page.relativeImageLinks.forEach((link, index, array) => {
+      //console.log(`XYYXLINK: ${JSON.stringify(link, null, 2)}`);
+      //console.log(`sharedData.options.root: ${sharedData.options.root}`);
+      //console.log(`sharedData.options.directory: ${sharedData.options.directory}`);
+      //console.log(`link.linkUrlt: ${link.url}`);
+      //console.log(`dirname: ${path.dirname(page.page_file)}`);
+
+      const fullImagePath = path.join(
+        path.dirname(page.page_file),
+        link.url
+      );
+      //console.log(`fullImagePath: ${fullImagePath}`);
+      const promise = new Promise((resolve) => {
+        fs.access(fullImagePath, fs.constants.F_OK, (err) => {
+          if (err) {
+            //console.log("Error");
+			      const error = new LocalImageNotFoundError({link: link});
+            /*
+            const error = {
+              type: "LocalImageNotFound",
+              page: `${page.page_file}`,
+              linkUrl: `${link.url}`,
+              linkText: `${link.text}`,
+              linkFullPath: `${fullImagePath}`,
+            };
+            */
+            errors.push(error);
+            resolve(false);
+          } else {
+            //console.log("SUCCESS");
+            resolve(true);
+          }
+        });
+      });
+      promises.push(promise);
+    });
+  });
+  await Promise.all(promises); //Wait for all files to be checked
+  return errors;
+}
+
+export { checkLocalImageLinks };